06.1 阶段 0:环境、语言基础与第一次模型调用
所属:全栈开发面试题库 / 学习路径 / 06 AI Agent
本页目录
一、阶段定位
本阶段是整条 AI Agent 路线的起点,解决一个问题:在本机把开发环境搭好,并真正向模型 API 发一次 HTTP 请求、拿到一段结构化的 JSON 回答。不涉及 Prompt 设计、不涉及工具调用、不涉及 RAG,目标是把"请求长什么样、响应里有哪些字段、报错怎么读"这三件事打到肌肉记忆里。
为什么必须先做这件事:后续所有阶段(采样参数、结构化输出、Function Calling、MCP、RAG、Agent)都是在同一个 chat completions 请求上叠加字段。如果连 messages 数组的结构、usage 字段的含义、429 报错的原文都不熟,后面每加一个概念都会被环境问题卡住,学习节奏会被打断。
与前后阶段的衔接:上接本篇的适用人群说明——无论你是零基础还是从 Java/Go 转来,这一阶段都要过一遍;往下接 阶段 1 LLM 基础与输出控制,那时你会知道 temperature、top_p、max_tokens 这些参数到底在调什么。本阶段只要求"能改参数、能看到输出变化",不要求理解原理。
本阶段的卡点(也是判断自己是否真的卡住的现象依据):
- 把 Key 硬编码进源码:现象是在
.py文件里直接写api_key="sk-...",或把含 Key 的文件提交到 Git,推送后仓库历史里永久留下密钥。判断标准:git log -p能搜到sk-开头的字符串,就算卡住。 - 分不清请求参数与返回字段:现象是看到响应 JSON 不知道
choices[0].message.content和usage.prompt_tokens在哪一层,改了temperature却看不到输出变化,因为改的位置不对。判断标准:能不看文档口述一次请求和响应的完整字段路径。 - 流式响应不会逐段读取:现象是开了
stream=True后拿到的是一堆字节或异常,不知道要按data:前缀切分、要处理data: [DONE]。判断标准:能把流式输出逐字打印出来。 - 网络与鉴权报错不会按状态码定位:现象是看到报错只说"调不通",不知道 401 是 Key 错、429 是限流、400 是请求体里某个字段不合规。判断标准:拿到一个报错能先说状态码再猜原因。
二、阶段目标与投入
学完本页,应当能用可观察的行为证明以下六条能力,而不是"装过环境":
| 能力目标(可验证的行为) | 验证方式 |
|---|---|
| 能用 venv 建独立环境,pip 安装包并导出锁定文件 | pip list 看到已装包,requirements.txt 可在新机器复现安装 |
| 能从环境变量读取 API Key,代码与仓库里搜不到明文 Key | 在代码仓库全局搜 sk- 无结果 |
| 能写出一次完整的 chat completions 请求并解析回答 | 打印出 choices[0].message.content 与 usage.total_tokens |
能切换 stream=True 并逐块接收 SSE 数据 |
终端看到文字逐个蹦出而不是一次性返回 |
| 能对 401、429、400 三类报错给出原因与处理方式 | 故意写错 Key 复现 401,能解释报错体里的 error.type |
能用 Git 管理项目,提交信息规范,.env 在 .gitignore 中 |
git status 干净,.env 不在跟踪列表里 |
建议学时:
- 全职(每天有效学习 4–6 小时):1 周,约 30 小时。其中环境与命令行 6 小时、请求与响应字段 10 小时、流式与错误处理 8 小时、Git 与复盘 6 小时。
- 在职(每天 2 小时、周末补 3 小时):2–3 周,约 30 小时。不要一天看完所有模块再动手,每个模块配一个可运行脚本。
学时分配建议:Python 环境与依赖 15%、密钥管理 10%、chat completions 请求与响应 30%、流式 SSE 20%、错误码与重试 15%、Git 与项目结构 10%。请求与响应字段是后面所有阶段的地基,时间给够。
三、先修自检
进入本阶段前,逐条自检;任何一条做不到,先补齐再继续。
| 先修项 | 合格标准 | 不合格时怎么办 |
|---|---|---|
| 命令行基础 | 能在终端 cd、看目录、用编辑器保存文件、区分相对路径与绝对路径 |
先练 1 小时命令行操作,再开始 |
| HTTP 与 JSON | 知道 GET/POST、请求头、状态码,能看懂一段 JSON 的层级 | 回到 01.2 计算机网络 补 HTTP 部分 |
| Python 基础语法 | 知道变量、函数、字典、列表、for 循环、import |
先补 Python 基础语法,再读本页 |
| 一个可用的模型账号 | 有任一兼容 OpenAI 协议的 API Key(云端模型或本地推理服务均可) | 先申请 Key 或起一个本地推理服务 |
| Git 基本操作 | 能 git init、git add、git commit,看懂 git status |
先练 30 分钟 Git 提交流程 |
另有一条经验判断:如果你写过其他后端语言,本阶段最容易犯的错是"把 SDK 当黑盒"——直接调高层封装函数,出错时看不到原始 HTTP 请求。建议前三次调用都用原始 HTTP 客户端(requests 或 httpx)手写请求体,把字段看清楚,再换 SDK。
四、知识地图
"掌握程度"分三档:了解(知道有这个东西)、会用(能写对、能调通)、能讲清原理(能解释字段含义与边界条件)。本阶段目标分布如下。
| 模块 | 知识点 | 掌握程度 | 对应题库章节 |
|---|---|---|---|
| Python 环境 | venv、pip、requirements.txt、依赖版本锁定 | 会用 | 10.1 LLM 基础 |
| 密钥管理 | API Key、环境变量、.env、.gitignore |
能讲清原理 | 10.1 LLM 基础 |
| chat completions | model、messages(role/content)、请求与响应字段路径 |
能讲清原理 | 10.1 LLM 基础 |
| 流式输出 | SSE、data: 前缀、[DONE]、stream_options |
会用 | 10.1 LLM 基础 |
| 错误与重试 | 401/429/400/500、error.type、指数退避、超时 |
会用 | 01.2 计算机网络 |
| Git 与项目结构 | .gitignore、提交信息、目录约定 |
会用 | 10.1 LLM 基础 |
进度管理建议:把这张表复制到自己的笔记里,每学完一个模块把"掌握程度"往下调一档;三档都到位再进阶段 1。《知识点全清单》是本篇更细的全量清单,与此表分工是"全量打勾"与"本阶段重点";术语定义查《术语表》,本页不重复展开。
五、分模块精讲
5.1 Python 环境与依赖管理
为什么需要它:LLM 生态的包更新极快(SDK、httpx、向量库、编排框架),用系统 Python 直接装会把包污染到全局,且不同项目之间版本冲突。venv 给每个项目一个独立的 Python 解释器和 site-packages,是隔离依赖的最低成本手段。
核心机制:
python -m venv .venv在当前目录建一个虚拟环境,目录名约定.venv(以点开头,默认不进 Git)。- 激活后终端提示符出现
(.venv),此时python、pip都指向环境内的副本。 pip install <pkg>装到环境内;pip freeze > requirements.txt把当前包及版本锁定为文本文件。- 复现环境用
pip install -r requirements.txt;更规范的依赖声明用pyproject.toml,本阶段先用 requirements 即可。 - 注意:venv 里的解释器路径是机器相关的,
.venv/目录本身绝不进 Git,只锁requirements.txt。
最小可运行示例:
# 在任意目录执行,全程使用相对路径
python -m venv .venv
# Windows PowerShell 激活:
# .venv\Scripts\Activate.ps1
# macOS / Linux 激活:
# source .venv/bin/activate
pip install --upgrade pip
pip install requests httpx python-dotenv
pip freeze > requirements.txt
cat requirements.txt
# check_env.py:确认解释器与已装包
import sys, requests, httpx
print("解释器路径:", sys.executable) # 应指向 .venv 内的 python
print("requests 版本:", requests.__version__)
print("httpx 版本:", httpx.__version__)
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
pip 装到全局目录,which python 不是 .venv 内的 |
没激活虚拟环境 | 先激活再操作;或直接用 .venv/bin/python(Windows: .venv\Scripts\python.exe)调用 |
Activate.ps1 报错"无法加载文件,因为在此系统上禁止运行脚本" |
PowerShell 执行策略限制 | 当前用户放宽:Set-ExecutionPolicy -Scope CurrentUser RemoteSigned |
requirements.txt 换台机器装不上 |
锁了平台相关的二进制包 | 用 pip install 重新生成;纯 Python 包跨平台无碍 |
面试考法:常见问法是"为什么要用虚拟环境,直接用全局 Python 不行吗"。要答到"全局环境会被不同项目拉到不同版本,且污染系统 Python;venv 通过独立 site-packages 实现隔离,requirements 锁版本保证可复现"。追问常落在"venv 和 conda 的区别",要点是 venv 只管 Python 包且随 Python 标准库自带,conda 连解释器版本和非 Python 依赖一起管。
5.2 API Key 与密钥管理
为什么需要它:API Key 是计费与鉴权凭证,泄漏后别人可以用你的额度跑模型。把 Key 写进代码或提交进 Git,是新手最常见的事故——哪怕仓库是私有的,CI 日志、编辑器同步、克隆副本都可能扩散。
核心机制:
- Key 应当从环境变量读取,代码里只写
os.environ["MODEL_API_KEY"]。 - 本地用
python-dotenv从项目根目录的.env文件加载,.env里每行KEY=value。 .env必须写进.gitignore;仓库里提供一个.env.example只放键名不放值。- 请求头
Authorization: Bearer $MODEL_API_KEY是 OpenAI 兼容协议的统一鉴权方式。 - 不同厂商的 base URL 不同(兼容协议通常通过
base_url参数切换),Key 与 base URL 成对管理。
最小可运行示例:
# .gitignore:项目根目录
.venv/
.env
__pycache__/
*.pyc
# .env.example:只放键名,进 Git,作为模板
MODEL_BASE_URL=https://api.example.com/v1
MODEL_API_KEY=sk-替换成你的key
MODEL_MODEL=gpt-4o-mini
# config.py:从环境变量读取,绝不硬编码
import os
from dotenv import load_dotenv
load_dotenv() # 从 .env 读取,不覆盖已有系统环境变量
BASE_URL = os.environ["MODEL_BASE_URL"].rstrip("/")
API_KEY = os.environ["MODEL_API_KEY"]
MODEL = os.environ.get("MODEL_MODEL", "gpt-4o-mini")
def auth_header() -> dict:
return {"Authorization": f"Bearer {API_KEY}"}
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
401 报错 invalid_api_key |
Key 写错、带了多余空格、或用了别的环境的 Key | 打印 Key 长度(不打印明文),检查首尾空格 |
.env 里的变量读不到 |
load_dotenv() 在工作目录不是项目根时找不到文件 |
用 load_dotenv(dotenv_path=...) 指定绝对路径(脚本内),或先切到项目根运行 |
| Key 已经提交进 Git 历史 | 之前 commit 过硬编码 | 立即到厂商控制台吊销旧 Key 生成新 Key;历史用 git filter-repo 清理 |
面试考法:问"Key 泄漏了怎么办"。答题要点:第一步到控制台吊销(rotate),因为代码清理追不上密钥扩散速度;第二步清理 Git 历史;第三步审查用量日志确认是否被盗刷。追问常问"为什么不能把 Key 放在前端",要点是前端代码会暴露给所有用户,Key 只能放在后端。
5.3 第一次 chat completions 请求
为什么需要它:这是整条路线的核心动作。所有高级能力(结构化输出、工具调用、多轮对话)都是在这个请求的 messages 和 tools 字段上扩展。必须把请求体和响应体的完整结构看明白。
核心机制:
- 端点是
POST {base_url}/chat/completions,请求体是 JSON。 - 请求体关键字段:
model(模型名)、messages(消息数组,每条含role与content)、temperature(采样温度,阶段 1 细讲)、max_tokens(单次回复最大 token 数)、stream(是否流式)。 messages中role有三种:system(设定行为,通常一条)、user(用户输入)、assistant(模型历史回复,多轮对话时回填)。- 响应体关键字段:
id(本次请求 ID)、choices数组,取choices[0],其下message.role、message.content、finish_reason(stop表示正常结束、length表示被max_tokens截断);usage下prompt_tokens、completion_tokens、total_tokens。 finish_reason是判断"回答为什么停了"的关键:stop是模型自己说完,length是被上限切断,tool_calls是要调工具(阶段 3 讲)。
最小可运行示例:
# first_call.py:用原始 httpx 手写请求,看清每个字段
import httpx
from config import BASE_URL, API_KEY, MODEL, auth_header
payload = {
"model": MODEL,
"messages": [
{"role": "system", "content": "你是一个简洁的助手,用中文回答。"},
{"role": "user", "content": "用一句话解释什么是 token。"},
],
"temperature": 0.2,
"max_tokens": 200,
}
resp = httpx.post(
f"{BASE_URL}/chat/completions",
headers=auth_header(),
json=payload,
timeout=30.0,
)
print("HTTP 状态码:", resp.status_code)
data = resp.json()
choice = data["choices"][0]
print("角色:", choice["message"]["role"])
print("回答:", choice["message"]["content"])
print("结束原因:", choice["finish_reason"])
print("用量:", data["usage"])
# 典型输出:
# HTTP 状态码: 200
# 角色: assistant
# 回答: token 是模型处理文本的最小单位,约等于一个常见词或词片断。
# 结束原因: stop
# 用量: {'prompt_tokens': 35, 'completion_tokens': 24, 'total_tokens': 59}
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
choices 数组为空、finish_reason 为 length |
max_tokens 设太小,话没说完就被截断 |
调大 max_tokens,或精简输入 |
400 报错 context_length_exceeded |
输入加输出超过模型上下文窗口 | 缩短输入,或在阶段 1 学截断策略 |
| 返回中文乱码 | 响应编码没按 UTF-8 读 | httpx 默认按响应头解码;确保 resp.json() 而非手动 resp.text |
改了 temperature 输出却没变化 |
改的是另一个请求体,或模型对该参数不敏感 | 确认请求体里确实带上了新值,多跑几次对比 |
面试考法:必问"一次 chat completions 请求里 messages 有哪几种 role,system 放第一条还是最后一条"。要答出三种 role、system 通常放第一条用于设定整体行为、多轮对话时按时间顺序回填 assistant 历史。追问常落在"finish_reason 有哪些取值,分别意味着什么",必须答出 stop/length/tool_calls。
5.4 流式响应与 SSE 读取
为什么需要它:长回答如果一次性等模型生成完再返回,用户要干等十几秒;流式(streaming)让文字逐块到达,首字延迟从"全部生成完"降到"第一个 token 出来"。这是 AI 应用体验的基础,也是阶段 6 服务化里 SSE 接口的底层。
核心机制:
- 请求体加
"stream": true,响应不再是一个完整 JSON,而是一串 Server-Sent Events(SSE)。 - 每行长这样:
data: {"choices":[{"delta":{"content":"你"}}]}\n\n;结束时发送data: [DONE]。 - 流式模式下增量在
choices[0].delta.content,而不是message.content;delta里还可能出现role、tool_calls的增量。 - 读取方式:按行迭代响应流,剥离
data:前缀,把剩余内容解析成 JSON;遇到data: [DONE]停止。 - 想在流式响应里拿到最终 token 用量,可加
stream_options: {"include_usage": true},最后一个 chunk 会带usage字段。
最小可运行示例:
# stream_call.py:逐块接收并打印
import json
import httpx
from config import BASE_URL, API_KEY, MODEL, auth_header
payload = {
"model": MODEL,
"messages": [{"role": "user", "content": "用三句话介绍向量数据库。"}],
"stream": True,
"stream_options": {"include_usage": True},
}
usage = None
with httpx.stream(
"POST",
f"{BASE_URL}/chat/completions",
headers=auth_header(),
json=payload,
timeout=60.0,
) as resp:
for line in resp.iter_lines():
if not line or not line.startswith("data: "):
continue
data_str = line[len("data: "):]
if data_str == "[DONE]":
break
chunk = json.loads(data_str)
delta = chunk["choices"][0]["delta"]
piece = delta.get("content")
if piece:
print(piece, end="", flush=True) # 逐字打印,不换行
if chunk.get("usage"):
usage = chunk["usage"]
print() # 结束换行
print("用量:", usage)
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
拿到一堆乱码或 Expecting value: line 1 column 1 |
直接把整个响应当 JSON 解析 | 按行读、剥离 data: 前缀再 json.loads |
| 流一直不结束 | 没判断 data: [DONE],或代理缓冲了响应 |
检查 iter_lines() 是否逐行到达;网关层要关闭缓冲 |
delta 里 content 偶尔是 None |
某些 chunk 只带 role 或 usage 增量 | 用 .get("content") 判空再拼接 |
| 首字延迟仍很长 | 客户端或网关做了缓冲 | 逐块 flush;服务化阶段用 SSE 时禁用反向代理缓冲 |
面试考法:问"流式和非流式在响应结构上有什么区别"。要点:非流式是 choices[0].message.content 一次性给出;流式是 choices[0].delta.content 增量,按 SSE 行推送,以 [DONE] 结束。追问常问"为什么流式能降低首字延迟",答到"不需要等全部 token 生成完,第一个 token 出来就开始推"。
5.5 错误码与重试基础
为什么需要它:模型 API 不是本地函数,它会限流、会抖动、会因为请求体不合规拒绝。不认识状态码就无法排查;盲目重试又会把限流打得更狠。本阶段建立"先看状态码、再看 error.type、最后决定是否重试"的条件反射。
核心机制:
401:鉴权失败,error.type通常是invalid_request_error,消息含Invalid API key。Key 错、过期、或没加 Bearer 前缀。400:请求体不合规,error.type可能是invalid_request_error,常见消息context_length_exceeded(输入超长)、messages结构不对。这类错误不要重试,改请求体。429:限流,error.type是rate_limit_exceeded(请求频率或 token 量超配额)。可重试,但要退避。500/503:服务端错误或过载,可重试。- 重试策略:指数退避(1s、2s、4s)加抖动,只对 429 与 5xx 重试,最多 2–3 次;设置超时(连接超时 5s、读取超时按任务设 30–60s)。
最小可运行示例:
# call_with_retry.py:带状态码判断与指数退避
import time
import httpx
from config import BASE_URL, API_KEY, MODEL, auth_header
def chat_once(user_text: str, max_retry: int = 3) -> str:
payload = {
"model": MODEL,
"messages": [{"role": "user", "content": user_text}],
"temperature": 0.2,
}
delay = 1.0
for attempt in range(max_retry):
try:
resp = httpx.post(
f"{BASE_URL}/chat/completions",
headers=auth_header(),
json=payload,
timeout=httpx.Timeout(connect=5.0, read=60.0),
)
except httpx.TransportError as e:
print(f"网络异常: {e},{delay}s 后重试")
time.sleep(delay)
delay *= 2
continue
if resp.status_code == 200:
return resp.json()["choices"][0]["message"]["content"]
err = resp.json().get("error", {})
print(f"HTTP {resp.status_code} type={err.get('type')} msg={err.get('message')}")
# 400 类错误不可重试,直接抛
if resp.status_code == 400:
raise RuntimeError(f"请求体错误: {err.get('message')}")
# 401 不可重试,Key 问题
if resp.status_code == 401:
raise RuntimeError("鉴权失败,检查 API Key")
# 429 与 5xx 退避重试
time.sleep(delay)
delay *= 2
raise RuntimeError("重试多次仍失败")
if __name__ == "__main__":
print(chat_once("用一句话解释指数退避。"))
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
报错 rate_limit_exceeded |
并发太高或超额 | 指数退避;降低并发;检查配额是否用尽 |
Invalid API key / 401 |
Key 错或没带 Bearer | 检查 Authorization: Bearer $KEY 格式 |
context_length_exceeded |
输入超长 | 缩短 messages,阶段 1 学截断 |
| 重试后 429 更严重 | 立即重试加剧限流 | 指数退避加随机抖动,退避间隔翻倍 |
| 请求长时间挂起无响应 | 没设读取超时 | 设 timeout=httpx.Timeout(connect=5, read=60) |
面试考法:问"429 和 500 分别要不要重试,为什么"。要答到"429 是限流,退避后重试;500/503 是服务端抖动,可重试;400 是请求体错,重试无用必须改请求;401 是鉴权错,重试无用"。追问常问"指数退避为什么要加抖动",答到"多个客户端同时失败会在同一时刻重试,形成同步脉冲,抖动把重试时间打散"。
5.6 Git 与项目结构
为什么需要它:Prompt、代码、配置都是要版本化的资产。没有 Git,改坏了回不去,也无法和别人协作。AI 项目还有个特殊点:Prompt 是会反复改的,Prompt 版本与代码版本必须能对应。
核心机制:
- 项目根目录放
.gitignore(.venv/、.env、__pycache__/、*.pyc)。 - 目录约定:
src/或直接平铺脚本,prompts/放提示词模板,.env.example放配置模板,README.md写如何安装与运行。 - 提交信息用约定式短描述(如"add: first streaming call"),不要一次提交包含无关改动。
- 不要提交模型产物、日志、缓存;这些进
.gitignore。
最小可运行示例:
# 项目初始化
git init
git add .gitignore .env.example README.md
git commit -m "chore: project scaffold and gitignore"
git add config.py first_call.py stream_call.py call_with_retry.py
git commit -m "feat: first chat completions call with streaming and retry"
git status # 应显示 working tree clean
<!-- README.md:最小可运行说明 -->
# 06.1 示例
1. python -m venv .venv 并激活
2. pip install -r requirements.txt
3. 复制 .env.example 为 .env,填入真实 Key
4. python first_call.py
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
.env 被提交了 |
.gitignore 写在文件已跟踪之后 |
先 git rm --cached .env 再提交,.gitignore 对已跟踪文件无效 |
| 提交历史里搜得到 Key | 之前 commit 过硬编码 | 吊销 Key,用 git filter-repo 清历史 |
__pycache__/ 反复出现 |
没忽略 Python 缓存 | .gitignore 加 __pycache__/ 与 *.pyc |
面试考法:问"AI 项目和普通后端项目在 Git 管理上有什么不同"。要点:Prompt 与配置要版本化、Key 绝不入库、模型产物与日志不入库、Prompt 版本要能和代码版本对应(阶段 2 展开)。
六、分层练习
三档练习逐档升级,上一档没做完不要跳。
6.1 复现型(照着做,目标是"跑通 + 能解释")
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 建 venv 并装包 | 建 .venv,装 requests/httpx/python-dotenv,导出 requirements |
新目录下 pip install -r requirements.txt 可复现 |
1 小时 |
| 手写一次请求 | 用 httpx.post 发 chat completions,打印回答与 usage |
能说出 prompt_tokens 与 completion_tokens 各是多少 |
1.5 小时 |
| 复现流式输出 | 改 stream=True,逐块打印 |
终端文字逐个出现,最终打印 usage | 1.5 小时 |
| 复现 401 | 故意把 Key 改错,看报错原文 | 能指出 error.type 与 Invalid API key 字样 |
0.5 小时 |
| 复现 429 | 短时间内连发 10 次请求触发限流 | 能贴出 rate_limit_exceeded 报错 |
1 小时 |
6.2 改造型(给出现成代码,改出正确行为)
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 把硬编码 Key 改为环境变量 | 给定一段写死 sk- 的脚本,改造 |
仓库全局搜 sk- 无结果 |
1 小时 |
| 给非流式调用加重试 | 给 5.5 的 chat_once 加 429/5xx 退避 |
断网后自动重试 3 次再抛错 | 1.5 小时 |
| 流式改为累计完整文本 | 把逐块打印改成拼接完整回答再返回 | 返回一个完整字符串,[DONE] 后停止 |
1 小时 |
加 stream_options 拿用量 |
流式结束后打印 total_tokens | 最终 usage 字段正确出现 | 0.5 小时 |
补 .gitignore 与 README |
给定乱提交的仓库,整理忽略规则 | git status 干净,README 可照跑 |
1 小时 |
6.3 设计型(自己定方案,目标是"能交付、能讲清取舍")
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 最小对话脚本 | 支持命令行连续输入多轮,把历史 messages 回填 | 能记住上一轮问题,退出不崩溃 | 3 小时 |
| 调用封装库 | 把鉴权、重试、超时封装成一个可复用函数,对外只暴露 chat() |
三个脚本复用同一封装,不重复写 Key 逻辑 | 3 小时 |
| 报错诊断工具 | 给定一个报错 JSON,输出"状态码/原因/是否可重试/建议动作"四列 | 对 401/400/429/500 各输出正确诊断 | 2 小时 |
七、排障表
| 现象 | 可能原因 | 排查步骤 | 解决办法 |
|---|---|---|---|
401 Unauthorized,error.message 含 Invalid API key |
Key 错、过期、或没加 Bearer |
打印 Key 长度;检查请求头拼写 | 检查 Authorization: Bearer $KEY;到控制台核对 Key |
429,error.type 为 rate_limit_exceeded |
频率或 token 量超配额 | 看响应头 retry-after;查控制台用量 |
指数退避重试;降并发;申请提额 |
400,context_length_exceeded |
输入加输出超上下文窗口 | 打印 usage.prompt_tokens 与模型上限 |
缩短输入;阶段 1 学截断与摘要 |
400,messages 结构错误 |
role 写错或 content 为空 | 打印请求体 JSON 逐条核对 | role 只能是 system/user/assistant;content 不能为 null |
流式输出报 Expecting value: line 1 column 1 |
把整个响应当 JSON 解析 | 打印每一行原始内容 | 按行读、剥 data: 、遇 [DONE] 停 |
| 请求长时间无响应 | 没设读取超时 | 用 curl 直接打接口测延迟 | 设 timeout=httpx.Timeout(connect=5, read=60) |
pip 装到全局而非 venv |
没激活环境 | which python 看路径 |
先激活 venv,或用 .venv 内解释器直接调用 |
.env 变量读不到 |
load_dotenv() 工作目录不对 |
在脚本里 print(os.getcwd()) |
用 load_dotenv(dotenv_path=...) 指定路径 |
八、出口条件
全部勾选后再进入 阶段 1 LLM 基础与输出控制。
- [ ] 能用 venv 建独立环境,
requirements.txt可在新机器复现安装 - [ ] 代码仓库全局搜不到明文 Key,
.env在.gitignore中 - [ ] 能不看文档口述一次 chat completions 请求的
model/messages结构与响应的choices[0].message.content、usage路径 - [ ] 能区分
finish_reason为stop与length的含义并解释 - [ ] 能开
stream=True逐块读取 SSE,正确处理data: [DONE] - [ ] 拿到 401/400/429/500 报错能先说状态码与
error.type,再决定是否重试 - [ ] 项目已纳入 Git,
git status干净,提交信息规范
自测题(先自己想,再看要点):
- 一次 chat completions 请求里,
system、user、assistant三种 role 分别放什么?多轮对话时 messages 怎么构造?- 要点:system 设定整体行为放第一条;user 是用户输入;assistant 回填模型上一轮回复;多轮按时间顺序交替追加。
- 响应里
choices[0].finish_reason为stop和length有什么区别?业务上分别意味着什么?- 要点:stop 是模型自己生成结束;length 是被 max_tokens 截断。length 出现时回答可能不完整,业务上要么调大上限要么精简输入。
- 流式响应里增量内容在
delta.content还是message.content?为什么?- 要点:流式是 delta,逐块推送;message 是一次性完整结果。两者结构不同,不能混用。
- 429 的
rate_limit_exceeded要不要立即重试?为什么?- 要点:不要立即重试,会加剧限流;用指数退避加抖动,间隔翻倍。
.env已经被提交进 Git,现在要怎么处理?- 要点:先到控制台吊销 Key(rotate),再
git rm --cached .env,用git filter-repo清历史,生成新 Key。
- 要点:先到控制台吊销 Key(rotate),再
stream_options: {"include_usage": true}的作用是什么?- 要点:让流式响应的最后一个 chunk 带上 usage 字段,否则流式模式默认不返回 token 用量。
- 为什么 400 类错误不能靠重试解决?
- 要点:400 是请求体不合规(字段错、超长、结构错),重试同样的请求体结果不变,必须改请求。