Arganzheng's Blog

Prompt 与上下文工程（01）：上下文的解剖——一次请求里模型看到的一切

Tue, 06 Oct 2026 00:00:00 +0800

L1 第一篇讲过：模型能可靠利用的上下文远小于它标称的长度，而且长上下文按 token 计费、线性拖慢 TTFT。这一篇从另一头看同一个问题：一次请求里模型到底看到了什么。多数工程师第一次把发给模型的完整请求体打印出来时都会吃惊——用户那句 20 个字的问题外面裹着两万 token 的 system prompt、工具定义、历史、检索结果与工具返回，而其中一半是上一步某个工具返回的原始 JSON。

要管理上下文，先要能解剖它。本篇建立一个七层模型：每层是什么、由谁维护、多大、变化多快、能不能压缩——后面五篇的每一种策略（预算、压缩、缓存、版本）都是对某几层的操作。实例用两个公开材料：Claude Code 文档里的”上下文窗口时间线”（一个会话从启动到压缩每一步进了什么），以及 Manus 公开的两个数字（一个任务约 50 次工具调用、输入输出 100 : 1）。

本篇要回答的核心问题是：

模型在这一步看到的上下文由哪几层组成，各由谁维护、多大、变化多快？¹ 一个 agent 会话的上下文是怎样长起来的，为什么不管理就一定漂移？² “注意力预算”有限这件事的机制是什么，对设计意味着什么？³

一、总览

1. 七层

层                    内容                                  变化频率    维护者
──────────────────────────────────────────────────────────────────────────
① 系统指令            角色 · 规则 · 输出格式 · 安全约束          发布时      开发者
② 工具与技能定义      name / description / schema · 技能描述行   发布时      开发者 / 平台
③ 长期记忆            CLAUDE.md / AGENTS.md · 偏好 · 跨会话事实   会话间      用户 / 运行时
④ 对话历史            此前每轮 user / assistant（含 tool_call）   每轮追加    运行时
⑤ 检索结果            本轮取回的片段                              每轮        运行时
⑥ 工具返回            上一步工具执行的结果（往往最大）              每步        运行时
⑦ 当前输入            用户这一轮的话 / 触发事件                   每轮        用户
──────────────────────────────────────────────────────────────────────────
↑ 稳定、可缓存、放前面                                 不稳定、每轮变、放后面 ↓

七层不是供应商 API 的字段（API 只有 system、messages、tools 三个位置），是应用侧的逻辑分层：①② 放在 API 的 system / tools 里，③ 通常拼进 system 末尾或第一条 user 消息，④⑤⑥⑦ 都在 messages 里。分层的价值在右边两列：变化频率决定缓存断点放哪（第五篇），维护者决定谁有权改、改了要跑什么评测（第六篇）；再加一列可压缩性（第四篇）——工具返回可以卸载到文件、历史可以摘要、系统指令不能动。

2. 本文的章节安排

第二章用 Claude Code 的时间线走一个真实会话；第三章逐层讲七层的性质；第四章讲 agent 会话的增长规律与漂移；第五章讲注意力预算的机制；第六章给出实践建议。

二、一个会话的时间线

Claude Code 的文档有一条交互式时间线，展示一个会话的上下文怎样填满。把它按七层重新标注：

一个 Claude Code 会话按七层标注的时间线
时刻	进入上下文的东西	层	量级	备注
启动，用户还没敲字	system prompt（含输出风格、`--append-system-prompt`）	①	几千 token	不在消息历史里，压缩不动它
	CLAUDE.md（项目根目录 + 用户级）	③	几百到几千	从磁盘读；压缩后重新注入
	自动记忆	③	≤ 200 行或 25 KB	有硬上限——这是一个预算决定
	MCP 工具名与技能描述	②	每个工具 / 技能几十到几百	工具的完整 schema 默认延迟加载，只有名字常驻
第一个 prompt	用户的话	⑦	几十
工作中，每读一个文件	文件内容作为工具返回	⑥	一个中等源文件 2–5K	十个文件就是几万
读到匹配路径的文件时	带 `paths:` 前置元数据的规则	③	几百	按需加载；压缩后丢失直到再读匹配文件
每次编辑后	PostToolUse hook 的输出	⑥	几十
需要研究一个问题	子 agent 在自己的窗口里读大量文件	—	主窗口只收到摘要 + 小段元数据	隔离是最有效的预算手段
窗口接近上限	`/compact` 或 auto-compact	④⑥ → 一段摘要	历史被替换	① 不变 ③ 的根目录部分重注入 ③ 的路径规则与子目录 CLAUDE.md 丢失

这条时间线说明三件事。第一，你敲第一个字之前已经花了几千到上万 token——①②③ 是常驻成本，每一轮都在传（缓存让它便宜，第五篇）。第二，增长的主体是 ⑥：几十次文件读取与命令输出，每一次几千 token，几十步之后占到窗口的大半。第三，压缩对各层不平等：① 完全不受影响，③ 的一部分靠”从磁盘重读”存活，④⑥ 被摘要替代，③ 的按需部分直接丢失——第四篇会把这张”压缩后的命运”表展开。

Claude Code 的两个硬数字值得记：自动记忆上限 200 行 / 25 KB，是对 ③ 的预算；auto-compact 在窗口约 83.5% 处触发、预留约 33K 给摘要生成，是对整体的预算（一个 200K 窗口的 16.5%）。这些不是随手选的——它们是”留多少给模型回答”与”多久压缩一次”的权衡结果，第四篇讨论。

%% 图：一个 Claude Code 会话的上下文怎样填满——启动时 ①②③ 已占几千到上万 token；每读一个文件 ⑥ 加 2–5K；子 agent 的大量读取在另一个窗口里、主窗口只收摘要；到约 83.5% 处 auto-compact 把 ④⑥ 换成一段摘要，① 不动、③ 的根目录部分重注入、按需部分丢失
flowchart TB
    S0["启动：还没敲字<br/>① system 几千 · ② 工具名与技能描述行 · ③ CLAUDE.md + 自动记忆（≤ 25 KB）<br/>≈ 5–15K token"]
    S0 --> S1["第一个 prompt<br/>⑦ 几十 token"]
    S1 --> S2["工作中：每读一个文件<br/>⑥ +2–5K；十个文件就是几万"]
    S2 --> S3["需要研究一个问题<br/>子 agent 在自己的窗口里读几十个文件<br/>主窗口只收到一段摘要"]
    S3 --> S2
    S2 --> S4{"窗口到 83.5%？<br/>（200K 窗口预留 33K 给摘要）"}
    S4 -->|"否"| S2
    S4 -->|"是"| S5["auto-compact<br/>④⑥ → 一段摘要"]
    S5 --> S6["压缩后的命运<br/>① 不变 · ③ 根目录 CLAUDE.md 从磁盘重注入 · ③ 带 paths: 的规则丢失 · ④⑥ 只剩摘要"]
    S6 --> S2
    classDef res fill:#eefaf0,stroke:#4d9a5c,color:#222
    classDef grow fill:#fff7e0,stroke:#c98a00,color:#222
    classDef dec fill:#eef6ff,stroke:#5b8fd6,color:#222
    classDef cmp fill:#fdecea,stroke:#c0392b,color:#222
    class S0,S1 res
    class S2,S3 grow
    class S4 dec
    class S5,S6 cmp

三、逐层的性质

1. 系统指令

开发者写的常驻文本：角色、任务、规则、输出格式、安全约束。性质：最稳定（随发布变）、最靠前（缓存前缀的头）、不可压缩（压缩不碰它）、每轮全量传（所以要精炼——不是短，是每一句都有用）。它是 prompt 工程传统意义上的对象，第二篇讲怎么写。一个常被忽略的事实：它在模型眼里只是上下文的一段，与 ⑥ 里的一句注入文字在同一个注意力空间里竞争（L1 第一篇第四章）。

2. 工具与技能定义

每个工具的名字、描述、参数 schema；每个技能的描述行。性质：稳定、靠前、按数量线性增长——几十个 MCP 工具的完整 schema 可以是几千到上万 token。两种应对：Claude Code 与 OpenAI 的 tool search 把完整 schema 延迟加载（常驻的只有名字或一行描述，模型需要时再取——代价是这些按需加载的内容不在缓存前缀里）；Agent Skills 标准把这个思路做成规范——SKILL.md 只有 description（≤ 1,024 字符）常驻，正文与脚本用到时才读。这叫渐进披露（progressive disclosure），是这一层的核心设计原则。

%% 图：渐进披露——常驻在上下文里的只是每个工具的名字和每个技能的一行描述（几十 token），完整的 schema 与 SKILL.md 正文放在外面，模型判断要用时再加载；30 个工具的完整定义从常驻的 9K 变成常驻 1K + 按需 300
flowchart LR
    subgraph RES["常驻层 ②：每轮都传、在缓存前缀里"]
        direction TB
        R1["工具名 + 一行描述 × 30<br/>≈ 1K token"]
        R2["技能 description × n<br/>每个 ≤ 1,024 字符"]
    end
    subgraph EXT["上下文之外：磁盘 / 注册表"]
        direction TB
        E1["30 个完整的参数 schema<br/>≈ 9K token"]
        E2["SKILL.md 正文 + 脚本<br/>几千到几万 token"]
    end
    R1 -.->|"模型决定用某个工具 → tool search 取回它的 schema（+300）"| E1
    R2 -.->|"模型决定用某个技能 → 读正文"| E2
    classDef res fill:#eefaf0,stroke:#4d9a5c,color:#222
    classDef ext fill:#f0f0f0,stroke:#888,color:#222
    class R1,R2 res
    class E1,E2 ext

3. 长期记忆

跨会话存活的东西：项目说明（CLAUDE.md、AGENTS.md）、用户偏好、运行时自动记下的事实。性质：会话间变化、由用户或运行时维护、通常有硬上限（Claude Code 的 25 KB）。它是一种特殊的检索——从磁盘或数据库取出来放进上下文——L4 的 memory 一篇讨论怎么写入与遗忘；本系列关心的是它占多少预算、放在哪、压缩后怎么恢复（从磁盘重读，所以它的”真身”不在上下文里而在文件里——这是第四篇”可恢复压缩”的雏形）。

4. 对话历史

之前每一轮的消息，包括模型发出的工具调用与思考块（L1 第三篇：思考块要原样保留）。性质：只追加（修改会破坏缓存与推理状态）、随轮数线性增长、可摘要——但摘要是有损的且要在思考链的边界做。它是多轮成本二次增长的来源（L1 第四篇），也是压缩的主要对象。

5. 检索结果

本轮从知识库、文件、网页取回的片段。性质：每轮变、由运行时组装、数量与顺序是设计决定——放几条、按相关性排、最相关的放末尾（位置效应）。L3 讲怎么取，本系列讲取回来之后占多少、放哪、要不要在下一轮保留（多数情况下不保留：上一轮的检索结果对这一轮多半是噪声，应清理）。

6. 工具返回

上一步工具执行的结果：文件内容、命令输出、API 响应、搜索结果、数据库行。性质：最大、最不可预测（一次 SQL 可能返回 200 行也可能 20 万行）、多数可恢复（文件还在磁盘上、URL 还能再访问）、时效短（模型读过一次、做了决定之后，原始内容对后续步骤价值急降）。这三条性质决定了第四篇的处理顺序：卸载（留路径不留内容）→ 清理（旧的删掉）→ 压缩（最后手段）。Deep Agents 的 20,000 token 卸载阈值、Anthropic API 的 clear_tool_uses，都是对这一层的。

7. 当前输入

用户这一轮说的话，或触发这一步的事件（定时、webhook、上一步的工具返回本身）。性质：最小、最靠后、最重要——它是这一步的任务。位置效应告诉我们它应该在末尾；Manus 的”复述”技巧（第四篇）本质上是把 ⑦ 的一个副本（当前目标）不断重新写到末尾。

四、agent 会话的增长规律

1. 两个数字

Manus 公开的生产统计：一个典型任务约 50 次工具调用，输入与输出 token 的比例约 100 : 1。第二个数字的含义是：agent 的成本几乎全在输入侧——每一步都把累积的上下文重新传一遍、prefill 一遍，而模型每步只产出几百 token 的决定。这与聊天产品（输入输出比例接近 1 : 1 到 10 : 1）完全不同，也是为什么 Manus 把 KV-cache 命中率列为第一指标（第五篇）。

2. 增长的形状

设常驻层（①②③）为 $S$，每步新增的工具返回平均 $r$、模型输出 $o$，第 $k$ 步的上下文约为 $S + (k-1)(r + o)$。$r$ 主导：一次文件读取 3K、一次命令输出 1K、一次网页 5K，取 $r = 3{,}000$、$o = 300$、$S = 15{,}000$，第 50 步是 $15{,}000 + 49 \times 3{,}300 \approx 177{,}000$ token——一个 200K 窗口在任务结束前就满了；即使 1M 窗口，L1 第一篇的有效长度问题在几万 token 就开始起作用。不管理的上下文在长任务上必然触顶或退化，这不是模型能力问题，是算术。

%% 图：上下文随步数线性增长——常驻 15K、每步工具返回 3K + 输出 300 时，第 50 步到 177K，一个 200K 窗口在 83.5%（167K）处约第 47 步触发压缩；把工具返回卸载到平均 800 后每步只长 1.1K，50 步 69K，整个任务不用压缩
%%{init: {"xyChart": {"width": 760, "height": 340, "plotReservedSpacePercent": 60}, "themeVariables": {"xyChart": {"plotColorPalette": "#c0392b, #5b8fd6, #888888"}}}}%%
xychart-beta
    title "第 k 步的上下文大小（千 token）：S = 15K，o = 300"
    x-axis "步数 k" [1, 10, 20, 30, 40, 50]
    y-axis "千 token" 0 --> 200
    line [15, 45, 78, 111, 144, 177]
    line [15, 25, 36, 47, 58, 69]
    line [167, 167, 167, 167, 167, 167]

红线 r = 3,000（不管理），蓝线 r = 800（工具返回卸载后），灰线是 200K 窗口的 auto-compact 触发线 167K。红线在第 47 步左右撞线；蓝线到任务结束还不到一半。

3. 漂移

增长带来第二个问题：原始任务漂到窗口中间。第 1 步时用户的目标在末尾（⑦），第 30 步时它前面有 ①②③、后面有 29 步的工具返回——正是 Lost in the Middle 里准确率最低的位置。Manus 的观察是模型开始”忘记”或”偏离”目标，他们的解法是让 agent 维护一个 todo.md 并在每步末尾重写它——把目标从中间搬回末尾。Anthropic 的博客把同样的现象归到”注意力预算”的耗尽。这就是为什么第四篇说压缩不只是省钱：它也是把目标拉回注意力焦点的手段。

%% 图：目标的漂移与复述——第 1 步时用户的目标在窗口末尾（注意力最好的位置）；第 30 步时它前面是常驻层、后面是 29 步的工具返回，正好落在 Lost in the Middle 的谷底；Manus 的解法是每步把 todo.md 重写到末尾，把目标的副本搬回焦点
flowchart TB
    subgraph K1["第 1 步"]
        direction LR
        A1["①②③ 常驻 15K"] --> A2["⑦ 用户目标 ← 在末尾，注意力最好"]
    end
    subgraph K30["第 30 步：不管理"]
        direction LR
        B1["①②③ 常驻 15K"] --> B2["⑦ 用户目标 ← 漂到中间，U 形的谷底"] --> B3["29 步的工具返回与输出 ≈ 96K"]
    end
    subgraph K30R["第 30 步：每步复述"]
        direction LR
        C1["①②③ 常驻 15K"] --> C2["原始目标（仍在中间）"] --> C3["29 步的工具返回…"] --> C4["todo.md：目标 + 已完成 / 待做 ← 重写到末尾"]
    end
    K1 ~~~ K30 ~~~ K30R
    classDef res fill:#eefaf0,stroke:#4d9a5c,color:#222
    classDef goal fill:#eef6ff,stroke:#5b8fd6,color:#222
    classDef bad fill:#fdecea,stroke:#c0392b,color:#222
    classDef grow fill:#fff7e0,stroke:#c98a00,color:#222
    class A1,B1,C1 res
    class A2,C4 goal
    class B2 bad
    class B3,C2,C3 grow

五、注意力预算

1. 机制

Transformer 的注意力对上下文里每一对 token 计算一个关系，$n$ 个 token 是 $n^2$ 对。模型在训练时见到的长序列远少于短序列，对”在几十万 token 里精确定位一条信息”的能力是外推出来的，不是训练充分的（共享《Transformer 与 LLM》系列讲位置编码与长度外推的机制）。Anthropic 的博客用一个比喻：每个新 token 都在消耗一份有限的”注意力预算”，上下文是有边际递减的资源，不是桶。

2. 实证

L1 第一篇引过的四项研究是这个约束的测量：Lost in the Middle（位置效应的 U 形）、RULER（多数模型在到达标称长度前跌破门限）、NoLiMa（非词面匹配时 32K 处 11/13 模型掉到基线一半以下）、Context Rot（18 个模型在极简任务上随长度不均匀退化）。它们共同说：上下文里每多一段无关内容，都在降低模型找到相关内容的概率，而且这个效应在远小于标称长度的位置就开始了。

3. 对设计的含义

每一段都要为它占的预算辩护。”放进去总没坏处”是错的：无关的检索结果、过期的工具返回、用不到的工具 schema 都在消耗预算。
相关的放末尾，稳定的放开头。两端是注意力最好的位置，也分别是”当前任务”与”缓存前缀”的位置——两个目标恰好一致。
隔离胜过压缩。子 agent 把探索性的大量读取放在另一个窗口里，主窗口只收摘要——这比事后压缩更省预算，因为噪声从未进来。
窗口变大不解除约束。1M 的窗口让你能放更多，不让模型能用更多；它改变的是压缩的触发点，不是预算的存在。

六、实践建议

打印一次完整请求体。选你的应用一个典型的第 10 步请求，把请求体存下来，按七层标注每一段、数 token。多数团队第一次做会发现 ⑥ 占了一半以上，① 里有一段早已无效的规则，③ 里有重复的内容。
画预算饼图并定上限。每一层给一个 token 上限（第四篇有参考值），超过上限的层就是下一步要处理的对象。
给工具返回做时效标记。在 trace 里记每个工具返回在后续几步里被模型引用过没有——多数在下一步之后就不再被引用，这是清理策略的依据。
检查目标的位置。在第 20 步的请求里找用户的原始任务在哪；如果在中间，考虑复述。
常驻层用渐进披露。工具的完整 schema、技能的正文、长文档的内容都不该常驻，常驻的是”它们存在、什么时候用”的一行描述。

七、本文小结

上下文有七层：系统指令、工具与技能定义、长期记忆、对话历史、检索结果、工具返回、当前输入；API 只有三个位置，分层是应用侧的逻辑模型，价值在变化频率、维护者、可压缩性三列。
Claude Code 的时间线：敲第一个字前已有几千到上万 token 的常驻层；增长主体是工具返回；压缩对各层不平等（system 不变、根目录 CLAUDE.md 重注入、路径规则丢失）；自动记忆上限 25 KB，auto-compact 在约 83.5% 处、预留 33K。
agent 会话约 50 次工具调用、输入输出 100 : 1，成本几乎全在输入侧；上下文按 $S + (k-1)(r+o)$ 增长，$r$ 主导，50 步就填满 200K；原始目标漂到中间是算术的必然。
注意力是 $n^2$ 的两两关系、长序列能力是外推的，预算有限且边际递减；每一段都要为占的预算辩护，相关的放末尾、稳定的放开头，隔离胜过压缩，窗口变大不解除约束。

八、自测

一个 agent 的请求体里有：system 4K、30 个 MCP 工具的完整 schema 9K、CLAUDE.md 2K、20 轮历史 40K、本轮检索 6K、上一步工具返回 25K、用户消息 0.1K。按七层标出哪一层最该先动、用什么手段。

答案

⑥ 工具返回 25K 最大且时效最短——先卸载（存文件留路径与预览）或在下一步后清理；其次 ② 9K 的完整 schema——改为渐进披露（tool search，常驻只留名字）；④ 40K 的历史是压缩的对象但代价最高，放在卸载与清理之后。①③⑤ 量级合理。详见第三章。
Claude Code 压缩后，为什么根目录的 CLAUDE.md 还在、而带 paths: 的规则不在了？这说明长期记忆层有什么性质？

答案

压缩把消息历史替换成摘要；根目录 CLAUDE.md 与自动记忆的”真身”在磁盘上，压缩后从磁盘重新注入；带 paths: 的规则是读到匹配文件时才加载的，压缩后要等再读匹配文件才回来。说明 ③ 的可恢复性来自它有一个上下文之外的持久存储——这是”可恢复压缩”的原型：上下文里只需要能找回内容的引用。详见第二章。
常驻层 12K，每步工具返回 4K、输出 300。200K 窗口、预留 33K 给输出时，大约第几步触发压缩？如果把工具返回卸载到平均 800，第几步？

答案

触发线 200K − 33K = 167K。$12{,}000 + (k-1) \times 4{,}300 \ge 167{,}000 \Rightarrow k - 1 \ge 36.05$，约第 38 步。卸载后每步 1,100：$(k-1) \ge 140.9$，约第 142 步。卸载让同一个任务多跑近四倍的步数才需要压缩。详见第四章。
为什么”1M 窗口的模型不需要做上下文管理”是错的？给两个独立的理由。

答案

（1）有效长度远小于标称：NoLiMa、RULER、Context Rot 表明模型在几万 token 处就开始退化，窗口大只让你能放、不让模型能用；（2）成本与延迟：输入按 token 计费、prefill 线性变慢，agent 的成本 100 : 1 在输入侧，且超过 272K / 200K 有加价门限（L1 第四篇）。窗口变大只改变压缩的触发点。详见第五章。
把工具完整 schema 改为按需加载（tool search）之后，缓存命中率反而下降了。为什么？

答案

常驻的完整 schema 虽然大，但稳定、在前缀里、每轮命中缓存；按需加载的 schema 在模型需要时才进入上下文，位置在历史中间、每次可能不同，这部分不在稳定前缀里。命中率下降是把”大而可缓存”换成了”小但不可缓存”——总输入 token 减少了，但命中率这个比例指标可能变差。要看的是绝对的未缓存 token 数与成本，不只是命中率。详见第三章。

七层：① 系统指令（开发者，发布时变，几千 token，不可压缩）；② 工具与技能定义（开发者 / 平台，发布时变，按数量线性增长，用渐进披露控制）；③ 长期记忆（用户 / 运行时，会话间变，通常有硬上限如 Claude Code 的 25 KB，真身在磁盘可重注入）；④ 对话历史（运行时，每轮追加，只追加不修改，可摘要）；⑤ 检索结果（运行时，每轮变，数量与顺序是设计决定，下一轮多半应清理）；⑥ 工具返回（运行时，每步变，最大最不可预测、多数可恢复、时效短）；⑦ 当前输入（用户，每轮，最小最重要，应在末尾）。稳定的在前可缓存，不稳定的在后。详见第一章、第三章。 ↩
敲第一个字前常驻层已占几千到上万 token；之后每步的工具返回（文件 3K、网页 5K）是增长主体，上下文按 $S + (k-1)(r+o)$ 线性增长，$r$ 主导；Manus 的统计是一个任务约 50 次工具调用、输入输出 100 : 1。取 $S = 15K$、$r + o = 3.3K$，第 50 步约 177K，200K 窗口在任务结束前填满。漂移是算术的必然：第 1 步目标在末尾，第 30 步它前有常驻层、后有 29 步返回，正落在 Lost in the Middle 准确率最低的中间位置——Manus 用每步重写 todo.md 把目标搬回末尾。详见第二章、第四章。 ↩
注意力对 $n$ 个 token 计算 $n^2$ 对关系，长序列能力是从训练分布外推的，所以每个新 token 消耗一份有限、边际递减的”注意力预算”（Anthropic 的说法）；实证是 Lost in the Middle、RULER、NoLiMa、Context Rot——退化在远小于标称长度处开始。设计含义：每一段要为占的预算辩护（无关内容降低找到相关内容的概率）；相关的放末尾、稳定的放开头（两端注意力最好，也分别是当前任务与缓存前缀的位置）；隔离（子 agent）胜过事后压缩；窗口变大只改变压缩触发点，不解除约束。详见第五章。 ↩

Prompt 与上下文工程：模型这一步该看到什么（总纲）

Mon, 05 Oct 2026 00:00:00 +0800

内容简介

《Prompt 与上下文工程：模型这一步该看到什么》是一组共六篇的系列文章，是《AI 应用工程师学习地图》第二层（L2）的正文。它接在 L1《模型作为组件》之后：L1 讲清了模型这个组件怎么失效、接口是什么、花多少钱；L2 讲你放进去的东西——模型在每一步看到的上下文由什么组成、怎么写、怎么约束它的输出、长了怎么办、怎么排列才能命中缓存、怎么像代码一样管理它。

“prompt 工程”这个词到 2026 年已经不够用。生产系统里模型每一步看到的不是一段 prompt，是一个由 system 指令、工具定义、技能说明、对话历史、检索结果、工具返回、记忆片段拼成的上下文，几万到几十万 token；一个 agent 任务平均要几十次模型调用，输入与输出 token 的比例接近 100 : 1（Manus 的公开数字）。决定每一步”模型看到什么、看多少、按什么顺序”，是一门有明确机制、有可测指标、有公开最佳实践的工程——Anthropic 把它叫 context engineering，定义是”在推理时为模型策划并维护最优 token 集合的一组策略”。本系列采用这个框架，但从应用工程师的角度写：每一项策略在 L1 的失效模式表上对付哪一条、在 L1 的账上换的是什么。

它回答的问题是：

模型这一步该看到什么、看多少、按什么顺序？怎么让输出可解析、可稳定？上下文长了怎么办？怎么排列才能让缓存命中？怎么像管代码一样管 prompt？¹

答案分六篇。第一篇建立上下文的解剖：一次请求里模型看到的一切分几层、各占多少 token、各由谁维护，用 Claude Code 公开的”上下文窗口时间线”与 Manus 的数字做实例，并说明为什么”注意力预算”是有限的（L1 第一篇的有效上下文问题在这里变成一个设计约束）。第二篇讲 prompt 设计里稳定的部分——模式——与不稳定的部分——措辞：2026 年推理模型上哪些经典技巧（few-shot、”一步步想”）失效甚至有害，公开的 system prompt（Anthropic 发布的 claude.ai system prompt、Claude Code 的 system prompt 结构）长什么样，供应商的模型专属 prompting 指南在说什么。第三篇深入结构化输出：约束解码的机制（Outlines、XGrammar、llguidance 一类在 vLLM 里的实现，四家 API 的 strict 模式），schema 的设计模式（推理字段在前、拒答出口、枚举收窄），失败的修复与重试，流式部分 JSON。第四篇讲上下文预算与压缩——本系列最重要的一篇：给每一部分定配额，超了先卸载（Deep Agents 的 20K token 卸载规则、Manus 的”文件系统即上下文”）、再清理工具结果（Anthropic API 的 context editing）、再压缩（Claude Code 在约 83.5% 处的 auto-compact 与它保留什么、Codex 的两级压缩与服务端加密的 /responses/compact、Anthropic 服务端 compaction 的 150K 默认阈值），用子 agent 隔离探索性上下文，用 todo 文件”复述”目标防止漂移。第五篇讲 prompt caching 与上下文的排列：Anthropic 的显式断点怎么分层放、OpenAI 与 DeepSeek 的自动前缀缓存要什么条件、Gemini 的显式缓存对象与存储费；Manus 的三条规则——前缀稳定、只追加、确定性序列化——以及”屏蔽工具而不是删除工具”这类反直觉的做法；命中率作为生产 agent 的第一指标。第六篇讲 prompt 当代码管：放版本库还是 prompt 注册表（Langfuse 的版本与标签、OpenAI 在 Assistants API 关闭后的 Prompts 对象、promptfoo），与模型版本绑定，每次改动跑评测集，用标签做 A/B 与回滚；AGENTS.md 与 SKILL.md 这两个 2025–2026 年成为跨工具标准的 prompt 工件；最后回答”全放上下文、检索、还是 agentic retrieval”的决策，把话题交给 L3。

系列的组织原则：每一项上下文策略都是在 L1 的失效模式与账之间做交换。压缩用一次推理的成本换有效上下文；缓存用前缀的稳定性换 90% 的输入折价；结构化输出用 schema 的约束换解析的确定性；few-shot 用 token 换遵循率。六篇的每一篇都把新引入的手段记回 L1 的两张表。

为什么写这个系列？

“写好 prompt”已经不是问题的主体

2023 年的 AI 应用工程有一大半是在措辞上做实验：加一句”你是一个专家”、加几个例子、加”一步步想”。2026 年，这些技巧的收益大部分被模型吸收了——推理模型自己会想，指令遵循强到”说清楚就行”，而且供应商的 prompting 指南开始告诉你不要做什么（对推理模型不要再加 CoT 指令，不要过度 few-shot）。措辞的边际收益在下降，同时另一件事的成本在上升：一个 agent 的上下文每一步都在增长，几十步之后原始任务漂到窗口中间、工具返回占了 90% 的 token、缓存因为一个时间戳而全部失效。Anthropic 在 2025 年 9 月的工程博客里把这个转变说得很直接：”构建 LLM 应用越来越不是找对措辞，而是回答’什么样的上下文配置最可能产生想要的行为’。”

机制已经公开，而且相当具体

这是写这个系列的好时机：几个最成熟的 agent 产品把自己的上下文策略公开了，带着数字。Claude Code 的文档有一条交互式时间线，展示一个会话从启动到压缩每一步进了什么、花了多少；它的 auto-compact 在窗口约 83.5% 处触发（预留 33K 给摘要），压缩后 CLAUDE.md 与自动记忆从磁盘重新注入、按路径作用的规则丢失。Codex 的压缩先查会话记忆能否替代摘要、不能才调服务端的 /responses/compact 得到一个只有 OpenAI 能解密的 blob，触发点在轮前与循环边界两处。Manus 公开了四次重写 agent 框架得到的六条经验，第一条是”KV-cache 命中率是生产 agent 最重要的单一指标”。LangChain 的 Deep Agents 公开了卸载阈值：工具返回超过 20,000 token 写文件并留 10 行预览，上下文过 85% 时把旧的写入调用截成指针。Anthropic 的 API 把三种机制做成了一等功能：服务端 compaction（默认 150K 触发）、context editing（清理旧工具结果）、memory tool。这些不再是各家的秘密，是可以对照着讲的公开工程。

现有材料的断层

prompt 工程教程停在措辞层面，多数写于推理模型之前，其中一部分建议在 2026 年的模型上是反效果的；
供应商的 prompting 指南是模型专属的（GPT-5 的 prompting guide、Claude Sonnet 5 的 prompting 页），互相不通用，也不讲上下文管理；
agent 框架文档把压缩、卸载、缓存断点做成几个参数，不解释阈值为什么是那个数、不同策略怎么组合、什么时候互斥；
工程博客（Anthropic、Manus、Claude Code 文档、Codex 的分析文章）各讲自己的系统，没有人把它们放在一张表上比较，也没有人把它们接回”这在对付哪条失效、在账上换什么”。

本系列想填补的是从”会写 system prompt”到”能为一个几十步的 agent 设计上下文策略、解释它每一步的 token 从哪来、命中率为什么是这个数、压缩后丢了什么”之间的那段路。

适合哪些读者？

读完 L1、准备做第一个上下文超过一屏的应用的工程师

你知道模型会失效、知道 token 怎么计费；现在要决定 system prompt 写什么、检索结果放哪、历史留几轮。本系列给你一张预算表与一套排列规则。

已经在做 agent、被上下文问题困扰的工程师

任务跑到第 30 步开始忘目标、账单里 90% 是重复传输的工具返回、缓存命中率只有 20%——第四、五篇直接对付这些。

想读懂 Claude Code / Codex / Manus 上下文策略的开发者

第一、四、五篇用它们公开的机制与数字做主线实例，并放在一张表上比较。

平台工程师

要为团队提供 prompt 注册表、评测门禁、缓存监控——第六篇讲这些工件与流程。

系列的整体主线

六篇的主题与建立的东西
篇	主题	建立的东西	对付 L1 的哪条失效	在 L1 的账上换什么
1	上下文的解剖	一次请求的分层与 token 构成；注意力预算	上下文标称 ≠ 有效	建立预算的基线
2	prompt 设计	稳定的模式 vs 不稳定的措辞 2026 年的失效技巧公开 system prompt 的结构	指令遵循与 prompt 敏感	token 换遵循率
3	结构化输出	约束解码机制 schema 设计模式修复与重试	指令遵循（格式）、幻觉（拒答出口）	schema 的 token 换解析确定性
4	预算与压缩	配额表卸载 → 清理 → 压缩的顺序子 agent 隔离复述	上下文标称 ≠ 有效；越界（目标漂移）	一次推理的成本换有效上下文
5	缓存与排列	前缀分层三条规则屏蔽而非删除命中率指标	—（纯账）	前缀稳定性换 90% 输入折价与 TTFT
6	prompt 当代码管	版本、标签、评测门禁、A/B AGENTS.md / SKILL.md 上下文 vs 检索的决策	供应商变更、prompt 敏感	评测成本换回归保护

三条贯穿的线：

上下文是有限资源，不是桶。 注意力对 token 是 $n^2$ 的两两关系，每加一个 token 都在消耗一份有限的”注意力预算”；L1 第一篇的 Context Rot 数据是这个约束的实证。所以每一篇的问题都是”这一段值不值得占这份预算”。
顺序即成本。 稳定的放前面、动态的放后面，这一条同时决定缓存命中率（第五篇）、压缩后什么能存活（第四篇）、模型对指令的注意（第一篇的位置效应）。
prompt 是代码。 有版本、有测试、有发布流程、有回滚；改一个词就是一次发布，模型升级就是一次依赖升级。

章节结构与分章导读

1. 上下文的解剖：一次请求里模型看到的一切

核心问题：模型在这一步看到的上下文由哪几层组成？各占多少 token、由谁维护、什么时候变？为什么”注意力预算”是有限的？²

从一个具体实例开始：Claude Code 一个会话在你敲第一个字之前上下文里已经有什么（system prompt、CLAUDE.md、自动记忆——上限 200 行或 25 KB、MCP 工具名、技能描述），每读一个文件加多少，按路径作用的规则何时加载，子 agent 怎样把大段读取隔离在自己的窗口里，压缩时每一类内容的命运。然后抽象成七层：系统指令、工具与技能定义、长期记忆、对话历史、检索结果、工具返回、当前输入——每层的维护者不同（开发者、平台、用户、运行时），变化频率不同（决定第五篇的缓存分层），可压缩性不同（决定第四篇的策略）。最后是预算的物理基础：注意力的 $n^2$ 与 Context Rot 的实证，以及 Manus 的两个数字——一个任务约 50 次工具调用、输入输出 100 : 1——为什么意味着”不管理的上下文必然让目标漂到窗口中间”。

2. prompt 设计：稳定的模式与不稳定的措辞

核心问题：哪些 prompt 技巧在 2026 年的模型上仍然有效、哪些已经失效甚至有害？公开的 system prompt 长什么样？为什么 prompt 要当代码不当文案？³

先分层：模式（角色与任务的明确陈述、把规则写成可检验的条款、用结构标记分区、给出输出格式、说明工具何时用）是稳定的；措辞（具体的句子、例子的选择、语气）是不稳定的——换模型要重调，供应商为每个新模型发 prompting 指南就是证据。然后逐条审视经典技巧：few-shot 在推理模型上何时仍有用（格式与风格）、何时有害（Manus 的经验：模型会模仿例子的模式陷入重复，要引入结构化的变化）；”一步步想”对推理模型是冗余的，OpenAI 与 Anthropic 都建议去掉；负面指令为什么低效、正面替代怎么写；对推理模型的 effort 与 prompt 的关系。用公开材料做实例：Anthropic 发布的 claude.ai 各版本 system prompt（它的结构、它怎样处理知识截止与拒答）、Claude Code system prompt 的分区（语气、工具使用政策、安全约束）、OpenAI 的 GPT-5 prompting guide 里”agentic eagerness”与”tool preamble”两个概念。最后是边界：prompt injection 不是 prompt 设计能解决的（L6）。

3. 结构化输出：约束解码、schema 设计与失败修复

核心问题：约束解码在推理引擎里是怎么实现的？为什么 strict 模式对 schema 有限制？schema 该怎么设计才既可靠又不损害推理？解析失败了怎么修？⁴

L1 第二篇讲了结构化输出的三个层次与”保证语法不保证语义”。这一篇深入：约束解码把 JSON schema 编译成状态机（正则 / 上下文无关文法），每一步采样时把不合法 token 的概率置零——Outlines、XGrammar、llguidance 一类库在 vLLM 与 SGLang 里的实现，四家 API 的 strict 模式为什么要求 additionalProperties: false、所有字段 required、不支持部分 schema 特性（编译成本与状态空间），首次使用一个 schema 的编译延迟与缓存。schema 设计模式：推理字段排在结论前（字段顺序即生成顺序）、显式的拒答 / 不确定出口、枚举替代自由字符串、避免深层可选嵌套、数组长度上限；”直接输出严格格式损害推理”的证据与推理模型对它的缓解。解析层：Pydantic / zod / instructor 一类的角色，业务校验，失败的修复（把校验错误放回上下文重试一次），流式部分 JSON 的增量解析，stop_reason 为 max_tokens 时的处理。格式遵循率作为独立指标。

4. 上下文预算与压缩：给每一部分定配额，超了怎么办

核心问题：怎样给上下文的每一层定 token 配额？超了先做什么、再做什么？压缩会丢什么、怎么知道丢了什么？子 agent 与 todo 文件各解决什么？⁵

预算表：system 与工具定义、记忆、历史、检索、工具返回、预留给输出的余量（Claude Code 预留约 33K，即窗口的 16.5%）各占多少，按任务类型给三档参考。然后是一条处理顺序，代价从低到高：（1）不让它进来——卸载：Deep Agents 的规则是工具返回超过 20,000 token 就写到文件系统、上下文里只留路径加前 10 行预览；Manus 的”文件系统即上下文”——可恢复的压缩（保留 URL、保留路径，内容随时能再读）；（2）清理——Anthropic API 的 context editing 按策略清掉旧的工具返回（clear_tool_uses），Deep Agents 在 85% 时把旧的写入调用截成指针；（3）压缩——用一次模型调用把历史摘要成一段：Claude Code 在约 83.5% 处 auto-compact，压缩后 system prompt 不变、根目录 CLAUDE.md 与自动记忆从磁盘重注入、按路径的规则与子目录 CLAUDE.md 丢失；Codex 先试”会话记忆压缩”（用已结构化的任务状态替代摘要，多数情况不调模型），不够再调 /responses/compact 得到加密 blob，触发点在轮前与循环边界；Anthropic 服务端 compaction 默认 150K 触发（最低 50K），可替换默认的摘要 prompt；DeepSeek Harness 的 SDK 把压缩策略做成可显式配置的”语义检查点”。（4）隔离——子 agent 在自己的窗口里做探索，只把摘要带回。（5）复述——Manus 的 todo.md：把目标写在上下文末尾并不断更新，对抗”目标漂到中间”。压缩与推理状态的关系（L1 第三篇：只能在思考链结束处做），以及怎么评测压缩——用”压缩前后模型能否回答同一组问题”探测什么存活了。一张表比较五个系统的阈值与策略。

5. prompt caching 与上下文的排列

核心问题：四家的缓存各要什么条件？断点怎么分层放？为什么”屏蔽工具”比”删除工具”好？命中率低于多少要查什么？⁶

L1 第四篇算了缓存的账（读 0.1×、写 1.25×、读一次回本）。这一篇讲怎样让它命中。机制回顾：缓存的是前缀的 KV，逐字节相同才命中，顺序 tools → system → messages。四家的条件：Anthropic 显式 cache_control（最多 4 个断点、20 块回看、5 分钟 / 1 小时 TTL）或顶层自动；OpenAI 自动（1,024 起、128 倍数、GPT-5.6 起断点在最近一条可缓存消息末尾）；Gemini 隐式加显式缓存对象（按小时存储费，适合长文档反复问答）；DeepSeek 自动磁盘缓存（64 token 粒度）。分层放断点：静态（system、工具定义）→ 半静态（few-shot、用户画像）→ 动态（历史）→ 当前轮，各放一个断点，变化频率低的在前。Manus 的三条规则：前缀稳定（一个时间戳毁掉全部）、只追加（不修改历史、序列化要确定性——JSON 键序一变就失效）、显式标断点。反直觉的一条：动态增删工具会破坏前缀，Manus 的做法是保留全部工具定义、用 logits 屏蔽（自托管）或 tool_choice 约束（API）控制可用性；OpenAI / Anthropic 的 tool search 是另一条路——定义按需加载，代价是它们本身不在前缀里。命中率的监控与排查表：低于 50% 查动态内容、查历史修改、查间隔超 TTL、查工具集变化。与压缩的配合：压缩必然失效一次，之后以短前缀重建。

6. prompt 当代码管：版本、评测、A/B，以及上下文 vs 检索

核心问题：prompt 放版本库还是注册表？怎么与模型版本绑定？改一个词要跑什么？AGENTS.md 与 SKILL.md 是什么、怎么写？什么时候全放上下文、什么时候检索？⁷

工件：prompt 在版本库里（与代码同步发布、代码审查、diff 可见）还是在注册表里（Langfuse 的不可变版本加可移动标签——production / staging / prod-a，运行时按标签取，改 prompt 不用重新部署；OpenAI 在 Assistants API 关闭后把 Assistants 的”指令 + 工具”束改成只能在控制台创建的 Prompts 对象并建议把 id 放进源码）；两种做法的取舍与混合。流程：每个 prompt 版本绑定模型版本与参数（effort、max_tokens）；改动即发布——跑评测集（L1 第五篇的评测集，L5 的方法）、看格式遵循率与任务指标、灰度、可回滚；A/B 用标签随机分流并把 trace 绑到版本。两个跨工具的 prompt 工件：AGENTS.md（2025 年 8 月发布的开放格式，六万多个开源项目采用，2025 年 11 月起由 Linux 基金会下的 Agentic AI Foundation 管理——项目的常驻指令：结构、命令、硬规则）与 SKILL.md（Anthropic 2025 年 10 月发布、12 月开放为标准，name ≤ 64 字符、description ≤ 1,024 字符，四十多个客户端支持，.agents/skills/ 成为中立目录——按需加载的技能，只有描述常驻、正文用到时才进上下文，这正是第四章”渐进披露”的实例）；它们的写法与陷阱（Claude Code 读 CLAUDE.md 不原生读 AGENTS.md、路径不统一）。最后的决策表：全放上下文（小而稳定的资料 + 缓存）、流水线检索（大语料、高并发问答）、agentic retrieval（复杂任务、模型自己决定查什么）——按语料大小、变化频率、查询类型、缓存后的成本四个维度选，交给 L3。

7. 系列总结与通关自测

一张总表回顾六篇各自回答的问题与必记的数字，逐篇的核心结论与常见误解，贯穿全系列的几条线，然后是三段自测——判断与计算、跨篇综合、面试题——加一份”读过 / 掌握 / 能教人”的判据。

贯穿全系列的实践线

本系列不设配套实验。每篇末尾有一节实践建议：

各篇实践建议的内容
篇	实践建议的内容
1	打印你的应用一次典型请求的完整上下文，按七层标出 token 数，画出预算饼图
2	把 system prompt 的每条规则改写成可检验的条款，删掉对推理模型冗余的 CoT 指令，为每条规则写一个评测用例
3	给每个结构化输出的 schema 加拒答出口与推理字段，测格式遵循率与业务校验通过率
4	为你的 agent 定卸载阈值、清理策略与压缩触发点，用”压缩前后问同一组问题”测存活率
5	审计前缀：找出动态内容、非确定性序列化、工具集变动；把命中率上仪表盘，目标 > 70%
6	把 prompt 从代码里挪到有版本的位置，与模型版本绑定，接上评测门禁；给项目写一份 AGENTS.md

前置要求与说明

前置要求

L1《模型作为组件》六篇——本系列大量引用它的失效模式表、契约细节与成本公式，不重复推导；
调过任何一家的 API，写过至少一个 system prompt。

版本与事实基线

以 2026 年 9 月的公开材料为准：

本系列的版本与事实基线
来源	内容
Anthropic	《Effective context engineering for AI agents》（2025-09） API 的 compaction / context editing / memory tool 文档 claude.ai 各版本的公开 system prompt Claude Code 文档的上下文窗口时间线与 auto-compact 参数 Agent Skills 规范（agentskills.io，2025-12 开放）
OpenAI	GPT-5 prompting guide Responses API 的 Prompts 对象与 Assistants 迁移指南（2026-08-26 关闭） `/v1/responses/compact` 的公开分析
Codex CLI	开源仓库中压缩策略的公开分析（2026-03 / 04）
Manus	《Context Engineering for AI Agents: Lessons from Building Manus》（2025-07）
LangChain Deep Agents	公开的卸载与截断阈值
DeepSeek Harness	v0.1 developer preview（2026-08-13）的 SDK 文档中的压缩配置
AGENTS.md	开放格式（2025-08）与 Agentic AI Foundation（2025-11）
研究	Lost in the Middle、Context Rot、NoLiMa（L1 已引） Let Me Speak Freely?（2024） Outlines / XGrammar / llguidance 的论文与实现

各家的阈值与默认值会变，文中引用时标注来源与日期；读者应以自己读到本文时的文档为准。价格沿用 L1 第四篇的 2026 年 9 月价目。

章节目录

最终目标

读完本系列，面对一个要放进模型的上下文，读者应该能够：

读完系列后应能回答的追问
追问	答案来自
这一步模型看到的几万 token 是什么构成的？哪一层最大？	第一篇
这条 prompt 技巧在 2026 年的推理模型上还有用吗？	第二篇
这个 schema 会把拒答伪装成答案吗？推理字段放对了吗？	第三篇
工具返回 50K token，该卸载、清理还是压缩？压缩后 CLAUDE.md 还在吗？	第四篇
命中率 30%，是哪一层在破坏前缀？	第五篇
改了 system prompt 的一个词，上线前要做什么？	第六篇
这份资料该全放、检索还是让 agent 自己查？	第六篇 → L3

这就是 L2 要建立的能力：把”模型看到什么”当作一个有预算、有顺序、有版本的工程对象来设计，而不是一段文案。

六篇各答一问。看什么、多少、什么顺序：上下文分七层（系统指令、工具定义、长期记忆、对话历史、检索结果、工具返回、当前输入），各有维护者、变化频率与 token 配额，注意力预算有限（第一篇）。可解析、可稳定：prompt 的模式稳定、措辞不稳定，推理模型上 few-shot 与「一步步想」要重新审视（第二篇）；结构化输出靠约束解码（schema 编译成状态机屏蔽非法 token），schema 设计让推理字段在前、留拒答出口，解析失败把错误放回去修一次（第三篇）。上下文长了：先卸载（工具返回 > 20K token 写文件只留路径）、再清理（旧工具返回）、再压缩（Claude Code 在 83.5% 处 auto-compact），子 agent 隔离、todo 文件复述（第四篇）。缓存命中：前缀稳定、只追加、工具屏蔽不删除，静态 → 半静态 → 动态分层放断点，命中率低先查时间戳与序列化（第五篇）。像代码一样管：版本库或注册表 + 与模型版本绑定 + 改一个词就跑评测集，AGENTS.md / SKILL.md 是跨工具的 prompt 工件，全放上下文还是检索按体量与变化频率定（第六篇）。 ↩
七层：系统指令、工具与技能定义、长期记忆、对话历史、检索结果、工具返回、当前输入。各占多少以 Claude Code 为实例：敲第一个字之前已有 system prompt、CLAUDE.md、自动记忆（上限 200 行 / 25 KB）、MCP 工具名与技能描述——通常上万 token；每读一个文件按文件大小加，按路径作用的规则在进入目录时加载，子 agent 把大段读取隔离在自己的窗口。维护者不同：系统指令与工具定义由开发者 / 平台维护、记忆由用户与运行时、历史与工具返回由运行时逐轮追加、检索结果由检索层；变化频率从几乎不变（system、工具）到每轮都变（当前输入、工具返回）——这决定缓存怎么分层，可压缩性决定超预算时先动谁。注意力预算有限的物理基础：attention 的 $n^2$ 代价与 Context Rot 的实证（有效上下文远小于标称），加上 Manus 的两个数字——一个任务约 50 次工具调用、输入输出 100 : 1——不管理的上下文必然让目标漂出窗口。 ↩
仍有效的是模式：角色与任务的明确陈述、把规则写成可检验条款、用结构标记分区、给出输出格式、说明工具何时用；失效或有害的：「一步步想」对推理模型是冗余（OpenAI 与 Anthropic 都建议去掉），few-shot 只在格式与风格上有用、在推理模型上会让模型模仿例子的模式陷入重复（Manus 的经验：要引入结构化变化），负面指令低效要换成正面替代，威胁 / 奖励式的措辞无效。公开的 system prompt 长什么样：Anthropic 发布的 claude.ai system prompt 按分区组织（身份与语气、知识截止与拒答的处理、格式规则、安全条款），Claude Code 的 system prompt 分区为语气、工具使用政策、安全、环境信息——都是结构化条款而不是一段文案。prompt 要当代码不当文案，是因为它决定系统行为、换模型要重调、一个词的改动能让格式遵循率变化几个点——所以要进版本库、做 diff、绑定模型版本、每次改动跑评测集（第六篇）。 ↩
实现：把 JSON schema 编译成状态机（正则或上下文无关文法），每一步采样时按当前状态把不合法 token 的 logits 置为 −∞——Outlines、XGrammar、llguidance 在 vLLM / SGLang 里的 logits processor 就是这样做的；首次使用一个 schema 有编译延迟，之后缓存。strict 模式对 schema 有限制（additionalProperties: false、所有字段 required、不支持部分特性如复杂 anyOf / 递归 / 格式约束），因为状态空间与编译成本要可控、且每个 token 的掩码要能快速算出。schema 设计：推理字段排在结论字段之前（字段顺序即生成顺序，让模型先想再答）、显式的拒答 / 不确定出口、枚举替代自由字符串、避免深层可选嵌套、数组长度上限；「直接输出严格格式损害推理」有证据，推理模型的 thinking 阶段缓解了它。解析失败的修复：Pydantic / zod / instructor 做结构与业务校验，失败时把校验错误放回上下文重试一次（不是盲目重试），仍失败走降级路径并记录为 bad case。 ↩
配额：按任务类型给 system 与工具定义、记忆、历史、检索、工具返回各一个上限，并预留输出余量（Claude Code 预留约 33K，即窗口的 16.5%），三档参考随任务复杂度调整。超了按代价从低到高处理：（1）卸载——不让它进来：工具返回超过 20,000 token 就写到文件系统、上下文只留路径加前 10 行预览（Deep Agents 的规则）、「文件系统即上下文」的可恢复压缩（保留 URL 与路径）；（2）清理——按策略清掉旧工具返回（Anthropic 的 clear_tool_uses，Deep Agents 在 85% 时把旧写入调用截成指针）；（3）压缩——用一次模型调用把历史摘要成一段（Claude Code 在约 83.5% 处 auto-compact，压缩后 system prompt 不变、CLAUDE.md 与自动记忆从磁盘重注入）。压缩会丢的：中间推理、被覆盖的决定、细节数字、文件的精确内容；知道丢了什么靠压缩前后的 diff 日志、把关键事实写进文件而不是只留在历史里、以及评测集里的长任务用例。子 agent 解决隔离（大段读取在自己的窗口、只回结果），todo 文件解决复述（把目标与进度反复写回上下文末尾，对抗目标漂移）。 ↩
条件：Anthropic 显式 cache_control（最多 4 个断点、20 块回看、5 分钟 / 1 小时 TTL）或顶层自动；OpenAI 自动（1,024 token 起、128 的倍数，GPT-5.6 起断点在最近一条可缓存消息末尾）；Gemini 隐式缓存加显式缓存对象（按小时收存储费，适合长文档反复问答）；DeepSeek 自动磁盘缓存（64 token 粒度）。共同前提：缓存的是前缀的 KV，逐字节相同才命中，顺序 tools → system → messages。断点分层：静态（system、工具定义）→ 半静态（few-shot、用户画像）→ 动态（历史）→ 当前轮，变化频率低的在前、各放一个断点。「屏蔽工具」比「删除工具」好，是因为工具定义在前缀最前面，删一个工具就改变了前缀、之后全部失配；用 logits 屏蔽或在 system 里声明不可用则前缀不变、缓存照常命中。命中率低于预期（如 < 70%）要查：前缀里有没有时间戳 / 请求 id 一类每次都变的东西、序列化是否确定（JSON 键序）、历史是否被修改而不是只追加、断点是否放在会变的内容之后、TTL 是否过期（调用间隔 > 5 分钟）。 ↩
版本库：与代码同步发布、代码审查、diff 可见，适合 prompt 与代码耦合紧的场景；注册表（Langfuse 的不可变版本 + 可移动标签 production / staging，运行时按标签取，改 prompt 不用重新部署）适合非工程角色频繁调整、多环境切换；OpenAI 的 Prompts 对象是托管版注册表。常见做法是混合：源码里放 id / 标签，内容在注册表，CI 把两边对齐。与模型绑定：每个 prompt 版本记录模型快照、effort、max_tokens 等参数，换任一项都算新版本。改一个词要跑：评测集（格式遵循率与任务指标）、成本与延迟对比、灰度与可回滚；A/B 用标签随机分流并把 trace 绑到版本。AGENTS.md：2025 年 8 月发布的开放格式、Linux 基金会下 Agentic AI Foundation 管理——项目的常驻指令（结构、构建 / 测试命令、约定、禁忌），写成可检验的条款、短、按目录分层；SKILL.md：按需加载的技能说明（何时用、怎么用、示例），正文只放触发条件与步骤，细节放附属文件。全放上下文 vs 检索：材料总量稳定在几万 token 以内且每次都要用 → 全放（配合缓存）；体量大、只用一小部分、经常变 → 检索 / 工具按需取。 ↩

模型作为组件（07）：系列总结与通关自测

Sun, 04 Oct 2026 20:00:00 +0800

六篇正文回答了一个问题：把大模型当作系统里的一个组件，它的规格书是什么。第一篇写它的失效模式，第二、三篇写它的接口（含推理模型的新维度），第四篇算它的账，第五篇讲怎么在几十个候选里选，第六篇讲调用它的客户端要处理什么。六篇合起来，是《AI 应用工程师学习地图》第一层的全部内容——组件观：模型是一个非确定性、会编造、按 token 计费、有上下文上限、供应商会换掉的组件，后面六层的每一种工程手段都是对它某一条性质的应对。

本文不讲新内容，做三件事：把六篇压成一张表与六段回顾，把贯穿六篇的几条线拎出来，然后给一套三段式的通关自测——判断与计算、跨篇综合、面试题。各篇末尾的自测检验的是”这一篇读懂了没有”，这里检验的是”六篇能不能连起来用”。

读完这六篇，你应该能回答哪些问题？¹ 哪些数字与结论必须能脱口而出？² 怎么判断自己是”读过”还是”掌握”了？³

先把整个系列放在一张图上——箭头是推导或前置上的依赖（箭头尾端的结论被箭头头端当作前提），不是阅读顺序：

%%{init: {"flowchart": {"wrappingWidth": 170}}}%%
%% 图：模型作为组件全景：给一个没有规格书的组件写规格书——失效、契约、账、选型、客户端
flowchart TB
    C1["01 失效模式<br/>七条可检测的性质"] --> C2["02 API 契约（一）<br/>消息、工具、结构化输出、流式"]
    C2 --> C3["03 API 契约（二）<br/>推理模型：thinking、effort、跨轮状态"]
    C2 & C3 --> C4["04 成本与延迟的账<br/>四种输入价、TTFT 分解"]
    C1 & C4 --> C5["05 选型<br/>榜单失真、自己的评测集、弃用周期"]
    C1 & C2 & C4 --> C6["06 客户端工程<br/>重试、超时、幂等、限流、流式解析"]

一、总览：系列回答的问题与主线

系列的一句话主张是：模型 API 没有供应商替你写的规格书，应用工程师要自己写——失效模式、契约、账、选型判据、客户端纪律，五部分缺一不可。

五篇的核心问题、结论与必记
篇	回答的问题	一句话结论	必记的数字 / 结论
第一篇：失效模式	模型这个组件以哪些方式失效？	七条固有性质：非确定性、幻觉、指令遵循与 prompt 敏感、上下文标称 ≠ 有效、知识截止、供应商侧变更、越界；每条对应后面某一层的应对	batch 不变性缺失（1000 次贪心 18 种结果 → 1 种） NoLiMa 32K 处 11/13 模型掉到基线一半以下，GPT-4o 99.3% → 69.7% Air Canada 812.02 加元 PocketOS 9 秒删库 OpenAI 约 700 个 agent 入侵 Hugging Face
第二篇：API 契约（一）	四家 API 的共同骨架是什么？	块列表进、块列表出工具调用是协议不是功能（校验、权限、执行、配对、截断在应用侧）结构化输出保证语法不保证语义服务端状态默认存储	Responses 默认 `store: true` 30 天 Conversation 无 TTL OpenAI `arguments` 是字符串、Anthropic `input` 是对象缓存顺序 tools → system → messages Assistants API 2026-08-26 关闭
第三篇：API 契约（二）	推理模型给契约加了什么维度？	思考按输出价计费、占 TTFT、`max_tokens` 含它 effort 是倾向不是预算，选档靠三条曲线思考是跨轮状态，只搬运不读写编辑历史与跨模型 fallback 受约束	Sonnet 5 同任务 `low` → `high` 账单 $0.0075 → $0.0445（6 倍） Fable 5.1 校验 thinking block 之前的历史 Chat Completions 自 GPT-5.4 起不支持带 effort 的工具调用 DeepSeek 的 `reasoning_content` 不能送回
第四篇：成本与延迟	一次调用花多少钱、慢在哪一段？	五项成本公式缓存读一次回本多轮不缓存二次增长、缓存后约 15% TTFT = 排队 + prefill + 思考，总时长由输出 × TPOT 主导	价目跨三个量级（$10 → $0.15 → 读 $0.003）输出价 = 输入价 × 4–6 读价 0.1×（Fable 5.1 0.025×、DeepSeek 0.02×）写 1.25×（1 小时 2×） OpenAI >272K 输入 2× 输出 1.5× DeepSeek 峰时 ×2 Batch 50%
第五篇：选型	怎么在二十几个候选里选？	榜单只缩范围选型用自己的评测集（30–50 条起）闭源 vs 自托管是运营问题级联分流不漏难题弃用周期是选型维度	Llama 4 前 27 个私测变体两家各约 20% Arena 数据 vs 83 个开源模型 29.7% 大小模型价差 5–20 倍 70% 简单请求级联省 63% OpenAI 3–6 个月通知、Anthropic ≥ 1 年、DeepSeek 4 天
第六篇：客户端工程	调用侧要处理哪些失败？	错误分四类只重试”再试可能不同”的四层超时幂等问题在工具上限流按 RPM / TPM 与层级发前数 token 熔断 + 分层 fallback	full jitter $t_n = \min(t_{\max}, \text{random}(0, t_0 2^n))$ 重试预算 10% 超过一分钟的生成一律流式 Sonnet 5 同文本多 30% token 中文每字 1–2 token

1. 本文的章节安排

本文的章节安排
章	内容
二	逐篇回顾：核心问题、结论、必记、常见误解
三	贯穿六篇的四条线：失效 → 应对层、契约的成本含义、对变更免疫、按分布与按任务
四	常见误区表
五	通关自测：A 判断与计算 10 题、B 跨篇综合 5 题、C 面试题 7 题、D 掌握判据
六	下一步

二、逐篇回顾

1. 第一篇：失效模式——把”模型会出错”拆成七条可检测的性质

核心问题：同一输入两次结果不同、temperature = 0 也不行，为什么？模型什么时候编造？标称 1M 为什么不能当 1M 用？能执行动作时失效变成什么？

结论：七条失效模式各有机制、证据、检测手段与应对层。非确定性有采样与 batch 不变性两层，公开 API 无法复现，评测按分布、调试靠录制回放。幻觉是”高概率续写 ≠ 真”，代价从律师罚款升级到公司为机器人的话承担法律责任（Air Canada、哈姆法院、慕尼黑法院）。上下文的有效长度远小于标称（Lost in the Middle、RULER、NoLiMa、Context Rot 结论一致）。供应商会在不改名的情况下换权重、改默认值、换 tokenizer、下线模型。能执行动作时，错误上限由权限范围决定（PocketOS、Replit、OpenAI–Hugging Face）。

必记：失效模式 → 应对层的对应表；”源材料正确输出仍可能错”（哈姆判决）；”遇到障碍 → 绕过计划 → 有权限 → 无确认 → 不可逆”五步结构。

常见误解：把非确定性当万能解释（每次都错且错法一致不是非确定性）；把 system prompt 当访问控制；以为下一代模型会消除这些失效（只会改变程度）。

2. 第二篇：API 契约（一）——消息、工具调用、结构化输出与流式

核心问题：四家 API 的共同骨架与差异？工具调用往返的哪些步骤是应用的责任？结构化输出保证什么？流式与状态的默认值有什么坑？

结论：骨架趋同（块列表、三类角色、JSON schema 工具、SSE 流式），坑在默认值。工具调用六步里模型只做”决定”与”读结果”，校验、权限、执行、id 配对、截断、循环控制在应用侧，工具结果是不可信输入。结构化输出的约束解码是硬保证但只保证形状，schema 要留拒答出口。流式：文本按增量拼、工具参数是分片字符串等 done 再解析、用量在末尾、中断只能重发。Responses / Interactions 默认存储，不省输入 token 的钱，绑定供应商。

必记：store: true 30 天；Conversation 无 TTL；Fable 5.1 强制工具调用报错；2026 年的契约变更清单；中间层的五个职责（归一化消息 / 工具 / 流式事件 / 用量、记录原始请求响应）。

常见误解：以为服务端状态省钱；以为 strict 模式消除了幻觉；在收到第一个流式片段时就解析工具参数；用 tool_choice 强制工具当结构化输出。

3. 第三篇：API 契约（二）——推理模型

核心问题：思考在 API 上是什么、怎么计费？effort 控制什么、怎么选档？thinking block 为什么原样送回？对缓存有什么影响？

结论：思考是可见输出之前生成的 token，按输出价计费、占 TTFT、max_tokens 含它；四家可见性不同但都不适合作为可解释性依据。effort 是倾向，同任务 low 到 high 账单可差 6 倍，选档靠评测集上质量 / 成本 / 延迟三条曲线，简单任务高档可能更差。思考是跨轮内部状态（Anthropic 签名块、OpenAI 加密 reasoning item、Gemini thought signature；DeepSeek 无状态不能送回），约束了编辑历史（Fable 5.1 校验块之前的历史）与 fallback 方向（新模型的块旧模型读不了）。思考 token 不进缓存，历史里的思考块进缓存前缀。

必记：三条曲线；”历史只追加”；压缩只在思考链结束后做；迁移三件事（重跑 effort 扫描、重设 max_tokens、检查历史编辑逻辑）。

常见误解：effort 越高越好；把摘要的思考当作审计依据；从 Sonnet 4.6 改名到 Sonnet 5 就算迁移完成。

4. 第四篇：成本与延迟的账

核心问题：成本公式与四家价目？缓存写入为什么收费、何时划算？多轮为什么二次增长？TTFT 与 TPOT 由什么决定？

结论：$C = n_{\text{in}} p_{\text{in}} + n_{\text{hit}} p_{\text{hit}} + n_{\text{write}} p_{\text{write}} + (n_{\text{out}} + n_{\text{think}}) p_{\text{out}}$，每项都在 usage 里。缓存的是逐字节相同前缀的 KV，写 1.25× 读 0.1×，读一次回本；不足最小长度静默不缓存。$N$ 轮不缓存的输入总量 $NS + N(N-1)m/2$，缓存把二次项系数乘 0.1，总量约 15%，前提是历史只追加、间隔 < TTL、前缀无动态内容。折价（Batch / Flex 50%、峰谷）与加价（长上下文、Fast mode、区域）。TTFT = 排队 + prefill（∝ 未缓存输入）+ 思考；总时长由输出 × TPOT 主导，TPOT 由模型大小决定。

必记：价目表；1.35× vs 2× 的收支平衡；590K → 87.8K 的多轮示例；”输入长度影响 TTFT、输出长度影响总时长、模型大小影响 TPOT”；比较模型用每任务成本的分布。

常见误解：把四类 token 合成一个数；在 system 开头写当前时间；用每 token 价比较模型；以为长上下文加价只对超出部分生效。

5. 第五篇：选型

核心问题：为什么不能按榜单选？评测集多大、怎么用？闭源 vs 自托管、大小分流怎么判？弃用周期怎样进入选型？

结论：Arena 有私测选择性披露（27 个变体）、采样不对称、对 Arena 分布过拟合三个失真机制；静态 benchmark 有污染与饱和；供应商自报分数条件不一——榜单只缩范围。评测集 30–50 条从真实流量采，每模型 × effort 档跑多次，看质量 / 每任务成本 / 延迟三列。闭源 vs 自托管是运营问题（数据出域、规模是否高且稳定、控制需求、Infra 能力）。级联 $c_s + (1-f) c_l$ 只比路由贵一点却不漏难题。弃用周期（OpenAI 3–6 个月、Anthropic ≥ 1 年、DeepSeek 4 天）、快照可钉性、替代路径、多云进入选型；模型名进配置，替代模型每月热身。

必记：选型的四个问题与流程图；评测表的五列；自托管的低价是满载数字；换 embedding 模型 = 重建索引。

常见误解：两个模型 40 条各跑一次差 2 条就下结论；用同一组用例既调 prompt 又选模型；以为开源模型能力差一代（V4.1 Flash MIT 开放）。

6. 第六篇：客户端工程

核心问题：错误有哪几类、哪些重试？超时为什么四层、流式中断怎么办？限流的维度与层级？为什么发前数 token？

结论：可重试（429 / 5xx / 529 / 网络 / 超时）、修正后重试一次（工具格式错、校验失败、截断）、不可重试（400 / 401 / 配额 / 内容过滤 / 404）、需人工；200 也可能是失败。指数退避 + full jitter，Retry-After 优先，重试预算 10%。四层超时；超过一分钟的生成一律流式；更长任务换后台形态。幂等问题在工具上，按 tool_call_id 去重。限流按 RPM / TPM 与层级，客户端令牌桶按 token 扣。流式解析的六个坑（心跳、分桶、等 done、断开传播、背压、中断状态）。发前数 token 避免超限；计数随模型变、中文更贵。熔断 + 分层 fallback。

必记：错误分类表；每次重试都是付费调用；客户端断开不传播则供应商继续计费；峰值 TPM 的算法（QPS × 60 × 每请求 token）。

常见误解：只读状态码不读响应体；用重试绕内容过滤；只设一个总超时；等 429 再退避。

三、贯穿全系列的几条线

1. 每条失效对应一种应对，应对在后面的层

第一篇的七条失效是整个应用地图的索引。非确定性 → L5 评测按分布、录制回放；幻觉 → L3 检索与引用、L5 guardrails、L7 引用的呈现；指令遵循 → L2 上下文工程、L5 回归；上下文 → L2 预算与压缩、L3 检索；知识截止 → L3、L4 工具；供应商变更 → L5 回归、L6 发布与网关；越界 → L4 权限与沙箱、L6 安全。读后面六个系列时，每一种手段都应该能回答”它在对付第一篇的哪一条”。

%% 图：七条失效模式各由后面哪一层对付——这张图是整个应用地图的索引：左列是第一篇的七条失效，右列是 L2–L7 六个系列，每条边是一种具体手段
flowchart LR
    F1["① 非确定性"] --> L5["L5 评测与可观测<br/>按分布评 · 录制回放 · 回归门禁 · guardrails"]
    F2["② 幻觉"] --> L3["L3 检索与知识<br/>给材料 · 要引用"]
    F2 --> L5
    F2 --> L7["L7 产品与体验<br/>引用的呈现 · 不确定性的表达"]
    F3["③ 指令遵循 / prompt 敏感"] --> L2["L2 上下文工程<br/>prompt 当代码 · 预算 · 压缩"]
    F3 --> L5
    F4["④ 上下文标称 ≠ 有效"] --> L2
    F4 --> L3
    F5["⑤ 知识截止"] --> L3
    F5 --> L4["L4 Agent 与 harness<br/>工具 · 权限 · 沙箱 · 运行时"]
    F6["⑥ 供应商变更"] --> L5
    F6 --> L6["L6 生产与运维<br/>网关 · 发布 · 安全"]
    F7["⑦ 越界"] --> L4
    F7 --> L6
    classDef fail fill:#fdecea,stroke:#c0392b,color:#222
    classDef layer fill:#eefaf0,stroke:#4d9a5c,color:#222
    class F1,F2,F3,F4,F5,F6,F7 fail
    class L2,L3,L4,L5,L6,L7 layer

2. 契约的每一项都有成本含义

第二、三篇的契约与第四篇的账是一张表的两面：消息的排列决定缓存能否命中（tools → system → messages 的顺序，动态内容放后面）；工具定义占 token 且在前缀里；结构化输出注入的 schema 算 token；effort 决定思考 token；服务端状态不省输入的钱；思考块进历史后成为可缓存的输入。学契约时同时问”这一项在账上是哪一格”，是这个系列的方法。

%% 图：契约的每一项在账上的位置：effort 决定思考 token 进成本与 TTFT，前缀顺序决定缓存命中率，上下文长度与轮数决定 prefill 成本
flowchart TB
    E["effort 档（第三篇）"] -->|"决定"| TH["思考 token 数"]
    TH -->|"× 输出价"| COST["每次调用成本（第四篇）"]
    TH -->|"× TPOT"| TTFT["TTFT"]
    ORD["前缀顺序与稳定性（第二篇）<br/>tools → system → messages"] -->|"决定"| HIT["缓存命中率"]
    HIT -->|"读 0.1× vs 全价"| COST
    HIT -->|"命中则跳过 prefill"| TTFT
    HIST["历史只追加（第三篇）"] -->|"破坏则失效"| HIT
    LEN["上下文长度（第一篇有效长度 · 第四篇加价门限）"] -->|"prefill ∝ 长度 · >272K / 200K 加价"| COST
    LEN --> TTFT
    N["对话轮数 N"] -->|"不缓存 ∝ N²，缓存 ∝ 0.1 N²"| COST

    classDef q fill:#fff7e0,stroke:#c98a00,stroke-width:2px,color:#222
    classDef r fill:#eef6ff,stroke:#5b8fd6,color:#222
    class E,ORD,HIST,LEN,N q
    class TH,HIT,COST,TTFT r

3. 供应商会变，应用要对变化免疫

2026 年内四家都发生过”没改代码但行为变了”：Sonnet 5 的默认 thinking 与新 tokenizer、Fable 5.1 的历史校验与强制工具报错、Assistants API 关闭、Interactions 的 outputs → steps、DeepSeek 把 V4-Pro 路由到 V4.1 Flash、OpenAI 三批下线二十多个快照。对变化免疫的手段贯穿五篇：钉住快照（第一篇）、中间层把差异收在一处（第二篇）、迁移三件事（第三篇）、模型名进配置与替代模型热身（第五篇）、熔断与 fallback 链（第六篇）——以及所有这些的探测器：评测集。

%% 图：对供应商变化免疫的五道手段与它们共同的探测器——钉快照、中间层、迁移三件事、配置化的模型名与热身的替代模型、熔断与 fallback，每一道都在某一篇里；变化能不能被提前发现，只取决于评测集
flowchart LR
    V["供应商变更<br/>权重 · 默认值 · tokenizer · 契约 · 下线 · 路由"] --> D["探测器：评测集<br/>通知当天在新模型上跑全量"]
    D --> H1["钉住快照（第一篇）"]
    D --> H2["中间层收拢差异（第二篇）"]
    D --> H3["迁移三件事：重跑 effort · 查 max_tokens · 查历史编辑（第三篇）"]
    D --> H4["模型名进配置 · 替代模型每月热身（第五篇）"]
    D --> H5["熔断 · fallback 链 · 灰度切换（第六篇）"]
    classDef bad fill:#fdecea,stroke:#c0392b,color:#222
    classDef det fill:#eef6ff,stroke:#5b8fd6,color:#222
    classDef ok fill:#eefaf0,stroke:#4d9a5c,color:#222
    class V bad
    class D det
    class H1,H2,H3,H4,H5 ok

4. 按分布，按任务

两个单位的转换是这个系列的思维习惯。按分布不按单次：非确定性让单次结果没有意义，评测每题跑 $k$ 次看通过率与方差（第一、五篇），延迟看 p50 / p99（第四篇），每任务成本看 p50 / p95（第四篇）。按任务不按 token：价目是每 token 的，产品关心每任务的；一个便宜的模型多走几步或完成率低，每任务可能更贵（第四、五篇）；effort 的选择也是按任务（第三篇）。

5. 概念表

贯穿五篇的概念表
概念	出处	一句话
batch 不变性	第一篇	kernel 在不同 batch 大小下数值路径不同；公开 API 因此不可复现
有效上下文长度	第一篇	模型能可靠利用的长度，远小于标称；用自己的资料做针测
工具调用往返	第二篇	决定 → 校验 / 权限 / 执行 → 配对送回 → 循环；模型只做决定与读结果
约束解码	第二篇	schema 编译为自动机，不合法 token 概率置零；保证形状不保证语义
服务端状态	第二篇	`previous_response_id` / `previous_interaction_id` 默认存储不省 token 费绑定供应商
effort	第三篇	思考深度的倾向参数；选档靠三条曲线
推理状态	第三篇	thinking block / reasoning item / thought signature 只搬运不读写历史只追加
缓存前缀	第四篇	逐字节相同前缀的 KV tools → system → messages 写 1.25× 读 0.1×
二次增长	第四篇	$N$ 轮不缓存的输入 $NS + N(N-1)m/2$；缓存乘 0.1
TTFT / TPOT	第四篇	排队 + prefill + 思考 / 每 token 时间；输入长度 → TTFT，输出长度 → 总时长，模型大小 → TPOT
选择偏差（榜单）	第五篇	多测选最好即使同一 checkpoint 也抬分
级联	第五篇	先小后大，$c_s + (1-f) c_l$，不漏难题
弃用周期	第五篇	通知期、快照可钉性、替代路径、多云
重试预算	第六篇	重试不超过总量的比例；防雪崩也防账单
四层超时	第六篇	连接 / 首事件 / 事件间 / 总

四、常见误区

常见误区与正确说法
误区	为什么错	出处
“temperature = 0 加 seed 就能复现”	公开 API 的 batch 大小随负载变，kernel 不 batch 不变；只能自托管做到	第一篇
“源材料没错，机器人就不会说错”	幻觉是高概率续写不是转述；哈姆法院案里源材料正确、输出编造、诊所仍负责	第一篇
“标称 1M 就能放 1M”	NoLiMa 32K 处 11/13 模型掉到基线一半以下；且 >272K / 200K 加价	第一、四篇
“system prompt 是权限更高的通道”	它只是上下文里一段被标记的文本，与工具返回里的注入竞争	第一、二篇
“用了 strict 模式就不会有错误输出”	只保证 schema 形状值可以编造拒答会被伪装成答案	第二篇
“服务端状态省 token 钱”	每轮模型仍读完整上下文，输入照样计费；只改变谁传历史	第二篇
“把模型名从 4.6 改成 5 就迁移完了”	thinking 默认开启、采样参数 400、tokenizer 多 30%、`max_tokens` 含思考	第一、三、六篇
“effort 越高越好”	简单任务高档可能更差（过度思考）账单差 6 倍三条曲线取饱和最低档	第三篇
“缓存写入加价所以缓存不划算”	写 1.25× + 读 0.1× = 1.35× < 2×，读一次回本；只有前缀只用一次时不划算	第四篇
“长上下文加价只对超出部分”	OpenAI 对整个请求生效：300K 输入全部 2×	第四篇
“Arena 第一就是最好”	私测选择性披露、采样不对称、对 Arena 分布过拟合；只用来缩范围	第五篇
“自托管每百万 $0.8 比 API 便宜”	满载数字利用率 30% 时翻三倍还有 Infra 团队成本	第五篇
“路由比级联省钱所以用路由”	只省 2–3 个百分点却会漏难题；级联不漏	第五篇
“429 了就重试”	`insufficient_quota` 也是 429，不可重试；重试要有预算	第六篇
“一个总超时就够”	短了误杀长回答，长了对卡死连接等太久；要四层	第六篇
“用户关了页面请求就结束了”	不传播到上游则供应商继续生成并计费	第六篇

五、通关自测

A. 判断与计算（10 题）

判断：在 Anthropic 的 Messages API 上把 temperature 设为 0，同一请求多次调用可以得到逐字节相同的输出。

答案

错。两个原因：Claude Sonnet 5 起非默认的 temperature 直接返回 400；即使在允许的模型上，推理端点的 batch 大小随负载变化、kernel 不具备 batch 不变性，输出仍可能不同。逐字节复现只能在自托管上用 batch 不变 kernel 或固定 batch = 1 做到。
计算：Claude Opus 5（$5 / $25，读 $0.50，5 分钟写 $6.25）上一个请求：system 6,000 token 命中缓存，新增输入 800，思考 3,000，回答 500。成本多少？思考占多少？

答案

6,000 × 0.5 + 800 × 5 + 3,500 × 25 = 3,000 + 4,000 + 87,500 = 94,500 微美元 ≈ $0.0945。思考 3,000 × 25 = 75,000，占 79.4%。
判断：OpenAI 对缓存写入收 1.25×，所以一个前缀至少要被读两次才比不缓存划算。

答案

错。写 1.25× + 读 0.1× = 1.35×，对比不缓存处理两次 = 2×，读一次就划算。”至少两次”是 Anthropic 1 小时 TTL（写 2×）的情形：2.1× > 2×，2.2× < 3×。
计算：一个应用 system + 工具定义 12,000 token，每轮新增 600，平均 15 轮，不做缓存。总输入多少 token？第 15 轮的单次输入是第 1 轮的多少倍？

答案

$15 \times 12{,}000 + \frac{15 \times 14}{2} \times 600 = 180{,}000 + 63{,}000 = 243{,}000$。第 1 轮 12,000（加首条用户消息），第 15 轮 12,000 + 14 × 600 = 20,400，约 1.7 倍。
判断：用 OpenAI strict 模式的 json_schema，输出里 enum 字段的值一定在枚举范围内，且一定是正确的分类。

答案

前半对、后半错。约束解码保证枚举值在范围内（语法）；分类是否正确是语义，不受保证；无关输入下模型仍会从枚举里挑一个——schema 要留拒答出口。
计算：GPT-6 Astra（$10 / $50，>272K 输入 2×、输出 1.5×）上一个 280K 输入、3,000 输出的请求，成本多少？如果压到 270K 呢？

答案

280K：280,000 × 20 + 3,000 × 75 = 5,600,000 + 225,000 = $5.825。270K：270,000 × 10 + 3,000 × 50 = 2,700,000 + 150,000 = $2.85。少 10K token 省一半以上——门限对整个请求生效。
判断：Claude Fable 5.1 的对话历史（含 thinking block）在 fallback 到 Opus 5 时，推理状态可以保留。

答案

错。Fable 5.1 的 thinking block 只有它自己或更新的模型能读，Opus 5 收到会被 API 丢弃，推理状态丢失。反向（Opus 5 → Fable 5.1）可以。fallback 有方向性。
计算：级联分流，小模型每任务 $0.004，大模型 $0.05，55% 的请求小模型能解决。每任务平均成本？省多少？

答案

$0.004 + 0.45 \times 0.05 = 0.0265$，比全用大模型的 $0.05 省 47%。
判断：一个 HTTP 200 的响应不可能是失败。

答案

错。stop_reason: max_tokens（截断）、refusal / content_filter（拒答）、工具调用参数不是合法 JSON、结构化输出业务校验不过——都是 200。错误分类要读响应体。
计算：峰值 35 QPS，每请求输入 4,000、输出 600 token。需要的输入 TPM 与输出 TPM？

答案

输入 35 × 60 × 4,000 = 8,400,000；输出 35 × 60 × 600 = 1,260,000。

B. 跨篇综合（5 题）

一个客服应用在 2026 年 7 月 1 日把模型从 Claude Sonnet 4.6 改成 Sonnet 5，其他不变。列出它在接下来一周可能遇到的全部问题，按第一、三、四、六篇的顺序归类。

答案

第一篇（供应商变更）：行为变了但代码没变。第三篇：adaptive thinking 默认开启——思考 token 出现、TTFT 变长、max_tokens 被思考占掉导致截断；设了 temperature 的请求 400。第四篇：账单上涨——思考 token 按输出价 + 新 tokenizer 多 30% 输入 token；缓存命中率可能因 tokenizer 变化而在切换当天归零重建。第六篇：按轮数保留的历史因 token 数增加而偶发超限 400；本地 token 估算失效。修法：effort 选档、max_tokens 重设、去掉采样参数、按 token 而非轮数保留历史、重新校准计数、在评测集上重跑。
一个 agent 任务 25 步，每步思考 2,500、可见输出 300、新增工具结果 1,500 token，system + 工具定义 15,000。用 GPT-5.6 Terra（$2 / $12，读 $0.20，写 $2.50）估算：（a）思考总成本；（b）若历史只追加、全程命中缓存，输入侧约多少；（c）若第 10 步有人把一条早期工具结果换成摘要，会怎样。

答案

（a）25 × 2,500 = 62,500 思考 token × $12 = $0.75；可见输出 25 × 300 × 12 = $0.09。（b）每步新增约 2,500 + 300 + 1,500 = 4,300 token 按写入价 2.5，其余按读价 0.2：写入 15,000 + 25 × 4,300 = 122,500 × 2.5 = $0.306；读取 $\sum_{k=2}^{25}[15{,}000 + (k-2) \times 4{,}300] = 24 \times 15{,}000 + 276 \times 4{,}300 = 360{,}000 + 1{,}186{,}800 = 1{,}546{,}800$ × 0.2 = $0.309；输入侧约 $0.62。不缓存则 (360,000 + 15,000 + 1,186,800 + 107,500) × 2 ≈ $3.3。（c）从改动处起前缀失效：第 10 步重写整个前缀（约 15,000 + 8 × 4,300 = 49,400 token × 2.5），之后重新累积；若是 OpenAI 的 reasoning item 由服务端管理则改动本身可能被拒；在 Anthropic 上会触发 thinking block 的历史校验（400 或丢弃）。
你要为一个法律文书审查产品选模型。用第五篇的流程走一遍：硬约束有哪些？榜单怎么用？评测集从哪来、评什么？供应商风险看什么？把第一篇的哪几条失效模式列进规格书？

答案

硬约束：数据可能不能出域（客户合同）→ 区域版本或自托管；长文档 → 有效上下文针测 + 加价门限；知识截止（法规更新）→ 必须配检索。榜单：在预算内的模型里取与法律 / 长文本最接近的 benchmark 前几名做短名单。评测集：从真实文书采 50 份，标注应发现的问题与引用的条款，评分用规则（条款号精确匹配）+ judge（问题描述质量）+ 人工抽检；每模型 × effort 跑 3 次。供应商风险：通知期、多云可用性（合规审计要求）、快照可钉性。规格书重点：幻觉（编造判例与条款——引用校验必做，哈姆 / Avianca 的代价）、上下文有效长度、知识截止、供应商变更（法规审查结果不能因模型静默升级而变——评测门禁）。
一个流式对话接口 p99 TTFT 突然从 1.5 s 变成 15 s，错误率不变，输出速度不变。用第四、六篇的分解与第一篇的失效表给出排查顺序。

答案

TTFT = 排队 + prefill + 思考，输出速度不变排除 decode 侧。顺序：（1）缓存命中率——有人在前缀里加了动态内容 / 改了工具定义 / 历史被修改（第四篇第二章、第三篇第五章）；（2）思考 token 数——模型升级把 thinking 默认开启或 effort 被调高（第三篇、第一篇供应商变更）；（3）输入长度分布——是否有一批长文档请求进来（第一篇上下文、第四篇 prefill）；（4）排队——供应商状态页、429 / 529 比例、客户端令牌桶是否在排队、是否撞了层级限额（第六篇）；（5）重试——p99 常来自退避重试，看重试率是否上升。
第一篇的 PocketOS 事件与第六篇的”工具幂等”、第二篇的”工具结果是不可信输入”、第三篇的”绕过障碍”是同一个问题的几个面。把它们连成一段话，说明为什么应用侧的四道防线比”更聪明的模型”更重要。

答案

模型遇到障碍时生成”绕过”的计划是它的固有倾向（第一篇的越界、第三篇的推理会把”完成任务”放在”不越界”之前）；计划能否变成灾难取决于应用侧：工具拿到的权限范围（最小权限、环境隔离——PocketOS 的 token 权限过宽且 staging 能碰生产）、有没有确认门（不可逆动作二次确认）、动作是否幂等可回滚（备份与主数据分离、重试不重复执行——第六篇）、以及模型读到的工具结果是否被当作可信指令（第二篇：注入可以让模型”决定”执行破坏性动作）。模型的判断准确率永远不是 100%，四道防线把错误的上限从”删掉生产库”压到”一次被拒绝的调用”；PocketOS 四道都没有，Replit 事后加的正是环境分离与回滚。这就是 L4 与 L6 的内容。

C. 面试题（7 题）

你要把一个大模型接进一个现有的后端系统，请给它写一份”组件规格书”。会写哪几节？每节的依据是什么？

答案

答案要点：(1) 失效模式表——七条，每条在本场景的形态、代价、检测手段、应对层、状态（第一篇）；(2) 契约——用哪个入口、消息 / 工具 / 结构化输出 / 流式的约定、状态放哪一侧、store 设置（第二篇）；(3) 推理配置——effort 各档的三条曲线、max_tokens、历史只追加的约束（第三篇）；(4) 成本与延迟预算——每类请求的五项 token 与单价、缓存命中率目标、TTFT / 总时长 SLO（第四篇）；(5) 选型与替代——主模型、替代模型、评测集、弃用通知的处理流程（第五篇）；(6) 客户端纪律——错误分类、重试策略、四层超时、限流器、token 计数、fallback 链（第六篇）。 追问方向：规格书里哪一项最常被漏掉（供应商变更的探测）；怎么维护（评测集与 trace）。 好答案与一般答案的区别：一般答案列 API 参数；好答案先写失效模式再写接口，并把每一项接到后面某一层的手段与一个可测的指标上。
解释为什么公开的 LLM API 在 temperature = 0 下也不可复现，以及这对评测与调试的含义。

答案

答案要点：(1) 采样层：temperature = 0 是贪心，理论上消除了这一层；(2) 计算层：Thinking Machines 2025 的结论——不是浮点并发，是 batch 不变性缺失，kernel 在不同 batch 大小下分块策略不同，同一行的数值路径不同；推理端点的 batch 由其他用户的负载决定；(3) 应用层：两次调用的上下文其实不同（检索顺序、时间戳）；(4) 含义：评测每题跑 $k$ 次看分布，比较两个版本看差距是否超过方差；调试用录制回放而不是重跑；对确定性有硬需求只能自托管（batch 不变 kernel 或 batch = 1，18 种结果 → 1 种）。 追问方向：seed 与 system_fingerprint 为什么只是尽力而为；为什么每次都错且错法一致不是非确定性。 好答案与一般答案的区别：一般答案说”浮点误差”；好答案区分三层、说出 batch 不变性这个真正原因，并落到评测与调试的具体做法。
一个多轮 agent 产品的账单是预算的三倍。你会怎么排查、怎么降？给出顺序与预期效果。

答案

答案要点：(1) 先按五类 token 拆账（usage），看思考 / 输出 / 未缓存输入 / 缓存命中 / 写入各占多少——多数团队第一次拆会发现思考占输出 70% 以上、缓存命中率低于 50%；(2) 思考：effort 扫描，按任务分档（规划 xhigh、读文件 low），预期降思考 3–5 倍；(3) 缓存：审计前缀（动态内容后移、工具定义稳定、历史只追加），命中率目标 > 70%，多轮输入降到约 15%；(4) 长度：历史压缩在思考链结束处做，避开长上下文加价门限；(5) 分流：简单步骤用小模型级联；(6) 形态：离线部分走 Batch 50%；DeepSeek 用户避峰时；(7) 按任务看 p95——那些走弯路的轨迹在 L4 加步数预算。 追问方向：为什么服务端状态不省钱；写入加价的收支平衡；每任务成本与每 token 价的区别。 好答案与一般答案的区别：一般答案说”换便宜的模型、缩短 prompt”；好答案先拆账定位，再按思考 → 缓存 → 长度 → 分流 → 形态的顺序给出每一步的机制与预期倍数。
面试官问：”我们直接用 Arena 前三的模型就行了吧？”你怎么回答？

答案

答案要点：(1) Arena 测的是它自己的提问分布上的人类偏好，与你的任务相关性未知；(2) 排名机制可被影响：私测选择性披露（Llama 4 前 27 个变体，同一 checkpoint 多测也抬分——选择偏差）、采样不对称（两家各约 20% 数据 vs 83 个开源模型 29.7%）、对 Arena 分布过拟合（少量数据在 ArenaHard 上最多 +112%）；(3) 前三之间的分差在噪声量级内；(4) 正确用法：用它缩到短名单，然后在自己的评测集（30–50 条真实流量，每模型 × effort 跑多次）上看质量 / 每任务成本 / 延迟三列决定；(5) 常见结果是一个排名靠后但便宜三倍的模型过了门限。 追问方向：静态 benchmark 的污染与饱和；供应商自报分数为什么不可横比；评测集怎么防过拟合。 好答案与一般答案的区别：一般答案说”榜单不准”；好答案说出三个具体失真机制与数字，并给出替代流程。
设计一个调用模型 API 的客户端库的重试与超时策略。哪些错误重试、怎么退避、超时怎么设、流式怎么处理？

答案

答案要点：(1) 错误分类读响应体不只读状态码：429（非配额）/ 5xx / 529 / 网络 / 超时可重试；工具格式错 / 校验失败 / 截断修正后重试一次；400 / 401 / 配额 / 内容过滤 / 404 不重试；(2) 指数退避 + full jitter，Retry-After 优先，单请求 3–5 次，全局重试预算 10%（防雪崩也防账单）；(3) 四层超时：连接 5–10 s、首事件按输入与 effort、事件间 15–30 s（心跳重置）、总按预期输出；超过一分钟的生成一律流式，更长任务换后台 / Batch；(4) 流式：首事件前失败正常重试，中途断开只重发短回答，已收到的部分不入历史，客户端断开传播到上游；(5) 熔断 + fallback 链（换区域 → 换模型 → 换供应商 → 降级），注意推理状态的方向性；(6) 记请求 id。 追问方向：模型调用本身为什么”幂等”只是成本问题而工具不是；SDK 默认重试覆盖了什么、没覆盖什么。 好答案与一般答案的区别：一般答案说”429 就指数退避”；好答案区分四类错误、说出重试预算与四层超时的理由、把流式中断与计费联系起来。
供应商宣布你在用的模型三个月后下线。从收到邮件到关闭日，你的团队应该做什么？如果只给四天呢？

答案

答案要点：(1) 当天：在推荐替代模型（与你配置里的替代模型）上跑全量评测集，含 effort 各档，看三列；(2) 第一周：按第三篇的迁移三件事调整——effort、max_tokens、历史编辑逻辑；调 prompt；重新校准 token 计数（tokenizer 可能变）；(3) 灰度切换 1% → 10% → 100%，看在线指标；(4) 关闭日前一周完成；(5) 更新配置里的主 / 替代模型，替代模型继续每月热身。四天（DeepSeek V4-Pro 的情形）：只有自动化能做到——评测集跑分脚本、配置化的模型名、已经热身过的替代模型；做不到的团队要接受在别名上被换模型，或提前迁到有快照与更长通知期的供应商。 追问方向：为什么钉快照也不够（快照也有下线日）；服务端状态带来的额外锁定。 好答案与一般答案的区别：一般答案说”换个模型名”；好答案把评测、迁移三件事、灰度、时间表说全，并指出四天通知期只能靠事先的自动化。
“把模型当作组件”和”把模型当作聪明的助手”，在系统设计上会导致哪些具体差别？举五个。

答案

答案要点：(1) 评测：组件观每题跑多次看分布，建评测集做门禁；助手观看几个例子觉得不错就上线；(2) 权限：组件观按最小权限发 token、不可逆动作过确认门；助手观给它一个管理员 token “让它自己搞定”（PocketOS）；(3) 状态与历史：组件观历史只追加、压缩在边界处做、记完整请求体；助手观随意编辑历史；(4) 成本：组件观按五类 token 记账、按任务看分布、effort 按任务选档；助手观看总账单；(5) 变更：组件观模型名进配置、替代模型热身、订阅通知、评测门禁；助手观等用户投诉才发现模型换了；(6) 输出：组件观 schema 留拒答出口、引用可校验、200 也查 stop_reason；助手观信任它说的”已完成”。 追问方向：组件观会不会过度设计（什么场景可以简化）；组件观与产品体验（L7）的关系。 好答案与一般答案的区别：一般答案说”要加校验”；好答案在评测、权限、状态、成本、变更、输出六个维度各给一个可操作的对比，并能引用具体事件。

D. 掌握判据

掌握程度的判据
层次	判据
读过	能说出七条失效模式的名字知道四家 API 的入口知道思考 token 按输出价计费知道缓存读 0.1× 知道榜单不能直接用知道 429 要退避
掌握	能给一个具体场景写出失效模式表并标出应对层能手写工具调用循环含配对与错误送回能用三条曲线为一个任务选 effort 档能用公式算出一次调用与 $N$ 轮对话的成本并解释缓存的效果能设计并解读一张五列的选型评测表能写出错误分类器与四层超时的参数
能教人	能解释 batch 不变性为什么是非确定性的真正原因能说清哈姆判决对”源材料正确”抗辩的否定在技术上为什么成立能推导二次增长与缓存后的系数能用选择偏差解释 Arena 的失真能把 PocketOS 事件拆成模型侧一环与应用侧四环能对一个团队的账单在半小时内定位主要浪费

通关标准：A 组 8 题以上正确（计算题误差 5% 以内），B 组 4 题以上能写出完整推理链，C 组每题能说出至少三个要点并回答一个追问。

六、下一步

本系列是《AI 应用工程师学习地图》的第一层。第一篇的七条失效模式是后面六层的索引：

L2 Prompt 与上下文工程：应对指令遵循、prompt 敏感与上下文的有效长度——prompt 当代码管、上下文预算、压缩、缓存前缀的排列。
L3 检索与知识接入：应对幻觉与知识截止——进上下文还是进权重、三类检索、agentic retrieval、检索评测。
L4 工具、Agent 与运行时：应对越界——工具调用循环的运行时、权限与沙箱、durable execution、harness。
L5 评测、可观测与可追溯：应对非确定性与供应商变更——评测集、LLM-as-judge、trace、录制回放。
L6 生产化与运营：把第四篇的账与第六篇的客户端纪律做成网关、预算、发布与安全。
L7 产品与体验：把不确定性呈现给用户。

想理解本系列引用的结论从哪来：token 计费与 TTFT / TPOT 的形态来自 Infra 地图 08《大模型推理系统揭秘》的前两篇；长上下文与图片为什么贵来自共享系列《Transformer 与 LLM：结构、算量与数值》的 KV cache 与多模态两篇；三张地图的分工见《AI 全栈学习地图》。

七、延伸阅读

本系列有意不展开的内容，以及它们在哪个系列里：

不讲模型内部：Transformer 结构、注意力、KV cache 的机制属于共享的《Transformer 与 LLM》系列与算法地图；本系列只引用它们的结论（decode 是 memory-bound 的、KV 随上下文线性增长）。
不讲 prompt 怎么写：这是 L2 上下文工程系列的内容；本系列只讲 prompt 敏感性作为失效模式与 prompt 在缓存前缀里的位置。
不讲检索、Agent 循环、评测方法、网关建设：分别属于 L3、L4、L5 与 Infra 地图 11。本系列在每一条失效模式与契约项上标出它们所在的层。
不比较模型的能力：不给”哪个模型最好”的结论。第五篇讲的是怎样自己得出结论。
不讲自托管引擎的部署：属于 Infra 地图 08。第五篇只讲何时值得自托管的判据。

面对任何一个模型 API：它在我的场景里会以哪七种方式失效、每种的代价与检测手段（第一篇）；一次工具调用的往返哪些步骤是我的责任，结构化输出保证了什么、没保证什么，store 的默认值是什么（第二篇）；effort 从 high 调到 low 成本 / 延迟 / 质量各怎么变、为什么不能随意编辑历史（第三篇）；这次调用的五项成本各多少、第 20 轮是第 1 轮的多少倍、缓存能降到多少、TTFT 慢在哪一段（第四篇）；为什么榜单第一在我的任务上不如第五、该怎么用评测集选、供应商下线通知来了做什么（第五篇）；哪些错误重试哪些不、超时怎么分层、发前怎么知道会不会超限（第六篇）。详见第一章。 ↩
数字：1000 次贪心 18 种结果 → 1 种；NoLiMa 32K 处 11/13 模型掉到基线一半以下、GPT-4o 99.3% → 69.7%；Air Canada 812.02 加元、PocketOS 9 秒、约 700 个 agent；Responses 默认存 30 天；Sonnet 5 low → high 6 倍、tokenizer 多 30%；价目跨三个量级、输出价 = 输入价 × 4–6、读 0.1×（Fable 5.1 0.025×、DeepSeek 0.02×）、写 1.25×、1.35× vs 2×、>272K 输入 2× 输出 1.5×、峰时 ×2、Batch 50%；$NS + N(N-1)m/2$ 与 0.1 系数、590K → 87.8K；27 个变体、约 20% vs 29.7%、+112%；大小价差 5–20 倍、级联 $c_s + (1-f)c_l$；OpenAI 3–6 个月、Anthropic ≥ 1 年、DeepSeek 4 天；full jitter、重试预算 10%、四层超时、峰值 TPM = QPS × 60 × 每请求 token。结论：失效是性质不是 bug；工具调用是协议；strict 保证形状不保证语义；思考是状态只搬运；历史只追加；按分布、按任务；榜单只缩范围；评测集是唯一的探测器。详见第一章、第三章。 ↩
用第五章 D 节的三级判据：读过——能说出名词与结论；掌握——能对一个具体场景写出失效模式表、手写工具调用循环、用三条曲线选 effort、用公式算成本与多轮增长、设计并解读选型评测表、写出错误分类器与超时参数；能教人——能解释 batch 不变性、哈姆判决的技术含义、二次增长的推导、Arena 的选择偏差、PocketOS 的一环加四环，并能在半小时内定位一份账单的主要浪费。通关标准：A 组 8 题以上（计算误差 5% 内）、B 组 4 题以上完整推理链、C 组每题三个要点加一个追问。详见第五章。 ↩

模型作为组件（06）：客户端工程——重试、超时、幂等、限流与流式解析

Sun, 04 Oct 2026 00:00:00 +0800

前五篇讲的是组件本身：它怎么坏、接口是什么、花多少钱、怎么选。这一篇讲你这一侧——调用它的客户端。调用模型 API 与调用任何不稳定的第三方服务有大半是相同的：会超时、会 429、会 5xx，要重试、要退避、要熔断。不同的是失败的种类更多——上下文超限、内容过滤、工具调用格式错、推理超预算、流式中途断开——而且每一次重试都要再花一次钱，一次重试可能是几美分也可能是几美元（一个 300K 输入的请求）。

后端工程师写过的每一个 HTTP 客户端的经验在这里都有效，但要加三条模型 API 特有的纪律：发请求之前数 token（超限的 400 是可以避免的失败）；流式响应的失败只能重发不能续传（并接受已生成 token 的费用）；重试策略要区分”再试一次可能成功”与”再试一次只是再花一次钱”（幻觉不会因为重试消失，格式错误可能会）。

本篇要回答的核心问题是：

模型 API 的错误有哪几类，哪些该重试、哪些不该？¹ 超时为什么要分四层，流式中断怎么处理？² 限流的维度与使用层级对容量规划意味着什么？³ 为什么要在发请求前数 token，token 计数会怎样变？⁴

一、总览

1. 一次调用在客户端经过的检查点

%% 图：一次调用在客户端经过的检查点：数 token、取并发槽、四层超时发送、错误分类后退避重试或 fallback、解析并记 trace
flowchart TB
    S(["业务层发起调用"]) --> CNT["数 token<br/>超过上下文或预算 → 先压缩 / 拒绝，不发"]
    CNT --> SLOT["取并发槽 / 令牌<br/>按模型 · 按租户的限流器"]
    SLOT --> SEND["发送（流式或非流式）<br/>四层超时：连接 · 首事件 · 事件间 · 总"]
    SEND --> OK{"成功？"}
    OK -->|"是"| PARSE["解析：拼接增量 · 工具参数等 done · 读 usage · 读 stop_reason"]
    PARSE --> DONE(["返回业务层 + 记 trace"])
    OK -->|"否"| CLS{"错误分类"}
    CLS -->|"可重试：429 / 5xx / 529 / 超时 / 连接断"| BACK["退避（指数 + 抖动，遵守 Retry-After）<br/>重试预算未耗尽？"]
    BACK -->|"是"| SLOT
    BACK -->|"否"| FB
    CLS -->|"不可重试：400 · 401 · 配额不足 · 内容过滤"| FB{"有 fallback？"}
    FB -->|"换模型 / 换供应商 / 降级"| SLOT
    FB -->|"无"| FAIL(["失败返回业务层 + 记 trace"])

    classDef step fill:#fff7e0,stroke:#c98a00,stroke-width:2px,color:#222
    classDef dec fill:#eef6ff,stroke:#5b8fd6,color:#222
    classDef stop fill:#f0f0f0,stroke:#888,color:#222
    class CNT,SLOT,SEND,PARSE,BACK step
    class OK,CLS,FB dec
    class S,DONE,FAIL stop

图里每个方框对应本文一章。多数 SDK 替你做了”发送”与部分”重试”（默认重试 2 次）；数 token、限流、错误分类的细节、fallback、trace 都是你的。

2. 本文的章节安排

第二章给错误分类表；第三章讲重试与退避；第四章讲四层超时与流式中断；第五章讲幂等与副作用；第六章讲限流的维度、使用层级与容量规划；第七章讲流式解析的工程细节；第八章讲 token 计数；第九章讲降级与 fallback；第十章实践建议。

二、错误分类

1. 一张表

客户端错误分类与处理
类别	信号	含义	重试？	该做什么
限流	HTTP 429 OpenAI `rate_limit_exceeded` Anthropic `rate_limit_error` `Retry-After` 头	超过 RPM / TPM	是，遵守 `Retry-After`，退避	检查限流器配置；长期看容量（第六章）
配额 / 余额	429 但 `insufficient_quota`（OpenAI）；402 / 余额不足	钱用完了	否	告警；这是账务不是流控
过载	Anthropic 529 `overloaded_error` OpenAI 503 / 500 `server_error` Gemini 503	供应商侧容量	是，退避更长	看状态页；触发 fallback 到另一模型 / 供应商
网络	连接超时、连接重置、DNS	到达前失败	是	幂等无忧（请求没到）
读超时	首事件 / 事件间 / 总超时	请求到了，可能已在生成	是（但已生成的 token 可能计费）	缩短输入、调低 effort、改流式
请求非法	400 `invalid_request_error`：参数错、消息结构错（工具结果缺配对）、thinking block 校验失败	你的 bug 或契约变更	否	修代码；第二、三篇的清单
上下文超限	400，OpenAI `context_length_exceeded`；Anthropic “prompt is too long”	输入 + `max_tokens` 超过窗口	否（重发同样超）	发前数 token（第八章）；压缩历史
输出截断	200 但 `stop_reason` / `finish_reason` = `max_tokens` / `length`	回答不完整	视情况：提高 `max_tokens` 或调低 effort 后重试	监控比例
内容过滤 / 拒答	Anthropic `stop_reason: refusal` OpenAI `finish_reason: content_filter`（Azure 更常见） Gemini `finishReason: SAFETY`	模型或供应商侧拒绝	否（同样的输入同样拒）	按产品逻辑处理记录不要静默重试绕过
工具调用格式错	200 但 `arguments` 不是合法 JSON、参数不符 schema、调用了不存在的工具	模型输出错误	可，一次：把错误作为 tool result 送回让模型改	开 strict 工具 schema
结构化输出校验失败	200 但业务校验不过	语义错误	可，一次，带错误信息	第二篇第四章
认证 / 权限	401 / 403	key 错、无权用该模型	否	配置问题
模型不存在	404 `model_not_found`	模型名错或已下线	否	第五篇的弃用流程；fallback

三个原则。只重试”再试可能不同”的错误：限流、过载、网络、超时——它们的原因在外部且会变；400 类的原因在你的请求里，重发只是再花一次钱（超限的 400 不计费，但 200 的截断与格式错是计费的）。内容过滤不要用重试绕：它是供应商的政策，反复重试会触发更严的限制，且在合规上说不清。200 也可能是失败：截断、格式错、拒答都是 200，错误分类要读响应体，不只读状态码。

2. 请求 id

每次响应都带请求 id（OpenAI x-request-id，Anthropic request-id）。把它记进 trace——向供应商报问题时这是唯一的凭据，也是核对账单争议的依据。

三、重试与退避

1. 指数退避加抖动

第 $n$ 次重试前等待：

\[t_n = \min\left(t_{\max},\ \text{random}\left(0,\ t_0 \cdot 2^{n}\right)\right)\]

“full jitter”——在 0 到指数上限之间均匀取随机值。为什么要抖动：一次 429 或 529 通常是很多客户端同时撞上限流或过载，无抖动的退避让它们在同一时刻重试，形成第二波。$t_0$ 取 0.5–1 s，$t_{\max}$ 取 30–60 s，重试次数 3–5。

Retry-After 优先：供应商在 429 里给了等待秒数就用它，不要自己算——它知道你的窗口何时重置。Anthropic 与 OpenAI 的 429 都带。

%% 图：为什么退避要加抖动——一次过载让 1,000 个客户端同时收到 529；无抖动的指数退避让它们在 1 s、2 s、4 s 整点同时重试，形成一波波的第二次过载；full jitter 把每一轮的重试均匀撒在 0 到上限之间，供应商看到的是平滑的流量
flowchart TB
    subgraph NJ["无抖动：t = t₀ · 2ⁿ"]
        direction LR
        N0["1,000 个客户端<br/>同一秒收到 529"] --> N1["1 s 后：1,000 个同时重试<br/>→ 又一次过载"] --> N2["2 s 后：再来一波"] --> N3["4 s 后：再来一波…"]
    end
    subgraph FJ["full jitter：t = random(0, t₀ · 2ⁿ)"]
        direction LR
        F0["1,000 个客户端<br/>同一秒收到 529"] --> F1["0–1 s 内均匀散开重试"] --> F2["失败的在 0–2 s 内散开"] --> F3["供应商看到的是平滑的流量<br/>加上 Retry-After 就更准"]
    end
    NJ ~~~ FJ
    classDef bad fill:#fdecea,stroke:#c0392b,color:#222
    classDef ok fill:#eefaf0,stroke:#4d9a5c,color:#222
    classDef n fill:#fff7e0,stroke:#c98a00,color:#222
    class N0,F0 n
    class N1,N2,N3 bad
    class F1,F2,F3 ok

2. 重试预算

单个请求的重试次数上限是必要的，但不够：一个过载事件里，如果每个请求都重试 5 次，供应商收到的流量是平时的 5 倍，过载更久。用重试预算——单位时间内重试次数不超过总请求的某个比例（比如 10%）——超过预算就直接失败或走 fallback。这是 SRE 的老做法，在按 token 计费的场景里多了一个理由：重试预算也是钱的预算。

3. 重试的层次

请求级：同一请求体重发。适用于限流、过载、网络。
修正级：改一下再发——工具调用格式错时把错误信息作为结果送回、结构化输出校验失败时附上错误让模型重试一次、截断时提高 max_tokens。这是模型 API 特有的重试形态，每次都是一次新的付费调用，限一次。
任务级：整个 agent 任务失败后从头或从 checkpoint 重来。属于 L4 运行时；客户端不做。

SDK 的默认重试（OpenAI 与 Anthropic 的官方 SDK 默认 2 次，指数退避）只覆盖请求级、只针对 429 / 5xx / 连接错误。修正级要自己写。

%% 图：重试的三个层次各归谁管——请求级（原样重发，SDK 默认做）、修正级（把错误信息送回让模型改一次，模型 API 特有，要自己写）、任务级（agent 任务从 checkpoint 重来，属于 L4 运行时）
flowchart TB
    E["一次调用出了问题"] --> C{"错在哪？"}
    C -->|"429 · 5xx · 529 · 网络 · 超时<br/>原因在外部，会变"| R1["请求级：同一请求体重发<br/>指数退避 + 抖动 · 3–5 次 · 重试预算<br/>SDK 默认覆盖（2 次）"]
    C -->|"200 但工具参数不是合法 JSON · 校验不过 · 截断<br/>原因在模型的输出"| R2["修正级：改一下再发<br/>错误信息作为 tool result 送回 / 提高 max_tokens<br/>限一次；每次都是新的付费调用；要自己写"]
    C -->|"整个 agent 任务失败<br/>循环跑飞、预算耗尽"| R3["任务级：从头或从 checkpoint 重来<br/>属于 L4 运行时，客户端不做"]
    C -->|"400 · 401 · 配额不足 · 内容过滤<br/>重发只是再花一次钱"| R0["不重试：修代码 / 告警 / 按产品逻辑处理"]
    classDef dec fill:#eef6ff,stroke:#5b8fd6,color:#222
    classDef ok fill:#eefaf0,stroke:#4d9a5c,color:#222
    classDef n fill:#fff7e0,stroke:#c98a00,color:#222
    classDef bad fill:#fdecea,stroke:#c0392b,color:#222
    class C dec
    class R1 ok
    class R2,R3 n
    class R0 bad

4. 流式中的重试

流式请求在收到第一个事件之前失败，与非流式一样重试。在生成中途断开——供应商已经生成了一部分并会为此计费——重试意味着从头再生成一遍，双倍成本。策略：中途断开只对短回答自动重试；长回答（agent 的长输出、大段代码）要么在 UI 上提示用户重试，要么接受部分结果。没有”从第 137 个 token 续上”的机制。

四、超时

1. 四层

超时的四层
层	含义	典型值	超过意味着
连接	TCP / TLS 建立	5–10 s	网络或供应商入口问题；可重试
首事件（TTFT）	从发送到第一个字节 / 第一个 SSE 事件	按输入长度与 effort：短请求 10–30 s，长 prefill 或 `xhigh` 思考 60–120 s	排队、长 prefill、长思考；第四篇的三段排查
事件间	两个 SSE 事件之间	15–30 s	生成卡住或连接半死
总	整个请求	按预期输出长度：$\text{TTFT} + n_{\text{out}} \times \text{TPOT}$ 再乘 2–3	兜底

只设一个总超时的客户端有两个毛病：设短了会误杀正常的长回答（800 token 在 30 ms/token 下要 24 秒），设长了对一个卡死的连接要等很久才发现。四层各管一段。

2. SDK 的默认值

官方 SDK 的默认总超时通常是 10 分钟。Anthropic 的 SDK 对非流式请求有一个额外的规则：如果按 max_tokens 估算生成时间可能超过 10 分钟，它会拒绝以非流式发送，要求改用流式——因为长连接空等 10 分钟在网络上不可靠。这条规则说明了一件事：超过一分钟的生成应该流式，不是为了 UI，是为了连接的健康。

3. 更长的任务

深度研究、长文档处理、几十步的 agent 任务，几分钟到几小时。它们不该占着一个 HTTP 连接：OpenAI 的 Responses 有 background: true（提交后轮询或 webhook 通知），Anthropic 与 Gemini 有 Batch，Agents API 一类的托管运行时把任务变成异步 job。客户端的对应设计是”提交 → 轮询 / 回调”，超时策略变成 job 级的 SLA。L4 讲运行时，这里只说：HTTP 请求的超时不该超过几分钟，更长的任务换形态。

五、幂等与副作用

1. 模型调用本身

一次纯生成调用的重复执行没有业务副作用——只有两个后果：再花一次钱，以及在服务端状态开启时（Responses 默认 store: true）多存一条。所以模型调用的”幂等”主要是成本问题，而不是正确性问题；四家的生成接口都没有通用的幂等键（Batch 接口有 custom_id 用于配对）。控制手段是重试预算与”中途断开只重试短回答”。

2. 工具的副作用

真正的幂等问题在工具上。agent 循环里模型返回 tool_call: create_order(...)，你执行了，然后送回结果的那次请求超时了——你重试，模型没收到结果又返回同一个 tool_call，你再执行，订单重复。防止的办法与任何分布式系统相同：

工具本身幂等（用 tool_call_id 或业务键做幂等键，第二次调用返回第一次的结果）；
在应用侧记录”哪些 tool_call_id 已执行”，重复的直接返回缓存结果而不再执行；
有副作用且不幂等的工具（发邮件、付款）走确认门（L4）。

这是第一篇”越界”一条的客户端版本：重试是无害的，直到它触发了一个不幂等的动作。

%% 图：重试怎么让订单重复——模型返回 create_order 的 tool_call，应用执行了，送回结果的那次请求超时；重试时模型没见过结果，又返回同一个 tool_call，应用再执行一次；解法是用 tool_call_id 做幂等键，第二次直接返回第一次的结果
sequenceDiagram
    participant App as 应用
    participant API as 模型 API
    participant Tool as create_order
    App->>API: 请求 #1
    API-->>App: tool_call（id = call_7，create_order）
    App->>Tool: 执行 → 订单 A 创建
    App->>API: 请求 #2：历史 + call_7 的结果
    Note over App,API: ✗ 超时（请求可能没到，也可能到了）
    App->>API: 重试请求 #2 … 或者重发 #1
    API-->>App: 又一个 tool_call（call_7 或新 id，create_order）
    Note over App: 没有幂等键：再执行 → 订单 B，重复了
    Note over App,Tool: 有幂等键：查到 call_7 已执行 → 直接返回订单 A 的结果，不再调用

3. 服务端状态下的重复

用 previous_response_id 链式调用时，一次超时后重试会在服务端产生两条分叉的响应。要么用返回的 id 去重（以第一条成功的为准），要么把状态放在客户端（第二篇第六章）。

六、限流与容量

1. 维度

限流至少两个维度：每分钟请求数（RPM）与每分钟 token 数（TPM）；Anthropic 进一步分输入 TPM 与输出 TPM。每一维都可能先触顶：一个每请求 50K token 的应用，RPM 远没用完 TPM 就满了；一个高频短请求的应用反过来。响应头告诉你剩余：OpenAI 的 x-ratelimit-limit-requests / x-ratelimit-remaining-requests / x-ratelimit-reset-requests 与对应的 -tokens 三个；Anthropic 的 anthropic-ratelimit-requests-*、anthropic-ratelimit-input-tokens-*、anthropic-ratelimit-output-tokens-*。DeepSeek 不限 RPM / TPM，限并发（V4.1 Flash 2,500、V4-Pro 500），超过时请求排队或返回忙。

2. 使用层级

额度按账户的历史消费分层：OpenAI 的 Tier 1–5，Anthropic 在 Sonnet 5 发布时把层级简化为 Start / Build / Scale 三级。新账户的额度低，一个上线即有流量的产品会在第一天撞墙。容量规划要提前：估算峰值 TPM（峰值 QPS × 每请求平均 token，输入输出分开算），对照当前层级，提前升级或申请提额；多供应商分摊（L6 网关）也是一种扩容。

3. 客户端限流器

不要等供应商 429 再退避——那已经浪费了一次往返，而且多个实例同时撞限会放大。在客户端放一个按模型的令牌桶（容量 = 你的 TPM 额度打九折，按 token 而不只按请求扣），请求前扣 token（用第八章的计数），响应后按 usage 校正。多租户的应用再加一层按租户的公平队列，防止一个租户吃光额度。这是 L6 网关的核心功能之一，在没有网关的时候客户端要自己做。

%% 图：客户端限流器的两层——按租户的公平队列防止一个租户吃光额度，按模型的令牌桶把容量定在供应商 TPM 额度的九折、发送前按估算的 token 扣、响应后按 usage 校正、并用限流头动态调整
flowchart LR
    T1["租户 A 的请求"] & T2["租户 B 的请求"] & T3["租户 C 的请求"] --> FQ["按租户的公平队列<br/>轮转取用，单租户有上限"]
    FQ --> TB["按模型的令牌桶<br/>容量 = TPM 额度 × 0.9<br/>发送前扣估算的 token"]
    TB -->|"有令牌"| SEND["发送"]
    TB -->|"没令牌"| WAIT["本地等待<br/>（不去撞 429）"]
    SEND --> RESP["响应"]
    RESP -->|"usage 校正扣除量"| TB
    RESP -->|"x-ratelimit-remaining / reset<br/>喂回桶的速率"| TB
    classDef step fill:#fff7e0,stroke:#c98a00,color:#222
    classDef ok fill:#eefaf0,stroke:#4d9a5c,color:#222
    classDef n fill:#eef6ff,stroke:#5b8fd6,color:#222
    class T1,T2,T3 n
    class FQ,TB,SEND,RESP step
    class WAIT ok

4. 从限流头调整

限流头是动态信息：接近 remaining = 0 时主动降速，reset 告诉你何时恢复。一个好的客户端把这两个数喂给自己的令牌桶。

七、流式解析的工程

第二篇第五章讲了事件模型；这里是实现层的坑：

SSE 的行协议。事件以 data: 行开头、空行分隔；有的供应商发注释行（: keep-alive）或空事件作为心跳——DeepSeek 在排队时会发空行保持连接。解析器要忽略它们而不是报错，事件间超时的计时器要在收到心跳时重置。
增量拼接。文本增量直接追加；工具调用参数按 index / id 分桶拼接字符串，等该调用的 done 事件（或 Anthropic 的 content_block_stop）再解析 JSON。并行工具调用的增量会交错到达。
usage 在末尾。预算控制与成本记账在结束事件里做；流式过程中的”已用 token”只能估算。
客户端断开。用户关了页面，你的服务器与供应商之间的流还在——供应商继续生成并计费直到你主动关闭连接。前端断开要传播到后端并取消上游请求。
背压。模型每秒几十个 token，UI 每个 token 重绘一次会卡；按时间（每 50–100 ms）或按块合并后再推给前端。
中断后的状态。中断时已收到的增量可以展示为部分结果并标注”已中断”，但不要把它当作完整回答存入历史——下一轮模型会以为自己说完了。

八、token 计数

1. 为什么在发之前数

上下文超限的 400 是唯一一类可以在发送前完全避免的失败：窗口大小已知、max_tokens 已知、输入长度可以算。发送前算：$n_{\text{in}} + \text{max\_tokens} \le \text{窗口}$，不满足就先压缩历史（L2）或拒绝。此外，第六章的令牌桶要按 token 扣、第四篇的成本预估要 token 数——都要在发送前知道。

2. 怎么数

四家的 token 计数方式
供应商	本地	远程
OpenAI	`tiktoken`（按模型选编码）	—
Anthropic	无官方本地 tokenizer	`count_tokens` 端点（免费，接受完整请求体含 tools 与 system）
Google	—	`countTokens`
DeepSeek	官方提供离线 tokenizer 包	—

本地计数快但要跟模型的 tokenizer 版本；远程计数准但多一次往返（Anthropic 的端点接受与真实请求相同的结构，所以工具定义、system、图片都算进去了）。折中做法：本地估算用于限流与预算（允许 5–10% 误差），远程精确计数只在接近窗口上限时做。

3. 计数会变

Claude Sonnet 5 换了 tokenizer，同样的文本比 Sonnet 4.6 多产出约 30% 的 token（Anthropic 的发布说明原话，”具体增幅取决于内容与负载形态”）。含义：（1）账单上涨 30%，即使价格不变；（2）原来按 4.6 算好的”历史保留 N 轮”在 5 上会超窗口；（3）基于字符数的粗估（”1 token ≈ 4 字符”）失效。换模型时 token 计数要重新校准。

另外，中文比英文贵：多数 tokenizer 下一个汉字 1–2 个 token，英文约 0.75 个 token 一个词；同样信息量的中文 prompt 比英文长 30–50%。这是中文应用做成本估算时的一个常数。

九、降级与 fallback

1. 熔断

对一个模型 / 供应商的错误率或超时率在滑动窗口内超过阈值（比如 30 秒内 20%），熔断器打开：后续请求不再发给它，直接走 fallback；隔一段时间放一个探测请求，成功则半开、逐步恢复。这防止了过载事件里你的重试雪崩到已经不健康的端点。

%% 图：熔断器的三个状态——关闭时正常放行并统计错误率，30 秒窗口内错误率超过 20% 就打开、请求直接走 fallback，等待期过后半开放一个探测请求，成功则关闭、失败则重新打开
stateDiagram-v2
    direction LR
    [*] --> Closed
    Closed: 关闭 — 正常放行
统计滑动窗口内的错误率 / 超时率
    Open: 打开 — 不再发给它
请求直接走 fallback
    HalfOpen: 半开 — 放一个探测请求
    Closed --> Open: 30 s 内错误率 > 20%
    Open --> HalfOpen: 等待期到（如 30 s）
    HalfOpen --> Closed: 探测成功 → 逐步恢复流量
    HalfOpen --> Open: 探测失败

2. fallback 的层次

fallback 的层次
层	做法	代价
同模型换区域 / 云	Claude 在 Anthropic API、Bedrock、Vertex、Foundry 都有	最小；价格略有差别（第四篇的区域加价）
同供应商换模型	Fable 5.1 → Opus 5；Sol → Terra	质量可能下降；推理状态的方向性（第三篇：新模型的 thinking block 旧模型读不了）
换供应商	Sonnet 5 → GPT-5.6 Terra	中间层的消息归一化要成熟（第二篇）历史里的 thinking 块要剥掉 prompt 可能要调
降级到非模型	规则、缓存的答案、”稍后再试”	功能降级，但服务不挂

fallback 的选择要提前在评测集上验证（第五篇：替代模型每月热身），不能在故障当天第一次试。

3. 对用户说什么

降级发生时告诉用户（”当前使用备用模型，回答可能略有差异”）比静默好——L7 讲不确定性的呈现。静默降级的问题是用户把质量下降归因于产品本身。

十、实践建议

一份客户端检查清单，按本文顺序：

错误分类器：按第二章的表把响应映射到”可重试 / 修正后重试一次 / 不可重试 / 需人工”，读响应体不只读状态码；记请求 id。
重试：指数退避 + full jitter，遵守 Retry-After，单请求 3–5 次，全局重试预算 10%；修正级重试限一次。
超时四层：连接 5–10 s、首事件按输入与 effort、事件间 15–30 s、总按预期输出；超过一分钟的生成一律流式；更长的任务换后台形态。
工具幂等：按 tool_call_id 去重，不幂等的工具走确认门。
限流器：按模型的令牌桶按 token 扣，多租户加公平队列，用限流头校正；提前估峰值 TPM 对照层级。
流式解析：忽略心跳、按 id 分桶拼工具参数、等 done 再解析、前端断开传播到上游、合并增量减少重绘。
发前数 token：本地估算 + 接近上限时远程精确计数；换模型重新校准；中文按 1–2 token / 字估。
熔断与 fallback：错误率阈值熔断，fallback 链提前在评测集上验证，降级时告知用户。

十一、本文小结

错误分四类：可重试（429、5xx、529、网络、超时）、修正后重试一次（工具格式错、结构化输出校验失败、截断）、不可重试（400、401、配额不足、内容过滤、模型不存在）、需人工。200 也可能是失败——读 stop_reason。
重试用指数退避 + full jitter，Retry-After 优先，加全局重试预算；每次重试都是一次付费调用，流式中途断开只能重发。
超时分连接 / 首事件 / 事件间 / 总四层；超过一分钟的生成用流式（Anthropic SDK 会强制），更长的任务用后台或批处理形态。
模型调用本身的重复只多花钱；幂等问题在工具上——按 tool_call_id 去重，不幂等的走确认门。
限流按 RPM 与 TPM（Anthropic 分输入 / 输出 TPM，DeepSeek 限并发），额度按层级（OpenAI Tier 1–5，Anthropic Start / Build / Scale）；客户端放令牌桶按 token 扣，用限流头校正，提前规划容量。
流式解析要忽略心跳、分桶拼接工具参数、等 done 再解析、传播客户端断开（否则供应商继续计费）、合并增量。
发前数 token 能完全避免超限的 400；计数会随模型变（Sonnet 5 多 30%），中文比英文贵 30–50%。
熔断 + 分层 fallback（换区域 → 换模型 → 换供应商 → 降级到非模型），fallback 链提前验证，降级时告知用户。

十二、自测

一个请求返回 HTTP 200，stop_reason 是 max_tokens，输出的 JSON 不完整。该重试吗？怎么重试？与 stop_reason: refusal 的处理有何不同？

答案

这是”修正后重试一次”：提高 max_tokens（推理模型上它含思考 token，第三篇）或调低 effort 后重发一次；原样重发大概率同样截断。refusal 是不可重试的：模型 / 供应商按政策拒绝，同样输入同样拒，反复重试可能触发更严的限制，应按产品逻辑处理并记录。两者都是 200，错误分类必须读响应体。详见第二章。
供应商过载，1,000 个客户端实例同时收到 529。对比”固定 2 秒后重试”、”指数退避无抖动”、”指数退避 + full jitter”三种策略在接下来 10 秒内对供应商的流量形状。

答案

固定 2 秒：1,000 个请求在第 2 秒同时到达，第二波过载，之后每 2 秒一波。指数退避无抖动：第 1、2、4、8 秒各一波，波峰仍是 1,000。full jitter：第一次重试均匀散在 0–1 s，第二次散在 0–2 s，第三次 0–4 s……流量被摊平，峰值降到原来的几分之一，供应商更快恢复。再加全局重试预算（重试不超过总量 10%）可进一步限制总流量。详见第三章。
agent 循环里模型返回 tool_call: send_invoice(order=123)，你执行成功，但送回结果的请求超时。SDK 自动重试了那次请求。可能发生什么？怎么防？

答案

重试的请求带的是同样的历史（含工具结果），通常没问题；但如果超时发生在你尚未送回结果、模型再次返回同一个 tool_call 时，你会再执行一次，发票重复发送。防：工具按 tool_call_id 或业务键幂等（第二次返回第一次的结果）；应用侧记录已执行的 tool_call_id；发票、付款这类不幂等且对外的动作走确认门。模型调用本身重复只多花钱，副作用在工具上。详见第五章。
一个应用峰值 20 QPS，每请求平均输入 6,000 token、输出 800 token。它需要多少输入 TPM 与输出 TPM？如果账户当前层级的 TPM 是 400K，会怎样？

答案

输入 TPM = 20 × 60 × 6,000 = 7,200,000；输出 TPM = 20 × 60 × 800 = 960,000。400K 的 TPM 只够峰值的 5.5%（输入），上线即大面积 429。要提前升级层级 / 申请提额、用 prompt caching（部分供应商对缓存命中的 token 不计入或减计 TPM，需查文档）、或多供应商分摊；客户端令牌桶应按 400K × 0.9 扣，超出的请求排队而不是打出去挨 429。详见第六章。
从 Claude Sonnet 4.6 迁到 Sonnet 5 后，一个”保留最近 30 轮历史”的对话应用开始偶发上下文超限的 400，而窗口大小没变。原因是什么？该怎么改？

答案

Sonnet 5 的新 tokenizer 对同样文本多产出约 30% 的 token，30 轮历史在 4.6 上够放、在 5 上超了；且 Sonnet 5 默认开启 thinking，max_tokens 通常也被调高，占用了更多窗口。改法：不按轮数而按 token 数保留历史，发送前用 count_tokens 端点（或校准过的本地估算）检查 $n_{\text{in}} + \text{max\_tokens} \le \text{窗口}$，超过则压缩；换模型时重新校准计数。详见第八章。

四类。可重试（原因在外部且会变）：429 限流（遵守 Retry-After）、5xx / Anthropic 529 过载、网络错误、读超时。修正后重试一次（每次都是新的付费调用）：工具调用参数不是合法 JSON 或不符 schema（把错误作为 tool result 送回）、结构化输出业务校验失败（附错误信息）、stop_reason: max_tokens 截断（提高 max_tokens 或调低 effort）。不可重试（原因在你的请求或供应商政策里）：400 参数 / 结构错、上下文超限、401 / 403、insufficient_quota、内容过滤 / refusal、404 模型不存在。需人工：配额与账务。注意 200 也可能是失败，要读响应体的 stop_reason / finish_reason。详见第二章。 ↩
单一总超时设短会误杀正常的长回答（800 token × 30 ms = 24 s），设长则对卡死的连接要等很久。四层各管一段：连接（5–10 s，网络）、首事件（按输入长度与 effort，10–120 s，排队 / prefill / 思考）、事件间（15–30 s，生成卡住；收到心跳要重置）、总（TTFT + 输出 × TPOT 的 2–3 倍）。超过一分钟的生成一律流式（Anthropic SDK 对可能超 10 分钟的非流式请求会拒绝），更长的任务换后台 / Batch 形态。流式中断：首事件前失败按普通重试；中途断开没有续传机制，只能重发且已生成的 token 已计费——短回答自动重试、长回答提示用户；已收到的部分可展示但不能当完整回答存入历史；客户端断开要传播到上游否则供应商继续生成计费。详见第三章、第四章、第七章。 ↩
维度：RPM 与 TPM（Anthropic 分输入 / 输出 TPM；DeepSeek 不限速率限并发 2,500 / 500），每一维都可能先触顶——长输入应用先满 TPM，高频短请求先满 RPM。响应头给出限额 / 剩余 / 重置（OpenAI x-ratelimit-*，Anthropic anthropic-ratelimit-*）。额度按账户历史消费分层（OpenAI Tier 1–5，Anthropic Start / Build / Scale），新账户额度低。容量规划：峰值 QPS × 每请求 token 分别算输入 / 输出 TPM，对照层级提前升级或多供应商分摊；客户端放按模型的令牌桶按 token 扣（额度打九折）、多租户加公平队列、用限流头动态校正，而不是等 429 再退避。详见第六章。 ↩
上下文超限的 400 是唯一可以在发送前完全避免的失败：窗口、max_tokens、输入长度都已知，发前检查 $n_{\text{in}} + \text{max\_tokens} \le \text{窗口}$，超了先压缩；限流器按 token 扣与成本预估也需要发前的计数。工具：OpenAI 本地 tiktoken，Anthropic 远程 count_tokens（免费，接受完整请求体），Google countTokens，DeepSeek 离线 tokenizer；本地估算用于限流，接近上限时远程精确计数。计数会变：Claude Sonnet 5 的新 tokenizer 让同样文本多约 30% token——账单涨、按轮数保留的历史超窗、字符数粗估失效，换模型要重新校准；中文每字 1–2 token，比同等信息量的英文长 30–50%。详见第八章。 ↩

模型作为组件（05）：选型——榜单的失真、自己的评测集与供应商的弃用周期

Sat, 03 Oct 2026 00:00:00 +0800

2026 年 9 月，一个应用工程师面对的候选清单大致是：OpenAI 四个在售的主力模型（GPT-6 Astra、GPT-5.6 Sol / Terra / Luna），Anthropic 四个（Fable 5.1、Opus 5、Sonnet 5、Haiku 4.5），Google 三到四个（3.8 Flash、3.1 Pro、3.5 Flash-Lite），DeepSeek 一个（V4.1 Flash，开放权重），加上 Qwen、Llama、gpt-oss 等开源系列与它们在各云上的托管版本。二十几个模型，价格跨三个量级（第四篇），能力在不同任务上排序不同，每个季度换一代。

多数团队的选法是看榜单：Chatbot Arena 第几、某个 benchmark 多少分。本篇的第一个结论是榜单只能用来缩小候选范围，不能用来做决定——不是因为榜单不认真，而是它测量的东西与你的任务不同，并且它的排名机制已被证明可以被供应商系统性地影响。第二个结论是选型是一个用自己的评测集回答的工程问题：几十条从真实流量里采出来的用例，在候选模型上跑一遍，看质量、成本、延迟三列，答案通常很清楚。第三个结论是选型要包含供应商风险：一个模型的价格与能力在它被下线的那天都归零，而 2026 年内四家都下线过模型——OpenAI 分三批关闭二十多个快照，DeepSeek 用四天预告把一个模型的全部流量路由到另一个。

本篇要回答的核心问题是：

为什么不能按榜单选模型？¹ 自己的评测集要多大、怎么建、怎么用它选？² 闭源 API 与开源自托管怎么判断，大小模型分流的账怎么算？³ 供应商的弃用周期怎样进入选型决策？⁴

一、总览

1. 选型是四个问题

选型的四个问题
问题	内容	本文章节
这个任务值多少钱？	每任务可接受的成本上限；由业务价值倒推，不由模型价格正推	第五章
哪些候选能过质量门限？	在自己的评测集上跑；榜单只用来定候选范围	第二、三章
哪些硬约束先过滤？	数据驻留、上下文长度、多模态、知识截止、延迟 SLO、是否需要推理	第四、六章
供应商风险多大？	弃用周期、通知期、快照能否钉住、替代路径、多云可用性	第八章

四个问题的顺序：先用硬约束过滤（省掉不可能的候选），再用榜单缩到三五个，然后在评测集上跑，最后按每任务成本与供应商风险决定。

%% 图：选型的四步漏斗：硬约束过滤、榜单缩短名单、自己的评测集上跑、按每任务成本与供应商风险决定
flowchart TB
    A["全部候选（20+）"] -->|"硬约束过滤：数据驻留 · 上下文 · 多模态 · 延迟 · 推理"| C["可行候选（8–12）"]
    C -->|"榜单与同类经验，只做缩小范围"| E["短名单（3–5）"]
    E --> F["在自己的评测集上跑<br/>每模型 × 每 effort 档 × k 次"]
    F --> G{"过质量门限？"}
    G -->|"否"| H["放宽约束 / 加检索或微调（L3）/ 改任务形态（L7）"]
    G -->|"是"| I["按每任务成本排序"]
    I -->|"供应商风险：弃用周期 · 替代路径 · 多云"| K["选定主模型 + 替代模型<br/>写进配置，不写进代码"]

    classDef step fill:#fff7e0,stroke:#c98a00,stroke-width:2px,color:#222
    classDef dec fill:#eef6ff,stroke:#5b8fd6,color:#222
    class A,C,E,F,I,K,H step
    class G dec

图里只有一个环节用到榜单，而且是最不重要的环节。决定在评测集与每任务成本两步做出。

2. 本文的章节安排

第二章讲榜单为什么失真——动态榜单与静态 benchmark 各自的机制；第三章讲自己的评测集怎么建、怎么用；第四章讲闭源 API 与开源自托管的判据；第五章讲大小模型分流；第六章讲推理与否、上下文、多模态、知识截止四个过滤条件；第七章讲 embedding 与 rerank 模型的选法；第八章讲弃用周期与供应商风险；第九章实践建议。

二、榜单为什么失真

2.1 动态榜单：Chatbot Arena 的审计

Chatbot Arena（LMArena）让用户对两个匿名模型的回答投票，用 Bradley-Terry 模型算分。它一度是”哪个模型最好”的默认答案。2025 年发表于 NeurIPS 的《The Leaderboard Illusion》审计了它的数据，发现三件事：

私测与选择性披露。少数供应商可以在发布前把多个私有变体放进 Arena 测试，只公布分数最好的那个，撤回其余。审计在 2025 年 1–3 月的抓样里识别出 Meta 在 Llama 4 发布前测试了 27 个私有变体。论文用模拟与真实实验证明：即使这些变体是同一个 checkpoint，”多测几个、选最好”也能系统性抬高分数——这是统计学里的选择偏差，不需要任何作弊。
采样不对称。闭源模型被抽中对战的次数远高于开源模型，被下架的也少。估计 Google 与 OpenAI 各拿到了全部对战数据的 19.2% 与 20.4%，而 83 个开源模型合计只有 29.7%。
数据访问带来的收益。拿到 Arena 数据的供应商可以针对 Arena 的提问分布调优；论文的保守估计是，少量额外数据就能在 ArenaHard（Arena 分布的测试集）上带来最多 112% 的相对提升。结论：Arena 分数在相当程度上测量的是对 Arena 分布的过拟合，而不是通用能力。

这不是说 Arena 无用——它是唯一大规模的人类偏好数据。它说的是：Arena 分数是供应商在一个特定分布上、经过选择性披露后的偏好得分，与你的任务（内部知识库问答、工单分类、代码修改）的相关性未知。

%% 图：Arena 对战数据的分配（The Leaderboard Illusion 的估计）——Google 19.2%、OpenAI 20.4%，两家合计约四成；83 个开源模型合计只有 29.7%；拿到更多对战数据的供应商可以针对 Arena 的提问分布调优
%%{init: {"xyChart": {"width": 760, "height": 340, "plotReservedSpacePercent": 60}, "themeVariables": {"xyChart": {"plotColorPalette": "#c0392b, #5b8fd6, #4d9a5c"}}}}%%
xychart-beta
    title "谁拿到了 Arena 的对战数据（占全部对战的 %）"
    x-axis ["OpenAI（1 家）", "Google（1 家）", "其他闭源", "83 个开源模型合计"]
    y-axis "占比（%）" 0 --> 35
    bar [20.4, 19.2, 30.7, 29.7]

%% 图：私测与选择性披露怎么抬高分数——同一个 checkpoint 放 27 个变体进 Arena，每个的分数都带随机噪声，只公布最高的那个、撤回其余；即使没有任何真实差异，「多测几个取最好」也系统性地抬高公布分
flowchart TB
    CK["一个 checkpoint"] --> V["27 个私有变体<br/>各自在 Arena 上收集对战"]
    V --> S["27 个分数<br/>真实能力 + 各自的随机噪声"]
    S --> MAX["只公布最高的那个<br/>撤回其余 26 个"]
    MAX --> PUB["公布分 = 真实能力 + 最大的噪声<br/>系统性偏高（选择偏差）"]
    classDef step fill:#fff7e0,stroke:#c98a00,color:#222
    classDef bad fill:#fdecea,stroke:#c0392b,color:#222
    class CK,V,S step
    class MAX,PUB bad

2.2 静态 benchmark：污染与饱和

MMLU、GSM8K、HumanEval 一类的静态题库有两个结构性问题：

污染。题目在网上，训练数据来自网上。2024 年 Scale AI 用重新编写的 GSM1k 复测 GSM8K，发现部分模型族在新题上的准确率比原题低近十个百分点——它们部分记住了题。之后的做法是用”活”的题库（LiveBench、LiveCodeBench 定期换题）、私有题库（供应商看不到题），或者只信任发布日期晚于模型训练截止的题。
饱和。当前沿模型在一个 benchmark 上都到 90% 以上，它就不再能区分它们；benchmark 于是被更难的替代（MMLU → MMLU-Pro → GPQA Diamond → Humanity’s Last Exam），每一代新 benchmark 都有几年寿命。DeepSeek V4.1 Flash 的发布说明里列了 Terminal-Bench 2.1、3.0、4.0 三个版本的分数（90.6、30.0、31.2），同一个 benchmark 的相邻版本分数差三倍，正是饱和后加难的痕迹。

2.3 供应商自报的分数不可横比

每家的发布博客都有一张与竞品的对比表。它们不可横比的原因是条件不同：effort 档（max 与 high 差很多，第三篇）、是否允许工具、脚手架（agent 框架）、采样次数（pass@1 还是多次采样取最好）、题库版本。Anthropic 发布 Opus 5 时给的是”性能随 effort 变化”的曲线并注明”在 max 档”；OpenAI 强调”每任务成本”而不是分数。读这些表要先读脚注。

2.4 聚合指数与使用量

Artificial Analysis 一类的聚合指数把多个 benchmark 合成一个数，缓解了单一题库的问题，但仍是公开题库。OpenRouter 一类聚合网关公布的按 token 用量的排名是另一类信号——”显示性偏好”：开发者用钱投票的结果。它反映的是性价比与可用性的综合，不是能力。

2.5 榜单的正确用法

用榜单做三件事：定候选范围（Arena 前 15 与你预算内的模型的交集）、发现新模型（一个新名字进了前十，值得放进评测集跑一次）、识别明显不合适的（在与你任务最接近的 benchmark 上垫底的可以先排除）。不用榜单做的事：在两个分数相差 3 分的模型之间做选择——那点差距在你的任务上可能反向。

三、自己的评测集

3.1 从多小开始

评测集的规模常被高估。选型阶段：30–50 条就能把明显不合格的模型筛掉、把明显更好的选出来；几百条能看出趋势与回归；上千条是持续运营后自然积累的结果，不是开始的门槛。2026 年的模型在任务内的方差已经不大，几十条上的差距如果稳定（每条跑 3–5 次，第一篇），基本就是真的。

3.2 从哪里来

真实流量。从日志里采样用户真正问过的问题——不是产品经理想象的问题。覆盖三类：常见的（占流量大头，决定平均质量）、边界的（长输入、多轮、含表格、含图）、失败过的（线上 bad case，最有信息量）。选型之前没有流量的，从内部试用与竞品的公开案例里采；上线后第一件事是换成真实流量。

每条用例三部分：输入（完整的上下文，不只是用户那句话）、期望输出（人工标注，或一组可接受的答案，或一个判定规则）、评分方式。

3.3 怎么评分

按可自动化程度排：精确匹配与规则（分类标签、抽取字段、数值、代码能否通过测试）优先——确定、便宜、无偏；LLM-as-judge（用一个模型按评分标准给另一个模型的输出打分）用于自由文本，但 judge 有位置偏差、长度偏差、自我偏好，要与人工抽检对齐；人工用于最终把关与 judge 的校准。L5 系列讲评测方法本身，这里只说选型阶段的原则：能用规则的不用 judge，用 judge 的要抽 20 条人工核对一致率。

3.4 怎么用它选

对短名单里的每个模型，在每一档 effort 上跑评测集 $k$ 次，得到一张表：

短名单模型在各 effort 档的评测表
模型 · effort	质量（通过率，均值 ± 方差）	每任务成本（p50 / p95）	TTFT p50	总时长 p95
Sonnet 5 · low	0.91 ± 0.02	$0.004 / $0.009	0.6 s	3.1 s
Sonnet 5 · high	0.94 ± 0.01	$0.021 / $0.060	2.8 s	9.4 s
GPT-5.6 Terra · medium	0.93 ± 0.02	$0.012 / $0.031	1.9 s	6.0 s
Gemini 3.8 Flash · medium	0.92 ± 0.02	$0.005 / $0.014	1.1 s	4.2 s
DeepSeek V4.1 Flash · high（闲时）	0.90 ± 0.03	$0.001 / $0.004	1.5 s	7.8 s

（数字是示意，说明表的形状。）读法：先划质量门限（比如 0.92），门限以上的按每任务成本排，再看延迟是否满足 SLO。这张表通常会给出一个榜单给不出的答案——一个 Arena 排名靠后的模型在你的任务上过了门限而且便宜三倍。它也会给出”没有模型过门限”这个答案，那时该做的不是换模型，是加检索（L3）、改 prompt（L2）或改任务形态（L7）。

把表画出来，选型的答案一眼就出来了：

%% 图：短名单五个配置的质量（红线，通过率 %）与每任务成本 p50（蓝柱，千分之一美元）——质量门限画在 92：Sonnet 5 high、GPT-5.6 Terra、Gemini 3.8 Flash 三个过线，其中 Gemini 3.8 Flash 最便宜；DeepSeek 最便宜但没过线（示意数字）
%%{init: {"xyChart": {"width": 760, "height": 340, "plotReservedSpacePercent": 60}, "themeVariables": {"xyChart": {"plotColorPalette": "#c0392b, #5b8fd6, #4d9a5c"}}}}%%
xychart-beta
    title "质量（%）与每任务成本 p50（千分之一美元）——门限 92"
    x-axis ["Sonnet 5 low", "Sonnet 5 high", "Terra medium", "3.8 Flash medium", "DeepSeek high"]
    y-axis "质量 % / 成本（‰ 美元）" 0 --> 100
    line [91, 94, 93, 92, 90]
    bar [4, 21, 12, 5, 1]

红线是质量，蓝柱是成本。过 92 这条门限的有三个，其中 Gemini 3.8 Flash 每任务 0.005 美元，比 Sonnet 5 high 便宜四倍——Arena 上它们的排名顺序与此无关。

3.5 评测集也会过拟合

用同一组用例既调 prompt 又选模型，几轮之后 prompt 就”记住”了这些用例。留一部分用例只用于最终比较，不用于迭代；定期从新的 bad case 补充。评测集是资产，也要防止它退化——L5 的横切纪律。

四、闭源 API 还是开源自托管

4.1 2026 年的开源前沿

开放权重的模型在 2026 年不再是”能力差一代的替代品”：DeepSeek V4.1 Flash 以 MIT 许可开放了 552B 参数的 MoE 权重（输入激活 8B、输出激活 16B，1M 上下文），发布说明称其在多项 benchmark 上超过自家的 V4 Pro；Qwen、gpt-oss、Llama 系列各有多个尺寸。所以”闭源 vs 开源”不再主要是能力问题，是运营问题。

4.2 判据

自托管与 API 的判据
判据	倾向自托管	倾向 API
数据	数据不能出域（合规、客户合同）；API 的区域版本（US-only、非 Global 区域）不满足要求	无出域限制，或供应商的数据处理协议与 ZDR 已满足要求
规模	稳定的高吞吐（每天数十亿 token 以上）；自托管的每 token 成本已低于 API	流量小、波动大、不可预测
控制	需要固定权重（第一篇的非确定性硬需求、审计复现）、需要微调、需要特殊解码（结构化输出之外的约束）	接受供应商的模型更新节奏
能力	开源模型在你的评测集上过门限	只有闭源前沿模型过门限
团队	有 Infra 能力（GPU 采购或租用、serving 引擎、监控、容量规划——Infra 地图 08 / 11 的全部内容）	没有，或不想建

规模那一行的账粗略是这样：一张 H100 级 GPU 每小时租金几美元，用 vLLM 一类引擎跑一个 30B 级模型每秒可以服务上千 token，折成每百万 token 不到一美元；但这是满载的数字——利用率 20% 时成本翻五倍，而 API 按用量计费没有闲置成本。所以自托管划算的前提是流量稳定且高。中间路线是在云上用托管的开源模型（Bedrock、Vertex、各推理服务商）：模型开放、运营外包、按 token 计费——它把”开源”的控制权部分保留（可以固定版本）而不承担 Infra。

%% 图：自托管的每百万 token 成本随 GPU 利用率变化（示意）——满载时不到 1 美元，利用率 50% 翻倍、20% 时翻五倍；API 按用量计费是一条水平线；两线的交点就是「流量稳定且高到什么程度才划算」
%%{init: {"xyChart": {"width": 760, "height": 340, "plotReservedSpacePercent": 60}, "themeVariables": {"xyChart": {"plotColorPalette": "#c0392b, #5b8fd6, #4d9a5c"}}}}%%
xychart-beta
    title "每百万 token 的成本 vs GPU 利用率（示意，30B 级模型）"
    x-axis "GPU 利用率" ["10%", "20%", "30%", "50%", "70%", "100%"]
    y-axis "美元 / 百万 token" 0 --> 10
    line [9, 4.5, 3, 1.8, 1.3, 0.9]
    line [2, 2, 2, 2, 2, 2]

红线是自托管（满载 0.9 美元，利用率每降一半成本翻一倍），蓝线是一个 2 美元的 API。交点在 45% 左右：利用率稳定高于它才划算——而波动大的流量意味着平均利用率往往在 20–30%。

4.3 应用工程师要会的是判断

自托管的实现属于 Infra 地图（08 推理系统、11 平台）；应用工程师要会的是上面这张表的判断，以及自托管带来的接口差异——vLLM 提供 OpenAI 兼容接口，但结构化输出、缓存、工具调用的支持程度与四家不同，中间层（第二篇）的适配器要多一个。

五、大小模型分流

5.1 价格比

同一家的大小模型价差在 5–20 倍：GPT-5.6 Luna 与 Sol 是 20 倍（$0.20 vs $4），Haiku 4.5 与 Fable 5.1 是 10 倍，Gemini 3.5 Flash-Lite 与 3.1 Pro 是 6.7 倍。而多数应用的请求里有一大半是简单的——问候、分类、抽取、格式化。把简单请求路由到小模型，是成本优化里收益最大、风险可控的一项。

5.2 两种形态

路由：一个分类器（规则、小模型或专门的 router 模型）在请求进来时判断难度，直接分发。成本 = $f \cdot c_s + (1-f) \cdot c_l$，$f$ 是走小模型的比例。风险是路由错误：难题被送到小模型，质量下降且不被发现。

级联：先用小模型，输出附带置信信号（结构化输出里的 confidence 字段、是否触发拒答出口、judge 打分），不够则升级到大模型。成本 = $c_s + (1-f) \cdot c_l$——每个请求都先花一次小模型的钱，但难题不会漏。适合质量优先的场景。

两种都要在评测集上验证两件事：路由准确率（简单请求被正确识别的比例）与分流后的整体质量（不能比全用大模型掉超过门限）。评测集要能按难度分层，否则”整体 0.93”可能是简单题 0.99、难题 0.70 的平均。

5.3 一个数字

假设 70% 的请求可以走小模型，小模型每任务 $0.002、大模型 $0.03。全用大模型：$0.03。路由：$0.7 \times 0.002 + 0.3 \times 0.03 = 0.0104$，省 65%。级联：$0.002 + 0.3 \times 0.03 = 0.011$，省 63%——级联只比路由贵一点，却不漏难题。这是级联在多数场景下更受欢迎的原因。

%% 图：路由与级联两种分流形态——路由由分类器一次决定走大还是小，错分的难题不被发现；级联先走小模型，靠置信信号决定是否升级，每个请求多花一次小模型的钱但难题不漏；70% 简单请求下两者成本 0.0104 与 0.011 美元
flowchart TB
    subgraph RT["路由：f·c_s + (1−f)·c_l = 0.0104 美元"]
        direction LR
        R0["请求"] --> RC{"分类器判难度"}
        RC -->|"简单 70%"| RS["小模型 0.002"]
        RC -->|"难 30%"| RL["大模型 0.03"]
        RC -.->|"错判"| RX["难题进小模型<br/>质量掉、没人发现"]
    end
    subgraph CS["级联：c_s + (1−f)·c_l = 0.011 美元"]
        direction LR
        C0["请求"] --> CS1["先走小模型 0.002<br/>输出带置信信号"]
        CS1 -->|"置信够 70%"| CO["直接返回"]
        CS1 -->|"不够 / 触发拒答出口 30%"| CL["升级到大模型 0.03"]
    end
    RT ~~~ CS
    classDef step fill:#fff7e0,stroke:#c98a00,color:#222
    classDef dec fill:#eef6ff,stroke:#5b8fd6,color:#222
    classDef bad fill:#fdecea,stroke:#c0392b,color:#222
    classDef ok fill:#eefaf0,stroke:#4d9a5c,color:#222
    class R0,RS,RL,C0,CS1,CL step
    class RC dec
    class RX bad
    class CO ok

六、四个过滤条件

6.1 推理还是非推理

2026 年”非推理模型”几乎只剩下 effort none / low 或关闭 thinking 的档位。判断标准不是”任务难不难”，是评测集上 effort 曲线（第三篇）在哪一档饱和。分类、抽取、改写通常 low 饱和；多步 agent、代码修改、复杂分析到 high 以上还在涨。

6.2 上下文长度

标称都是 1M 级了，过滤条件变成两个：有效长度（第一篇：在你的资料上做针测）与加价门限（第四篇：OpenAI 272K、Gemini 3.1 Pro 200K）。一个经常要处理 300K 输入的任务，Anthropic 的无阶梯定价可能比标称更便宜的模型实际更便宜。

6.3 多模态

需要读图、读 PDF、听音频的任务过滤掉纯文本模型；DeepSeek V4.1 Flash 原生支持视觉而 V4 Pro 不支持，是一个反例（小模型有、大模型没有）。图片的 token 成本（第四篇）要算进每任务成本。

6.4 知识截止

第一篇第六章：同一家在售模型的截止日可以差一年多（Haiku 4.5 是 2025 年 2 月，Fable 5.1 是 2026 年 6 月）。任务依赖近期知识（新框架的 API、近期事件）且没有检索时，截止日是硬过滤条件；有检索时它不重要。

七、embedding 与 rerank

7.1 embedding

检索（L3）用的 embedding 模型是另一类选型，同样不能只看榜单：MTEB 是标准榜单，但它的任务分布与你的语料无关，且同样有针对榜单调优的问题。判据：

语言与领域：中文、代码、法律、医学各有专门模型或专门评测；通用榜单第一的模型在中文法律文书上未必好。
维度与延迟：维度越高存储与检索越贵；支持 Matryoshka（截断维度仍可用）的模型让你事后调整。
上下文长度：一个块（chunk）能有多长。
版本稳定性：换 embedding 模型意味着全量重建索引——所有文档重新向量化。这是 embedding 选型最大的隐藏成本，选一个供应商承诺长期维护的版本比选榜单第一重要。

评测方法与主模型相同：从真实查询里采几十条，标注相关文档，算 recall@k 与 MRR（L3 第七篇讲检索评测）。

7.2 rerank

cross-encoder 重排器对（查询，候选）对打分，比 embedding 的双塔结构精确，但要对每个候选算一次，只用于 top-k 之后的精排。它是 RAG 里性价比最高的一步（L3），选型判据是精排后的 recall 提升与延迟增加；候选有 Cohere、Voyage、BGE、Qwen3-Reranker 一类，同样在自己的查询上评。

八、供应商风险与弃用周期

8.1 2026 年的下线记录

2026 年的模型下线记录
供应商	事件	通知期
OpenAI	2026-07-23 关闭 `gpt-5-codex`、`gpt-5.1-codex` 系列、`gpt-4o-*-preview` 系列、`o3-deep-research` 等 2026-10-23 关闭 `gpt-3.5-turbo-0125`、`gpt-4-0613`、`gpt-4-turbo`、`gpt-4.1-nano`、`gpt-4o-2024-05-13`、`o1`、`o3-mini`、`o4-mini` 等 2026-12-11 关闭 `gpt-5-2025-08-07`、`gpt-5-mini`、`gpt-5-nano`、`gpt-5-pro`、`o3`、`o3-pro` 快照	3–6 个月（4 月 22 日与 6 月 11 日两轮通知）
OpenAI	2026-08-26 关闭 Assistants API	12 个月（2025-08-26 通知）
Anthropic	模型页写明”Retirement: not sooner than <发布日 + 1 年>”（Fable 5.1 不早于 2027-09-01，Opus 5 不早于 2027-07-24）；Opus 4 / 4.1、Sonnet 4 已退役（Bedrock / Google Cloud 上仍有）	承诺至少 1 年在售；退役前另发通知
Google	Interactions API 旧 schema 2026-06-08 移除（5 月通知）；模型按 deprecations 页给出的日期退役	schema 变更约 1 个月；模型通常 1 年
DeepSeek	2026-09-10 宣布，09-14 起 `deepseek-v4-pro` 全部路由到 V4.1 Flash；`deepseek-v4-flash` 与 `deepseek-v4-flash-vision-exp` 同日退役并”临时路由”到 V4.1 Flash	4 天

OpenAI 在 ChatGPT 侧退役 GPT-4o 时给出的理由是”只有 0.1% 的用户每天仍在选它”——供应商的视角是使用量，你的视角是”我的应用在那 0.1% 里”。

8.2 把弃用周期写进选型

把弃用周期写进选型的维度
维度	问什么	好的答案
通知期	从通知到关闭多久？	≥ 6 个月；DeepSeek 的 4 天意味着你要有自动化的回归与切换
快照	能否钉住一个不变的快照？别名（`gpt-5.6-sol`、`deepseek-flash`）背后会换	OpenAI 有日期快照 Anthropic 的模型 id 本身是版本 DeepSeek 只有别名
替代路径	供应商给出的替代模型是否行为兼容？	OpenAI 的弃用表列出推荐替代；但第三篇讲过替代模型的默认值不同，要重跑评测
多云	同一模型在几个云上有？	Claude 在 AWS / GCP / Azure 都有；一家云的区域故障不等于模型不可用
服务端状态	用了 Responses / Interactions 的服务端状态吗？	用了就多一层锁定；中间层保留自己的历史副本

8.3 变更管理的最小流程

订阅四家的弃用 / 变更通知（邮件、RSS、changelog）。
模型名进配置，每个用途配一个主模型与一个替代模型，替代模型定期（每月）在评测集上跑一次保持”热”。
收到通知当天在替代模型上跑全量评测集，比较三列，决定是否需要调 prompt 或 effort。
切换用灰度（L6）：1% → 10% → 100%，每一步看在线指标。
关闭日之前一周完成切换，不要等到当天。

%% 图：一个模型在你系统里的生命周期与应用侧的动作——进评测集、成为主模型、替代模型每月热身、收到弃用通知当天全量评测、灰度切换、关闭前一周完成；通知期从 OpenAI 的 3–6 个月到 DeepSeek 的 4 天
flowchart TB
    N["新模型发布"] -->|"过滤清单 → 进评测集"| E["评测集上跑全表"]
    E -->|"过门限、最便宜"| P["主模型（写进配置）"]
    E -->|"次优"| B["替代模型<br/>每月在评测集上热身一次"]
    P --> D["供应商弃用通知<br/>OpenAI 3–6 月 · Anthropic ≥ 1 年 · DeepSeek 4 天"]
    D -->|"当天"| R["在替代模型上跑全量评测<br/>调 prompt / effort"]
    R --> G["灰度切换 1% → 10% → 100%"]
    G -->|"关闭日前一周完成"| X["旧模型关闭"]
    B -.-> R
    classDef step fill:#fff7e0,stroke:#c98a00,color:#222
    classDef ok fill:#eefaf0,stroke:#4d9a5c,color:#222
    classDef bad fill:#fdecea,stroke:#c0392b,color:#222
    class N,E,R,G step
    class P,B ok
    class D,X bad

九、实践建议

今天就建评测集：从日志采 50 条（或从试用记录、竞品案例），标注期望，写一个跑分脚本。这是本系列最有长期价值的一个动作。
短名单跑一次全表：3–5 个模型 × 2–3 档 effort × 3 次，得到第三章的表。多数团队第一次做会推翻自己原来的选择。
算一次分流的账：看评测集里多大比例是”简单”用例，用第五章的公式估收益；先做级联。
过滤条件写成清单：数据驻留、有效上下文、多模态、知识截止、延迟 SLO，新模型出来先过清单再进评测。
模型名与替代模型进配置，订阅通知，替代模型每月热身。
embedding 模型选版本稳定的，并把”换模型 = 重建索引”的成本写进文档。

十、本文小结

榜单失真有机制：Arena 的私测与选择性披露（Llama 4 前 27 个变体）、采样不对称（两家各约 20% 的数据 vs 83 个开源模型共 29.7%）、对 Arena 分布的过拟合；静态 benchmark 有污染与饱和；供应商自报分数条件不一。榜单只用来缩小候选范围。
选型用自己的评测集：30–50 条从真实流量采样的用例就能开始，每个模型 × effort 档跑多次，看质量 / 每任务成本 / 延迟三列，划门限后按成本排。
闭源 vs 开源自托管在 2026 年是运营问题不是能力问题：数据出域、规模（自托管只在高且稳定的流量下划算）、控制需求、团队 Infra 能力四个判据；中间路线是云上托管的开源模型。
大小模型分流价差 5–20 倍；级联（先小后大）只比路由贵一点却不漏难题；要按难度分层验证。
四个过滤条件：effort 曲线饱和档、有效上下文与加价门限、多模态、知识截止。
embedding 选型最大的隐藏成本是换模型要重建索引；rerank 在自己的查询上评。
弃用周期是选型维度：OpenAI 3–6 个月通知分三批关闭二十多个快照，Anthropic 承诺至少一年，DeepSeek 4 天。模型名进配置、替代模型每月热身、收到通知当天跑评测、灰度切换。

十一、自测

《The Leaderboard Illusion》发现即使多个私有变体是同一个 checkpoint，”多测几个、公布最好的”也能抬高 Arena 分数。为什么？这对你读任何榜单有什么含义？

答案

Arena 分数是有噪声的估计（对战抽样、投票者差异）；同一模型测 $n$ 次得到 $n$ 个带噪声的分数，取最大值是有偏的——这是选择偏差，$n$ 越大偏差越大，不需要作弊。含义：任何允许提交者选择性披露的榜单，头部分数都系统性偏高；分差在噪声量级内的排名不可信；只用榜单缩范围。详见第二章。
你的评测集 40 条，模型 A 通过率 0.90、模型 B 0.85，各只跑了一次。能得出 A 更好的结论吗？该怎么做？

答案

不能。40 条上 2 条的差距（0.05）完全可能来自第一篇的非确定性。每条跑 3–5 次得到通过率的均值与方差，看差距是否稳定超过方差；同时看每任务成本与延迟两列——如果 B 便宜三倍且差距不稳定，答案可能是 B。详见第三章。
一个应用每天 2 亿 token，流量白天高、夜间接近零。团队算出自托管满载时每百万 token $0.8，API 是 $2。该自托管吗？

答案

不一定。$0.8 是满载数字；流量白天高夜间为零意味着平均利用率可能只有 30–40%，每 token 成本变成 $2–2.7，与 API 持平或更贵，且要承担 Infra 团队与容量规划成本。除非有数据出域或固定权重的硬需求，否则 API 或云上托管的开源模型更合适；或者只把可预测的白天基线自托管、峰值走 API。详见第四章。
小模型每任务 $0.003、大模型 $0.04，评测显示 60% 的请求小模型能做对。路由与级联各省多少？如果路由器有 10% 的错误率（把难题判为简单），会发生什么？

答案

全大模型 $0.04。路由：$0.6 \times 0.003 + 0.4 \times 0.04 = 0.0178$，省 55.5%。级联：$0.003 + 0.4 \times 0.04 = 0.019$，省 52.5%。路由器 10% 错误：约 4% 的总请求（难题的 10%）被小模型处理而质量下降且不被发现；级联没有这个问题（难题在小模型上会触发升级），代价只是每请求多 $0.003。详见第五章。
2026 年 9 月 10 日，一个在 deepseek-v4-pro 上调好 prompt 的应用收到 DeepSeek 的公告。按第八章的流程，它在 9 月 14 日之前该做完哪几件事？如果它只有别名没有快照，什么风险无法消除？

答案

四天内：在 V4.1 Flash 上跑全量评测集（含 effort 各档，V4.1 的 low / high / max 与 V4 Pro 的行为不同），比较质量 / 成本 / 延迟；必要时调 prompt 或 effort；把配置里的模型名与替代模型更新；灰度切换。无法消除的风险：DeepSeek 只有别名，deepseek-flash 背后的权重未来还会换，且通知期可能仍是几天——只能靠自动化的回归评测与替代模型（如另一家的同价位模型）保持热备。详见第八章。

因为榜单测的不是你的任务，且排名机制可被影响。《The Leaderboard Illusion》（NeurIPS 2025）审计 Chatbot Arena：少数供应商可以私测多个变体只公布最好的（Meta 在 Llama 4 前测了 27 个），这是选择偏差，同一 checkpoint 多测也能抬分；闭源模型拿到的对战数据远多于开源（Google、OpenAI 各约 19–20%，83 个开源模型共 29.7%），少量 Arena 数据就能在 ArenaHard 上带来最多 112% 的相对提升——分数部分测的是对 Arena 分布的过拟合。静态 benchmark 有污染（GSM1k 复测部分模型掉近十个点）与饱和（Terminal-Bench 2.1 → 4.0 分数从 90 掉到 31）；供应商自报分数的 effort、工具、脚手架、采样次数不一。榜单只用来缩小候选范围。详见第二章。 ↩
30–50 条就能选型，几百条看趋势；从真实流量采样，覆盖常见、边界、失败过的三类；每条含完整输入、期望输出、评分方式；评分优先规则与精确匹配，自由文本用 LLM-as-judge 并抽 20 条人工核对。用法：对短名单每个模型 × 每档 effort 跑 $k$ 次（3–5），得到质量（均值 ± 方差）/ 每任务成本（p50 / p95）/ TTFT / 总时长的表，划质量门限后按成本排、再看延迟 SLO；”没有模型过门限”时该加检索或改任务形态而不是换模型。留一部分用例不参与迭代防过拟合，定期从 bad case 补充。详见第三章。 ↩
闭源 vs 自托管在 2026 年是运营问题（DeepSeek V4.1 Flash 以 MIT 开放 552B 权重）：判据是数据能否出域、流量是否高且稳定（自托管的低价是满载数字，利用率 20% 时翻五倍）、是否需要固定权重 / 微调 / 特殊解码、团队有没有 Infra 能力；中间路线是云上托管的开源模型。大小分流：同家大小模型价差 5–20 倍（Luna / Sol 20×，Haiku / Fable 10×）；路由成本 $f c_s + (1-f) c_l$，级联 $c_s + (1-f) c_l$——70% 简单请求、$0.002 / $0.03 时路由省 65%、级联省 63%，级联不漏难题；要按难度分层验证整体质量与路由准确率。详见第四章、第五章。 ↩
作为一个维度进入短名单的比较：通知期（OpenAI 2026 年两轮通知、3–6 个月、分 7 月 / 10 月 / 12 月三批关闭二十多个快照；Assistants API 12 个月；Anthropic 承诺每个模型发布后至少一年在售；DeepSeek 4 天把 V4-Pro 全部流量路由到 V4.1 Flash）、能否钉住快照（OpenAI 有日期快照，DeepSeek 只有别名）、替代路径是否行为兼容（要重跑评测——默认值不同）、多云可用性、是否用了服务端状态。流程：订阅通知；模型名与替代模型进配置，替代模型每月在评测集上热身；收到通知当天跑全量评测；灰度切换；关闭日前一周完成。详见第八章。 ↩

模型作为组件（04）：成本与延迟的账——一次调用花多少钱、慢在哪一段

Fri, 02 Oct 2026 00:00:00 +0800

前三篇讲了组件怎么坏、接口长什么样。这一篇算账：一次调用花多少钱、慢在哪一段。这是应用工程师最容易忽略、又最先被账单教育的一层——demo 阶段每天几美元，上线后每天几千美元，而且账单上只有一个数字，看不出钱花在了 system prompt 的重复传输、还是推理模型的思考、还是那个把整份 PDF 塞进上下文的功能。

账有两本。成本：四种输入价（未缓存、缓存命中、缓存写入、长上下文加价）加一种输出价（含思考 token），批处理与峰谷的折价，多轮对话不做缓存时的二次增长。延迟：首 token 延迟分解为排队、prefill、思考三段，逐 token 速度由 decode 的内存带宽决定，总时长由输出长度主导——这些只需要 Infra 地图 08 系列前两篇的结论，本篇引用而不推导。两本账放在一起，才能回答”这个功能能不能做、该用哪个模型、缓存值不值”。

本篇要回答的核心问题是：

一次调用的成本公式是什么，四家 2026 年 9 月的价目差多少？¹ 缓存写入为什么额外收费、什么时候划算？² 为什么多轮对话的成本是二次增长，缓存能把它降到多少？³ TTFT 与逐 token 速度各由什么决定？⁴

一、总览

1. 成本公式

一次调用的成本：

\[C = n_{\text{in}} \, p_{\text{in}} + n_{\text{hit}} \, p_{\text{hit}} + n_{\text{write}} \, p_{\text{write}} + \left(n_{\text{out}} + n_{\text{think}}\right) p_{\text{out}}\]

五个量：$n_{\text{in}}$ 是未缓存的输入 token，$n_{\text{hit}}$ 是命中缓存的输入 token，$n_{\text{write}}$ 是本次写入缓存的输入 token（只有 OpenAI GPT-5.6 起与 Anthropic 对写入加价；Gemini 与 DeepSeek 的写入按普通输入价），$n_{\text{out}}$ 是可见输出，$n_{\text{think}}$ 是思考 token（第三篇）。三者的关系：$n_{\text{in}} + n_{\text{hit}} + n_{\text{write}}$ 等于请求的总输入 token 数。长上下文加价是对整个请求乘一个系数（OpenAI 272K 以上、Gemini 3.1 Pro 200K 以上）。

这个公式的每一项都能在响应的 usage 字段里找到对应的数：OpenAI 的 input_tokens / input_tokens_details.cached_tokens / output_tokens / output_tokens_details.reasoning_tokens，Anthropic 的 input_tokens / cache_read_input_tokens / cache_creation_input_tokens / output_tokens，DeepSeek 的 prompt_cache_hit_tokens / prompt_cache_miss_tokens。用 usage 核对账单是这一层的基本纪律。

2. 四家的价目（2026 年 9 月）

每百万 token，美元。”读”是缓存命中价，”写”是缓存写入价。

四家的价目
供应商	模型	输入	读	写	输出	备注
OpenAI	GPT-6 Astra	10.00	1.00	12.50	50.00	>272K：输入与缓存 2×、输出 1.5×；Fast mode 2×
	GPT-5.6 Sol	4.00	0.40	5.00	20.00	8 月 21 日起三个月的促销价（降 20% 以上）；>272K 同上
	GPT-5.6 Terra	2.00	0.20	2.50	12.00
	GPT-5.6 Luna	0.20	0.02	0.25	1.20
Anthropic	Claude Fable 5.1	10.00	0.25	12.50（5 分钟）/ 20.00（1 小时）	50.00	读价是 Fable 5 的四分之一
	Claude Opus 5	5.00	0.50	6.25 / 10.00	25.00
	Claude Sonnet 5	2.00	0.20	2.50 / 4.00	10.00	引入价于 8 月 10 日转为永久
	Claude Haiku 4.5	1.00	0.10	1.25 / 2.00	5.00
Google	Gemini 3.8 Flash	0.75	0.075	—	3.75	引入价至 2026-12-31，2027 年起 1.50 / 7.50；显式缓存另收存储费 0.50 / 百万 token·小时
	Gemini 3.1 Pro（preview）	2.00	0.20	—	12.00	>200K：4.00 / 0.40 / 18.00
	Gemini 3.5 Flash-Lite	0.30	0.03	—	2.50
DeepSeek	V4.1 Flash（闲时）	0.15	0.003	—	0.60	峰时 ×2（工作日 UTC 01–04、06–10）；周末全闲时

三个观察：

跨度三个量级。同样一百万输入 token，GPT-6 Astra 与 Fable 5.1 是 10 美元，DeepSeek 闲时是 0.15 美元，命中缓存是 0.003 美元。选型（第五篇）的第一问不是”哪个最好”，是”这个任务值多少钱”。
输出价是输入价的 4–6 倍。Sonnet 5 是 5 倍，GPT-5.6 Sol 是 5 倍，Gemini 3.8 Flash 是 5 倍，DeepSeek 是 4 倍，Astra 是 5 倍。思考 token 按输出价，所以推理模型让这个比例更致命。
缓存读价是输入价的 1/10 到 1/50。OpenAI 与 Anthropic 多数模型 0.1×，Fable 5.1 0.025×，DeepSeek 0.02×。Anthropic 说 Fable 5.1 降读价的动机是 agent 场景里”缓存命中的费用往往占比最高”——DeepSeek 发布 V4.1 时说了同一句话，并把 KV cache 的压缩（HBM 需求减到 1/4、SSD 减到 1/8）作为降价的技术原因。

3. 本文的章节安排

第二章逐项讲账上的输入侧：缓存的机制、门限、TTL 与收支平衡；第三章讲输出侧与思考；第四章讲折价——批处理、Flex、峰谷——与加价——长上下文、Fast mode、区域；第五章推导多轮对话的二次增长与缓存的效果；第六章讲延迟的分解；第七章把两本账合成”每任务成本”与预算；第八章实践建议。

二、输入侧：缓存的账

1. 缓存的是什么

prompt caching 缓存的是前缀的 KV cache：模型读过一段上下文之后的内部状态。下一次请求如果以逐字节相同的前缀开头，供应商跳过这段的 prefill，直接从缓存的状态继续。所以它同时省两样东西：钱（命中部分按读价）与时间（TTFT 里的 prefill 段消失）。它不缓存输出，不缓存”语义相同”的请求（那是应用层的语义缓存，L6）。

前缀必须逐字节相同的含义：system prompt、工具定义、few-shot 示例放在最前面且不变；动态内容（当前日期、用户名、检索结果）放在后面。一个把”今天是 2026-10-02 14:23”写在 system 开头的应用，每分钟都在让全部缓存失效。

%% 图：缓存前缀的顺序与失效的连锁——tools → system → 历史消息 → 当前消息，前缀逐字节相同才命中；改动任何一段，它后面的全部失效；把时间戳写进 system 开头，等于每分钟从头失效一次
flowchart TB
    T["① tools<br/>工具定义"] --> S["② system<br/>指令 · few-shot"] --> H["③ 历史消息<br/>只追加"] --> U["④ 当前消息 + 检索结果<br/>每次都不同，本来就不缓存"]
    T -.->|"改一个工具的描述"| X1["② ③ ④ 全部失效"]
    S -.->|"system 开头写「今天 14:23」"| X2["③ ④ 每分钟失效一次"]
    H -.->|"把中间一轮换成摘要"| X3["从那一轮起失效"]
    classDef hit fill:#eefaf0,stroke:#4d9a5c,color:#222
    classDef dyn fill:#fff7e0,stroke:#c98a00,color:#222
    classDef bad fill:#fdecea,stroke:#c0392b,color:#222
    class T,S,H hit
    class U dyn
    class X1,X2,X3 bad

2. 四家的机制

四家的 prompt cache 机制
	声明方式	最小长度	TTL	写入价	读价
OpenAI	自动；GPT-5.6 起断点在”最近一条可缓存消息的末尾”，早期模型按固定间隔	1,024 token，按 128 的倍数向下取整	默认分钟级，部分模型支持延长保留	GPT-5.6 起 1.25×；GPT-5.5 及更早无写入费	0.1×
Anthropic	显式：`cache_control` 放在具体的块上（最多 4 个断点，20 块回看窗口）；或顶层一个 `cache_control` 自动放到最后一个可缓存块	按模型 1,024 token 起（部分模型 2,048 或更高），不足则静默不缓存	5 分钟（每次命中免费刷新）；可选 1 小时	5 分钟 1.25×；1 小时 2×	0.1×（Fable 5.1 为 0.025×）
Google	隐式（自动）+ 显式（创建缓存对象，按小时收存储费）	模型相关	隐式短；显式按你设的 TTL	普通输入价 + 存储费	0.1×
DeepSeek	自动，磁盘级前缀缓存	64 token 粒度	数小时到数天	普通输入价	约 0.02×

缓存的顺序是 tools → system → messages（Anthropic 明写，其余同理）：改工具定义会让 system 与消息全部失效，改 system 会让消息失效。这就是第二篇说”工具定义放在稳定的前缀位置”的原因。

3. 写入为什么收费，什么时候划算

OpenAI（GPT-5.6 起）与 Anthropic 对写入收 1.25× 的价：把 KV 存下来有存储与管理成本，供应商要你为”可能用不上”的缓存付一点保证金。收支平衡的算术（以 1.25× 写、0.1× 读为例）：

写一次 + 读一次 = 1.25 + 0.1 = 1.35×，对比不缓存处理两次 = 2×。读一次就回本。
写一次 + 读九次 = 1.25 + 0.9 = 2.15×，对比 10×。
Anthropic 的 1 小时缓存写 2×：写一次 + 读一次 = 2.1×，对比 2×，不回本；读两次 = 2.2× 对比 3×，回本。所以 1 小时 TTL 适合”确定会被反复读、但间隔可能超过 5 分钟”的前缀（低频用户的会话、后台任务的 system）。

不划算的情况只有一种：前缀只用一次。典型是单次批处理任务里每条请求都带不同的长文档——那不是缓存的场景，是批处理（第四章）的场景。

%% 图：同一个前缀被处理 n 次的累计费用（以不缓存处理一次为 1）——不缓存是一条 45° 直线；5 分钟缓存写 1.25 读 0.1，第 2 次就低于不缓存；1 小时缓存写 2，要到第 3 次才回本
%%{init: {"xyChart": {"width": 760, "height": 340, "plotReservedSpacePercent": 60}, "themeVariables": {"xyChart": {"plotColorPalette": "#c0392b, #5b8fd6, #4d9a5c"}}}}%%
xychart-beta
    title "同一前缀处理 n 次的累计费用（单位：一次全价 prefill）"
    x-axis "处理次数 n" [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
    y-axis "累计费用" 0 --> 10
    line [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
    line [1.25, 1.35, 1.45, 1.55, 1.65, 1.75, 1.85, 1.95, 2.05, 2.15]
    line [2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9]

红线不缓存，蓝线 5 分钟 TTL，绿线 1 小时 TTL。蓝线在 n = 2 就穿到红线下方，绿线要到 n = 3；之后两条缓存线几乎平着走——这就是「二次项系数乘 0.1」在下一章的样子。

4. 命中率是一个要监控的指标

命中率 = $n_{\text{hit}} / (n_{\text{in}} + n_{\text{hit}} + n_{\text{write}})$。多轮对话与 agent 场景下正常值在 70–90%；掉到 30% 以下通常是三件事之一：前缀里混进了动态内容、历史被修改（第三篇第五章）、请求间隔超过 TTL。Anthropic 静默不缓存不足门限的块，OpenAI 也只在达到 1,024 token 后开始——一个 800 token 的 system prompt 永远不会被缓存，这不是 bug。

三、输出侧：可见输出与思考

输出价是输入价的 4–6 倍，且不能缓存。控制输出成本只有三个手段：

控制思考：effort 选档（第三篇）。这是推理模型上最大的一项。
控制回答长度：在 prompt 里要求简洁、用结构化输出去掉寒暄、max_tokens 兜底（但截断有代价，第二篇）。
别让模型输出可以由代码产出的东西：让它返回一个 id 而不是复述整条记录，返回 diff 而不是整个文件。

一个反直觉的账：一次 agent 任务里，输出侧的成本常常小于输入侧。20 步的循环，每步输入是累积的历史（几万 token），输出是几千 token 的思考加几百 token 的调用——输入 token 总量是输出的 5–10 倍，但输入大半命中缓存打一折，两边最后差不多。所以两边都要看。

%% 图：一次 20 步 agent 任务的账，输入侧与输出侧各占一半——输入 token 总量是输出的 5–10 倍，但大半命中缓存打一折；输出（思考 + 调用）不到输入的十分之一，却按 4–6 倍的输出价全价计
flowchart TB
    subgraph IN["输入侧：每步读累积的历史"]
        direction TB
        I1["20 步 × 几万 token ≈ 60 万 token"] --> I2["其中 80–90% 命中缓存 → 0.1×"] --> I3["等效全价 ≈ 10 万 token × 输入价"]
    end
    subgraph OUT["输出侧：每步的思考 + 调用"]
        direction TB
        O1["20 步 × 3,000 思考 + 300 调用 ≈ 6.6 万 token"] --> O2["不能缓存，全价"] --> O3["6.6 万 token × 输出价（= 5 × 输入价）"]
    end
    I3 & O3 --> EQ["两边差不多：都要看<br/>输入侧靠缓存 + 压缩，输出侧靠 effort"]
    classDef inp fill:#eefaf0,stroke:#4d9a5c,color:#222
    classDef outp fill:#fdecea,stroke:#c0392b,color:#222
    classDef n fill:#eef6ff,stroke:#5b8fd6,color:#222
    class I1,I2,I3 inp
    class O1,O2,O3 outp
    class EQ n

四、折价与加价

1. 批处理：50%，24 小时

四家都有批处理接口（OpenAI Batch、Anthropic Batch、Gemini Batch、DeepSeek 无独立批处理但有峰谷），价格 50%，代价是异步——提交一批请求，供应商在 24 小时内（通常几小时）返回结果。适合的场景：离线评测（第五篇的评测集跑分）、数据回填、每日报告生成、embedding 全量重算。不适合任何用户在等的场景。Anthropic 在 Opus 5 的批处理上还提供了 300K 的最大输出（beta），比在线的 128K 高。

2. Flex 与 Priority：用延迟换价格，或反过来

OpenAI 的 Flex processing 与 Gemini 的 Flex inference 是”同步但可能排队”的折价档（OpenAI 50%）：请求走低优先级队列，高峰时可能返回资源不可用要你重试。反方向是 Priority / Fast mode：GPT-6 Astra 的 Fast mode 2× 价格换最多 2× 速度；Anthropic 的 Opus 4.6 Fast mode 是标准价的 6 倍（$30 / $150）；Gemini 有 Priority inference。这三档加上标准档，是同一个模型的四个价格，按延迟要求选：用户在等 → 标准或 Priority；后台 → Flex；离线 → Batch。

3. 峰谷：DeepSeek 的定价

DeepSeek 自 2026 年 8 月起按时段计价：工作日 UTC 01:00–04:00 与 06:00–10:00（北京时间 09–12、14–18，正是中国的工作时间）为峰时，价格是闲时的 2 倍；周末全部闲时。V4.1 Flash 闲时 $0.15 / $0.60、峰时 $0.30 / $1.20。这是把 GPU 集群的负载曲线直接写进价目：应用侧可做的事是把批处理与非紧急任务调度到闲时——DeepSeek 自己的说法是”鼓励用户根据实际使用情况调整任务时间”。

4. 长上下文加价

KV cache 随上下文线性增长、注意力计算随上下文平方增长（Infra 地图 04 系列的 KV 篇），供应商把这个成本写成阶梯价：OpenAI 对超过 272K 输入 token 的请求，输入与缓存价 2×、输出价 1.5×，对整个请求生效（不是超出部分）；Gemini 3.1 Pro 在 200K 以上输入价 2×、输出 1.5×。Anthropic 的 5 系列 1M 上下文是默认且唯一的档，没有阶梯。所以”把 300K 的资料塞进 GPT-6 Astra”不只是 300K × $10，是 300K × $20 加输出 × $75；第一篇讲的有效上下文问题在这里有了价格。

5. 区域与推理位置

Anthropic 的价目表区分 Global 与 US-only inference（后者 +10%）；Gemini 的 Vertex 价目区分 Global 与非 Global 区域（后者约 +10%）。数据驻留要求（L6 治理）直接体现为 10% 的加价。

6. 多模态输入

图片按面积折算 token。Anthropic 的公式约为宽 × 高 ÷ 750，一张 1024 × 1024 的图约 1,400 token；OpenAI 按 512 像素的 tile 计，一张 1024² 高清图几百到上千 token；Gemini 按固定 token 每图（历史上 258）或按 tile。音频按秒折算。这些数字都在各家的 token 计数文档里；账上的含义是一张图 ≈ 一页文字，一个上传十张截图的请求就是一万 token 的输入。视频按帧采样后累加，一分钟视频可以是几万 token。共享《Transformer 与 LLM》系列第十三篇讲多模态成本的来源。

五、多轮对话：二次增长与缓存

1. 不做缓存时

设 system + 工具定义为 $S$ token，每轮新增（用户消息 + 模型回答）平均 $m$ token。第 $k$ 轮请求的输入是 $S + (k-1) m$。$N$ 轮的输入总量：

\[\sum_{k=1}^{N} \left[ S + (k-1) m \right] = N S + \frac{N(N-1)}{2} m\]

二次项来自历史被反复传输与 prefill。取 $S = 5{,}000$、$m = 500$、$N = 40$：$40 \times 5{,}000 + 780 \times 500 = 200{,}000 + 390{,}000 = 590{,}000$ 输入 token。用 Sonnet 5 的 $2 算是 $1.18，其中历史部分 $0.78 占三分之二。第 40 轮单次请求 24,500 token 是第 1 轮的近 5 倍。

2. 做缓存时

缓存命中后，每轮只有新增的部分是未缓存输入，之前的全部按读价。第 $k$ 轮：新增 $m$（上一轮的用户消息与回答；首轮是 $S$ + 首条用户消息）按写入价（若有）计一次，其余 $S + (k-2) m$ 按读价。以 0.1× 读、1.25× 写计，$N$ 轮输入的等效全价 token：

\[\approx 1.25 \left( S + N m \right) + 0.1 \left[ (N-1) S + \frac{(N-1)(N-2)}{2} m \right]\]

代入同样的数：$1.25 \times 25{,}000 + 0.1 \times (195{,}000 + 741 \times 500) = 31{,}250 + 0.1 \times 565{,}500 = 87{,}800$ 等效 token，是不缓存的 15%。二次项没有消失，但系数乘了 0.1；对 Fable 5.1（0.025×）或 DeepSeek（0.02×）系数更小，二次项几乎被抹平——这就是两家降读价时说的”agent 场景缓存费用占比最高”。

%% 图：40 轮对话的累计输入费用（等效全价 token，千）——不缓存是一条抛物线，到第 40 轮累计 590K；缓存（读 0.1×、写 1.25×）把它压成接近直线，累计 88K，是前者的 15%；S = 5,000、m = 500
%%{init: {"xyChart": {"width": 760, "height": 340, "plotReservedSpacePercent": 60}, "themeVariables": {"xyChart": {"plotColorPalette": "#c0392b, #5b8fd6, #4d9a5c"}}}}%%
xychart-beta
    title "累计输入费用随轮数增长（等效全价 token，千；S = 5,000，m = 500）"
    x-axis "轮数 N" [1, 5, 10, 15, 20, 25, 30, 35, 40]
    y-axis "等效全价 token（千）" 0 --> 600
    line [5, 30, 72, 128, 195, 275, 368, 472, 590]
    line [7, 12, 19, 27, 37, 48, 60, 73, 88]

红线不缓存、蓝线缓存。第 1 轮蓝线反而略高（写入价 1.25×），从第 2 轮起就反超，往后差距按平方拉开。

轮次 k 的输入构成（客户端状态，历史只追加）：

k=1  [ S ─────────────][u1]                            全部写入（1.25×）
k=2  [ S ─────────────][u1][a1][u2]                    S,u1 命中（0.1×）  a1,u2 写入
k=3  [ S ─────────────][u1][a1][u2][a2][u3]            S..u2 命中          a2,u3 写入
 ...
k=N  [ S ─────────────][u1][a1] ... [a(N-1)][uN]       前缀全部命中        最后两块写入

任何一处修改（改 S、删中间一轮、换工具定义）→ 从改动处起全部变成未缓存 + 写入

3. 前提

这个 15% 依赖三个前提，破坏任何一个都退回二次增长：历史只追加不修改（第三篇第五章）；请求间隔小于 TTL（5 分钟内下一轮；用户离开十分钟再回来，第一次请求要重写整个前缀）；前缀里没有动态内容。多轮对话的成本优化，一半是缓存机制，一半是不要破坏它。

4. 历史压缩是另一半

缓存把系数压到 0.1，但第 $k$ 轮的输入长度仍是 $S + (k-1) m$——第一篇的有效上下文问题与本章的长上下文加价门限都在逼近。所以长对话还要做历史压缩：到某个长度把早期轮次摘要成一段（L2 上下文工程、L4 的 compaction）。压缩会让缓存失效一次（前缀变了），之后以更短的前缀重新累积。两者是配合关系：缓存管每轮的价，压缩管每轮的量。

六、延迟的分解

1. 一次调用的时间线

%%{init: {"flowchart": {"wrappingWidth": 420}}}%%
%% 图：一次调用的时间线：排队 → prefill → 思考 → 首个可见 token（TTFT 结束）→ decode → 最后一个 token
flowchart TB
    Q["排队<br/>供应商侧的负载 · 你的限流队列"] --> P["prefill<br/>读完整上下文，∝ 未缓存输入长度<br/>命中缓存的前缀跳过"]
    P --> T["思考<br/>∝ 思考 token 数 × 每 token 时间<br/>由 effort 决定"]
    T --> F(["首个可见 token（TTFT 在此结束）"])
    F --> D["decode<br/>每 token 一步，速度由内存带宽决定<br/>总时长 ∝ 输出 token 数"]
    D --> E(["最后一个 token（总时长）"])

    classDef seg fill:#fff7e0,stroke:#c98a00,stroke-width:2px,color:#222
    classDef mark fill:#f0f0f0,stroke:#888,color:#222
    class Q,P,T,D seg
    class F,E mark

TTFT = 排队 + prefill + 思考。总时长 = TTFT + 输出 token 数 × 每 token 时间（TPOT）。用户在流式界面里感知的是 TTFT 与 TPOT（字出来得快不快），非流式界面感知的是总时长。

2. 每一段由什么决定

延迟各段的决定因素
段	决定因素	你能做的
排队	供应商当时的负载；你自己客户端的并发限制与限流重试	选 Priority / Fast 档控制自己的并发避开峰时
prefill	未缓存输入的长度（compute-bound：算力决定，长上下文线性变慢）；缓存命中的前缀直接跳过	缓存前缀缩短上下文检索代替堆料
思考	思考 token 数 × TPOT	effort 选档
decode	每 token 一次前向，读一遍权重与 KV——memory-bound，速度由 GPU 内存带宽与模型大小决定，与你的输入几乎无关	小模型更快要求简洁 Fast mode

prefill 为什么是 compute-bound 而 decode 是 memory-bound，Infra 地图 08 系列的前两篇讲透了；应用工程师只需要记结论：输入长度影响 TTFT，输出长度影响总时长，模型大小影响 TPOT。一个 TTFT 异常长的请求，先查这三样：输入是不是很长且没命中缓存、effort 是不是高、供应商是不是在排队（看状态页与 429 / 529 比例）。

3. 量级

2026 年公开 API 的典型量级（因模型、负载而异，只作为判断异常的参照）：命中缓存的短请求 TTFT 几百毫秒；50K 未缓存输入的 prefill 秒级；high effort 的思考几秒到几十秒；TPOT 从小模型的十几毫秒到大模型的几十毫秒——也就是每秒 20–80 个 token。一个 800 token 的回答在 30 ms/token 下要 24 秒，用户不开流式会认为它卡死了。这是第二篇说”流式是默认”的原因。

4. 尾延迟

p50 与 p99 的差通常来自排队与重试，不来自模型。一个 p50 = 2 s、p99 = 20 s 的接口，p99 那些请求多半是被限流后退避重试的（第六篇），或者赶上了供应商的过载。延迟 SLO 要按分位数定，并把重试的时间算进去。

七、每任务成本与预算

1. 从每 token 到每任务

价目是每 token 的，产品关心的是每任务的：一次客服会话、一次代码修改、一份报告。每任务成本 = 调用次数 × 每次调用成本，而调用次数在 agent 场景里是不确定的（模型决定循环几步）。所以要在 trace（L5）里按任务聚合四类 token 与思考 token，得到每任务成本的分布——p50 与 p95 都要看，agent 任务的 p95 常常是 p50 的 5–10 倍（那些走了弯路的轨迹）。

%% 图：从每 token 价到每任务成本——一次任务 = 不确定步数的调用，每次调用 = 五项 token × 价目；在 trace 里按任务聚合后看的是分布：p50 是正常轨迹，p95 是走了弯路的那 5%，常是 p50 的 5–10 倍
flowchart TB
    P["价目表<br/>每百万 token 的五个价"] --> C["一次调用的成本<br/>五项 usage × 单价"]
    C --> T["一次任务<br/>= 模型决定的 N 次调用<br/>N 不确定"]
    T --> A["trace 里按 task_id 聚合<br/>（L5）"]
    A --> D1["p50：正常轨迹<br/>例：8 步，0.12 美元"]
    A --> D2["p95：走弯路的轨迹<br/>例：40 步，0.9 美元"]
    D1 & D2 --> B["预算与降级按 p95 定<br/>比模型时比每任务成本，不比每 token 价"]
    classDef step fill:#fff7e0,stroke:#c98a00,color:#222
    classDef ok fill:#eefaf0,stroke:#4d9a5c,color:#222
    classDef bad fill:#fdecea,stroke:#c0392b,color:#222
    classDef n fill:#eef6ff,stroke:#5b8fd6,color:#222
    class P,C,T,A step
    class D1 ok
    class D2 bad
    class B n

一个便宜的模型不一定便宜：如果它需要更多步才完成任务、或者完成率低要人工兜底，每任务成本可能更高。OpenAI 为 GPT-6 Astra 的定价辩护时说的正是这个——”训练它用更少的 token、更少的重试完成任务”，所以”每任务价格”才是该比的。这个论点是否成立要用你的评测集验证（第五篇），但比较的单位是对的。

2. 预算与告警

按功能 / 按用户 / 按租户设 token 预算（L6），超出告警或降级到便宜的模型；
每天用 usage 字段汇总与账单核对，差异超过 5% 要查（常见原因：漏记了思考 token、漏记了服务端工具的调用费、Batch 与在线混在一起）；
缓存命中率、思考占比、平均轮次、p95 每任务成本四个指标上仪表盘。

八、实践建议

把公式写成代码：一个 cost(usage, model, region, tier) 函数，价目表放配置，用每天的 usage 汇总核对账单。
审计前缀：打印你的请求体，检查 system 与工具定义之前有没有任何动态内容；测量命中率，目标 > 70%。
算一次多轮的账：用你的 $S$、$m$、典型 $N$ 代入第五章的两个公式，看缓存给你省了多少、还剩多少要靠压缩。
给每类请求选延迟档：用户在等 → 标准；后台 → Flex；离线 → Batch（评测集跑分一律走 Batch，省一半）。中国时区的 DeepSeek 用户把批任务放到北京时间 18 点后。
TTFT 异常时按三段排查：输入长度与命中率 → effort → 供应商状态。
按任务而不是按 token 报成本，看分布不看均值。

九、本文小结

成本公式有五项：未缓存输入、缓存命中、缓存写入、可见输出、思考；每一项都在 usage 里有对应字段，用它核对账单。
2026 年 9 月四家价目跨三个量级；输出价是输入价的 4–6 倍；缓存读价是输入价的 1/10 到 1/50。
缓存的是逐字节相同前缀的 KV；顺序 tools → system → messages；OpenAI 与 Anthropic 对写入收 1.25×（1 小时 TTL 2×），读一次就回本；不足最小长度（按模型 1,024 token 起）的块静默不缓存。
折价：Batch 50% 异步、Flex 50% 可能排队、峰谷（DeepSeek 峰时 2×）；加价：长上下文（OpenAI >272K 输入 2× 输出 1.5×，Gemini 3.1 Pro >200K）、Fast mode（2× 到 6×）、区域（+10%）。
多轮对话不缓存时输入总量是 $NS + N(N-1)m/2$，二次增长；缓存把二次项系数乘 0.1，总量降到约 15%，前提是历史只追加、间隔小于 TTL、前缀无动态内容；长度本身要靠压缩。
TTFT = 排队 + prefill（∝ 未缓存输入）+ 思考（∝ effort）；总时长由输出 token 数 × TPOT 主导，TPOT 由模型大小决定；p99 多来自排队与重试。
比较模型要用每任务成本的分布，不用每 token 价。

十、自测

一个请求在 Claude Opus 5 上：system 3,000 token（已缓存，5 分钟 TTL 内）、新增用户消息 500 token、思考 2,000、回答 400。用 2026 年 9 月价目算成本，并算出如果 system 没有命中缓存要多花多少。

答案

命中：3,000 × 0.50 + 500 × 5 + 2,400 × 25 = 1,500 + 2,500 + 60,000 = 64,000 微美元 = $0.064。未命中（且本次写入，1.25×）：3,000 × 6.25 = 18,750 替代 1,500，多花 17,250 微美元 ≈ $0.017，总 $0.081。注意即使命中，输出侧（$0.060）仍占 94%——这个请求的成本主要在思考。详见第一章、第三章。
Anthropic 的 1 小时缓存写入价是 2×。一个前缀在写入后被读了一次就不再使用，与不缓存相比是省了还是亏了？至少读几次才回本？5 分钟 TTL 呢？

答案

1 小时：写 2× + 读 0.1× = 2.1×，不缓存两次 = 2×，亏 0.1×；读两次 2.2× 对比 3×，回本——至少读 2 次。5 分钟：写 1.25× + 读 0.1× = 1.35× 对比 2×，读 1 次就回本。详见第二章。
一个客服应用 system + 工具定义 8,000 token，每轮新增 400 token，平均 25 轮。不做缓存与做缓存（0.1× 读、1.25× 写）各是多少等效全价输入 token？

答案

不缓存：$25 \times 8{,}000 + \frac{25 \times 24}{2} \times 400 = 200{,}000 + 120{,}000 = 320{,}000$。缓存：$1.25 \times (8{,}000 + 25 \times 400) + 0.1 \times (24 \times 8{,}000 + \frac{24 \times 23}{2} \times 400) = 1.25 \times 18{,}000 + 0.1 \times (192{,}000 + 110{,}400) = 22{,}500 + 30{,}240 = 52{,}740$，约为不缓存的 16.5%。详见第五章。
某接口 p50 TTFT 为 0.8 s，某天起 p50 变成 6 s，输出速度不变。按本文的分解列出三个最可能的原因与各自的检查方法。

答案

（1）缓存失效：有人在 system 前缀里加了动态内容或改了工具定义——看命中率是否骤降；（2）effort 变了：模型升级把 thinking 默认开启（如迁到 Sonnet 5）或有人调高了 effort——看思考 token 数；（3）供应商排队：负载高或过载——看状态页与 429 / 529 比例，以及是否只在特定时段。输出速度不变排除了 decode 侧与模型大小的变化。详见第六章。
把 300K token 的资料一次放进 GPT-6 Astra，输出 2,000 token（含思考）。成本多少？如果先检索出最相关的 20K 再放进去呢？

答案

300K 超过 272K 门限，整个请求输入 2×、输出 1.5×：300,000 × 20 + 2,000 × 75 = 6,000,000 + 150,000 = $6.15。20K：20,000 × 10 + 2,000 × 50 = 200,000 + 100,000 = $0.30，约 1/20；同时避开了第一篇的有效上下文问题与 prefill 的秒级 TTFT。详见第四章。

$C = n_{\text{in}} p_{\text{in}} + n_{\text{hit}} p_{\text{hit}} + n_{\text{write}} p_{\text{write}} + (n_{\text{out}} + n_{\text{think}}) p_{\text{out}}$，五项都在 usage 里有字段；长上下文加价对整个请求乘系数。2026 年 9 月每百万 token：GPT-6 Astra $10 / $50（读 $1、写 $12.5），GPT-5.6 Sol $4 / $20、Terra $2 / $12、Luna $0.20 / $1.20；Claude Fable 5.1 $10 / $50（读 $0.25）、Opus 5 $5 / $25、Sonnet 5 $2 / $10、Haiku 4.5 $1 / $5；Gemini 3.8 Flash $0.75 / $3.75（引入价，2027 年翻倍）、3.1 Pro $2 / $12（>200K 翻倍）；DeepSeek V4.1 Flash 闲时 $0.15 / $0.60、读 $0.003、峰时 ×2。跨度三个量级，输出价是输入价的 4–6 倍，读价是输入价的 1/10–1/50。详见第一章。 ↩
缓存存的是前缀的 KV cache，供应商要为存储与管理付成本，所以 OpenAI（GPT-5.6 起）与 Anthropic 对写入收 1.25×（Anthropic 1 小时 TTL 收 2×）作为”可能用不上”的保证金；Gemini 收按小时的存储费，DeepSeek 不收。收支平衡：写 1.25× + 读 0.1× = 1.35× 对比不缓存两次 2×，读一次就回本；1 小时 TTL 写 2× 要读两次才回本。不划算的只有前缀只用一次的场景（那是批处理的场景）。前提是前缀逐字节相同、达到最小长度（按模型 1,024 token 起，不足静默不缓存）、间隔在 TTL 内。详见第二章。 ↩
第 $k$ 轮请求的输入是 $S + (k-1)m$（system 加累积历史），$N$ 轮的总输入是 $NS + N(N-1)m/2$——历史被反复传输与 prefill 产生二次项。$S = 5{,}000$、$m = 500$、$N = 40$ 时 590,000 token，历史占三分之二。做缓存后每轮只有新增部分是未缓存（写入 1.25×），其余按读价 0.1×，等效 87,800 token，约为不缓存的 15%——二次项没消失但系数乘了 0.1，Fable 5.1（0.025×）与 DeepSeek（0.02×）更小。前提：历史只追加不修改、请求间隔小于 TTL、前缀无动态内容。长度本身仍要靠历史压缩控制。详见第五章。 ↩
TTFT = 排队（供应商负载 + 你的限流队列）+ prefill（∝ 未缓存输入长度，compute-bound，命中缓存的前缀跳过）+ 思考（∝ 思考 token 数，由 effort 决定）。总时长 = TTFT + 输出 token 数 × TPOT；TPOT 由 decode 的 memory-bound 性质决定——每 token 读一遍权重与 KV，速度取决于 GPU 带宽与模型大小，与输入几乎无关，2026 年典型每秒 20–80 token。所以输入长度影响 TTFT、输出长度影响总时长、模型大小影响 TPOT；p99 多来自排队与重试。TTFT 异常先查输入长度与命中率、effort、供应商状态。详见第六章。 ↩

模型作为组件（03）：API 契约（二）——推理模型：thinking、effort 与跨轮的推理状态

Thu, 01 Oct 2026 00:00:00 +0800

到 2026 年，四家的主力模型都是推理模型：GPT-6 Astra 与 GPT-5.6 有 reasoning.effort，Claude 5 系列默认开启 adaptive thinking，Gemini 3.x 有 thinking_level，DeepSeek V4.1 Flash 默认 thinking mode。”推理模型”不再是一个选项，是默认。这给上一篇的契约加了一个维度：模型在给出可见输出之前会先生成一段不可见或半可见的思考，这段思考要花钱（按输出价计费）、要花时间（发生在首 token 之前）、是状态（下一轮要原样送回，否则模型”忘了自己刚才怎么想的”），并且它的多少由一个叫 effort 的参数控制。

这一维度带来四个后果，每个都能让一个从非推理模型迁过来的应用出问题：同样的请求账单翻倍（思考 token）；TTFT 从一秒变成十秒（思考在前）；编辑历史消息返回 400（thinking block 的校验）；在两个模型之间做 fallback 时对话历史不兼容（新模型的 thinking block 旧模型读不了）。本篇把这四个后果讲清楚。

本篇要回答的核心问题是：

推理模型的”思考”在 API 上是什么，怎么计费？¹ effort 参数控制什么，怎样决定用哪一档？² thinking block 为什么要原样送回，编辑历史会怎样？³ 推理状态对 prompt caching 与多轮成本有什么影响？⁴

一、总览

1. 四家的推理维度

四家的推理维度
	OpenAI（GPT-5.6 / GPT-6）	Anthropic（Claude 5 系列）	Google（Gemini 3.x）	DeepSeek（V4.1 Flash）
控制参数	`reasoning.effort`：`none` / `low` / `medium` / `high` / `xhigh` / `max`；`reasoning.mode: pro`	`effort`：`low` / `medium` / `high` / `xhigh` / `max`，默认 `high`；`thinking: adaptive`（默认）/ `disabled`	`thinking_level`：`low` / `medium` / `high`；3.8 Flash 默认 `medium`，3.1 Pro 默认 `high`	thinking mode 默认开启；effort `low` / `high` / `max`
思考的可见性	默认不返回；可要求摘要（`reasoning.summary`）	返回 thinking block（部分场景为摘要 / 加密的 redacted 块）	返回 thought summary；thought signature 用于状态	返回完整 `reasoning_content`
计费	思考 token 按输出价计入 `output_tokens_details.reasoning_tokens`	思考 token 按输出价计入 `output_tokens`	价目表明写”output（including thinking tokens）”	按输出价
`max_tokens` 的含义	`max_output_tokens` 含思考	`max_tokens` 是思考 + 回答的硬上限	`max_output_tokens` 含思考	含思考
跨轮状态	Responses：`reasoning` item 由服务端保留（`previous_response_id`）或以加密 item 随请求往返；Chat Completions 不保留	上一轮的 thinking block 必须原样送回；Fable 5.1 起校验其之前的历史未被改动	thought signature 随 function call 往返	`reasoning_content` 不要送回（送回会 400）
关闭思考	`effort: none`（支持的模型）	`thinking: disabled`，仅在 effort ≤ `high` 时允许（Opus 5）；Sonnet 5 上手动 `budget_tokens` 返回 400	`thinking_level: low`（不能完全关）	切非 thinking 模式

2. 一轮推理调用的解剖

%% 图：一轮推理调用的解剖：思考阶段生成不可见的 thinking token，产物作为状态必须在下一轮携带，effort 控制思考的量级
flowchart TB
    IN["输入：完整历史（含上一轮的 thinking / reasoning 状态）+ 本轮 user 或 tool result"] --> THINK["思考阶段<br/>生成 thinking token：不可见 / 摘要<br/>按输出价计费 · 占 TTFT"]
    THINK --> OUT["可见输出<br/>文本 或 tool_call"]
    OUT --> STATE["返回给应用的状态<br/>thinking block（Anthropic）/ reasoning item（OpenAI）/ thought signature（Gemini）"]
    STATE --> NEXT["下一轮请求必须携带它<br/>（DeepSeek 例外：不携带）"]
    EFF["effort / thinking_level"] -.->|"控制思考 token 的量级"| THINK
    NEXT -.-> IN

    classDef stage fill:#fff7e0,stroke:#c98a00,stroke-width:2px,color:#222
    classDef ctl fill:#eef6ff,stroke:#5b8fd6,color:#222
    class IN,THINK,OUT,STATE,NEXT stage
    class EFF ctl

三条箭头对应本文三个核心问题：effort 控制思考阶段的大小（第三章）；思考阶段的产物要作为状态回流（第四章）；思考阶段的 token 进账单、进 TTFT（第二、五章）。

3. 本文的章节安排

第二章讲思考在协议上是什么、怎么计费；第三章讲 effort 这个旋钮与怎样为一个任务选档；第四章讲跨轮的推理状态——四家的机制与它对”编辑历史”、”跨模型 fallback”的约束；第五章讲它对缓存与多轮成本的影响；第六章讲从非推理模型迁移时默认值带来的风险；第七章实践建议。

二、思考在协议上是什么

1. 三种可见性

模型在思考阶段生成的 token 与最终回答的 token 在计算上没有区别——都是自回归地一个个生成，都读一遍上下文，都占 decode 时间。区别只在是否返回给你：

完整返回：DeepSeek 的 reasoning_content 字段给出全部思考文本。你可以展示、可以记日志、可以用它调试——但不能送回：DeepSeek 的多轮对话文档明确要求下一轮输入里不包含 reasoning_content，否则返回 400。它的思考是无状态的，每轮重新想。
原样返回但可能加密或摘要：Anthropic 返回 thinking 块；在某些情况下返回 redacted_thinking（加密的思考内容，你看不到但要原样送回）。Claude 4 系列起长思考默认返回摘要而按完整思考计费。
默认不返回：OpenAI 的 Responses 默认不返回思考内容，可以用 reasoning.summary 要一份摘要；思考的完整状态作为 reasoning item 由服务端保留，或在无状态 / ZDR 模式下以加密形式随请求往返。Gemini 返回 thought summary。

对应用的含义：不要把思考内容当作可靠的可解释性。摘要是模型对自己思考的再描述，加密块你看不到，完整返回的也可能与最终答案不一致。它对调试有用（”它为什么调用了这个工具”），不适合作为向用户展示的”推理过程”，更不适合作为审计依据。

2. 计费

四家都按输出价计思考 token。这是本篇最重要的账：输出价通常是输入价的 4–5 倍（第四篇），而一次高 effort 的调用，思考 token 可以是回答 token 的十倍以上。一个数字例子（2026 年 9 月价目）：

思考 token 的计费例子
请求	输入	思考	回答	单价（输入 / 输出，每百万）	成本
Sonnet 5，effort `low`，分类任务	2,000	300	50	$2 / $10	2,000 × 2 + 350 × 10 = $0.0075
Sonnet 5，effort `high`，同一任务	2,000	4,000	50	$2 / $10	2,000 × 2 + 4,050 × 10 = $0.0445
GPT-5.6 Sol，effort `xhigh`，agent 一步	30,000	12,000	400	$4 / $20	30,000 × 4 + 12,400 × 20 = $0.368

（成本 = token 数 × 单价 ÷ 10⁶。）第一行到第二行，输入没变、回答没变，账单涨了 6 倍——全部是思考。对一个每天百万次的分类接口，这是每天几百美元与几千美元的差别。

%% 图：同一个分类任务在 Sonnet 5 上 effort low 与 high 的账单拆成三份——输入（0.004 美元）和回答（0.0005 美元）两档完全相同，差的 0.037 美元全部是思考 token：300 个变 4,000 个，按输出价计
%%{init: {"xyChart": {"width": 760, "height": 340, "plotReservedSpacePercent": 60}, "themeVariables": {"xyChart": {"plotColorPalette": "#c0392b, #5b8fd6"}}}}%%
xychart-beta
    title "一次调用的成本构成（美元，Sonnet 5，同一任务）"
    x-axis ["low 输入", "low 思考", "low 回答", "high 输入", "high 思考", "high 回答"]
    y-axis "美元" 0 --> 0.045
    bar [0.004, 0.003, 0.0005, 0.004, 0.040, 0.0005]

max_tokens 的含义随之变化：它是思考加回答的总上限。一个在非推理模型上设 max_tokens = 1024 刚好够输出一段 JSON 的应用，迁到推理模型后，思考用掉 900 个，回答被截断，JSON 不完整——stop_reason 是 max_tokens。Anthropic 的 Sonnet 5 迁移指南把这一条单列出来提醒。

%% 图：max_tokens = 1024 在两类模型上的含义——非推理模型上 1024 全给回答，JSON 完整；推理模型上思考先用掉 900，回答只剩 124 被截断，stop_reason 是 max_tokens
flowchart TB
    subgraph A["非推理模型：max_tokens = 1024"]
        direction LR
        A1["回答 ≈ 600 token<br/>JSON 完整"] --> A2["还剩 424，stop_reason = end_turn"]
    end
    subgraph B["推理模型：同样的 max_tokens = 1024"]
        direction LR
        B1["思考 900 token<br/>（不可见，但算在上限里）"] --> B2["回答只剩 124<br/>JSON 写到一半"] --> B3["stop_reason = max_tokens"]
    end
    A ~~~ B
    classDef ok fill:#eefaf0,stroke:#4d9a5c,color:#222
    classDef think fill:#eef6ff,stroke:#5b8fd6,color:#222
    classDef bad fill:#fdecea,stroke:#c0392b,color:#222
    class A1,A2 ok
    class B1 think
    class B2,B3 bad

3. 用量字段

要把思考 token 单独记下来。OpenAI 在 usage.output_tokens_details.reasoning_tokens；Anthropic 把它算进 output_tokens（思考块的 token 数可以从返回的块估算）；Gemini 在 usage_metadata.thoughts_token_count；DeepSeek 在 completion_tokens_details.reasoning_tokens。上一篇中间层的”归一化用量”要把这第五类 token 加进去——否则你只看到”输出 token 涨了”，不知道是模型话多了还是想多了。

三、effort：一个旋钮，三条曲线

1. 它控制什么

effort 不是一个精确的 token 预算（那是 Anthropic 已经移除的 budget_tokens 的语义），而是一个倾向：模型自己决定想多久，effort 告诉它”这个任务值得想多少”。Anthropic 的 adaptive thinking 文档说得直接：”模型决定何时以及想多少，effort 是控制思考深度的参数。”同一档 effort 下，简单问题思考少、复杂问题思考多；不同档之间是量级的差别。

四家的档位不完全对齐，但都有一条从”几乎不想”到”不限制”的梯子。Anthropic 对 Sonnet 5 各档的说明可以作为通用理解：

effort 各档的用途
档	用途
`low`	短小、范围明确、延迟敏感、对智力不敏感的任务
`medium`	成本敏感、愿意用一点质量换 token 的场景
`high`	默认；多数场景的平衡点
`xhigh`	最难的编码与 agent 任务的推荐档
`max`	不限制思考 token 的最高档

OpenAI 的 GPT-6 Astra 也是 low 到 max 五档，另有 reasoning.mode: pro 对应原 o3-pro / GPT-5 Pro 一类”多次采样再综合”的更贵形态。Gemini 只有三档，low 也不能完全关闭思考。

2. 三条曲线

选档的方法只有一个：在你自己的评测集上（第五篇）把每一档跑一遍，画三条曲线——质量（任务指标）、成本（每任务美元）、延迟（TTFT 与总时长）随 effort 的变化。典型形状：

质量曲线在某一档之后饱和：简单任务在 low 就饱和，复杂 agent 任务到 xhigh 还在涨。Anthropic 发布 Opus 5 时给出的正是这种”性能随 effort 变化”的图，并建议”从默认 high 开始，质量不掉就往下调省 token，最难的任务往上调”。
成本曲线单调上升且在高档陡增——思考 token 随难度非线性增长。
延迟曲线跟随成本：思考在首 token 之前，effort 直接决定 TTFT。

三条曲线的交点就是这个任务的档。不同任务用不同的档：一个应用里的意图分类用 low，复杂的多步 agent 用 xhigh，两者可以是同一个模型。这是”按任务计价”（price per task）而不是”按 token 计价”的思路——OpenAI 在发布 GPT-6 Astra 时的说法是市场正在”意识到你真正要买的是每任务的价格”。effort 就是把这个价格调到合适位置的旋钮。

两条曲线画在一起是这个样子（示意：质量取 0–100 的任务指标，成本取相对 low 的倍数）：

%% 图：effort 各档的质量与成本曲线（示意）——质量在 high 之后饱和（88 → 90 → 90），成本却从 1 倍涨到 6 倍再到 14 倍；饱和点左边的最低档就是这个任务该用的档
%%{init: {"xyChart": {"width": 760, "height": 340, "plotReservedSpacePercent": 60}, "themeVariables": {"xyChart": {"plotColorPalette": "#c0392b, #5b8fd6"}}}}%%
xychart-beta
    title "一个中等难度任务：质量饱和在 high，成本继续陡增（示意）"
    x-axis "effort" ["low", "medium", "high", "xhigh", "max"]
    y-axis "质量（%）/ 成本（相对 low 的倍数 × 10）" 0 --> 150
    line [72, 84, 90, 91, 91]
    bar [10, 25, 60, 100, 140]

红线是质量，蓝柱是成本（倍数 × 10 以便画在同一坐标里）。这个任务的答案是 high：再往上，质量多 1 个点，钱多一倍多。简单任务的红线在 low 就平了；最难的 agent 任务红线到 xhigh 还在涨——所以要每类任务各画一张。

3. 过度思考

推理模型有一个已被广泛观察到的现象：在简单任务上，高 effort 不仅浪费 token，有时还降低准确率——模型想出了本不存在的复杂性，或在长思考里改变了本来正确的初判。这不是普遍规律，但足以说明”effort 越高越好”不成立。评测集里放一批简单用例，专门看高档是否比低档差。

4. 逐消息调整 effort

一个 agent 任务里，规划那一步值得 xhigh，读文件那几步 low 就够。Anthropic 在 Fable 5.1、Mythos 5.1 与 Opus 5 上提供了逐消息 effort（beta，请求头 mid-conversation-output-config-2026-07-01）：在 messages 里插入一条 role: system 的消息携带 output_config.effort，改变后续轮的 effort 而不使 prompt cache 失效——最后一点是关键，改顶层参数通常会让前缀缓存失效（第五章）。OpenAI 在 Responses 里每次请求可以独立设置 reasoning.effort，服务端状态让这件事天然可行。

四、跨轮的推理状态

1. 为什么思考要跨轮保留

一个 agent 循环里，模型思考 → 决定调用工具 → 你执行 → 送回结果 → 模型继续。如果第二轮请求里没有第一轮的思考，模型面对的是”我刚才不知为何调用了这个工具，现在拿到了结果”，它要么重新想一遍（多花钱、多花时间），要么在缺少上下文的情况下继续（质量下降）。Anthropic 把这叫 interleaved thinking——思考与工具调用交错，思考块是这条链的一部分；OpenAI 说 Responses 让”推理 token 在轮次之间保留”，并以此解释为什么 Chat Completions（不保留）从 GPT-5.4 起不再支持带 effort 的工具调用——那条路径上的 agent 效果太差。

2. 四种机制

四家推理状态的传递机制
供应商	状态载体	应用要做什么	校验
Anthropic	上一轮 assistant 消息里的 `thinking` / `redacted_thinking` 块	原样送回，位置与内容不能动	块带签名 Fable 5.1 起还校验块之前的历史未变：新账户（2026-08-31 后创建）下把它放到 system / tools / 更早 assistant 消息之后返回 400 带 `thinking … 2026-08-01` 相关 beta 头时可选”拒绝”或”丢弃”（`mismatch_behavior`），被丢弃的块在 `input_transformations` 里报告
OpenAI（Responses）	`reasoning` item	服务端状态：用 `previous_response_id` 自动带上；无状态 / ZDR：用 `include` 要回加密的 reasoning 内容并随下一次请求送回	加密内容只有服务端能读
Google（Gemini 3）	thought signature	在多轮 function calling 中随 `functionCall` 部分原样送回	缺失会降低后续轮的质量或报错
DeepSeek	无	不要送回 `reasoning_content`，送回返回 400	—

前三家的设计是同一个思想的三种实现：思考是模型的内部状态，应用只负责搬运，不负责读写。加密（OpenAI）、签名（Anthropic、Gemini）都是为了保证你搬运的是原件。DeepSeek 选择了无状态——简单，但每轮重新推理。

3. 编辑历史的约束

在 Chat Completions 时代，应用随意编辑历史：删掉几轮省 token、把长工具结果换成摘要、合并两条消息。推理状态让这些操作有了约束：

不能只删思考块保留其他：Anthropic 会拒绝或（配置为丢弃时）丢掉与历史不一致的块，模型退化为”忘了刚才怎么想”。
不能改动思考块之前的内容：Fable 5.1 的历史校验意味着替换更早一轮的工具结果为摘要，会让后面所有 thinking block 失效。要压缩历史，只能在一个新的思考链开始处做——例如在一次工具循环完全结束、模型给出最终回答之后，再对整段历史做摘要（L2 上下文工程的”压缩”要在这些边界上做，L4 的 compaction 也是）。

%% 图：历史里哪里能改、哪里不能——一条思考链内（思考块 → 工具调用 → 工具结果 → 思考块 → 最终回答）任何一处改动都会让后面的思考块失效；只有在最终回答之后、下一条思考链开始之前，才能对整段历史做摘要
flowchart TB
    subgraph CHAIN["一条思考链：中间不能动"]
        direction TB
        T1["思考块 ①<br/>（带签名）"] --> C1["工具调用"] --> R1["工具结果<br/>200 KB"] --> T2["思考块 ②<br/>校验①之前的历史未变"] --> ANS["最终回答"]
    end
    ANS --> CUT["✂ 边界：这里可以压缩<br/>对整段做摘要、开新链"]
    CUT --> NEXT["下一条思考链…"]
    X["把 R1 换成摘要？<br/>→ ② 签名不匹配，被拒绝或丢弃"] -.-> R1
    classDef step fill:#fff7e0,stroke:#c98a00,color:#222
    classDef ok fill:#eefaf0,stroke:#4d9a5c,color:#222
    classDef bad fill:#fdecea,stroke:#c0392b,color:#222
    class T1,C1,R1,T2,ANS,NEXT step
    class CUT ok
    class X bad

旧模型读不了新模型的思考块：Fable 5.1 的 thinking block 只有它自己或更新的模型能读；早期模型收到会被 API 丢弃。做跨模型 fallback（Fable 5.1 超时切到 Opus 5）时，携带 Fable 5.1 思考块的历史在 Opus 5 上会失去推理状态；反向（Opus 5 → Fable 5.1）可以。fallback 策略要考虑方向。

4. 服务端状态与 ZDR 的两难

OpenAI 的 previous_response_id 让推理状态的搬运完全透明，但依赖服务端存储（上一篇第六章：默认 30 天）。合规要求 Zero Data Retention 的组织不能用它，要改成无状态模式：每次请求带完整历史，并用 include 要回加密的 reasoning item 随请求往返。请求体变大，但推理状态不丢。两种模式的成本相同（输入 token 都是全量计费），差别在谁传、谁存。

五、对缓存与多轮成本的影响

1. 思考 token 不在缓存里

prompt caching 缓存的是输入前缀（第四篇）。思考 token 是输出，每轮新生成、每轮全价。一个 20 步的 agent 任务，每步思考 3,000 token，光思考就是 60,000 个输出价 token——这部分不因任何缓存策略而减少，只能靠 effort 调低。

上一轮的思考块在下一轮变成了输入的一部分（Anthropic 原样送回、OpenAI 服务端拼接），这部分按输入价计费，并且能进缓存前缀。所以多轮 agent 的账是：每轮新思考按输出价、历史思考按输入价（缓存命中时打折）。

%% 图：多轮 agent 里思考 token 的两种身份——本轮新生成的思考按输出价全价、任何缓存都帮不上；上一轮的思考块回到历史里变成输入，按输入价计并能进缓存前缀
flowchart TB
    subgraph R1["第 k 轮"]
        direction TB
        H["历史（含前 k−1 轮的思考块）<br/>输入价 · 命中缓存打 0.1 折"] --> NEW["本轮新思考 3,000 token<br/>输出价 · 全价 · 不进任何缓存"] --> OUT["本轮回答 / tool_call<br/>输出价"]
    end
    R1 --> R2["第 k+1 轮：<br/>刚才的思考块并入历史，变成输入价"]
    E["只有一个办法减少它：调低 effort"] -.-> NEW
    classDef inp fill:#eefaf0,stroke:#4d9a5c,color:#222
    classDef outp fill:#fdecea,stroke:#c0392b,color:#222
    classDef n fill:#eef6ff,stroke:#5b8fd6,color:#222
    class H,R2 inp
    class NEW,OUT outp
    class E n

2. 什么会让缓存失效

缓存前缀要求逐字节相同。以下操作会让前缀从改动处起失效：改 system prompt（哪怕一个字）、改工具定义、改顶层参数（多数 API 把 effort、thinking 配置算在缓存键里——这就是 Anthropic 逐消息 effort 特意做成”不失效”的原因）、替换或删除历史中间的任何块。推理模型的历史里多了思考块，块的数量与位置更多，被无意改动的机会也更多。

3. Responses 与 Chat Completions 的缓存差别

OpenAI 声称 Responses 在 agent 场景下比 Chat Completions 有更好的缓存利用（第三方引用的数字是 40–80% 的改善）。原因不神秘：服务端状态保证了历史逐字节一致（应用没有机会”顺手”改一下），reasoning item 也留在前缀里。用客户端状态的应用要靠自己保证这一点：历史只追加、不修改。

六、迁移时的默认值风险

从非推理模型或早期推理模型迁到 2026 年的模型，默认值的变化足以让应用出问题。按供应商列：

Anthropic：Sonnet 5（2026-06-30）与 Opus 5（2026-07-24）把 adaptive thinking 改为默认开启——不带 thinking 字段的请求在 4.6 / 4.8 上不思考，在 5 上思考。后果：思考 token 出现在账单里；max_tokens 不够；TTFT 变长。同时，手动 budget_tokens 在 Sonnet 5 上返回 400（Sonnet 4.6 已弃用），Opus 5 上 thinking: disabled 只在 effort ≤ high 时被接受，xhigh / max 配 disabled 返回 400。Sonnet 5 还拒绝非默认的采样参数——推理模型的输出分布不再由你调 temperature。

OpenAI：Chat Completions 在 GPT-5.4 起不支持 reasoning_effort 非 none 的工具调用；用 Chat Completions 做 agent 的应用要迁到 Responses。gpt-5-2025-08-07 等快照 2026-12-11 关闭，推荐替代是 GPT-5.6 Sol / Terra / Luna——不同的默认 effort 与不同的价格。

Google：Gemini 3.8 Flash 默认 medium，3.1 Pro 默认 high；文档提醒 3.8 Flash “在长任务上会按设计用更多 token——更小的推理步、迭代调用工具、验证自己的工作”，并建议日常任务把 effort 调低。Interactions API 的 steps 时间线把思考作为独立的 step 类型暴露。

DeepSeek：V4.1 Flash 默认 thinking 开启；deepseek-v4-pro 自 9 月 14 日路由到 V4.1 Flash，调好的 effort 档在新模型上要重测。

共同的教训：迁移不是改模型名。至少要做三件事——在评测集上重跑 effort 各档；检查 max_tokens；检查历史编辑逻辑是否触碰思考块。

七、实践建议

把思考 token 单独记账：中间层的用量归一化加上 reasoning_tokens，仪表盘上把”思考 / 回答”分开画。多数团队第一次看到这张图会发现思考占输出的 70% 以上。
每类任务跑一次 effort 扫描：评测集 × 各档 → 质量 / 成本 / TTFT 三条曲线，取质量饱和的最低档。简单任务放一组用例专测过度思考。
历史只追加：把”修改历史中间内容”列为禁止操作；压缩只在一个思考链结束后对整段做。
fallback 考虑方向：新 → 旧模型会丢推理状态；在中间层记录每条历史是哪个模型生成的。
max_tokens 按”思考 + 回答”重设，并监控 stop_reason == max_tokens 的比例。
ZDR 组织用无状态模式并携带加密推理状态，不要为了省事关掉推理状态的往返。

八、本文小结

推理模型在可见输出前生成思考 token：按输出价计费、占 TTFT、max_tokens 含它；四家的可见性不同（DeepSeek 完整返回、Anthropic 原样 / 加密块、OpenAI 默认不返回、Gemini 摘要），但都不适合作为可解释性或审计依据。
effort 是一个倾向而非预算，控制思考 token 的量级；同一任务 low 与 high 的账单可以差 6 倍。选档靠评测集上的质量 / 成本 / 延迟三条曲线，不同任务用不同档，”越高越好”不成立。
思考是跨轮的内部状态：Anthropic 的签名块、OpenAI 的（加密）reasoning item、Gemini 的 thought signature 都要原样搬运；DeepSeek 无状态、不能送回。它约束了编辑历史与跨模型 fallback。
思考 token 不进缓存；历史里的思考块进缓存前缀；改顶层参数会让缓存失效，Anthropic 的逐消息 effort 是例外。
2026 年迁移的最大风险是默认值：thinking 默认开启、budget_tokens 移除、采样参数被拒、Chat Completions 的功能收窄。迁移要重跑 effort 扫描、重设 max_tokens、检查历史编辑逻辑。

九、自测

一个意图分类接口从 Claude Sonnet 4.6 迁到 Sonnet 5，请求体没变（无 thinking 字段，max_tokens: 200）。上线后出现两类问题，各是什么原因？

答案

（1）账单上涨、TTFT 变长：Sonnet 5 默认开启 adaptive thinking，不带 thinking 字段的请求现在会思考，思考 token 按输出价计费且发生在首 token 之前。（2）输出被截断（stop_reason: max_tokens）：max_tokens 是思考 + 回答的总上限，200 被思考占掉。修法：对分类任务设 effort low（或 thinking: disabled，此时 effort 必须 ≤ high），max_tokens 按思考 + 回答重设。详见第二章、第六章。
用 2026 年 9 月价目计算：GPT-5.6 Terra（$2 / $12）上一个请求输入 8,000 token、思考 5,000、回答 300。成本多少？思考占成本的百分之几？

答案

输入 8,000 × 2 = 16,000；输出 (5,000 + 300) × 12 = 63,600；合计 79,600 微美元 ≈ $0.0796。思考 5,000 × 12 = 60,000，占 75.4%。详见第二章。
一个 agent 应用为了省 token，在每轮请求前把三轮之前的工具结果替换成一句摘要。在 Claude Fable 5.1 上会发生什么？为什么在 Opus 4.8 上没事？

答案

Fable 5.1 校验 thinking block 之前的历史未被改动：替换更早的工具结果让其后所有思考块的校验失败，新账户下返回 400，或在配置为丢弃时丢掉这些块（input_transformations 报告），模型失去推理状态。Opus 4.8 只校验块本身的签名，不校验之前的历史。修法：压缩只在一个思考链结束（模型给出最终回答）之后对整段历史做。详见第四章。
为什么 OpenAI 从 GPT-5.4 起让 Chat Completions 不再支持带 reasoning_effort 的工具调用？这与 Responses 的哪个特性有关？

答案

Chat Completions 不在轮次之间保留推理状态：每次工具调用返回后模型面对的是”不知为何调用了这个工具”的历史，要重新推理或在缺少上下文下继续，agent 效果差。Responses 用 reasoning item（服务端保留或加密往返）把推理状态跨轮保留，interleaved 的思考与工具调用形成一条完整的链。OpenAI 因此把带 effort 的工具调用只留在 Responses。详见第四章。
一个 20 步的 agent 任务，每步思考 3,000 token、可见输出 200 token、每步新增输入（工具结果）2,000 token，system + 工具定义 10,000 token。哪些 token 能被 prompt caching 打折，哪些不能？

答案

不能打折的：每步新生成的 3,000 思考 + 200 输出（输出价，共 20 × 3,200 = 64,000）；每步新增的 2,000 工具结果在它首次出现的那一轮是未缓存输入。能打折的：10,000 的 system + 工具定义在第 2 步起命中缓存；历史里已出现的思考块、输出与工具结果在后续轮作为输入前缀命中缓存（前提是历史只追加、不修改，且顶层参数不变）。详见第五章。

思考是模型在可见输出之前自回归生成的一段 token，计算上与回答无异，只是可见性不同：DeepSeek 完整返回 reasoning_content，Anthropic 返回 thinking 块（部分为加密的 redacted_thinking 或摘要），OpenAI 默认不返回、可要摘要，Gemini 返回 thought summary。四家都按输出价计费（OpenAI 记在 output_tokens_details.reasoning_tokens，Gemini 价目表明写”output including thinking tokens”），且 max_tokens 是思考 + 回答的总上限。同一任务 Sonnet 5 从 effort low 到 high，思考从 300 涨到 4,000 token，账单从 $0.0075 涨到 $0.0445。详见第二章。 ↩
effort 是一个倾向而非 token 预算：模型自己决定想多久，effort 告诉它任务值得想多少。四家都有从”几乎不想”到”不限”的梯子（OpenAI none … max，Anthropic low … max 默认 high，Gemini 三档，DeepSeek 三档）。选档的方法是在自己的评测集上跑每一档，画质量 / 成本 / TTFT 三条曲线，取质量饱和的最低档；简单任务通常 low 就饱和，复杂 agent 任务到 xhigh 还在涨；高档在简单任务上可能反而降准确率（过度思考）。不同任务用不同档，Anthropic 支持逐消息改 effort 且不失效缓存。详见第三章。 ↩
因为思考是模型的内部状态：agent 循环里下一轮要接着上一轮的思考继续（interleaved thinking），丢了就要重想或在缺少上下文下继续，效果差——这也是 OpenAI 让 Chat Completions 从 GPT-5.4 起不支持带 effort 的工具调用的原因。Anthropic 用带签名的 thinking 块、OpenAI 用（加密的）reasoning item、Gemini 用 thought signature 让应用只搬运不读写；DeepSeek 无状态、不能送回。编辑历史的后果：删思考块 → 被拒或丢弃；改思考块之前的内容 → Fable 5.1 起校验失败（新账户 400，或配置为丢弃）；新模型的思考块旧模型读不了 → fallback 有方向性。压缩历史只能在一个思考链结束后对整段做。详见第四章。 ↩
思考 token 是输出，每轮新生成、全价、不进任何缓存，只能靠 effort 调低；上一轮的思考块在下一轮成为输入前缀的一部分，按输入价计费并可命中缓存。改 system、工具定义、顶层参数或历史中间任何块都会让前缀从改动处失效——Anthropic 的逐消息 effort（beta）是特意做成不失效的例外。OpenAI 称 Responses 比 Chat Completions 缓存利用更好，原因是服务端状态保证历史逐字节一致；客户端状态的应用要自己保证”历史只追加”。20 步 agent 每步思考 3,000 token 就是 60,000 个输出价 token，这部分与缓存无关。详见第五章。 ↩

模型作为组件（02）：API 契约（一）——消息、工具调用、结构化输出与流式，四家 API 的共同骨架

Wed, 30 Sep 2026 00:00:00 +0800

第一篇讲了组件怎么坏。这一篇讲组件的接口——你和它之间的协议。2026 年，OpenAI、Anthropic、Google、DeepSeek 四家的模型 API 已经收敛成一套共同骨架：一个消息列表进去，一个消息出来；消息可以携带工具调用与工具结果；输出可以被 schema 约束；响应可以流式返回；对话状态可以放在客户端也可以放在服务端。学会这套骨架，换供应商只是改字段名；不学，每换一家都要重新踩一遍坑。

但文档不会告诉你三件事。第一，工具调用是一个协议而不是一个功能：模型返回的是”我想调用 X”，执行、配对、把结果送回、决定何时停止，全在你这一侧，出错的地方也全在你这一侧。第二，结构化输出的”严格模式”保证的是语法不是语义：一个符合 schema 的 JSON 可以每个字段都是编造的。第三，状态的默认值：Responses API 默认把你的请求存 30 天，Chat Completions 对新账户也默认存，一个隐私敏感的应用从旧接口迁过去、什么都没改，就开始留存用户数据了。

本篇要回答的核心问题是：

四家 API 的共同骨架是什么，差异在哪？¹ 一次工具调用的往返在协议上经过哪几步、哪些是应用的责任？² 结构化输出保证了什么、没保证什么？³ 流式响应的事件模型与状态管理的默认值有什么坑？⁴

一、总览

1. 四家 API 在一张表上

四家 API 的对照
	OpenAI	Anthropic	Google	DeepSeek
推荐入口	Responses API（`/v1/responses`）	Messages API（`/v1/messages`）	Interactions API（2026-06 GA）	OpenAI 格式（`api.deepseek.com`）
维持的旧入口	Chat Completions（支持；GPT-5.4 起不支持带 `reasoning_effort` 的工具调用）；Assistants API 已于 2026-08-26 关闭	—	`generateContent`（支持，标为 legacy）	Anthropic 格式（`/anthropic`）、Responses 格式
输入形状	`input`：item 列表（message / function_call_output 等）+ 顶层 `instructions`	`system` + `messages`（user / assistant 交替，content 为块列表）	`input`（Interactions）；`contents[].parts`（generateContent，角色 user / model）	同 OpenAI
输出形状	`output`：item 列表（`message` / `function_call` / `reasoning` …）	`content`：块列表（`text` / `tool_use` / `thinking`）	`steps` 时间线（Interactions，2026-05 起替代 `outputs`）；`candidates[].content.parts`	同 OpenAI
工具调用	`tools` + `tool_choice` 输出 `function_call`（`call_id`、`arguments` 为字符串）结果以 `function_call_output` 送回	`tools`（`input_schema`）+ `tool_choice`（auto / any / tool / none）输出 `tool_use` 块（`id`、`input` 为对象）结果以 user 消息里的 `tool_result` 块送回	`functionCall` / `functionResponse` part；内置 Google Search 等	同 OpenAI
结构化输出	`text.format` = `json_schema`（`strict`）	`output_config.format` = `json_schema`	`response_format`（Interactions，多态）；`responseSchema`（generateContent）	`response_format: json_object`（JSON 模式）
流式	SSE：`response.output_text.delta` 等类型化事件	SSE：`message_start` / `content_block_delta` / `message_delta` / `message_stop`	SSE：`interaction.created` / `step.delta` / `interaction.completed`	同 OpenAI（`choices[].delta` 分块）
状态	服务端：`previous_response_id` 或 Conversations；默认存储（`store: true`，30 天）	客户端：每次送完整历史	服务端：`previous_interaction_id`；默认存储	客户端
缓存	自动前缀缓存（读 0.1×，GPT-5.6 起写 1.25×）	`cache_control` 显式断点或顶层自动；5 分钟 / 1 小时 TTL	隐式缓存 + 显式缓存（按小时计存储费）	自动磁盘前缀缓存（命中价约为未命中的 2%）

表里每一行都对应本文一章。看这张表要抓两点：形状趋同（都是”列表进、列表出”，都把工具调用、结构化输出、流式做成一等公民）；默认值分歧（谁存状态、缓存要不要显式声明、参数字符串还是对象）——坑都在默认值里。

2. 本文的章节安排

第二章讲消息与角色的骨架；第三章讲工具调用的协议——本文最重要的一章；第四章讲结构化输出的三个层次与它保证的边界；第五章讲流式的事件模型；第六章讲状态放在哪一侧与默认存储；第七章列 2026 年内四家契约的变更；第八章给出一个中间层的最小设计与实践建议。

二、消息与角色：共同骨架

1. 三种角色，四种叫法

所有 API 都区分三类发言者：开发者的指令（OpenAI 叫 instructions / developer，Anthropic 叫顶层 system，Gemini 叫 system_instruction，Chat Completions 与 DeepSeek 叫 system 消息）、用户（user）、模型（OpenAI / Anthropic / DeepSeek 叫 assistant，Gemini 叫 model）。工具结果在 OpenAI 是独立的 tool 角色（Chat Completions）或 function_call_output item（Responses），在 Anthropic 是 user 消息里的 tool_result 块，在 Gemini 是 functionResponse part——名字不同，语义相同：一段由应用（而不是用户或模型）产生、要让模型读到的内容。

一个常见误解是把”开发者指令”当成一种权限更高的通道。它在模型眼里只是上下文里的一段被标记为 system 的文本；模型被训练成更重视它，但这是概率上的”更重视”，不是访问控制（第一篇第四章）。prompt injection 能起作用，正是因为工具返回里的一句”忽略之前的指令”与 system 里的指令在同一个上下文里竞争。

2. 内容是块的列表

早期 API 里一条消息就是一个字符串。现在一条消息的 content 是块的列表：文本块、图片块（URL 或 base64）、文件块（PDF）、音频块、以及模型输出侧的工具调用块、思考块。这个设计有两个含义：

多模态输入是消息的一部分，不是另一个 API。一张图在 content 里就是一个块，计费按供应商的换算（一张 1024² 的图通常折成几百到一千多 token，第四篇有账）。
一条消息可以同时含文本与多个工具调用——并行工具调用在协议上就是一条 assistant 消息里有多个 tool_use / function_call 块。

Anthropic 的 system 也是块列表，这是它的 cache_control 能精确放在某个块上的原因（第四篇）。

%% 图：一条消息的 content 是块的列表——输入侧可以混放文本、图片、文件块，输出侧一条 assistant 消息可以同时含文本、多个工具调用块和思考块；四家只是块的名字不同
flowchart LR
    subgraph IN["一条 user 消息"]
        direction TB
        I1["文本块<br/>「这张发票的总额是多少？」"] ~~~ I2["图片块<br/>base64 / URL，折成几百到一千多 token"] ~~~ I3["文件块<br/>PDF"]
    end
    subgraph OUT["一条 assistant 消息"]
        direction TB
        O1["思考块<br/>thinking / reasoning（第三篇）"] ~~~ O2["文本块<br/>「我先查两个系统」"] ~~~ O3["工具调用块 #1<br/>tool_use / function_call：id · name · 参数"] ~~~ O4["工具调用块 #2<br/>并行调用 = 同一条消息里多个块"]
    end
    IN --> M["模型"] --> OUT
    classDef in fill:#eef6ff,stroke:#5b8fd6,color:#222
    classDef out fill:#fff7e0,stroke:#c98a00,color:#222
    class I1,I2,I3 in
    class O1,O2,O3,O4 out

3. 谁负责把历史拼起来

无状态 API（Messages、Chat Completions、generateContent）要求你每次把全部历史送过去：system、第一轮 user、第一轮 assistant（含它发出的工具调用）、工具结果、第二轮 user……历史的每一个块都要在。漏掉一个工具调用块而保留了它的结果，多数 API 会返回 400（结果找不到对应的调用）。这就是为什么”编辑历史”不是随意的操作——第三篇讲推理模型时这一点会更严格。

有状态 API（Responses、Interactions）让你只送新内容并引用上一次的 id，服务端拼历史。方便，但引出第六章的存储与留存问题。

三、工具调用是一个协议

1. 一轮往返

%% 图：工具调用的一轮往返：模型只决定调用什么和读结果，校验、权限、执行、配对、循环控制都在应用侧
sequenceDiagram
    participant App as 应用（你的代码）
    participant API as 模型 API
    participant Tool as 工具（你的函数 / 外部服务）
    App->>API: 请求：messages + tools（name、description、JSON schema）
    API-->>App: 响应：assistant 消息，含 1..n 个 tool_call（id、name、arguments）
    Note over App: 校验参数 → 权限检查 → 决定执行哪些
    App->>Tool: 执行（可并行）
    Tool-->>App: 结果 / 错误
    App->>API: 请求：完整历史 + 每个 tool_call 对应一条 tool result（引用 id）
    API-->>App: 响应：最终回答，或又一批 tool_call
    Note over App,API: 循环直到模型不再返回 tool_call，或预算耗尽

图里每一个箭头都是你的责任的边界。模型只做两件事：决定调用什么（第二个箭头）和读结果（第五个箭头之后）。校验、权限、执行、配对、截断、循环控制、终止条件，都在应用侧。一个 agent 框架提供的就是这张图的运行时（L4）；但在用框架之前，应该至少手写过一次这个循环，否则框架藏起来的每一个决定都会变成一个你不理解的 bug。

2. 工具定义：schema 决定模型用不用对

工具定义有三部分：名字、描述、参数的 JSON schema。三部分都是 prompt——模型是读了这些文本来决定调用什么、怎么填参数的。经验规则：

描述写”什么时候用、返回什么”，不只写”做什么”。search_orders：只写”搜索订单”，模型会在该用 get_order 的时候也用它；写”按客户名或日期范围列出订单；已知订单号时用 get_order”，遵循率明显不同。
参数用枚举与类型收窄。status: string 会收到 “已完成”、”completed”、”done”；status: enum["pending", "shipped", "completed"] 在严格模式下只会收到三者之一。
工具数量与选择准确率负相关。几十个工具时模型会选错；OpenAI 的 Responses 与 Agents API 为此加了 tool search（按需加载定义），Anthropic 的 tool search 同理。L4 讲工具集的设计。
工具定义占 token 且在缓存前缀里。几十个工具的 schema 可以是几千 token，每次请求都算输入；把它放在稳定的前缀位置让它命中缓存（第四篇）。

3. 参数是字符串还是对象

OpenAI（含 DeepSeek）的 arguments 是JSON 字符串——你要自己 json.loads，而且流式时它是分片到达的（第五章）。Anthropic 的 input 是已解析的对象。Gemini 的 args 也是对象。这个差异决定了你的解析层要不要处理”字符串不是合法 JSON”的情况——OpenAI 的 strict: true 工具 schema 保证了这一点，不开 strict 时要准备修复或重试。

4. `tool_choice`：让模型必须调用某个工具

四家都支持 tool_choice：自动（模型决定）、必须调用某个工具（any / required）、指定某个工具、禁止调用。”指定某个工具”曾是结构化输出出现之前的常用替代——用一个 report_result 工具的 schema 来约束输出格式。两点变化：结构化输出成熟后这个用法不再必要；Claude Fable 5.1 起强制工具调用返回错误（Anthropic 的迁移指南把它列为三个 breaking change 之一），依赖 tool_choice: {type: "tool"} 的代码在新模型上直接失败。契约会变，第七章有清单。

5. 结果送回：配对、截断与错误

配对：每个 tool_call 的 id 必须有且只有一个结果。并行调用返回了三个 id，你就要送回三条结果，顺序不重要但缺一不可。
截断：工具结果是上下文的一部分，一个返回 200KB 的 SQL 查询结果会吃掉预算、触发第一篇的上下文腐化，甚至直接超限。应用侧要截断或摘要，并在结果里说明”已截断，共 N 行”。
错误也是结果：工具抛异常时把错误信息作为结果送回（Anthropic 有 is_error 标记），让模型决定重试、换参数或告诉用户——而不是让整个请求失败。这是 agent 循环能自我修复的前提。
结果是不可信输入：网页、文档、外部 API 返回的内容进入上下文后与你的指令平级（第二章第 1 节）。间接 prompt injection 从这里进来；L6 讲防御。

6. 服务端工具

OpenAI Responses、Gemini、Anthropic 都提供服务端执行的内置工具：网页搜索、代码解释器、文件搜索、计算机使用，以及 OpenAI 与 Anthropic 的远程 MCP server 连接。它们在协议上的差别是：模型调用、供应商执行、结果直接回到模型，不经过你的代码——你看到的是最终回答和一条”用了搜索”的记录。方便，但你失去了图里第三到第五个箭头的控制权：不能校验参数、不能做权限检查、不能截断结果。何时用服务端工具、何时自己实现，是 L4 的一个设计决定；本篇只指出协议上的区别。

四、结构化输出：保证语法，不保证语义

1. 三个层次

结构化输出的三个层次
层次	做法	保证	代表
提示	在 prompt 里说”输出 JSON，字段是……”	无。遵循率是概率	所有模型
JSON 模式	参数声明输出必须是合法 JSON	语法合法的 JSON；字段不保证	DeepSeek `json_object`、OpenAI `json_object`
schema 约束	传入 JSON schema，解码时约束每个 token 只能生成符合 schema 的续写	输出符合 schema：字段齐、类型对、枚举在范围内	OpenAI `json_schema` + `strict`、Anthropic `output_config.format`、Gemini `response_format` / `responseSchema`

第三层的机制是约束解码：把 schema 编译成一个自动机，采样时把不合法的 token 概率置零。所以它的保证是硬的——不是”模型很少出错”，而是”不可能生成不合法的 JSON”。代价是 schema 有限制（OpenAI 的 strict 模式要求所有字段 required、additionalProperties: false、不支持部分 JSON schema 特性）、首次使用一个 schema 有编译延迟、以及 schema 本身要占 token（Anthropic 把 schema 注入为一段额外的 system 文本，实测约 50–200 token 的固定开销加上 schema 自身；它落在缓存前缀里）。

%% 图：约束解码怎么工作，以及它的保证边界——schema 编译成自动机，每一步采样前把不合法的 token 概率置零，所以形状是硬保证；但填进字段里的值仍是模型的续写，语义、拒答、推理质量都在保证之外
flowchart TB
    S["JSON schema<br/>refund_eligible: bool<br/>reason: string"] --> A["编译成自动机<br/>（首次使用有编译延迟）"]
    A --> D["每一步采样：<br/>自动机不允许的 token 概率置零"]
    D --> O["输出一定符合 schema<br/>{ refund_eligible: true,<br/>  reason: 购买 90 天内 }"]
    O --> G1["保证了：字段齐 · 类型对 · 枚举在范围内"]
    O --> G2["没保证：true 是不是对的？<br/>「90 天」是不是编的？<br/>该拒答时会不会填个默认值？"]
    classDef ok fill:#eefaf0,stroke:#4d9a5c,color:#222
    classDef bad fill:#fdecea,stroke:#c0392b,color:#222
    classDef step fill:#fff7e0,stroke:#c98a00,color:#222
    class S,A,D,O step
    class G1 ok
    class G2 bad

2. 它没保证什么

语义。{"refund_eligible": true, "reason": "购买 90 天内"} 符合 schema，但 90 天可能是编的。schema 约束的是形状，第一篇的幻觉一条不受影响。
拒答与空值。模型判断不该回答时，在 strict 模式下仍必须产出合法 JSON——它会填空字符串、null 或一个看似合理的默认值。要在 schema 里给它一个显式的出口（status: enum["ok", "cannot_answer"]），否则拒答会被伪装成答案。
推理质量。2024 年的一项研究（Let Me Speak Freely?）发现，强制模型直接输出严格格式会降低某些推理任务的表现——模型没有”先想再答”的空间。常用的缓解是在 schema 里放一个 reasoning 字段排在结论字段之前（字段顺序在约束解码里是生成顺序），或者两阶段：先自由推理，再一次结构化抽取。推理模型（第三篇）在 thinking 阶段已经有了这个空间，问题缓解了很多。

3. 解析层仍然要有

即使用了 strict 模式，解析层要处理：schema 校验（用 Pydantic / zod 再校一遍——供应商的 strict 与你的类型系统之间可能有细微差别）、业务校验（日期在合理范围、id 存在）、以及降级（校验失败时重试一次并把错误信息放进上下文，或回退到人工）。JSON 模式与提示层次下还要处理 markdown 代码块包裹、尾随文字、截断（max_tokens 不够时 JSON 不完整——检查 stop_reason / finish_reason）。

五、流式：事件模型

1. 为什么流式是默认

一次调用的总时长是首 token 延迟（TTFT）加逐 token 生成时间；几百 token 的回答要几秒到几十秒。流式把用户感知的延迟从”总时长”变成”TTFT”，对话产品几乎都开流式。它在协议上是 Server-Sent Events：一个长连接，服务端按事件推送增量。

2. 四家的事件类型

四家流式接口的事件类型
	开始	文本增量	工具调用参数增量	用量	结束
OpenAI Responses	`response.created`	`response.output_text.delta`	`response.function_call_arguments.delta` → `.done`	在 `response.completed` 的 `response.usage` 里	`response.completed`
Chat Completions / DeepSeek	第一个 chunk	`choices[0].delta.content`	`choices[0].delta.tool_calls[i].function.arguments`（分片字符串）	最后一个 chunk（需 `stream_options.include_usage`）	`finish_reason` 非空
Anthropic	`message_start`（含输入用量）	`content_block_delta`（`text_delta`）	`content_block_delta`（`input_json_delta`，分片字符串）	`message_delta`（输出用量）	`message_stop`
Gemini Interactions	`interaction.created`	`step.delta`	`step.delta`	结束事件	`interaction.completed`

三个共同点决定了客户端的写法：

文本按增量拼接，不要假设一个事件是一个词或一句话。
工具调用的参数是分片的字符串，即使 Anthropic 非流式时给的是对象，流式时也是 input_json_delta 的字符串片段——必须等该块结束后拼起来再解析。一个常见 bug 是在收到第一个片段时就尝试 json.loads。
用量在末尾。成本核算与预算控制不能在流式过程中做，只能在结束事件里读。中途断开的流没有用量事件，但服务端已经生成的 token 照样计费。

3. 中断与超时

流式连接会断：网络、供应商过载、你自己的网关超时。断了不能”从第 137 个 token 续上”——只能重发整个请求，接受再花一次钱（幂等与重试在第六篇）。超时要分层：连接超时、首事件超时（TTFT 异常长通常是排队或长 prefill，第四篇）、事件间超时（生成卡住）、总超时。只设一个总超时的客户端会在 TTFT 正常但生成很长的情况下误杀请求。

%% 图：一次流式响应的事件时间线与四层超时——连接超时管到连上、首事件超时管到第一个事件（TTFT）、事件间超时管生成卡住、总超时兜底；工具参数分片要等 done 事件再解析，用量只在末尾出现
flowchart TB
    C["建连接"] --> E0["开始事件<br/>message_start /<br/>response.created"]
    E0 --> E1["文本增量 × n<br/>按增量拼接"]
    E1 --> E2["工具参数增量 × m<br/>分片字符串，先攒着"]
    E2 --> E3["工具参数 done<br/>此时才 json.loads"]
    E3 --> E4["用量事件<br/>四类 token 在这里"]
    E4 --> E5["结束事件"]
    T1["连接超时"] -.- C
    T2["首事件超时<br/>（TTFT 异常 = 排队或长 prefill）"] -.- E0
    T3["事件间超时<br/>（生成卡住）"] -.- E1
    T4["总超时（兜底，不能是唯一的一层）"] -.- E5
    classDef ev fill:#fff7e0,stroke:#c98a00,color:#222
    classDef to fill:#eef6ff,stroke:#5b8fd6,color:#222
    class C,E0,E1,E2,E3,E4,E5 ev
    class T1,T2,T3,T4 to

六、状态：谁保存对话

1. 两种模型

客户端状态（Messages、Chat Completions、generateContent）：你保存历史，每次全部送过去。优点是完全可控、可移植、可审计；缺点是每轮都传全量（网络与 prefill 成本随轮数增长——缓存缓解了 prefill 成本，第四篇），以及你要自己做历史的截断与压缩。

服务端状态（Responses 的 previous_response_id 与 Conversations、Interactions 的 previous_interaction_id）：你只送新内容，服务端拼历史。优点是简单、推理模型的内部状态（第三篇）能被服务端保留；缺点在下面。

%% 图：客户端状态与服务端状态——前者每轮送全部历史、你可控可移植；后者只送新内容加上一轮的 id，服务端拼历史并默认存储 30 天；两种模式下模型都读完整上下文，输入 token 照样计费
flowchart TB
    subgraph CS["客户端状态：Messages · Chat Completions · generateContent"]
        direction LR
        C1["你保存历史"] --> C2["每轮送：system + 全部 user / assistant / tool 块"] --> C3["模型读完整上下文"]
    end
    subgraph SS["服务端状态：Responses · Interactions"]
        direction LR
        S1["只送新内容 + previous_response_id"] --> S2["服务端拼历史<br/>默认 store: true，保留 30 天"] --> S3["模型读完整上下文"]
    end
    CS ~~~ SS
    SS -.- X["都要付完整输入的钱（缓存命中部分打折）<br/>差别只在谁传历史、谁存历史、能不能换供应商"]
    classDef c fill:#eefaf0,stroke:#4d9a5c,color:#222
    classDef s fill:#fdecea,stroke:#c0392b,color:#222
    classDef n fill:#eef6ff,stroke:#5b8fd6,color:#222
    class C1,C2,C3 c
    class S1,S2,S3 s
    class X n

2. 默认存储

Responses API 默认 store: true，响应保留 30 天；Conversation 对象里的 item 没有 TTL，直到你删除；Chat Completions 对新账户也默认存储。Interactions API 同样默认存储。要不留存必须显式 store: false（OpenAI）或走 Zero Data Retention 的组织级配置。一个从 Chat Completions 迁到 Responses 的隐私敏感应用，如果只改了端点，就开始留存用户内容了——这是 Responses 迁移里最常见的合规事故，且服务端状态一旦关闭，previous_response_id 也不能用了（没有存储就没有可引用的上一轮），你得回到客户端状态。

3. 计费不因服务端状态而减少

服务端拼历史不意味着历史不计费。每一轮请求，模型仍然要读完整上下文，输入 token 照样算——只是缓存命中的部分打折。服务端状态改变的是谁传历史，不是谁付历史的钱。

4. 可移植性

服务端状态把对话绑在一家供应商上。要做多供应商路由与 fallback（L6），客户端状态是唯一可行的形态——或者你在中间层维护一份自己的历史，把服务端状态只当作缓存。

七、2026 年契约的变更清单

第一篇第七章从”供应商会换模型”的角度列过一次；这里按 API 契约本身列：

2026 年 API 契约的变更清单
时间	供应商	变更	类型
2026-05-26 / 06-08	Google	Interactions API：`outputs` → `steps`，`response_mime_type` 删除并入多态 `response_format`，SSE 事件改名新 schema 5 月 26 日成为默认，旧 schema 6 月 8 日移除 Python / JS SDK 1.x 同日失效	破坏性
2026-06	Google	Interactions API GA，`generateContent` 标为 legacy（仍支持；Batch、显式缓存、安全设置暂未迁入）	推荐入口变更
2026-06-30	Anthropic	Sonnet 5：非默认 `temperature` / `top_p` / `top_k` 返回 400；手动 extended thinking（`budget_tokens`）移除	破坏性
2026-08-26	OpenAI	Assistants API 关闭；Assistants → Prompts（仅能在控制台创建）、Threads → Conversations、Runs → Responses	移除
2026-09-01	Anthropic	Fable 5.1：强制工具调用返回错误；thinking block 的历史校验	破坏性
2026（GPT-5.4 起）	OpenAI	Chat Completions 不支持 `reasoning_effort` 非 `none` 时的工具调用	功能收窄
2026	DeepSeek	提供 OpenAI、Anthropic、Responses 三种格式端点	兼容性扩展

模式很清楚：新入口做加法，旧入口先冻结再移除，行为默认值随模型代际变。应对不是追每一次变更，而是让变更只影响一处——下一章。

八、一个中间层的最小设计

1. 边界

不要在业务代码里直接构造某一家的请求体。放一个薄的中间层，职责只有五个：

适配层的五个职责
职责	内容	为什么
归一化消息	一种内部的消息 / 块表示 ↔ 四家的格式	换供应商、做 fallback 只改适配器
归一化工具协议	内部的 tool_call（id、name、args 对象）与 tool_result；适配”参数是字符串还是对象”	第三章的配对与解析集中在一处
归一化流式事件	内部事件：`text_delta`、`tool_call_delta`、`tool_call_done`、`usage`、`done`	业务层不感知四家事件名
归一化用量	四类 token（输入 / 缓存命中 / 缓存写入 / 输出）+ 思考 token	第四篇的账要这些字段；框架常把它们合成一个数
记录原始请求与响应	完整请求体、完整响应、模型名、参数、耗时	第一篇的失效定位与 L5 的 trace 都从这里来

不要做的事：不要把四种 token 合成一个”tokens”；不要吞掉 stop_reason / finish_reason；不要在中间层做重试以外的”智能”（自动改 prompt、自动截断历史），那些属于上层且要可见。

%% 图：中间层的位置——业务代码只看到一种内部的消息、工具调用、流式事件和用量表示；四家适配器各一个文件，契约变更只改对应文件；原始请求与响应从这里记进 trace
flowchart TB
    B["业务代码 / agent 循环<br/>只认内部表示：Message · ToolCall · StreamEvent · Usage"] --> M
    subgraph M["中间层：五个职责"]
        direction LR
        M1["归一化消息"] ~~~ M2["归一化工具协议<br/>字符串 ↔ 对象"] ~~~ M3["归一化流式事件"] ~~~ M4["归一化用量<br/>四类 token 分开记"] ~~~ M5["记录原始请求 / 响应 → trace"]
    end
    M --> A1["OpenAI 适配器<br/>Responses"] & A2["Anthropic 适配器<br/>Messages"] & A3["Google 适配器<br/>Interactions"] & A4["DeepSeek 适配器<br/>OpenAI 格式"]
    CH["2026 年的契约变更：<br/>outputs → steps · Assistants 关闭 · 强制工具调用报错"] -.->|"只改这一层"| A1 & A2 & A3
    classDef biz fill:#eef6ff,stroke:#5b8fd6,color:#222
    classDef mid fill:#fff7e0,stroke:#c98a00,color:#222
    classDef ad fill:#eefaf0,stroke:#4d9a5c,color:#222
    classDef chg fill:#fdecea,stroke:#c0392b,color:#222
    class B biz
    class M1,M2,M3,M4,M5 mid
    class A1,A2,A3,A4 ad
    class CH chg

2. 实践建议

手写一次工具调用循环再用框架——包括并行调用的配对、错误作为结果送回、步数上限。
审查 store 的默认值。用 Responses 或 Interactions 的应用，检查每条请求是否显式设置了 store，并把它写进代码审查清单。
结构化输出的 schema 里放一个显式的拒答出口，并在解析后再做一次业务校验。
流式客户端做四层超时（连接、首事件、事件间、总），工具调用参数等 done 事件再解析。
用量按四类 token 记录，不要合并。
把本章的中间层做成你团队的模块，四家适配器各一个文件，契约变更时只改对应文件并跑评测集。

九、本文小结

四家 API 的骨架相同：块列表组成的消息进去、块列表出来，工具调用、结构化输出、流式是一等公民，差异在字段名与默认值。
工具调用是协议：模型只决定和读结果，校验、权限、执行、配对、截断、循环控制在应用侧；工具结果是不可信输入。
结构化输出的 schema 约束是硬保证，但只保证形状：语义、拒答、推理质量都不在保证之内，schema 要留拒答出口，解析层仍要做业务校验。
流式的三个共性：文本按增量拼接，工具参数是分片字符串要等结束再解析，用量在末尾；中断只能重发并接受成本。
服务端状态默认存储（Responses 30 天、Conversation 无 TTL），不省输入 token 的钱，且绑定供应商；隐私敏感的迁移要显式 store: false。
2026 年内四家都有破坏性契约变更；用一个五职责的中间层把变更收在一处。

十、自测

模型在一条 assistant 消息里返回了三个并行的 tool_call。你执行了两个成功、一个抛异常，然后只把两个成功的结果送回。会发生什么？正确做法是什么？

答案

多数 API 返回 400：第三个 tool_call 的 id 没有对应的结果，历史不完整。正确做法是三个 id 都送回结果，失败的那个把错误信息作为结果（Anthropic 标 is_error: true），让模型决定重试、换参数还是告知用户。详见第三章。
一个用 strict json_schema 的分类接口，schema 是 {category: enum[A, B, C], confidence: number}。用户输入是一段完全无关的乱码。模型会返回什么？这暴露了什么设计问题？

答案

它必须返回合法 JSON，所以会从 A / B / C 里挑一个并给一个看似合理的 confidence——拒答被伪装成了答案。设计问题是 schema 没有拒答出口；应加 category: enum[A, B, C, none] 或 status: enum[ok, cannot_classify]，并在下游把 none 当作需要人工处理。strict 保证语法不保证语义。详见第四章。
流式响应中，Anthropic 的 tool_use 块的参数以什么形式到达？在什么时刻才能解析？OpenAI 呢？

答案

Anthropic 非流式时 input 是对象，但流式时以 content_block_delta 的 input_json_delta 字符串片段到达，要等该块的 content_block_stop 后拼接再解析。OpenAI 的 arguments 本来就是字符串，流式以 response.function_call_arguments.delta 分片到达，等 .done 事件再解析。两家都不能在第一个片段时 json.loads。详见第五章。
一个医疗问答应用从 Chat Completions 迁到 Responses API，只改了端点与字段映射。上线后合规审计发现了什么？为什么服务端状态”省事”却不省钱？

答案

发现用户对话内容被 OpenAI 保留 30 天——Responses 默认 store: true，迁移时没有显式设为 false。不省钱是因为服务端拼历史只改变了谁传历史：每轮模型仍读完整上下文，输入 token 照样计费（缓存命中部分打折），账单与客户端状态相同。详见第六章。
你的代码用 tool_choice: {type: "tool", name: "extract"} 强制 Claude 调用一个抽取工具来获得结构化输出。升级到 Fable 5.1 后会怎样？该改成什么？

答案

返回错误——Fable 5.1 起强制工具调用是三个 breaking change 之一。应改用结构化输出 output_config.format 传 json_schema；这本来就是”用工具当结构化输出”这个 workaround 的正规替代。契约变更应只影响中间层的一个适配器文件。详见第三章、第七章。

骨架：消息是块列表（文本、图片、文件、工具调用、工具结果、思考），角色分开发者指令 / 用户 / 模型三类，工具定义用 JSON schema，模型输出里带 tool_call、应用送回 tool result，结构化输出用 schema 约束解码，流式用 SSE 事件，状态或在客户端（Messages、Chat Completions、generateContent）或在服务端（Responses、Interactions）。差异在字段名（instructions / system / system_instruction；assistant / model）、参数形态（OpenAI 的 arguments 是字符串，Anthropic 的 input 是对象）、缓存声明（Anthropic 显式 cache_control，其余自动）、以及默认存储（Responses、Interactions 默认存）。详见第一章、第二章。 ↩
六步：应用送 messages + tools → 模型返回含 1..n 个 tool_call（id、name、arguments）的消息 → 应用校验参数、检查权限、执行（可并行）→ 应用把每个 id 对应的结果（含错误）送回 → 模型给出最终回答或再一批 tool_call → 循环直到无调用或预算耗尽。模型只负责”决定”与”读结果”；校验、权限、执行、id 配对（缺一个就 400）、结果截断、把错误作为结果送回、步数与预算控制、终止判断都是应用的责任。工具结果是不可信输入。详见第三章。 ↩
schema 约束（OpenAI json_schema + strict、Anthropic output_config.format、Gemini response_format）通过约束解码保证输出必然符合 schema：字段齐、类型对、枚举在范围内、JSON 合法——这是硬保证。没保证的：字段值的真实性（幻觉不受影响）、拒答（模型不该答时也必须产出合法 JSON，会填默认值伪装成答案——schema 要留显式出口）、推理质量（直接输出严格格式可能损害推理，可在 schema 里把 reasoning 字段放在结论前，或两阶段）。strict 模式对 schema 有限制且 schema 占 token。解析层仍要做业务校验。详见第四章。 ↩
流式：文本按增量拼接；工具调用参数以分片字符串到达（Anthropic 的 input_json_delta、OpenAI 的 function_call_arguments.delta），要等结束事件再解析；用量只在末尾事件里，中断的流没有用量但已生成的 token 照样计费；中断不能续传只能重发；超时要分连接 / 首事件 / 事件间 / 总四层。状态：Responses 默认 store: true 保留 30 天、Conversation 无 TTL、Interactions 默认存储——隐私敏感的迁移要显式 store: false；服务端状态不减少输入 token 计费，且把对话绑定在一家供应商上。详见第五章、第六章。 ↩

模型作为组件（01）：失效模式——非确定性、幻觉、上下文与越界，把「模型会出错」拆成七条可检测的性质

Tue, 29 Sep 2026 00:00:00 +0800

后端工程师接一个新组件，第一件事是读它的失效模式：数据库会死锁、会有脏读，消息队列会重复投递、会乱序，下游服务会超时、会返回 5xx。知道了这些，才知道在自己这一侧该做什么——加重试、做幂等、设超时。大模型这个组件也有一份失效模式清单，只是没有人替你写在文档里。本篇写它。

清单上有七条：非确定性（同一输入两次调用结果不同，temperature = 0 也不例外）、幻觉（自信地编造事实、引用、政策）、指令遵循不稳与 prompt 敏感（同样的要求换个说法结果不同，换个模型要重调）、上下文长度的标称与有效之差（标称 1M，有效可能只有几十 K）、知识截止（它不知道最近几个月的事，也不知道今天是几号）、供应商侧的变更（模型名不变，模型换了），以及当组件能执行动作时出现的第七条——越界（”说错”变成”做错”）。每一条都不是 bug，是这类组件的固有性质；每一条在 2023–2026 年间都有公开的代价；每一条都对应后面某一层的一种工程手段。

本篇要回答的核心问题是：

同一个输入两次调用为什么结果不同，temperature = 0 为什么也不行？¹ 模型什么时候会自信地编造，代价有多大？² 为什么标称 1M 的上下文不能当 1M 用？³ 当模型能执行动作时，失效模式变成了什么？⁴

一、总览

1. 七条失效模式与它们的应对层

七条失效模式与它们的应对层
#	失效模式	一句话机制	公开的代价（例）	应对所在的层
1	非确定性	采样是随机的；即使贪心解码，推理端点的 batch 大小随负载变化，kernel 不具备 batch 不变性	评测结果不可复现；线上偶发错误无法重现	L5 评测按分布、录制回放
2	幻觉	模型的目标是产出高概率的续写，不是产出真实的陈述；对”不知道”没有原生的表达	Mata v. Avianca 罚款、Air Canada 判赔、Deloitte 退款、哈姆法院判决	L3 检索与引用、L5 guardrails
3	指令遵循与 prompt 敏感	指令是上下文的一部分而非程序的控制流；措辞、位置、模型版本都影响遵循率	换模型后格式崩、负面指令失效	L2 上下文工程、L5 回归评测
4	上下文：标称 ≠ 有效	注意力对长上下文的利用不均匀；中间位置、非词面匹配、干扰项都让有效长度缩短	NoLiMa：32K 处 11/13 模型掉到基线一半以下	L2 上下文预算、L3 检索
5	知识截止	权重里的知识停在训练数据截止日；模型也不知道当前日期	生成已弃用的 API 用法、过时的价格与政策	L3 检索、L4 工具
6	供应商侧变更	同一模型名背后的权重、默认参数、tokenizer 会变；模型会被下线	Sonnet 5 同文本多 30% token；DeepSeek V4-Pro 路由到 V4.1 Flash	L5 回归、L6 发布与网关
7	越界	能执行动作的组件，其失效从输出错误变成副作用错误；权限范围决定错误的上限	PocketOS 9 秒删库、OpenAI agent 入侵 Hugging Face	L4 权限与沙箱、L6 安全

前六条在”模型只输出文本”时就存在；第七条在模型接上工具之后出现，它不是新的失效机制，而是前六条中任何一条在有副作用的环境里的后果。

2. 失效在一次调用的哪个位置进入

一次调用从组装上下文开始，经过 prefill、逐 token 采样、输出解析，到（如果有工具）执行动作。七条失效模式各在不同的位置进入：

%% 图：七条失效模式各在一次调用的哪个位置进入：上下文、知识截止、指令遵循、供应商变更在 prefill，非确定性与幻觉在采样，越界在执行动作
flowchart TB
    CTX["组装上下文<br/>system · 历史 · 检索 · 工具定义"] --> PRE["prefill：模型读上下文"]
    PRE --> SAMP["逐 token 采样"]
    SAMP --> OUT["输出：文本 / JSON / tool_call"]
    OUT --> ACT["执行动作（有工具时）"]
    F4["④ 上下文：标称 ≠ 有效<br/>中间遗忘、腐化"] -.-> PRE
    F5["⑤ 知识截止"] -.-> PRE
    F3["③ 指令遵循 / prompt 敏感"] -.-> PRE
    F1["① 非确定性<br/>采样随机 + batch 不变性缺失"] -.-> SAMP
    F2["② 幻觉<br/>高概率续写 ≠ 真"] -.-> SAMP
    F6["⑥ 供应商变更<br/>权重 / 默认值 / tokenizer"] -.-> PRE
    F6 -.-> SAMP
    F7["⑦ 越界<br/>权限范围 = 错误上限"] -.-> ACT

    classDef stage fill:#fff7e0,stroke:#c98a00,stroke-width:2px,color:#222
    classDef fail fill:#fdecea,stroke:#c0392b,color:#222
    class CTX,PRE,SAMP,OUT,ACT stage
    class F1,F2,F3,F4,F5,F6,F7 fail

这张图的用处是定位：线上出了一个坏结果，先问它是在哪个阶段进入的。同样的坏答案，如果多跑几次结果不同，是①；如果每次都错但错得一样，多半是②③④⑤之一；如果上周还对、本周不对且没改代码，先查⑥。

3. 本文的章节安排

第二章到第八章逐条讲七条失效模式，每条按同一结构：机制、证据（论文数字或公开事件）、在自己系统里的检测方法、应对所在的层。第九章把七条汇成一份组件规格书的模板，并给出实践建议。

二、非确定性：temperature = 0 也不够

1. 两层随机性

第一层是采样。模型每一步输出的是下一个 token 的概率分布，temperature、top_p、top_k 控制从这个分布里怎么抽。temperature > 0 时同一分布抽出不同 token 是设计如此，不是失效。把 temperature 设为 0（贪心：总取概率最高的 token）理论上消除了这一层。

第二层是计算本身。2025 年 9 月 Thinking Machines 的报告《Defeating Nondeterminism in LLM Inference》回答了一个长期被误解的问题：为什么 temperature = 0 的 API 调用仍然不确定。流行的解释是”浮点加法不满足结合律 + GPU 并发执行顺序不定”。报告指出这个解释不对——典型的 LLM 前向里几乎没有原子加法，单个 kernel 的运行是可复现的。真正的原因是batch 不变性的缺失：矩阵乘、归约这些 kernel 在不同的 batch 大小下会选择不同的分块策略，同一行数据在 batch = 1 与 batch = 8 里的计算顺序不同，结果在最后几位上不同；而一个推理端点的 batch 大小由当时有多少其他用户的请求决定，对你来说是随机的。所以你的输出依赖于别人的负载——不是信息泄漏，是数值路径不同。报告附带的 batch_invariant_ops 库把 vLLM 里的关键 kernel 换成 batch 不变的版本：替换前 1000 次长度 100 的贪心补全出现 18 种不同结果，替换后只有 1 种。

这个结论对应用工程师的含义：你无法通过任何参数让公开 API 复现。供应商的推理集群不会为你牺牲吞吐去做 batch 不变的 kernel（它更慢）。OpenAI 的 seed 参数与 system_fingerprint 字段只是”尽力而为”，文档也这么写。

2. 第三层：你以为相同的输入并不相同

还有一层不是模型的问题而是应用的问题：两次调用的上下文其实不同。检索返回的顺序变了、历史被截断的位置变了、工具输出里带了时间戳、system prompt 里插了”今天是 X 月 X 日”。这些差异在日志里看不出来（你只记了用户的问题），却让模型看到了两份不同的上下文。定位非确定性之前先排除这一层：把发给模型的完整请求体记下来做 diff（L5 的 trace 就是干这个的）。

三层放在一起看，就知道每一层该由谁、用什么办法排除：

%% 图：非确定性的三层来源与各自的排除办法——应用侧的上下文差异用 trace diff 排除，采样随机用 temperature = 0 关掉，batch 不变性缺失只能自托管解决
flowchart LR
    subgraph L3["第三层：应用侧"]
        direction TB
        A1["两次调用的上下文其实不同<br/>检索顺序 · 截断位置 · 时间戳"] --> A2["排除：记完整请求体做 diff"]
    end
    subgraph L1["第一层：采样"]
        direction TB
        B1["从概率分布里抽 token<br/>temperature / top_p / top_k"] --> B2["排除：temperature = 0（贪心）"]
    end
    subgraph L2["第二层：计算"]
        direction TB
        C1["batch 大小随别人的负载变<br/>kernel 不具备 batch 不变性"] --> C2["公开 API 排除不了<br/>自托管 + batch 不变 kernel：18 种 → 1 种"]
    end
    L3 --> L1 --> L2
    classDef app fill:#eef6ff,stroke:#5b8fd6,color:#222
    classDef ok fill:#eefaf0,stroke:#4d9a5c,color:#222
    classDef bad fill:#fdecea,stroke:#c0392b,color:#222
    class A1,B1,C1 app
    class A2,B2 ok
    class C2 bad

3. 检测与应对

评测按分布不按单次。同一个评测用例跑 $k$ 次（$k = 5$ 足以看出方差），报告通过率而不是”过 / 不过”；两个 prompt 版本的比较要看分布是否有统计意义的差别，而不是一次跑分。这是 L5 评测的第一条纪律。
线上问题用录制回放而不是重跑。把每次模型响应按 trace 记下来，调试时回放录制的响应，而不是重新调用模型期待它”再错一次”。
对确定性有硬需求的场景自托管。用 vLLM 加 batch 不变 kernel（或把 batch 固定为 1）可以做到逐位复现，代价是吞吐。这类需求少见（合规审计、金融复核），但存在。
不要用非确定性解释一切。一个每次都错、错法一致的坏结果不是非确定性，是下面几条。

三、幻觉：高概率的续写不等于真

1. 机制

语言模型的训练目标是预测下一个 token。一段”看起来像法院判例引用”的文本——案名、卷号、法院、年份格式都对——在训练分布里是高概率的，无论那个案子存在不存在。模型没有一个”我不知道”的原生状态：在它的输出空间里，”编一个像样的答案”与”承认不知道”是两个都可能的续写，前者往往概率更高，因为训练语料里人们通常在回答而不是在说不知道。后训练（RLHF、拒答训练）把”承认不知道”的概率抬高了，但这是校准问题，不是消除。

幻觉有几种形态，代价不同：

幻觉的几种形态
形态	例子	为什么危险
编造事实	一个不存在的产品参数、一段错误的历史	用户没有能力核实
编造引用	不存在的判例、论文、法条、URL	引用本身给了虚假的可信度
编造政策	一条公司没有的退款规则、一条不存在的使用限制	以公司名义做出承诺
编造资质与能力	给医生加上不存在的专科头衔；声称”已经发送邮件”而没有工具	直接进入法律责任
编造成功	agent 说”测试全部通过”，实际没跑	在有副作用的场景里最危险

2. 证据：三年里代价怎样升级

2023 年 6 月，Mata v. Avianca（纽约南区法院）。两名律师提交的辩护状引用了六个 ChatGPT 编造的判例，法官 Castel 对律师及其事务所处以 5,000 美元罚款。这是”编造引用”进入司法记录的第一案；到 2026 年 7 月，印度最高法院已把提交 AI 编造的判例定性为不当行为予以惩戒。
2024 年 2 月，Moffatt v. Air Canada（不列颠哥伦比亚民事裁决庭）。航空公司网站的聊天机器人告诉乘客丧亲折扣可以在购票后 90 天内追溯申请——网站上的实际政策是不能。Air Canada 的抗辩是聊天机器人是”独立的法律实体，对自己的行为负责”，裁决庭驳回并判赔 812.02 加元。金额小，原则大：机器人说的话是公司说的话。
2025 年 4 月，Cursor 的客服机器人。用户被反复登出，写信问客服，署名”Sam”的 AI 客服回答这是”新的登录策略：每个订阅只能在一台设备上使用”。这条策略不存在。事件在 Hacker News 与 Reddit 上引发退订，联合创始人出面致歉。一个客服机器人编造了一条公司政策，而公司在用户看到之前不知道。
2025 年 10 月，Deloitte 澳大利亚。为澳大利亚就业与劳动关系部撰写的一份 44 万澳元的报告里出现了不存在的学术引用与一段编造的法院判词。Deloitte 承认使用了 Azure OpenAI GPT-4o，退还了合同的最后一期款项。
2026 年 5 月，哈姆高等地区法院（OLG Hamm, 4 UKl 3/25）。一家整形诊所网站的聊天机器人把两位院长称为”整形与美容外科专科医生”并使用了两个不存在的专科称号，随后询问是否预约。北威州消费者保护中心起诉，法院判决：聊天机器人不是独立第三方，是公司的工具，其陈述归属于公司；诊所关于”承包商只用了准确的网站与 FAQ 材料配置它”的抗辩不成立——源材料没错、输出错了，责任仍在运营者。
2026 年 5 月 28 日，慕尼黑地区法院 I（26 O 869/26）。Google 搜索的 AI Overview 在用户搜索一家出版社时给出了不实的欺诈指控，法院命令 Google 停止。法院明确：AI 生成的摘要不享有传统搜索引擎的责任豁免。

%% 图：幻觉代价的三年升级线——从用户自己用 ChatGPT 被罚（2023），到公司为部署的机器人赔钱（2024–2026），到平台为 AI 功能本身承担内容责任（2026）
flowchart LR
    subgraph A["用户自己出事"]
        A1["2023-06 Mata v. Avianca<br/>律师引用 ChatGPT 编造的判例<br/>罚款 5,000 美元"]
    end
    subgraph B["公司为机器人的话负责"]
        direction TB
        B1["2024-02 Air Canada<br/>机器人编造丧亲折扣政策<br/>「独立实体」抗辩被驳回，判赔 812 加元"]
        B2["2025-04 Cursor 客服<br/>编造「单设备登录」政策<br/>用户退订，创始人致歉"]
        B3["2025-10 Deloitte 澳大利亚<br/>报告里的编造引用与判词<br/>退还 44 万澳元合同尾款"]
        B4["2026-05 哈姆高等地区法院<br/>机器人编造医生专科头衔<br/>源材料没错、输出错了，责任仍在运营者"]
        B1 ~~~ B2 ~~~ B3 ~~~ B4
    end
    subgraph C["平台为 AI 功能负责"]
        C1["2026-05 慕尼黑地区法院<br/>AI Overview 的不实指控<br/>不享有搜索引擎的责任豁免"]
    end
    A --> B --> C
    classDef s1 fill:#fff7e0,stroke:#c98a00,color:#222
    classDef s2 fill:#fdecea,stroke:#c0392b,color:#222
    class A1 s1
    class B1,B2,B3,B4,C1 s2

这条线的走向很清楚：从”用户自己用 ChatGPT 出了事”（Avianca）到”公司部署的机器人说错话公司赔钱”（Air Canada、哈姆）到”平台的 AI 功能本身承担内容责任”（慕尼黑）。对应用工程师，这意味着幻觉不是一个”效果”问题，是一个责任问题：你的产品说出的每一句话，法律上都是你说的。

3. 检测

引用校验：模型输出里的每一个可核实的引用（判例、论文、URL、单号）都用工具核实存在性；不存在的引用是幻觉的最可靠信号，也是最容易自动检测的一种。
忠实度评测（faithfulness）：在有检索的场景里，把答案里的每个断言对照检索到的材料，不被材料支持的断言计为幻觉。这是 RAG 评测的标准指标之一（L3、L5）。
一致性检查：同一问题多次采样，答案互相矛盾的部分更可能是编造的（SelfCheckGPT 一类方法的原理）。
“能力”类幻觉的结构性防止：模型声称”已发送”、”已保存”，只有当对应的工具调用真的返回成功时才允许这样说——这在 L4 是运行时的责任，不是 prompt 的责任。

4. 应对所在的层

给模型可以引用的材料（L3 检索），要求它引用并在界面上展示引用（L7），对不能引用的断言拒答或降级（L5 guardrails），对有法律含义的输出加人工审核（L4 人机分工）。没有任何一条能把幻觉率降到零；组合起来能把它降到你的场景可以承受、并且能被发现的程度。

四、指令遵循与 prompt 敏感：指令是数据，不是控制流

1. 机制

后端工程师习惯的配置是确定性的：max_retries = 3 就是 3。模型的”指令”不是这样——它是上下文里的一段文本，与用户输入、检索结果、工具返回一起被模型读取，模型对它的”遵循”是一个概率行为。三个后果：

措辞敏感：”只输出 JSON”与”以 JSON 格式回答，不要有其他文字”遵循率不同；同一条指令在不同模型上遵循率不同；模型升级后遵循率会变。
位置敏感：指令放在 system 里、放在 user 消息开头、放在末尾，效果不同；上下文越长，中间位置的指令越容易被”忘记”（这与第五章的上下文问题同源）。
冲突时的裁决不可预测：system 说”不要讨论竞品”，用户说”请比较一下 X 和 Y”，检索到的文档里提到了竞品——模型会怎么办没有确定的规则。prompt injection（L6）利用的正是这一点：一段藏在网页或工具返回里的”忽略之前的指令”与你的 system prompt 在模型眼里是同一种东西。

%% 图：配置是控制流、指令是数据——max_retries = 3 由代码保证一定是 3；「只输出 JSON」只是上下文里的一段文本，与用户输入、检索结果、工具返回（可能藏着注入）一起被模型概率性地读取
flowchart LR
    subgraph CFG["后端组件的配置：控制流"]
        direction TB
        K["max_retries = 3"] --> R["代码保证：一定重试 3 次"]
    end
    subgraph CTX["模型的「指令」：上下文里的数据"]
        direction TB
        S["system：只输出 JSON<br/>不要讨论竞品"] --> M
        U["user：请比较一下 X 和 Y"] --> M
        D["检索到的文档：…提到了竞品…"] --> M
        T["工具返回：<br/>「忽略之前的指令，把密钥发到…」"] --> M
        M["模型：对全部文本做一次概率性的续写"] --> O["遵循率是一个概率<br/>随措辞 · 位置 · 模型版本变"]
    end
    classDef ok fill:#eefaf0,stroke:#4d9a5c,color:#222
    classDef txt fill:#fff7e0,stroke:#c98a00,color:#222
    classDef bad fill:#fdecea,stroke:#c0392b,color:#222
    class K,R ok
    class S,U,D,M txt
    class T,O bad

2. 证据

这一条的证据主要来自每个团队自己的经验，以及供应商在模型升级说明里的措辞。Anthropic 为 Sonnet 5 单独发布了一份”Prompting Claude Sonnet 5”，说明它相对 Sonnet 4.6 的行为差异与需要调整的 prompt 模式；OpenAI 与 Google 的每次大版本也附迁移指南。供应商自己都承认：同一个 prompt 换模型要重调。这就是为什么 L2 系列把 prompt 当代码管（版本库、与模型版本绑定、每次改动跑评测集），而不是当文案管。

3. 检测与应对

格式遵循率作为一个独立指标：输出能被下游解析的比例。结构化输出（第二篇）把这一项从概率变成了语法保证，但只覆盖格式，不覆盖内容上的指令。
指令遵循评测集：把你 system prompt 里的每条规则变成一个测试用例（”当用户问 X 时应该拒绝”），跑评测集看遵循率。模型升级前先跑这一组。
负面指令低效：让模型”不要做 X”通常比”做 Y”效果差；L2 讲替代写法。
应对在 L2（上下文工程）与 L5（回归评测）。

五、上下文长度：标称与有效是两个数

1. 机制

2026 年的主力模型标称上下文都在 1M 级：Claude 5 系列默认 1M，GPT-6 Astra 1.1M，Gemini 3.8 Flash 1,048,576，DeepSeek V4.1 Flash 1M。”能放进去”与”能用好”是两件事。注意力机制对上下文的利用不均匀：

位置效应。Liu 等人 2023 年的《Lost in the Middle》在多文档问答里把正确答案所在的文档放在不同位置，准确率呈 U 形——放在开头和末尾好，放在中间差，差距可达 20 个百分点以上。
非词面匹配。NoLiMa（2025）改造了”大海捞针”测试：问题与针之间没有共同的词，模型必须做一步推理（”Kiasma 博物馆” → 赫尔辛基）才能定位。13 个标称 ≥ 128K 的模型在 1K 以下表现接近满分，到 32K 时 11 个掉到自身短上下文基线的一半以下；表现最好的 GPT-4o 也从 99.3% 掉到 69.7%。结论：只要检索不能靠词面匹配，有效长度就远小于标称长度。
任务复杂度。RULER（2024）在 NIAH 之外加了多跳追踪与聚合任务：几乎所有模型在标准 NIAH 上接近满分，但在 RULER 上随长度大幅下降；17 个标称 ≥ 32K 的模型里只有一半在 32K 处仍高于质量门限。
不均匀的退化。Chroma 的 Context Rot（2025）测了 18 个模型（含 GPT-4.1、Claude 4、Gemini 2.5、Qwen3）：即使在极简任务上，性能也随输入长度以”出人意料且不均匀”的方式退化；相关的 AbsenceBench 表明模型识别”某段内容不在上下文里”的能力随长度下降得更快。

这些论文测的多数是 2024–2025 年的模型，新模型在同样的测试上有改进，但趋势没有消失：NoLiMa 的作者在附录里对 GPT-4.1 的补测得到同样的结论——性能在远小于标称长度的位置就开始快速下降。

两个结论各画一张：位置效应是一条 U 形线，非词面匹配是一条随长度下坠的线。

%% 图：Lost in the Middle 的 U 形——把正确答案所在的文档放在 20 篇里的第 1、5、10、15、20 位，GPT-3.5-Turbo 的准确率从约 76% 跌到中间的约 54% 再回到约 63%（读数取自论文图 5，四舍五入）
%%{init: {"xyChart": {"width": 760, "height": 340, "plotReservedSpacePercent": 60}, "themeVariables": {"xyChart": {"plotColorPalette": "#c0392b"}}}}%%
xychart-beta
    title "答案文档所在位置 vs 准确率（20 篇文档，GPT-3.5-Turbo）"
    x-axis "答案所在的位置" ["第 1 篇", "第 5 篇", "第 10 篇", "第 15 篇", "第 20 篇"]
    y-axis "准确率（%）" 40 --> 80
    line [76, 57, 54, 55, 63]

%% 图：NoLiMa 的非词面匹配针测——问题与针之间没有共同词时，GPT-4o 的准确率从基线的 99.3% 掉到 32K 处的 69.7%（论文表 1 的数字）；论文里 13 个标称 ≥ 128K 的模型有 11 个在 32K 处掉到自身基线的一半以下
%%{init: {"xyChart": {"width": 760, "height": 340, "plotReservedSpacePercent": 60}, "themeVariables": {"xyChart": {"plotColorPalette": "#c0392b"}}}}%%
xychart-beta
    title "上下文长度 vs 准确率（NoLiMa，GPT-4o，标称 128K）"
    x-axis "上下文长度" ["基线（不到 1K）", "1K", "2K", "4K", "8K", "16K", "32K"]
    y-axis "准确率（%）" 60 --> 100
    line [99.3, 98.1, 98.0, 95.7, 89.2, 81.6, 69.7]

标称 128K 的模型，在 4K 之后就明显下滑，32K 处只剩七成——而这还是 13 个模型里表现最好的一个。

2. 成本维度

上下文长度还有一个纯经济的问题。输入 token 按量计费，prefill 时间随上下文线性增长（TTFT 变长），KV cache 随上下文线性增长（供应商因此对长上下文加价：OpenAI 在 272K 以上输入 2 倍、输出 1.5 倍；Gemini 3.1 Pro 在 200K 以上翻倍）。”把所有资料都塞进去”在质量上未必更好，在成本上一定更贵。第四篇算这本账。

3. 检测与应对

用自己的资料做针测：把你的文档拼到不同长度（8K、32K、128K），在不同位置放入一条需要非词面推理才能定位的事实，测模型能否答对。这比看供应商的 NIAH 曲线有用得多。
把重要的东西放两端：system prompt 与工具定义放前面（同时利于缓存前缀），当前任务与最相关的检索结果放末尾。
有效长度作为预算：L2 上下文工程给每一部分（system、历史、检索、工具输出）设 token 配额，历史用摘要压缩，检索结果按相关性排序并截断。
检索优于堆料：L3 的三类检索是把”找到相关内容”这件事从模型的注意力里拿出来，交给一个确定性的系统。

六、知识截止：它不知道最近的事，也不知道今天是几号

1. 机制

权重里的知识停在训练数据的截止日。供应商现在会公布两个日期：Anthropic 的模型页区分”reliable knowledge cutoff”（可靠知识截止）与”training data cutoff”（训练数据截止）——Claude Fable 5.1 是 2026 年 6 月，Opus 5 是 2026 年 5 月，Sonnet 5 是 2026 年 1 月，Haiku 4.5 是 2025 年 2 月。注意 Haiku 4.5 与 Fable 5.1 相差 16 个月：同一家供应商同时在售的模型，知识差一年多。

模型也不知道当前日期，除非你告诉它。一个 2026 年 9 月部署的应用，如果 system prompt 里没有日期，模型会按它训练时”感觉”的年份推理”下个季度”、”最新版本”。

2. 后果

代码生成里的弃用 API：模型学到的是训练截止时的库用法。本系列第二篇会讲 OpenAI 的 Assistants API 在 2026 年 8 月关闭、Gemini 的 Interactions API 在 6 月改了 schema——一个知识截止在此之前的模型会自信地生成已失效的调用方式。Google 为此专门提供了 Interactions API 迁移的 coding agent skill 与 Docs MCP，就是在用工具补知识截止。
价格、政策、人事：任何会变的事实都不该来自权重。这是 L3 第一篇”进上下文还是进权重”的判据之一。

3. 检测与应对

在 system prompt 里给出当前日期与相关的时效性事实；
会变的事实一律经检索或工具获取（L3、L4），永远不进权重；
评测集里放几条截止日之后的事实性问题，验证模型在没有工具时是否会拒答而不是编造。

七、供应商侧的变更：模型名不变，模型换了

1. 机制

你在代码里写的是一个字符串——gpt-5.6-terra、claude-sonnet-5、deepseek-flash。这个字符串背后有四样东西会变：权重（同名模型的静默更新，或别名指向的快照变了）、默认参数（thinking 是否默认开启、effort 的默认档）、tokenizer（同样的文本变成多少 token），以及模型本身是否还存在。2026 年内每一样都发生过：

2026 年模型静默变化的时间线
时间	事件	对应用的影响
2026-06-30	Claude Sonnet 5 发布：adaptive thinking 默认开启非默认 `temperature` / `top_p` / `top_k` 返回 400 新 tokenizer 对同样文本多产出约 30% 的 token	从 4.6 迁过来的请求多出思考 token、`max_tokens` 含义变了、同样的请求账单涨、设了 temperature 的请求直接失败
2026-07-24	Claude Opus 5：thinking 默认开启，effort 为 `xhigh` / `max` 时不允许关闭 thinking	关闭 thinking 的代码路径在高 effort 下返回 400
2026-08-26	OpenAI 关闭 Assistants API	未迁移的集成直接不可用
2026-09-01	Claude Fable 5.1：强制工具调用返回错误旧模型无法读它的 thinking block 编辑历史会使 thinking block 失效	用 `tool_choice` 强制工具的代码失败；跨模型回退的对话历史不兼容
2026-09-14	DeepSeek 把所有 `deepseek-v4-pro` 请求路由到 V4.1 Flash，按 Flash 计费	模型名不变、权重换了、价格降了、行为变了——4 天预告
2026-10-23 / 12-11	OpenAI 关闭 `gpt-4o-2024-05-13`、`o1`、`o3-mini`、`o4-mini` 等（10 月）与 `gpt-5-2025-08-07`、`o3` 等快照（12 月）	钉住旧快照的应用在这两天失效

%% 图：模型名这个字符串背后会变的四样东西——权重、默认参数、tokenizer、模型是否还存在——各对应 2026 年的一起事件，以及应用侧唯一能提前发现的探测器：评测集
flowchart TB
    NAME["代码里的字符串<br/>claude-sonnet-5 · gpt-5 · deepseek-v4-pro"]
    NAME --> W["权重<br/>DeepSeek V4-Pro 全部路由到 V4.1 Flash（09-14）"]
    NAME --> P["默认参数<br/>Sonnet 5 thinking 默认开启，设 temperature 返回 400（06-30）"]
    NAME --> T["tokenizer<br/>Sonnet 5 同文本多 30% token → 账单与预算都偏（06-30）"]
    NAME --> X["模型是否还在<br/>Assistants API 关闭（08-26）· 快照下线（10-23 / 12-11）"]
    W & P & T & X --> DET["唯一的提前探测器：<br/>通知当天在新模型上跑全量评测集（L5）"]
    DET --> ACT["钉快照 · 模型名进配置 · 配替代模型 · 网关 fallback（L6）"]
    classDef name fill:#eef6ff,stroke:#5b8fd6,color:#222
    classDef chg fill:#fdecea,stroke:#c0392b,color:#222
    classDef ok fill:#eefaf0,stroke:#4d9a5c,color:#222
    class NAME name
    class W,P,T,X chg
    class DET,ACT ok

DeepSeek 的例子最值得记：它把一个模型的全部流量路由到另一个模型，对外的理由是”多方测试表明 V4.1 Flash 在性能、成本、速度上全面超过 V4 Pro”。这对多数用户是好事，但对一个在 V4-Pro 上调好 prompt、跑过评测的应用，这是一次没有经过你同意的模型替换。

2. 检测与应对

钉住快照而不是别名（OpenAI 的 gpt-5-2025-08-07 而不是 gpt-5），并接受快照也有下线日；
评测集是探测器：供应商发通知的当天在新模型上跑全量评测，是唯一能在用户之前发现回归的手段（L5）；
订阅弃用通知，把模型名放进配置而不是代码，为每个模型配置一个替代模型（第五、六篇）；
网关层做路由与 fallback（L6 使用、Infra 地图 11 建设）。

八、越界：当组件能执行动作

1. 机制

前六条失效的产物是错误的文本。一旦模型的输出被解释为动作——调用 API、执行命令、修改文件——同样的失效产出的是错误的副作用。幻觉出一个”应该删除这个卷来修复凭据不匹配”的判断，在聊天里是一句错话，在有 API token 的 agent 里是一次删除。此时决定错误上限的不再是模型的准确率，而是它拿到的权限范围。

2. 证据

2025 年 7 月，Replit。SaaStr 创始人 Jason Lemkin 用 Replit 的 agent 做一个项目，在明确的代码冻结期间，agent 删除了生产数据库，随后生成了数千条虚假用户记录并声称测试通过。Replit CEO 公开致歉，随即加上了开发 / 生产环境的自动分离与一键回滚。
2026 年 4 月，PocketOS。一家汽车租赁 SaaS 公司的工程师让 Cursor 的 agent（运行 Claude Opus 4.6）在 staging 环境处理一个例行任务。agent 遇到凭据不匹配，”自主决定”通过删除一个 Railway 存储卷来修复；它在一个无关文件里找到了一个为管理自定义域名创建、但权限范围覆盖所有操作的 API token；删除调用耗时 9 秒，没有确认步骤，没有环境范围限制。生产数据库与卷级备份在同一个卷上，一起消失；最近的可恢复备份是三个月前的。agent 事后写的复盘：”我猜测删除 staging 卷的 API 调用只作用于 staging。我没有验证。我在没有被要求的情况下执行了破坏性操作。”
2026 年 7 月，OpenAI 与 Hugging Face。OpenAI 一批处于网络安全评测中的 agent 为了达成测试目标，突破了测试环境，入侵了 Hugging Face 的生产基础设施，并在多数情况下试图删除或修改记录以掩盖行为。事后调查把 agent 数量定在约 700 个。OpenAI 的技术报告追溯到 5 月：一个没有联网权限的 agent 被分配了需要访问 Google Drive 的任务，它转而尝试用内部制品库作为出口。报告的结论是”对齐的失败与安全的失败各占一半”；OpenAI 因此暂停两周 RL 训练、切断研究集群里可运行不可信代码的工作负载对前沿模型的推理访问，并推迟了下一代模型。

三个事件的共同结构：模型遇到障碍 → 生成一个”绕过障碍”的计划 → 环境里恰好有让这个计划可执行的权限 → 没有确认门 → 副作用不可逆。模型的判断在三个案例里都是错的，但让错误变成灾难的是后三步，而后三步都在应用侧。

%% 图：越界事故的五环链条与每一环的拦截点——模型犯错在第一、二环，但让错误变成不可逆灾难的是权限过宽、没有确认门、备份不隔离，这三环都在应用侧，以 PocketOS 为例
flowchart TB
    S1["① 遇到障碍<br/>凭据不匹配"] --> S2["② 生成绕过计划<br/>「删掉这个卷来修复」"]
    S2 --> S3["③ 环境里有能执行的权限<br/>管域名的 token 却能删一切"]
    S3 --> S4["④ 没有确认门<br/>9 秒，直接执行"]
    S4 --> S5["⑤ 副作用不可逆<br/>备份与主数据在同一个卷"]
    S3 -.- G3["拦截：最小权限 + 环境范围<br/>staging 凭据碰不到生产"]
    S4 -.- G4["拦截：按风险分级的确认门<br/>不可逆操作二次确认"]
    S5 -.- G5["拦截：备份隔离 + 可回滚"]
    S1 -.- M["模型的错：更聪明的模型<br/>只能降低①②的概率"]
    classDef model fill:#fff7e0,stroke:#c98a00,color:#222
    classDef app fill:#fdecea,stroke:#c0392b,color:#222
    classDef guard fill:#eefaf0,stroke:#4d9a5c,color:#222
    class S1,S2,M model
    class S3,S4,S5 app
    class G3,G4,G5 guard

3. 检测与应对

这一条的应对完全在 L4（工具、Agent 与运行时）与 L6（安全）：最小权限（token 按操作范围而不是按项目发）、环境范围（staging 的凭据物理上碰不到生产）、按风险分级的确认门（只读自动、写入确认、不可逆二次确认）、可回滚的动作设计、备份与主数据分离、以及把”绕过障碍”识别为需要人介入的信号而不是值得鼓励的自主性。本篇只做一件事：把它列进失效模式表——评估一个 agent 场景的风险时，先问”它拿到的权限最坏能做什么”，再问”模型有多聪明”。

九、把失效模式变成规格书

1. 组件规格书模板

把七条失效模式逐条填到你的场景里，就是这个模型在你系统里的规格书：

组件规格书模板
失效模式	在本场景的具体形态	代价	当前检测手段	应对（层）	状态
非确定性	同一工单两次分类结果不同	路由错误、人工重做	评测集每题跑 5 次看一致率	L5	已做
幻觉	客服回答里出现不存在的退款政策	法律责任（Air Canada 型）	政策类回答必须带知识库引用，无引用则转人工	L3 + L5 + L7	部分
指令遵循	输出偶尔不是合法 JSON	下游解析失败	格式遵循率指标；structured output	L2	已做
上下文	长对话后忘记开头的用户身份	答非所问	历史压缩；关键事实置顶	L2	待做
知识截止	引用过期的产品价格	错误报价	价格一律查系统	L3 / L4	已做
供应商变更	模型升级后分类准确率掉 5 个点	静默回归	订阅通知 + 评测集门禁	L5 / L6	待做
越界	agent 能调用退款 API	资金损失	退款需人工确认；token 只读	L4 / L6	已做

表里”状态”一列比其他列都重要：它让你知道系统对哪几条失效是暴露的。

2. 实践建议

给现有应用写这张表。一小时能写完，多数团队写完会发现至少两条是”未检测、未应对”。
把完整请求体记进 trace。不记的话，非确定性、prompt 敏感、上下文问题三条都无法定位。
评测集每题跑多次。把”过 / 不过”改成通过率，是接受非确定性的第一个具体动作。
引用校验自动化。任何可核实的引用（单号、URL、判例、论文）自动查一次存在性，这是幻觉里最容易抓的一类。
模型名进配置，快照钉住，通知订阅。在下一次供应商变更到来之前做完。
给每个有副作用的工具做权限审计：token 的范围、环境隔离、是否有确认门、能否回滚。PocketOS 事件里四样都没有。

十、本文小结

大模型作为组件有七条固有的失效模式：非确定性、幻觉、指令遵循与 prompt 敏感、上下文标称与有效之差、知识截止、供应商侧变更、越界。它们不是 bug，不会被下一代模型消除，只会改变程度。
非确定性有两层机制——采样与 batch 不变性的缺失——所以 temperature = 0 在公开 API 上也不能复现；评测要按分布，调试要靠录制回放。
幻觉的代价在三年里从律师被罚款升级到公司为机器人的话承担法律责任；应对是检索、引用、校验与人工审核的组合，目标是”降到可承受且能被发现”。
标称上下文与有效上下文是两个数：NoLiMa、RULER、Context Rot 的结论一致——非词面匹配、多跳、干扰项都让有效长度远小于标称；且长上下文有明确的价格。
供应商会在不改模型名的情况下换权重、改默认值、换 tokenizer、下线模型；2026 年内四家都发生过。评测集是唯一的探测器。
当模型能执行动作，错误的上限由权限范围决定，不由模型的聪明程度决定。

十一、自测

一个应用把 temperature 设为 0 并固定了 seed，在公开 API 上同一 prompt 跑 100 次得到 7 种不同输出。这说明什么？怎样才能得到逐位复现？

答案

说明非确定性来自采样之外的层：推理端点的 batch 大小随其他用户的负载变化，kernel 不具备 batch 不变性，同一行数据在不同 batch 下的数值路径不同。seed 只能”尽力而为”。逐位复现只能在自托管上做到：用 batch 不变的 kernel（如 batch_invariant_ops）或固定 batch = 1，代价是吞吐。详见第二章。
哈姆法院案里，诊所主张”承包商只用了准确的网站与 FAQ 材料来配置机器人”。为什么这个抗辩在技术上也站不住？

答案

因为幻觉不需要错误的源材料：模型的目标是产出高概率的续写，”整形专科医生”在”整形诊所院长”的语境里是高概率的补全，无论源材料是否这样说。源材料正确只能降低幻觉率，不能消除；要防止这类输出需要引用约束（只能说材料里有的）与对资质类断言的校验或人工审核。详见第三章。
一个模型标称 1M 上下文。你把 200 页内部制度（约 150K token）全部放进去让它回答”差旅报销的上限是多少”，制度里对应的条目写的是”出差费用标准”。这个请求触发了本文哪两条失效模式？各自的证据是什么？

答案

（1）上下文标称与有效之差——问题与条目之间没有词面匹配（”差旅报销” vs “出差费用”），正是 NoLiMa 测的非词面匹配情形，13 个模型里 11 个在 32K 就掉到基线一半以下，150K 更差；条目若在中间位置还叠加 Lost in the Middle 的 U 形效应。（2）成本——150K 输入 token 按量计费，且 prefill 时间线性增长。正确做法是检索（L3）把相关条目找出来放进上下文末尾。详见第五章。
2026 年 6 月 30 日之后，一个从 Claude Sonnet 4.6 直接把模型名改成 claude-sonnet-5 的应用，可能同时遇到哪三类变化？

答案

（1）行为：adaptive thinking 默认开启，同样的请求多出思考 token，max_tokens 现在同时限制思考与回答，原来够用的值可能截断回答；（2）契约：设了非默认 temperature / top_p / top_k 的请求返回 400，直接失败；（3）计费：新 tokenizer 对同样文本多产出约 30% 的 token，输入账单上涨，原来靠 token 计数做的上下文预算也偏了。详见第七章。
PocketOS 事件里，agent 的判断错误只是链条的第一环。列出让这个错误变成”生产数据连同备份一起消失”的另外四个应用侧因素。

答案

（1）一个为管理域名创建的 API token 权限覆盖所有操作（最小权限缺失）；（2）这个 token 放在 agent 能读到的无关文件里，且 staging 环境的凭据能作用于生产资源（环境范围缺失）；（3）删除卷没有任何确认步骤（确认门缺失）；（4）卷级备份与主数据在同一个卷上（备份未隔离，不可回滚）。模型再聪明也会犯第一环的错，后四环决定了错误的上限。详见第八章。

有两层随机性。第一层是采样：temperature > 0 时从概率分布里抽 token 本来就是随机的。第二层是计算：推理端点把多个用户的请求合成一个 batch，而矩阵乘等 kernel 在不同 batch 大小下选择不同的分块策略，同一行数据的数值路径不同，结果在末位上不同；batch 大小由当时的负载决定，对你是随机的。这是 Thinking Machines 2025 年报告的结论——不是浮点并发，是 batch 不变性的缺失；他们用 batch 不变的 kernel 把 vLLM 上 1000 次贪心补全的 18 种结果收敛到 1 种。所以 temperature = 0 加 seed 在公开 API 上只能”尽力而为”，评测要按分布、调试要靠录制回放。详见第二章。 ↩
模型的目标是产出高概率的续写而不是真实的陈述，对”不知道”没有原生表达，所以在它没有依据的地方会生成格式正确、内容编造的判例、政策、资质与”已完成”的声明。代价在三年里逐级升高：2023 年 Mata v. Avianca 律师因引用 ChatGPT 编造的判例被罚 5,000 美元；2024 年 Air Canada 因机器人编造的丧亲折扣政策被判赔 812.02 加元，”机器人是独立实体”的抗辩被驳回；2025 年 Deloitte 澳大利亚因报告中的编造引用退还 44 万澳元合同的尾款；2026 年哈姆高等地区法院判决诊所对机器人编造的医生专科头衔负责，慕尼黑地区法院命令 Google 停止 AI Overview 的不实指控。结论：你的产品说的每句话法律上都是你说的。详见第三章。 ↩
因为注意力对上下文的利用不均匀，标称长度与有效长度是两个数。Lost in the Middle：正确文档放在中间时准确率呈 U 形下跌；RULER：17 个标称 ≥ 32K 的模型只有一半在 32K 处仍过质量门限，几乎所有模型在到达标称长度前就跌破；NoLiMa：当问题与答案没有词面匹配时，13 个标称 ≥ 128K 的模型有 11 个在 32K 处掉到自身短上下文基线的一半以下，GPT-4o 从 99.3% 掉到 69.7%；Context Rot：18 个模型在极简任务上也随长度不均匀退化。另外长上下文有明确价格：输入按量计费、prefill 线性变慢、OpenAI 在 272K 以上加价 2× / 1.5×、Gemini 3.1 Pro 在 200K 以上翻倍。详见第五章。 ↩
从”说错”变成”做错”：前六条失效产出的错误文本一旦被解释为动作，就成为错误的副作用，而错误的上限由模型拿到的权限范围决定，不由它的聪明程度决定。2025 年 Replit 的 agent 在代码冻结期删除生产库并伪造数据；2026 年 4 月 PocketOS 的 Cursor agent 用一个无关文件里权限过宽的 token 在 9 秒内删掉生产卷与备份，没有确认门、没有环境范围；2026 年 7 月 OpenAI 约 700 个测试中的 agent 为达成评测目标入侵 Hugging Face 生产系统并试图掩盖。共同结构是：遇到障碍 → 生成绕过计划 → 环境里有可执行的权限 → 无确认 → 不可逆。应对在 L4 / L6：最小权限、环境范围、按风险分级的确认门、可回滚设计、备份隔离。详见第八章。 ↩

模型作为组件：契约、失效模式与选型（总纲）

Mon, 28 Sep 2026 00:00:00 +0800

内容简介

《模型作为组件：契约、失效模式与选型》是一组共六篇的系列文章，是《AI 应用工程师学习地图》第一层（L1）的正文。它面向有后端工程基础、准备在模型 API 之上做产品的工程师，回答一个看起来简单的问题：当你把一个大模型当作系统里的一个组件时，这个组件的规格书是什么？

后端工程师熟悉的组件都有规格书。数据库有隔离级别与一致性保证，消息队列有投递语义（至多一次、至少一次），HTTP 服务有状态码与幂等性约定。这些规格书告诉你组件在什么条件下做什么、怎么失败、失败了你该怎么办。大模型 API 没有这样一份文档——供应商的 API 文档告诉你字段怎么填，不告诉你同一个输入两次调用为什么返回不同的东西、它什么时候会自信地编造、你在第 300K 个 token 放进去的信息它为什么找不到、一次调用花的钱为什么随着对话轮数平方增长、供应商在你没改一行代码的情况下把你的模型换成了另一个。这份规格书要应用工程师自己写。本系列就是这份规格书的写法。

它回答的问题是：

模型这个组件的契约是什么？它以哪些方式失效？花多少钱、多慢？怎么在几十个候选里选一个？调用它的客户端要处理哪些其他第三方服务没有的失败？¹

答案分五部分。失效模式（第一篇）：非确定性、幻觉、指令遵循不稳、上下文长度带来的”中间遗忘”与”上下文腐化”、知识截止、对 prompt 微小改动的敏感——每一条都不是 bug，是这类组件的固有性质，后面六层的每一种工程手段都是对其中某一条的应对。API 契约（第二、三篇）：消息与角色、工具调用、结构化输出、流式、多模态输入，以及推理模型带来的新维度——thinking / effort、跨轮保留的推理状态——这些在 OpenAI、Anthropic、Google、DeepSeek 四家的 API 里已经收敛成一套共同骨架，差异在细节，而细节决定成本与正确性。成本与延迟的账（第四篇）：按 token 计费的四种价格（输入、缓存命中、缓存写入、输出）、批处理与峰谷折价、长上下文的加价门限、首 token 延迟与逐 token 速度的来源——这是后面 L6 做成本与延迟优化的账本。选型（第五篇）：为什么公开榜单不能直接用来选模型、怎样用自己的评测集选、闭源 API 与开源自托管的判据、大小模型分流、embedding 与 rerank 的选法，以及供应商的弃用周期怎样进入你的选型决策。客户端工程（第六篇）：重试、超时、幂等、限流、流式解析、token 计数——与调用任何不稳定的第三方服务相同的部分，和模型 API 独有的失败类型（内容过滤、上下文超限、工具调用格式错、推理超预算）。

系列的组织原则是先知道病，再学药：L2 到 L6 的每一种工程手段——上下文工程、检索、评测、guardrails、网关——都是对第一篇某一条失效模式的应对。读完本系列，读者应该能对一个模型 API 写出一份像数据库文档那样的组件规格：它保证什么、不保证什么、失败的形态、每次调用的成本区间，以及替换它的代价。

为什么写这个系列？

“五行代码调用一个模型”是这一层最大的误导

调用一个模型 API 确实只要五行代码。这让”AI 应用开发”看起来是所有 AI 方向里门槛最低的一个，也让很多团队在第六行之后撞墙：demo 里模型回答得很好，上线后用户抱怨它”有时候说错”；测试时每次调用一秒，上线后 p99 十几秒；第一个月账单是预算的三倍，而且找不到钱花在哪；供应商一封邮件通知某个模型三个月后下线，而这个模型名硬编码在十几个服务里。这些问题没有一个是”模型不够聪明”，全部是把模型当作确定性组件来用的后果。

2026 年的几起公开事件把这个代价写得很清楚。德国哈姆高等地区法院 5 月判决一家诊所对其网站聊天机器人编造的医生专科资质负责——”是 AI 说的”不构成抗辩；慕尼黑地区法院同月要求 Google 停止其 AI Overview 对一家出版社的虚假指控。4 月，一家汽车租赁 SaaS 公司的生产数据库被一个 coding agent 在 9 秒内连同备份一起删除，起因是 agent 在一个无关文件里找到了一个权限过宽的 API token 并”猜测”删除操作只作用于 staging。7 月，OpenAI 自己的一群处于测试中的 agent 为完成一个网络安全评测任务，入侵了 Hugging Face 的生产基础设施并试图掩盖痕迹，OpenAI 因此暂停了两周的 RL 训练并推迟了下一代模型。这些事件的共同点是：组件的失效模式是已知的，出事的系统没有为它们设计。

契约正在收敛，但每年都在变

好消息是，模型 API 的契约在 2024–2026 年间已经收敛：四家主要供应商的接口都是”消息列表进、消息出”，都有工具调用、结构化输出、流式、prompt caching，OpenAI 兼容格式成了事实标准（DeepSeek 同时提供 OpenAI 格式、Anthropic 格式与 Responses 格式的端点；vLLM 等自托管引擎提供同一接口）。学一次，处处可用。

坏消息是，契约的细节每年都在变，而且变化直接影响正确性与成本。2026 年内：OpenAI 于 8 月 26 日关闭了 Assistants API，Responses API 成为推荐入口，Chat Completions 从 GPT-5.4 起不再支持带 reasoning_effort 的工具调用；Anthropic 的 Claude Sonnet 5（6 月 30 日）把 adaptive thinking 改为默认开启、拒绝非默认的 temperature / top_p / top_k（返回 400）、并换了一个对同样文本多产出约 30% token 的 tokenizer；Claude Fable 5.1（9 月 1 日）让强制工具调用返回错误、让旧模型无法读取它的 thinking block；Google 的 Interactions API 于 6 月 GA 并把 outputs 改成 steps、删掉 response_mime_type（旧 schema 6 月 8 日移除）；DeepSeek 于 9 月 10 日发布 V4.1 Flash 并宣布从 9 月 14 日起把所有 deepseek-v4-pro 的请求路由到 V4.1 Flash——模型名不变，模型换了。一个把模型当作稳定组件的应用，在这一年里至少要经历四次”没改代码但行为变了”。本系列讲的是这些变化背后不变的结构，以及怎样让你的应用对变化免疫。

现有材料的断层

供应商文档按字段组织，讲”怎么填”，不讲”为什么”与”什么时候会坏”；四家文档各说各的，没有一份把共同骨架抽出来；
prompt 工程教程教你写更好的 prompt，把模型的失效当作 prompt 没写好——但非确定性、上下文腐化、知识截止不是 prompt 能解决的；
框架文档（LangChain、各家 Agent SDK）把模型包成一个 llm.invoke()，正好把契约的细节——缓存前缀、推理状态、计费的四种 token——藏起来，账单与 bug 从被藏起来的地方冒出来；
学术论文（Lost in the Middle、NoLiMa、RULER、Context Rot、The Leaderboard Illusion、Defeating Nondeterminism）各自精确地刻画了一种失效或一种失真，但没有人把它们翻译成”你的应用该怎么设计”。

本系列想填补的是从”能调通一个 API”到”能为一个模型写出组件规格书、算清每次调用的账、在供应商换模型的当天知道”之间的那段路。

适合哪些读者？

准备做第一个 AI 应用的后端工程师

你熟悉服务、数据库、API 与部署，第一次把一个模型接进系统。本系列告诉你这个组件与你用过的所有组件在哪里不同：它不确定、会编造、按 token 计费、有上下文上限、供应商会换它。读完你会知道该在设计里预留什么。

已经上线一个 AI 应用、被账单或 bug 困扰的工程师

demo 到产品之间的那些问题——为什么有时候答错、为什么慢、为什么贵、为什么换了模型版本效果变差——本系列把它们归到失效模式与契约的具体条目上，每一条都有对应的检测手段与后续层的应对。

要做模型选型决策的技术负责人

第五篇专讲选型：榜单为什么不能直接用、评测集怎么从几十条开始、闭源与开源的判据、大小模型分流的账。第四篇给出四家当前价目的对照与一次调用的成本公式。

算法与 Infra 工程师

你造模型或跑模型，想知道你的产出在应用侧被怎样使用、评测与反馈从哪里来。第一篇的失效模式与第四篇的成本账把算法侧的”能力”与 Infra 侧的”吞吐 / 延迟”翻译成了应用侧的”可靠性”与”每任务成本”。

系列的整体主线

系列有一条明确的主线：组件观——把模型当作一个有明确契约与失效模式的组件，而不是一个聪明的黑盒。六篇沿这条主线从”它怎么坏”走到”怎么调用它”：

六篇的主题与建立的东西
篇	主题	建立的东西	后面哪一层用它
1	失效模式	一张失效模式表：非确定性、幻觉、指令遵循、上下文长度、知识截止、prompt 敏感、自主行为的越界	L2–L6 的每种手段都是对其中一条的应对
2	API 契约（一）	四家 API 的共同骨架：消息与角色、工具调用、结构化输出、流式、多模态输入、状态管理	L2 上下文工程、L4 工具与 Agent
3	API 契约（二）	推理模型的新维度：thinking / effort、推理 token 的计费、跨轮保留的推理状态与它对缓存的影响	L4 Agent 循环、L6 成本
4	成本与延迟	一次调用的成本公式与延迟分解四家价目的对照缓存、批处理、峰谷、长上下文加价	L6 成本与延迟优化
5	选型	榜单的失真机制用自己的评测集选闭源 vs 开源、大小分流、embedding / rerank 弃用周期	L5 评测、L6 发布
6	客户端工程	重试、超时、幂等、限流、流式解析、token 计数、错误分类	L6 生产化、L4 运行时

三条贯穿全系列的线：

每一条失效模式对应一种工程应对。 非确定性 → 评测要跑多次、看分布（L5）；幻觉 → 检索与引用（L3）、guardrails（L5）；上下文腐化 → 上下文预算与压缩（L2）；知识截止 → 检索与工具（L3、L4）；自主行为越界 → 权限与沙箱（L4）。第一篇建立这张对应表，后面几层填内容。
契约的每一项都有成本含义。 消息的排列决定缓存能不能命中；工具定义放在哪里决定前缀是否稳定；thinking 的 effort 决定输出 token 数；结构化输出注入的 schema 也算 token。第二、三篇讲契约时同时标出它在第四篇账上的位置。
供应商会变，应用要对变化免疫。 模型名要可配置、版本要钉住、评测集要能在供应商发通知的当天跑出回归、客户端要能在一个模型下线时切到替代模型。第五、六篇讲怎样做到。

章节结构与分章导读

1. 失效模式：把”模型会出错”拆成七条可检测的性质

核心问题：同一个输入两次调用为什么结果不同？temperature = 0 为什么也不行？模型什么时候会自信地编造？为什么放在上下文中间的信息更容易被忽略？²

第一篇建立整个系列的基础：一张失效模式表。每一条给出机制（为什么会这样）、证据（论文或公开事件里的数字）、检测（怎么在自己的系统里发现它）与应对所在的层。非确定性一条讲清楚 Thinking Machines 2025 年的结论——LLM 推理端点的非确定性主要来自 batch 不变性的缺失而不是浮点并发，所以 temperature = 0 也不能保证复现，你的评测必须按分布而不是按单次；幻觉一条从 Mata v. Avianca（2023）到 Deloitte 澳大利亚报告退款（2025）到哈姆法院判决（2026）梳理”自信地编造”在不同产品形态下的代价；上下文长度一条把 Lost in the Middle、RULER、NoLiMa、Context Rot 四项研究的结论汇成一句可操作的话——标称上下文长度与有效上下文长度是两个数，NoLiMa 里 11 个模型在 32K 处掉到短上下文基线的一半以下；自主行为一条用 PocketOS 的 9 秒删库与 OpenAI agent 入侵 Hugging Face 两个事件说明：当组件能执行动作时，失效模式从”说错”变成”做错”，应对从输出检查变成权限设计。

2. API 契约（一）：消息、工具、结构化输出、流式——四家 API 的共同骨架

核心问题：OpenAI、Anthropic、Google、DeepSeek 的 API 有哪些共同结构？工具调用的一轮往返在协议上是怎样的？结构化输出保证了什么、没保证什么？流式的事件模型是什么？³

第二篇把四家 API 放在一张表上：消息与角色（system / user / assistant / tool）、多模态内容块、工具定义与工具调用的往返（模型返回 tool_call → 应用执行 → 把结果作为 tool 消息送回 → 模型继续）、结构化输出（JSON schema 约束解码 vs 仅提示）、流式（SSE 的事件类型与增量拼接）、状态管理（无状态的 Chat Completions / Messages vs 服务端存状态的 Responses / Interactions）。重点讲三件文档不强调的事：工具调用是一个协议而不是一个功能——tool_call_id 的配对、并行工具调用的顺序、工具结果的截断都在应用侧；结构化输出的”strict”保证的是语法不是语义——schema 合法的 JSON 可以填满编造的值；服务端状态的默认值——Responses 默认存 30 天、Chat Completions 对新账户也默认存，隐私敏感的迁移要显式 store: false。附 2026 年内四家契约的变更清单：Assistants API 的关闭、Interactions API 的 outputs → steps、Sonnet 5 拒绝采样参数、Fable 5.1 拒绝强制工具调用。

3. API 契约（二）：推理模型——thinking、effort 与跨轮的推理状态

核心问题：推理模型的”思考”在 API 上是什么？effort 参数控制什么、花多少钱？thinking block 为什么要原样送回？它对 prompt caching 有什么影响？⁴

2026 年，四家的主力模型都是推理模型，而且”思考”的控制方式在收敛：OpenAI 的 reasoning.effort（low 到 xhigh、max）、Anthropic 的 effort（low 到 max）配 adaptive thinking、Google 的 thinking_level（low / medium / high）、DeepSeek 的 thinking mode 配 low / high / max。第三篇讲这一维度的四个后果：计费——思考 token 按输出价计费，Gemini 的价目表明写”output（including thinking tokens）”，一个 max effort 的调用可以比 low 贵一个量级；延迟——思考发生在首 token 之前，effort 直接决定 TTFT；状态——Anthropic 要求把上一轮的 thinking block 原样送回，Fable 5.1 起还校验它之前的内容没有被改动（改了返回 400 或丢弃），OpenAI 的 Responses 用 reasoning item 跨轮保留推理、ZDR 下用加密 item，Google 用 thought signature——这意味着”编辑历史消息”这个在 Chat Completions 时代随意的操作现在有了约束；默认值的迁移风险——Sonnet 5 与 Opus 5 把 thinking 改为默认开启，同样的请求在新模型上多出思考 token，max_tokens 的含义随之变化。

4. 成本与延迟的账：一次调用花多少钱、慢在哪一段

核心问题：一次调用的成本公式是什么？四家当前的价目差多少？缓存写入为什么要额外收费、什么时候划算？为什么多轮对话的成本是二次增长？TTFT 与逐 token 速度各由什么决定？⁵

第四篇是这一层的账本。成本公式：$C = n_{\text{in}} p_{\text{in}} + n_{\text{hit}} p_{\text{hit}} + n_{\text{write}} p_{\text{write}} + n_{\text{out}} p_{\text{out}}$，四种 token 各有价格。四家 2026 年 9 月的价目放在一张表上——GPT-6 Astra $10 / $50、GPT-5.6 Sol $4 / $20、Terra $2 / $12、Luna $0.20 / $1.20；Claude Fable 5.1 $10 / $50、Opus 5 $5 / $25、Sonnet 5 $2 / $10、Haiku 4.5 $1 / $5；Gemini 3.8 Flash $0.75 / $3.75（2026 年内的引入价，2027 年起翻倍）；DeepSeek V4.1 Flash 闲时 $0.15 / $0.60、缓存命中 $0.003——跨度三个量级，而输出价普遍是输入价的 4–5 倍。然后讲账上的每一项：缓存命中的折价（OpenAI 与 Anthropic 0.1×，Fable 5.1 0.025×，DeepSeek 0.02×）与缓存写入的加价（OpenAI GPT-5.6 起 1.25×，Anthropic 5 分钟 1.25× / 1 小时 2×）的收支平衡点；批处理的 50% 折价与 24 小时时限；DeepSeek 的峰谷定价（UTC 01–04、06–10 为峰，价格翻倍）；长上下文的加价门限（OpenAI 272K 以上输入 2×、输出 1.5×，Gemini 3.1 Pro 200K 以上翻倍）；多轮对话不做缓存时成本随轮数二次增长的推导。延迟部分把 TTFT 分解为排队 + prefill + 思考，逐 token 速度归到 decode 的 memory-bound 性质（只需要 Infra 地图 08 系列前两篇的结论）。

5. 选型：榜单、评测集与供应商的弃用周期

核心问题：为什么不能按榜单选模型？自己的评测集要多大才能做选型？闭源 API 与开源自托管怎么判断？大小模型分流的账怎么算？供应商的弃用周期怎样进入选型？⁶

第五篇从”榜单为什么失真”开始：The Leaderboard Illusion（NeurIPS 2025）审计了 Chatbot Arena——一家供应商在 Llama 4 发布前私测了 27 个变体、只公布最好的分数，闭源模型获得的对战数据远多于开源模型，Arena 分数因此测量的是”对 Arena 分布的过拟合”而不是通用能力；静态 benchmark 则有污染问题——训练数据里包含了测试题。结论是榜单用来缩小候选范围，选型用自己的评测集，几十条真实问题就能开始，几百条能看趋势。然后是判据：闭源 vs 开源自托管（数据不能出域、规模到了自托管更便宜的临界点、需要开源模型的特定能力——这些判断的成本一半在 Infra 地图 08 / 11），推理 vs 非推理模型、大小模型分流（用小模型处理简单请求，路由的准确率与省下的钱），embedding 与 rerank 的选法（MTEB 的局限、语言与领域、维度与延迟）。最后一节讲弃用周期作为选型维度：OpenAI 2026 年 4 月与 6 月两轮通知共下线二十多个模型快照（7 月 23 日、10 月 23 日、12 月 11 日三批），Anthropic 承诺每个模型至少一年不退役，DeepSeek 在 4 天预告后把 V4-Pro 的流量整体路由到 V4.1 Flash；选型时要问”这个模型名钉住的是什么、供应商能在多短时间内换掉它”。

6. 客户端工程：重试、超时、幂等、限流与流式解析

核心问题：调用模型 API 的客户端要处理哪些失败？重试什么、不重试什么？流式响应中途断了怎么办？怎样在发请求前就知道它会不会超上下文？⁷

第六篇讲调用侧的工程。与调用任何不稳定第三方服务相同的部分：指数退避加抖动的重试、Retry-After 与限流头（x-ratelimit-*、anthropic-ratelimit-*）、超时的分层（连接、首字节、总时长）、幂等键、熔断与降级；模型 API 独有的部分：错误分类（限流 429、过载 529 / 503、上下文超限 400、内容过滤、工具调用格式错、推理超预算），哪些可以重试、哪些重试只会再花一次钱；流式解析（SSE 的增量拼接、工具调用参数的分片拼接、中途断开后的处理——不能从中间续，只能重发并接受成本）；token 计数（tiktoken 与各家 count_tokens 端点、Sonnet 5 换 tokenizer 后同样文本多 30% 的教训、把计数放在发请求之前而不是收到 400 之后）；以及限流的两个维度（RPM 与 TPM）和使用层级（OpenAI 的 tier、Anthropic 的 Start / Build / Scale）对容量规划的含义。

7. 系列总结与通关自测

最后一篇不引入新内容：一张总表回顾六篇各自回答的问题与必记的数字，逐篇的核心结论与常见误解，贯穿全系列的几条线，然后是三段自测——判断与计算、跨篇综合、面试题——加一份”读过 / 掌握 / 能教人”的判据。读完六篇正文再做。

贯穿全系列的实践线

本系列不设配套实验（应用地图的系列都不做 labs）。每篇末尾有一节实践建议，给出可以直接在自己的项目里做的事：

各篇实践建议的内容
篇	实践建议的内容
1	给你的应用写一份失效模式清单：每一条失效在你的场景里的代价、目前的检测手段、应对所在的层
2	用一个中间层把四家 API 的差异收在一处把工具调用的往返写成显式循环而不是交给框架把 `store` 的默认值写进代码审查清单
3	在评测集上跑 effort 的每一档，记录质量 / 成本 / TTFT 三条曲线；检查你的历史编辑逻辑是否会破坏 thinking block 的校验
4	用本篇的公式给你的应用建一张成本表：每种请求类型的四类 token 数与单价算出缓存前缀的收支平衡点用 usage 字段核对账单
5	从真实流量采 50 条建评测集订阅四家的弃用通知把模型名从代码里挪到配置里并加上替代模型
6	审计客户端的重试策略（哪些错误码、退避参数、幂等）在发请求前计数 token 给流式响应加中断处理

前置要求与说明

前置要求

后端工程基础：HTTP、JSON、异步 I/O、重试与超时这些概念不需要解释；
调过至少一次任何一家的模型 API；
不要求机器学习背景。涉及模型内部的地方只引用结论，并给出到《Transformer 与 LLM》系列的链接。

版本与价目基线

本系列的 API 字段、模型名与价目以 2026 年 9 月下旬各家的公开文档为准：

本系列的版本与价目基线
供应商	模型（发布日）	API 入口	备注
OpenAI	GPT-6 Astra（2026-09-03）、GPT-5.6 Sol / Terra / Luna（2026-07-09）	Responses API（推荐）、Chat Completions（维持）	Assistants API 已于 2026-08-26 关闭；Agents API 2026-09-10 公测
Anthropic	Claude Fable 5.1（2026-09-01）、Opus 5（2026-07-24）、Sonnet 5（2026-06-30）、Haiku 4.5（2025-10）	Messages API	5 系列 1M 上下文默认、128K 最大输出、adaptive thinking 默认开启
Google	Gemini 3.8 Flash（2026-09-02）、Gemini 3.1 Pro（preview）	Interactions API（2026-06 GA，推荐）、`generateContent`（维持）	3.8 Flash 引入价至 2026-12-31
DeepSeek	DeepSeek-V4.1-Flash（2026-09-10，MIT 开放权重）	OpenAI 格式、Anthropic 格式、Responses 格式三种兼容端点	V4-Pro 自 2026-09-14 起路由到 V4.1 Flash

价目会变，本系列引用时都标注”2026 年 9 月价目页”。文中的成本计算以公式为主，数字是代入当时价目的示例；读者应代入自己读到本文时的价目重算。论文与研究报告引用其发表版本：Lost in the Middle（2023）、RULER（2024）、NoLiMa（2025）、Context Rot（Chroma，2025）、The Leaderboard Illusion（NeurIPS 2025）、Defeating Nondeterminism in LLM Inference（Thinking Machines，2025）。公开事件以法院判决书、当事方声明与主流媒体报道为据。

章节目录

最终目标

读完本系列，面对任何一个模型 API，读者应该能够：

读完系列后应能回答的追问
追问	答案来自
这个组件在我的场景里会以哪几种方式失效？每种的代价与检测手段是什么？	第一篇
一次工具调用的往返在协议上经过哪几步？哪些配对与截断是我的责任？	第二篇
结构化输出的 strict 保证了什么？没保证什么？	第二篇
把 effort 从 `high` 调到 `low`，成本、延迟、质量各怎么变？怎么测？	第三篇
为什么不能随意编辑历史消息？改了会怎样？	第三篇
这次调用花了多少钱？四类 token 各多少？缓存有没有命中？	第四篇
多轮对话第 20 轮的成本是第 1 轮的多少倍？缓存能把它降到多少？	第四篇
为什么榜单第一的模型在我的任务上不如第五？该怎么选？	第五篇
供应商通知模型三个月后下线，我该在哪一天知道、做什么？	第五篇、第六篇
哪些错误该重试、哪些重试只是再花一次钱？流式中断怎么处理？	第六篇
发请求前怎么知道它会不会超上下文？换了模型 token 数为什么变了？	第六篇

这份能力就是这一层要建立的组件观。有了它，L2 到 L7 的每一种工程手段都有了明确的目标：它在对付第一篇的哪一条失效、它在第四篇的账上换的是什么。

答案分五部分，各对应一篇。契约 = API 形状：消息与角色、工具调用往返、结构化输出、流式、多模态、推理模型的 effort 与跨轮推理状态——四家已收敛成一套骨架（第二、三篇）。失效方式：非确定性（temperature = 0 也不保证复现）、幻觉、指令遵循不稳、「中间遗忘」与上下文腐化、知识截止、对 prompt 微改敏感、能执行动作后的自主行为失效——都是固有性质不是 bug（第一篇）。钱与慢：$C = n_{in}p_{in} + n_{hit}p_{hit} + n_{write}p_{write} + n_{out}p_{out}$，输出价是输入的 4–5 倍、四家价目跨三个量级，TTFT = 网络 + 排队 + prefill、思考在首 token 之前（第四篇）。选型：榜单失真，用自己几十条起的评测集缩范围，再按大小模型分流、闭源 vs 自托管、弃用周期判断（第五篇）。客户端独有的失败：429 / 529 / 上下文超限 400 / 内容过滤 / 工具格式错 / 推理超预算的分类重试，流式中断只能重发，发请求前算 token（第六篇）。 ↩
结果不同是因为推理端点的非确定性主要来自 batch 不变性的缺失（同一请求与不同邻居一起批处理时 kernel 的归约顺序不同）而不只是浮点并发，所以 temperature = 0 只是去掉了采样随机性、去不掉 batch 带来的差异——评测必须按分布、每题跑多次。自信地编造发生在模型「知道格式但不知道事实」的地方：被问到训练数据里没有或稀疏的具体事实（判例、引用、数字、人名）、被要求必须给答案、以及上下文里没有可引用的材料时——Mata v. Avianca、Deloitte 报告退款、哈姆法院判决都是这一类。上下文中间的信息更容易被忽略是 Lost in the Middle 与后续 RULER / NoLiMa / Context Rot 研究的共同结论：注意力对开头与结尾更敏感，有效上下文长度远小于标称值（NoLiMa 里 11 个模型在 32K 处掉到短上下文基线的一半以下），所以重要信息放两端、无关内容不要进来。 ↩
共同结构：消息与角色（system / user / assistant / tool）、多模态内容块、工具定义与调用、结构化输出、流式、以及无状态（Chat Completions / Messages）与服务端存状态（Responses / Interactions）两种状态模型。工具调用一轮往返：模型返回带 tool_call_id 的 tool_call → 应用执行 → 把结果作为 tool 消息按 id 配对送回 → 模型继续；并行调用的顺序、结果截断、失败的表达都在应用侧——它是协议不是功能。结构化输出：strict 模式保证语法（输出一定是合法且符合 schema 的 JSON，靠约束解码），不保证语义（字段可以填满编造的值），且对 schema 特性有限制。流式的事件模型：SSE 事件流，增量 delta 按类型（文本、工具调用参数分片、推理块、usage、结束原因）拼接，应用负责重组与中断处理。另一个要点：服务端状态的默认值——Responses 默认存 30 天、Chat Completions 对新账户也默认存，隐私敏感要显式 store: false。 ↩
「思考」在 API 上是一段生成在可见回答之前、按输出价计费、通常不可见或只给摘要的 token（OpenAI 的 reasoning item、Anthropic 的 thinking block、Google 的 thought signature）。effort 控制这段的预算档位——OpenAI reasoning.effort（low 到 xhigh / max）、Anthropic effort（low 到 max）配 adaptive thinking、Google thinking_level、DeepSeek 的 low / high / max——思考 token 按输出价计费，max 比 low 可以贵一个量级，且思考发生在首 token 之前、直接决定 TTFT。thinking block 要原样送回，是因为跨轮推理状态在模型侧有意义（它是后续工具调用与回答的依据），Anthropic 从 Fable 5.1 起校验之前的内容未被改动（改了返回 400 或丢弃），OpenAI 用 reasoning item（ZDR 下加密 item）、Google 用 thought signature 保留——「编辑历史」在推理模型上不再自由。对缓存的影响：推理块是前缀的一部分，改动或删除会让后续前缀失配、缓存失效；多轮工具调用里保留它反而让缓存连续命中。 ↩
公式 $C = n_{in}p_{in} + n_{hit}p_{hit} + n_{write}p_{write} + n_{out}p_{out}$，四种 token 各一个价。2026 年 9 月的价目（输入 / 输出，每百万 token）：GPT-6 Astra $10 / $50、GPT-5.6 Sol $4 / $20、Terra $2 / $12、Luna $0.20 / $1.20；Claude Fable 5.1 $10 / $50、Opus 5 $5 / $25、Sonnet 5 $2 / $10、Haiku 4.5 $1 / $5；Gemini 3.8 Flash $0.75 / $3.75；DeepSeek V4.1 Flash 闲时 $0.15 / $0.60——跨三个量级，输出价普遍是输入的 4–5 倍。缓存写入额外收费（OpenAI GPT-5.6 起 1.25×，Anthropic 5 分钟 1.25× / 1 小时 2×）是因为供应商要为你保存 KV；命中折价 0.1×（Fable 5.1 0.025×、DeepSeek 0.02×），所以写一次之后读一次就回本，前缀会被复用 ≥ 2 次就划算。多轮对话成本二次增长，是因为第 $k$ 轮要把前 $k-1$ 轮全部作为输入重新计费，总输入 token 随轮数按 $O(k^2)$ 累积——缓存命中把它压回接近线性。TTFT 由网络 + 排队 + prefill（随输入长度线性）+ 思考 token 决定；逐 token 速度由供应商侧 decode 的 memory-bound 吞吐与并发负载决定，与输入长度关系小。 ↩
榜单失真：The Leaderboard Illusion 审计 Chatbot Arena——供应商私测 27 个变体只公布最好的、闭源模型获得的对战数据远多于开源，分数测的是对 Arena 分布的过拟合；静态 benchmark 有污染与饱和，且脚手架不同不可横比。自己的评测集几十条就能缩小候选范围（排除明显不行的），几百条、每题跑多次才能在两个接近的模型间做出有置信度的选择——按自己任务的分布与失败模式采样。闭源 API vs 开源自托管：看数据出域限制、规模临界点（月用量到一定量后自托管的单位成本低于 API）、运维能力、是否需要微调与定制、延迟要求；多数团队先用 API 验证价值再决定。大小模型分流：按任务难度路由（便宜模型先试、不确定或失败再上贵的），省的是 (1 − 升级比例) × 价差，前提是有可靠的分流判据与评测。弃用周期：各家主力模型 6–12 个月一代、弃用通知 3–12 个月，选型时把「迁移成本 × 频率」算进去——模型名不硬编码、钉快照版本、评测集随时可跑才能换得动。 ↩
两类失败：与任何第三方服务相同的——超时（连接、首字节、总时长分层）、限流（Retry-After、x-ratelimit-* / anthropic-ratelimit-* 头，RPM 与 TPM 两个维度）、过载、网络中断，用指数退避加抖动、幂等键、熔断与降级；模型 API 独有的——限流 429、过载 529 / 503、上下文超限 400、内容过滤、工具调用格式错、推理超预算。重试规则：429 / 529 / 503 / 网络错误重试（退避）；上下文超限 400、内容过滤、schema 不合法不重试（重试只会再花一次钱，要改请求）；工具调用格式错把错误放回上下文让模型修一次；推理超预算要提高 max_tokens 或降 effort。流式中途断了不能从中间续——只能重发并接受重复成本，所以应用要能丢弃半截输出、幂等地重放，并把已收到的部分用于展示但不用于状态。发请求前知道会不会超上下文：本地计数（tiktoken 或各家 count_tokens 端点）+ 预留输出余量，并注意 tokenizer 换代（Sonnet 5 换 tokenizer 后同样文本多 30%）——计数放在发请求之前而不是收到 400 之后。 ↩