1. 环境搭建与首次成功

欢迎开启用 Python 构建 AI 代理（agent）之旅！在本章结束时，你将完成对大语言模型（LLM, Large Language Model）的第一次成功调用，并且清楚理解幕后究竟发生了什么。这将成为你后续所有内容的基础。

先决条件

读者与前提假设

本书面向Python 开发者，他们希望构建 AI 代理（agent），但没有使用过 LLM 或 AI 框架的经验。我们假设你已熟悉：

• Python 基础：函数、类、导入、基础数据结构
• Python 3.10+：你的系统应安装 Python 3.10 或更高版本
• 虚拟环境：使用 python -m venv 创建并激活 venv
• 包管理：用 pip 安装包
• 环境变量：在 shell 中设置并读取环境变量
• API 密钥：理解 API 密钥是什么，以及如何从服务提供商处获取

如果上述概念有任何不熟悉，我们建议在继续之前单独复习。Python 官方文档，以及关于虚拟环境与 pip 的教程，都是很好的起点。

我们不假设你具备的背景：你不需要任何机器学习、神经网络、transformers 或 AI 理论方面的基础。我们会在遇到 LLM 相关概念时进行解释，并始终把它们与熟悉的编程模式联系起来。

模型约定

在本书中，我们会使用 GPT-5-mini 作为示例的默认模型。原因如下：

• 可广泛获取：OpenAI 的 API 可在全球范围内使用，注册流程也很直接
• 速度合理：在最小推理强度下，响应足够快，适合迭代式开发
• 成本友好：按 2026 年价格，输入每百万 token $0.25，输出每百万 token $2.00，适合学习与实验
• 能力足够：它能够很好地处理绝大多数实用的 AI 代理（agent）任务

当你看到没有显式指定模型的代码示例时，默认我们使用的是 GPT-5-mini。在第 2 章，我们会探索可用模型的完整版图（Claude、Gemini 以及其他 GPT 变体），并讨论你可能会在上下文窗口大小、成本或专用能力等因素的影响下，选择替代方案的时机。

1.1) 什么是 LLM？

在写任何代码之前，我们先明确我们到底在操作什么。大语言模型（LLM, Large Language Model） 是一种神经网络，它在海量文本数据上训练，用于预测序列中接下来应该出现什么文本。

你可以把它理解成一个极其先进的自动补全系统。当你在手机上输入时，它会建议下一个词，这就是 LLM 所做事情的一个简单版本。但 LLM 的规模与复杂度更高，使它们能够：

• 针对问题生成连贯、符合上下文的回答
• 编写代码、文章、邮件以及其他结构化内容
• 在语言之间进行翻译
• 总结长文档
• 从非结构化文本中提取信息
• 以及更多

LLM 与传统软件有何不同

传统软件遵循你编写的显式规则：

def calculate_discount(price, customer_type):
    if customer_type == "premium":
        return price * 0.8  # 20% 折扣
    elif customer_type == "regular":
        return price * 0.95  # 5% 折扣
    else:
        return price

这个函数在相同输入下总会产生相同输出。其逻辑是确定性的，并且透明可见。

LLM 的工作方式不同。它们不依赖显式规则，而是使用从训练数据中学到的模式来生成回答。你提供输入文本（称为提示（prompt）），模型生成输出文本（称为补全（completion）或响应（response））。

# 概念示例——我们很快会写真实代码
response = llm.generate("高级客户适合什么折扣？")
# 输出示例："高级客户通常可获得15-25%的折扣..."

LLM 并没有硬编码的折扣百分比。它基于训练中学到的模式生成回答。这意味着：

1. 响应可能变化：同一个提示每次可能产生略有不同的回答
2. 行为是学习得来的，而非编程写死的：你通过提示来引导模型，而不是编写显式逻辑
3. 能力来自规模涌现：模型能够处理一些并未被显式训练过的任务

关键术语

我们来定义你会频繁遇到的术语：

• 提示（prompt）：你发送给模型的输入文本。可以把它视作“问题”或“指令”
• 补全/响应（completion/response）：模型针对你的提示生成的文本
• Token：LLM 处理的基本单位。粗略来说，1 token ≈ 4 个字符或 ¾ 个单词。“Hello world” 大约是 2 个 token
• 上下文窗口（context window）：模型一次能处理的最大文本量（以 token 计）。GPT-5-mini 的上下文窗口为 400K token
• Temperature：控制随机性的参数。较低（0.0-0.3）= 更聚焦、更确定；较高（0.7-1.0）= 更有创意、更多变化

LLM 能做什么与不能做什么

理解 LLM 可靠擅长什么——以及它们只是看起来能做什么——对构建健壮的 AI 代理（agent）至关重要。

LLM 非常擅长：

• 理解与生成自然语言：它们能解析意图、生成连贯回复，并处理复杂表述

