环境准备(二):三条链路打通
本合集目录
本章目录
单册说明:本文件是「AI Agent 完整教程」卷 0 的第 4 章,可独立阅读。 前置:必须做完第 3 章(实验目录已建、三个环境变量已配)。这一章的所有命令都在
ai-agent-lab/code里执行。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 0 · 学习地图(第 4 / 6 章) |
| 前置章节 | 第 3 章(环境准备一) |
| 本章产出 | 网页 / 客户端 / API 三条链路全部打通 |
| 对应代码 | code/hello_model.py(零依赖)、code/check_env.py(零依赖) |
| 配图 | 图 0-3(三条链路)、图 0-8(报错四步定位) |
| 读完的判定 | 三条链路各完成一次任务;给一个错误码能说出改哪个变量 |
4.1 为什么是三条链路,不是一条
"我能用 AI" 这句话,实际上可能是三种完全不同的状态:

| 链路 | 谁发起请求 | 能做什么 | 不能做什么 |
|---|---|---|---|
| ① 网页 | 你,在浏览器里 | 对话、上传文件、看结果 | 接不进任何流程,不能定时,不能批量 |
| ② 客户端 | 一个装了 Agent 能力的软件 | 读写文件、跑命令、查网页,能动手 | 受客户端限制,难以嵌进你自己的系统 |
| ③ API | 你的程序 | 一切自动化:批量、定时、集成 | 要自己写代码,自己处理错误和费用 |
必须按 ①②③ 的顺序打通,原因很实际:出问题时能确定是谁的问题。
- 如果链路①就不通 → 是账号、网络、额度的问题,与代码无关;
- 如果①通、②不通 → 是客户端安装或配置的问题;
- 如果①②通、③不通 → 是密钥、接口地址、模型名或代码的问题。
跳过①②直接写代码,一旦报错,你要同时怀疑网络、账号、密钥、地址、模型名、代码六件事。
顺序本身就是一种排查工具。 本章后面那张四步定位图能起作用,前提就是你已经按 ①②③ 的顺序走过一遍,知道自己在哪一步卡住。
4.2 链路① 网页:先确认"服务本身是好的"
打开你的模型服务网页版,发一句话:
你好,用一句话介绍你自己,并说明你能做什么、不能做什么。
要观察的不是它答得好不好,而是三件事:
- 能不能答(不能答 → 账号/额度/网络问题,先解决,别往下走);
- 回答的语言和风格(后面写提示词时,你要知道它的默认倾向);
- 它自称能做什么(模型的自我描述常常夸大,记住这一点——这直接关系到 5.7 的"它会吹牛")。
链路①通过的标准很低:能稳定返回一段正常回答。 到此为止,不要在这里花太多时间。
4.3 链路② 客户端:拿到"能动手"的体验
客户端是"Agent 能力"最直观的载体。它和网页版的核心区别是:它有权访问你的文件系统和终端。
市面上的客户端大致分三类,选一个装就行,不要装五个:
| 类型 | 形态 | 特点 | 适合 |
|---|---|---|---|
| 命令行型 | 在终端里对话 | 轻、快、可直接操作当前目录 | 画像 B,习惯终端的人 |
| IDE 型 | 嵌在编辑器里 | 与代码、文件强结合 | 画像 B,写代码为主 |
| 桌面型 | 独立应用窗口 | 有界面、易上手、可管多个项目 | 画像 A,非程序员 |
装完之后,做一个测试任务(这个任务本身就在检验它是不是真 Agent):
在
ai-agent-lab/inbox里建一个test.md,写上今天日期和一句话;然后把该目录的文件名列给我。
你要观察四件事:
- 它是直接动手,还是先问你确认?(好的客户端会在写文件前询问)
- 它有没有先看目录再操作?(不看就写,说明它在猜)
- 它改错了会不会自己发现?(把文件写到别处,看它是否检查结果)
- 它有没有权限边界?(能不能碰到
ai-agent-lab以外的目录)
这四点就是你判断一个客户端好坏的依据,比任何评测榜单都实在。
4.4 链路③ API:三个值决定一切
API 这件事,被讲得很玄。实际上它只有三个变量:
| 变量 | 含义 | 例子 | 配错的典型症状 |
|---|---|---|---|
AI_BASE_URL |
去哪找服务(地址) | https://api.openai.com/v1 |
404 / 连不上 |
AI_API_KEY |
你是谁(凭据) | sk-... |
401 / 403 |
AI_MODEL |
用哪个模型(型号) | gpt-4o-mini |
404 / 400 |
为什么"换个服务商只改两个值就行"?
因为现在绝大多数模型服务都兼容同一套请求格式(OpenAI 的 /chat/completions)。请求长这样:
{
"model": "gpt-4o-mini",
"messages": [
{ "role": "system", "content": "你是一个简洁的中文助手。" },
{ "role": "user", "content": "用一句话解释什么是 token" }
],
"temperature": 0.3
}
messages 是一个数组,里面每条消息有一个 role(谁说的)和 content(说了什么)。这个结构是后面所有内容的地基——第 5 章的 Agent 循环,本质上就是往这个数组里不断追加消息。
记住这句话:Agent 的"记忆",在代码层面就是这个
messages数组越来越长。 卷 2 讲记忆系统时,你会看到这句话展开成三层结构。
4.5 代码:跑通第一次 API 调用
下面是完整可运行的脚本,只用 Python 标准库,不需要 pip install 任何东西。文件在 code/hello_model.py。
核心部分就是这 30 行:
import json, os, urllib.request, urllib.error
def build_payload(model, prompt):
return {
"model": model,
"messages": [
{"role": "system", "content": "你是一个简洁、准确的中文助手。"},
{"role": "user", "content": prompt},
],
"temperature": 0.3,
"max_tokens": 800,
}
def call_model(base_url, api_key, payload, timeout=60):
url = base_url.rstrip("/") + "/chat/completions"
req = urllib.request.Request(
url,
data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
method="POST",
headers={
"Content-Type": "application/json",
"Authorization": f"Bearer {api_key}",
"User-Agent": "ai-agent-tutorial/volume0",
},
)
with urllib.request.urlopen(req, timeout=timeout) as resp:
return json.loads(resp.read().decode("utf-8"))
# 用起来
resp = call_model(
os.environ["AI_BASE_URL"],
os.environ["AI_API_KEY"],
build_payload(os.environ["AI_MODEL"], "用三句话解释什么是 AI Agent"),
)
print(resp["choices"][0]["message"]["content"])
print(resp["usage"]) # 这一行很重要:告诉你这次花了多少 token
运行:
cd ai-agent-lab/code
python hello_model.py
如果三个环境变量配好了,你会看到模型回答 + 一行用量信息。
如果还没有密钥,可以先看它会发什么(不花钱、不联网):
python hello_model.py --mock
它会打印完整的请求体,让你核对 model、messages 结构是否正确。这个习惯建议保持:先看请求,再发请求。
4.6 报错诊断:四步定位法
第一次调用失败是常态。顺序不能反——反了就会同时怀疑六件事。

