罗罗编程学习记录
本页内容 展开查看

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 干净,提交信息规范

自测题(先自己想,再看要点):

  1. 一次 chat completions 请求里,system、user、assistant 三种 role 分别放什么?多轮对话时 messages 怎么构造?
    • 要点:system 设定整体行为放第一条;user 是用户输入;assistant 回填模型上一轮回复;多轮按时间顺序交替追加。
  2. 响应里 choices[0].finish_reason 为 stop 和 length 有什么区别?业务上分别意味着什么?
    • 要点:stop 是模型自己生成结束;length 是被 max_tokens 截断。length 出现时回答可能不完整,业务上要么调大上限要么精简输入。
  3. 流式响应里增量内容在 delta.content 还是 message.content?为什么?
    • 要点:流式是 delta,逐块推送;message 是一次性完整结果。两者结构不同,不能混用。
  4. 429 的 rate_limit_exceeded 要不要立即重试?为什么?
    • 要点:不要立即重试,会加剧限流;用指数退避加抖动,间隔翻倍。
  5. .env 已经被提交进 Git,现在要怎么处理?
    • 要点:先到控制台吊销 Key(rotate),再 git rm --cached .env,用 git filter-repo 清历史,生成新 Key。
  6. stream_options: {"include_usage": true} 的作用是什么?
    • 要点:让流式响应的最后一个 chunk 带上 usage 字段,否则流式模式默认不返回 token 用量。
  7. 为什么 400 类错误不能靠重试解决?
    • 要点:400 是请求体不合规(字段错、超长、结构错),重试同样的请求体结果不变,必须改请求。