"我想退款" → 识别意图：refund_request
"总结这份文档" → 生成简洁摘要

• 在提示中遵循指令：在给出清晰指引时，它们可以输出结构化结果，比如 JSON 或格式化文本

"转换为 JSON：John Smith，32岁，住在波士顿"
→ {"name": "John Smith", "age": 32, "city": "Boston"}

• 识别文本中的模式：情感分析、分类、信息抽取通常很可靠

• 生成代码与结构化内容：在提示恰当时，可以写出有效的 Python、SQL 或其他格式化输出

• 逐步推理：当明确要求“逐步思考”时，它们会把问题方法论式地拆解

LLM 的局限：

• 不是数据库：它们不检索事实——而是生成统计上看起来合理的文本。它们可能会非常自信地陈述听起来权威但实际错误的信息。

"Python 4.0 是什么时候发布的？" 
→ 可能生成 "Python 4.0 于 2023 年发布"（错误，但看似合理）

• 不是计算器：它们预测“答案应该长什么样”，而不是执行计算。简单算术经常可行；复杂数学会以不可预测的方式失败。

"8,247 × 6,839 等于多少？" → 可能给出看起来合理但错误的结果

• 不是确定性的：同一个提示每次都可能得到不同输出。这种变化由 temperature 参数控制。

• 不一定准确：它们会不管事实正确与否，生成听起来可信的文本。“幻觉（hallucinations）”——细节丰富、自信但完全捏造的信息——经常发生。

关键洞见：构建代理（agent）时，要把 LLM（用于理解与决策）与传统工具（用于计算、数据检索与事实操作）结合起来。我们会从第 13 章开始实现这一模式：让 LLM 决定何时使用计算器，而不是自己尝试做数学。

你将学到什么

在本书中，你将学习构建AI 代理（agent）——一种系统：LLM 会自主决定采取哪些行动来达成目标，而不是遵循预先写死的逻辑。我们会在第 2 章深入探索这一范式。

1.2) 安装依赖

让我们搭建开发环境。我们将创建一个干净的项目结构，并安装用于构建 AI 代理（agent）的框架 LangChain。

验证 Python 安装

首先，确保你的系统已安装 Python。我们推荐 Python 3.10 或更高版本（截至 2026 年，Python 3.13 或 3.14 是不错的选择）。

检查你的 Python 版本：

python --version
# or
python3 --version

你应该会看到类似 Python 3.13.x 或 Python 3.14.x 的输出。

如果未安装 Python：

• macOS：

  • 从 python.org 下载
  • 或使用 Homebrew：brew install python@3.14

• Windows：

  • 从 python.org 下载
  • 安装时勾选 “Add Python to PATH”

• Linux：

  • Ubuntu/Debian：sudo apt update && sudo apt install python3.14
  • Fedora：sudo dnf install python3.14

安装后，再次用 python --version 验证。

注意：在某些系统上，你可能需要使用 python3 而不是 python。本书中如果 python 不起作用，请尝试 python3。

创建你的项目

打开终端，为你的项目创建一个新目录：

mkdir agentic-ai-project
cd agentic-ai-project

创建虚拟环境以隔离依赖：

python -m venv venv

激活虚拟环境：

# On macOS/Linux:
source venv/bin/activate
 
# On Windows:
venv\Scripts\activate

你应该会在终端提示符中看到 (venv)，表示虚拟环境已激活。

安装 LangChain 与 OpenAI

我们将安装 LangChain 的 OpenAI 集成，它包含与 OpenAI 模型交互所需的一切：

pip install langchain-openai

这会安装 langchain-openai 及其依赖，包括 langchain-core（LangChain 的核心抽象）以及 OpenAI 的 Python 客户端。你应该能看到输出确认安装了多个包。

验证安装：

pip show langchain-openai

你应该会看到已安装包的详细信息，包括版本号与安装位置。这确认安装成功。

获取你的 OpenAI API Key

要调用 OpenAI 的模型，你需要一个 API key：

1. 进入 platform.openai.com
2. 注册或登录
3. 在账号设置中进入 API Keys
4. 点击 “Create new secret key”
5. 复制该 key（以 sk- 开头）

⚠️ 安全警告：把这个 key 当作密码。不要把它提交到版本控制系统，也不要公开分享。任何拿到你的 key 的人都可以发起 API 调用，并计费到你的账号。

将你的 API Key 设置为环境变量

推荐通过环境变量提供 API key：

# On macOS/Linux:
export OPENAI_API_KEY='sk-your-actual-key-here'
 
# On Windows (Command Prompt):
set OPENAI_API_KEY=sk-your-actual-key-here
 
# On Windows (PowerShell):
$env:OPENAI_API_KEY='sk-your-actual-key-here'

注意：此设置是临时的，关闭终端后会丢失。要永久生效，你可以：