先用 curl 测网络 → 再用 hello_model.py --mock 核对请求体 → 再真发一次 → 按错误码查表
完整诊断表(覆盖 90% 的情况):
| 错误 | 含义 | 优先检查 | 常见真实原因 |
|---|---|---|---|
401 Unauthorized |
密钥无效 | AI_API_KEY |
值带空格/引号;Key 已失效;用了别家的 Key 配这家的地址 |
403 Forbidden |
无权限 | 账号权限、地区 | 模型未开通;账号被限;地区限制 |
404 Not Found |
地址或模型不存在 | AI_BASE_URL、AI_MODEL |
地址多了/少了 /v1;模型名拼错或该账号没有这个模型 |
400 Bad Request |
请求格式有问题 | 请求体 | 模型名不支持;max_tokens 超限;参数名拼错 |
429 Too Many Requests |
限流或余额不足 | 额度、频率 | 并发太高;免费额度用完;账户欠费 |
5xx |
服务端问题 | 与你无关 | 稍后重试;若走中转,换节点 |
| 连接超时 | 网络不通 | 网络、代理 | 直连被拦;代理端口错;DNS 问题 |
CERTIFICATE_VERIFY_FAILED |
证书校验失败 | 代理、系统时间 | 代理做中间人;系统时间偏差;公司网络 |
| 返回 200 但内容为空 | 请求成功、模型没输出 | max_tokens、内容过滤 |
max_tokens 太小;触发内容策略 |
不要一上来就改代码。80% 的"代码问题"其实是配置问题。
4.7 代码:一条命令做完全身体检
code/check_env.py 会把第 3、4 章的所有前置条件查一遍,输出一张体检表:
python check_env.py # 完整检查(含网络)
python check_env.py --no-network # 只查本地
python check_env.py --base-url https://你的服务地址/v1
实际输出示例(第一次跑,密钥还没配):
==============================================================
卷 0 环境自检
==============================================================
系统:Windows 11 · AMD64
Python 可执行文件:...\python.exe
工作目录:C:\Users\你\ai-agent-lab
目标服务:https://api.openai.com/v1
--------------------------------------------------------------
[ OK ] Python 版本 3.12.4 —— 满足 >= 3.9
[ OK ] 标准库 —— json / urllib / ssl / sqlite3 / pathlib 均可导入
[ OK ] 命令 git —— ...
[WARN] 命令 node —— 未找到 · 可选,装 JavaScript 类 Agent 工具时需要
[FAIL] AI_API_KEY —— 未设置。没有它,链路③ 跑不通
[ OK ] 目录 C:\Users\你\ai-agent-lab —— 已自动创建
[ OK ] 目录可写 —— C:\Users\你\ai-agent-lab\output
[ OK ] DNS 解析 api.openai.com —— 162.159.x.x
[ OK ] TCP 443 api.openai.com —— 可连接
--------------------------------------------------------------
结果:14 项检查 · 通过 11 · 警告 2 · 失败 1
先修这些(按顺序):
1. AI_API_KEY —— 未设置。没有它,链路③ 跑不通
注意它做了两件"多余"的事,这两件事恰好是新手最容易漏的:
- 不只看目录存不存在,还真的写一次文件——目录在但没权限,是极常见的坑;
- 不只 ping,而是做 DNS 解析 + TCP 443 连接——ping 通不等于 HTTPS 通。
4.8 三条链路打通之后
到这里,你手上应该有三样东西:
| 链路 | 通过标准 | 意义 |
|---|---|---|
| ① 网页 | 能稳定返回回答 | 服务是好的 |
| ② 客户端 | 能读写文件,且会问你确认 | Agent 能力是真的 |
| ③ API | hello_model.py 打印出回答和 token 用量 |
可以编程了 |
如果只走到②:你已经可以开始用 Agent 干活了,可以跳到第 6 章选路径 A。 如果想让它每天自动干活:必须走通③,继续第 5 章。
4.9 本章验收
- 应当会独立完成三条链路的验证,并说出每条链路"通"的判定标准;
- 应当会看错误码定位问题:给一个
401和一个404,你能分别说出该改哪个变量; - 应当会解释为什么换服务商通常只改两个值。
自测题:
| 题 | 你的答案 |
|---|---|
curl 返回 401,说明网络通不通? |
通。401 是服务端在回你"没凭据" |
报 404,先改 AI_API_KEY 还是 AI_MODEL? |
后者(地址或模型名) |
报 429,代码有问题吗? |
没有。是额度或频率 |
返回 200 但 content 是空字符串 |
查 max_tokens 和内容策略 |
4.10 下一步
三条链路都通了,现在写第一个真正的 Agent → 第 5 章 第一个 Agent:从 20 行到能干活
回看:第 3 章 环境准备(一) · 返回导读