跳到正文
AI Agent 教程 · 卷 0 · 学习地图

环境准备(二):三条链路打通

本合集目录
本章目录

单册说明:本文件是「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" 这句话,实际上可能是三种完全不同的状态:

三条链路:网页、客户端、API

链路 谁发起请求 能做什么 不能做什么
① 网页 你,在浏览器里 对话、上传文件、看结果 接不进任何流程,不能定时,不能批量
② 客户端 一个装了 Agent 能力的软件 读写文件、跑命令、查网页,能动手 受客户端限制,难以嵌进你自己的系统
③ API 你的程序 一切自动化:批量、定时、集成 要自己写代码,自己处理错误和费用

必须按 ①②③ 的顺序打通,原因很实际:出问题时能确定是谁的问题。

  • 如果链路①就不通 → 是账号、网络、额度的问题,与代码无关;
  • 如果①通、②不通 → 是客户端安装或配置的问题;
  • 如果①②通、③不通 → 是密钥、接口地址、模型名或代码的问题。

跳过①②直接写代码,一旦报错,你要同时怀疑网络、账号、密钥、地址、模型名、代码六件事。

顺序本身就是一种排查工具。 本章后面那张四步定位图能起作用,前提就是你已经按 ①②③ 的顺序走过一遍,知道自己在哪一步卡住。


4.2 链路① 网页:先确认"服务本身是好的"

打开你的模型服务网页版,发一句话:

你好,用一句话介绍你自己,并说明你能做什么、不能做什么。

要观察的不是它答得好不好,而是三件事:

  1. 能不能答(不能答 → 账号/额度/网络问题,先解决,别往下走);
  2. 回答的语言和风格(后面写提示词时,你要知道它的默认倾向);
  3. 它自称能做什么(模型的自我描述常常夸大,记住这一点——这直接关系到 5.7 的"它会吹牛")。

链路①通过的标准很低:能稳定返回一段正常回答。 到此为止,不要在这里花太多时间。


4.3 链路② 客户端:拿到"能动手"的体验

客户端是"Agent 能力"最直观的载体。它和网页版的核心区别是:它有权访问你的文件系统和终端。

市面上的客户端大致分三类,选一个装就行,不要装五个:

类型 形态 特点 适合
命令行型 在终端里对话 轻、快、可直接操作当前目录 画像 B,习惯终端的人
IDE 型 嵌在编辑器里 与代码、文件强结合 画像 B,写代码为主
桌面型 独立应用窗口 有界面、易上手、可管多个项目 画像 A,非程序员

装完之后,做一个测试任务(这个任务本身就在检验它是不是真 Agent):

在 ai-agent-lab/inbox 里建一个 test.md,写上今天日期和一句话;然后把该目录的文件名列给我。

你要观察四件事:

  1. 它是直接动手,还是先问你确认?(好的客户端会在写文件前询问)
  2. 它有没有先看目录再操作?(不看就写,说明它在猜)
  3. 它改错了会不会自己发现?(把文件写到别处,看它是否检查结果)
  4. 它有没有权限边界?(能不能碰到 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 —— 未设置。没有它,链路③ 跑不通

注意它做了两件"多余"的事,这两件事恰好是新手最容易漏的:

  1. 不只看目录存不存在,还真的写一次文件——目录在但没权限,是极常见的坑;
  2. 不只 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 章 环境准备(一) · 返回导读