• 把 export 命令加入你的 shell 配置文件（.bashrc、.zshrc 等）
• 使用 .env 文件（我们会在第 3 章为更好的项目组织来设置它）

现在，临时设置足够继续往下进行。

验证是否已设置：

# On macOS/Linux:
echo $OPENAI_API_KEY
 
# On Windows (Command Prompt):
echo %OPENAI_API_KEY%
 
# On Windows (PowerShell):
echo $env:OPENAI_API_KEY

你应该会看到打印出的 API key。如果没有，请重复 export/set 命令并确保没有拼写错误。

1.3) 你的第一次 LLM 调用

现在进入最激动人心的部分——让我们发起对 LLM 的第一次调用。创建一个名为 first_call.py 的文件：

# first_call.py
from langchain_openai import ChatOpenAI
 
# 初始化 LLM
llm = ChatOpenAI(model="gpt-5-mini")
 
# 发送提示并获取响应
response = llm.invoke("LangChain 是什么？")
 
# 打印响应
print(response.content)

运行它：

python first_call.py

你应该会看到类似这样的输出（具体措辞可能不同）：

LangChain 是一个框架，用于简化由大语言模型（LLM）驱动的应用程序的开发。它提供了一系列工具和抽象，用来构建由多次 LLM 调用组成的链条、集成外部数据源、管理提示（prompt），以及创建能够与各种 API 和数据库交互的代理（agent）。通过这些可复用的组件和模式，LangChain 让构建复杂的 AI 应用变得更加容易。

恭喜！ 你刚刚完成了第一次 LLM 调用。让我们拆解这段代码里发生了什么。

故障排查：如果你看到错误：

• AuthenticationError：API key 无效或未设置 → 检查你的 OPENAI_API_KEY 环境变量（见 1.2 节）
• RateLimitError：请求过快或超出使用限额 → 等几秒后重试，或在 platform.openai.com/usage 查看用量
• APIConnectionError：网络连接问题 → 检查你的网络连接

理解代码

导入 LLM 包装器：

from langchain_openai import ChatOpenAI

ChatOpenAI 是 LangChain 对 OpenAI chat 模型的封装。它会为你处理 API 认证、请求格式化以及响应解析。

初始化模型：

llm = ChatOpenAI(model="gpt-5-mini")

这会创建一个配置为使用 GPT-5-mini 的实例。幕后，LangChain 会读取你的 OPENAI_API_KEY 环境变量用于认证。你也可以显式传入 key：

llm = ChatOpenAI(model="gpt-5-mini", api_key="sk-your-key")

但使用环境变量更安全也更灵活。

调用模型：

response = llm.invoke("LangChain 是什么？")

invoke() 方法会把你的提示发送到 OpenAI 的 API，并等待完整响应返回。这是一次同步（synchronous）调用——你的程序会暂停，直到响应到达。

访问响应内容：

print(response.content)

响应对象包含多个字段。.content 字段保存模型生成的实际文本。下一节我们会探索其他字段。

尝试不同的提示

修改提示，看看模型对不同输入的响应：

# first_call.py
from langchain_openai import ChatOpenAI
 
llm = ChatOpenAI(model="gpt-5-mini")
 
# 尝试不同的提示
prompts = [
    "用一句话解释 Python 装饰器。",
    "15 * 23 等于多少？",
    "列出在 Python 中使用类型标注的三个好处。",
]
 
for prompt in prompts:
    response = llm.invoke(prompt)
    print(f"Prompt: {prompt}")
    print(f"Response: {response.content}\n")

模型可以处理不同类型的请求——解释、计算以及结构化列表。你会注意到，如果你多次运行相同提示，响应可能会略有不同。这是正常行为——我们会在第 2 章探讨为什么会这样，以及如何控制它。

1.4) 刚刚发生了什么？（请求 → 模型 → 响应流程）

让我们准确看看你调用 llm.invoke() 时发生了什么。理解这个流程对构建可靠的 AI 代理（agent）至关重要。

完整的请求-响应周期

让我们跟踪每一步：

第 1 步：你的代码调用 invoke()

response = llm.invoke("LangChain 是什么？")

invoke() 方法是你与 LLM 交互的主要接口。你传入一个提示字符串，它返回一个包含模型回答的响应对象。在这次简单调用背后，会自动发生多个步骤。

第 2 步：LangChain 格式化请求

LangChain 会把你的字符串转换为结构化的 API 请求。幕后它会创建类似如下的 JSON payload：

{
  "model": "gpt-5-mini",
  "messages": [
    {
      "role": "user",
      "content": "LangChain 是什么？"
    }
  ],
  "temperature": 1.0
}

messages 数组是 chat 模型接收输入的方式。每条消息都有 role（user、assistant 或 system）和 content（文本）。我们会在第 4 章探索消息角色。

第 3 步：调用 OpenAI 的 API

LangChain 会向 OpenAI 的 API 端点发送一个 HTTPS POST 请求：

POST https://api.openai.com/v1/chat/completions
Authorization: Bearer sk-your-api-key
Content-Type: application/json
 
{request payload}

你的 API key 会对请求进行身份验证。OpenAI 服务器接收请求并将其路由到指定模型。

第 4 步：模型处理提示

GPT-5-mini 接收你的提示，并逐 token 生成响应。模型会：

1. 将你的文本转换为 tokens（数值化表示）
2. 通过其神经网络层处理 token
3. 预测最可能的下一个 token
4. 重复，直到生成完整响应或触发停止条件

这些发生在 OpenAI 的服务器上——你的代码只是等待结果。

第 5 步：API 返回响应

OpenAI 的 API 会返回一个 JSON 响应：

{
  "id": "chatcmpl-8x7y9z",
  "object": "chat.completion",
  "created": 1704067200,
  "model": "gpt-5-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "LangChain 是一个旨在简化..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 58,
    "total_tokens": 70
  }
}

关键字段：

• message.content：生成的文本
• usage：用于计费与监控的 token 计数
• finish_reason：生成停止的原因（"stop" = 自然结束，"length" = 达到 token 上限）

第 6 步：LangChain 解析响应

LangChain 会把 JSON 转换为你可以操作的 Python 对象：

from langchain_openai import ChatOpenAI
 
llm = ChatOpenAI(model="gpt-5-mini")
response = llm.invoke("LangChain 是什么？")
 
# 探索响应对象
print(f"Content: {response.content}")
print(f"Type: {type(response)}")
print(f"Response metadata: {response.response_metadata}")

输出：

Content: LangChain 是一个旨在简化...
Type: <class 'langchain_core.messages.ai.AIMessage'>
Response metadata: {'token_usage': {'completion_tokens': 58, 'prompt_tokens': 12, 'total_tokens': 70}, 'model_name': 'gpt-5-mini', 'finish_reason': 'stop'}

响应是一个 AIMessage 对象，包含若干有用属性：

• content：生成的文本（通常你最关心的）
• response_metadata：token 使用量、模型名、finish reason
• id：该响应的唯一标识符
• usage_metadata：更详细的 token 拆分

理解 Token 使用量

在查看 token 计数之前，先简单说明：tokens 是 LLM 处理的基本单位。英语文本通常每个单词略多于 1 个 token（例如 "explain quantum computing" = 3 个词，4-5 个 token），但像韩语、中文这样的非英语语言，往往需要明显更多的 token 才能表示同样的文本。我们会在第 2 章更详细地讨论 token。

让我们更仔细地查看 token 消耗：

from langchain_openai import ChatOpenAI
 
llm = ChatOpenAI(model="gpt-5-mini")
response = llm.invoke("用简单的术语解释量子计算。")
 
usage = response.response_metadata['token_usage']
print(f"Input tokens: {usage['prompt_tokens']}")
print(f"Output tokens: {usage['completion_tokens']}")
print(f"Total tokens: {usage['total_tokens']}")

输出：

Input tokens: 11
Output tokens: 95
Total tokens: 106

注意：prompt_tokens = 输入 token（你的提示），completion_tokens = 输出 token（模型响应），total_tokens = 两者之和。

Token 消耗会因以下因素而变化：

• 提示长度：更长的提示会使用更多输入 token
• 响应细节：更细致的响应会生成更多输出 token
• 语言复杂度：技术术语与代码的分词方式可能不同

例如，一个短提示如 "What's 2+2?" 可能只使用 5-6 个输入 token 和 8-10 个输出 token，而 "Write a detailed essay about the history of Python programming language" 可能会使用 15-20 个输入 token 和 500+ 个输出 token。

成本计算（以上示例）：

按 GPT-5-mini 的定价（输入每百万 token $0.25，输出每百万 token $2.00）：

• 输入：11 tokens × $0.25 / 1,000,000 = $0.00000275
• 输出：95 tokens × $2.00 / 1,000,000 = $0.00019
• 总计：~$0.0002（百分之二美分）

输入与输出 token 都计费，但输出 token 更贵（此处是 8×）。

你学到了什么

你现在理解了一次 LLM 调用的完整生命周期：

1. 你的代码提供提示字符串
2. LangChain把它格式化为带认证信息的 API 请求
3. OpenAI 的 API将请求路由到模型
4. 模型逐 token 生成响应
5. API返回包含响应与元数据的结构化 JSON
6. LangChain把它解析为 Python 对象
7. 你的代码读取内容与元数据

你还学到了：

• 如何检查响应对象并提取元数据
• token 使用量如何影响成本

这些基础将为第 2 章做好准备：我们将探索 LLM 在底层如何工作、比较不同模型，并学习提示工程（prompt engineering）技巧以获得更好的结果。