模块 2 — Claude 模型与消息

目标：掌握 Claude 现役模型家族（截至 2026-08-30）、消息结构、多模态输入、token 计量、stop reasons、streaming、rate limits、延迟与成本、模型生命周期。这些是架构师做"选型 + 容量 + 预算"决策的全部输入。 通用机制（token、上下文窗口、context rot）见模块 1；本模块聚焦"落到 Claude 具体产品上是什么"。 📚 模块 02 重要英文词汇

1. 模型家族概览（截至 2026-08-30）

🎯 学习重点：必考的是按任务复杂度、延迟、窗口和单价联合选型；易错点是把“能力最强”误答成“所有流量默认最优”。

官方建议：不确定时从 Claude Opus 5 开始（复杂 agentic coding 与企业级工作）；需要最高能力用 Claude Fable 5（来源: https://platform.claude.com/docs/en/models/overview（访问于 2026-08-30））。

（来源: https://platform.claude.com/docs/en/models/overview 与 https://platform.claude.com/docs/en/about-claude/model-deprecations（访问于 2026-08-30））

要点：

• 全部现役模型都支持：文本+图片输入、文本输出、vision、tool use、多语言。
• Legacy 仍可用：Opus 4.8 / 4.7 / 4.6 / 4.5、Sonnet 4.6 / 4.5。另有 Claude Mythos 5（limited availability，anthropic.com/glasswing）；Mythos Preview 已弃用。
• 模型 ID 都是 pinned snapshot——包括 4.6 代起的"无日期"ID。4.6 之前的 ID（如 claude-haiku-4-5）是指向 dated ID 的 alias。
• Batch API 全线 5 折；prompt cache 读取 0.1x（§9）。
• 退役日期是"承诺不早于"，且仅适用于 Anthropic 自营平台；Bedrock / Google Cloud 自定退役日程。

1.1 选型直觉

🎯 学习重点：高频题型是先分流简单/复杂任务，再用评估集证明升级模型带来的质量收益值得价差。

架构师经验法则：先在便宜模型上把 prompt/检索/工具调好，再升档——官方同样建议"不确定就从 Opus 5 起"，但升级方向与降级方向的成本差是 25x（Haiku 输出 $5 vs Fable 输出 $50 /MTok）。

🔪 架构师犀利细节 01｜别只看“每 MTok 单价”：若一次请求输入 20K、输出 2K，则 Fable 5 的标价成本是 $0.20 + $0.10 = $0.30，Haiku 4.5 是 $0.02 + $0.01 = $0.03，正好相差 10 倍；“输出单价相差 10 倍”不等于任意请求总价都按同一个口径比较。正确做法是拿真实 usage 分布计算 P50/P95 单请求成本，再把质量收益放进同一张选型表。

2. 消息结构：system prompt 与 user/assistant 消息

🎯 学习重点：必考结构是顶层 system + 交替 user/assistant；不存在输入角色 system，连续同角色会被合并。

Messages API 的请求体核心是三层：顶层 system、messages 数组、（可选）tools 数组。

2.1 system prompt

🎯 学习重点：System prompt 管全局行为边界，工具定义也进入系统前缀；稳定前缀直接关系到缓存命中。

• system prompt 是顶层参数（字符串或 content block 数组），不存在 "system" role 的消息（来源: https://platform.claude.com/docs/en/api/messages（访问于 2026-08-30））。
• 用途：角色、职责、行为边界、输出规范——所有"对整场对话生效"的指令。工具定义也会被 API 拼进一个特殊的 system prompt 结构（来源: https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools（访问于 2026-08-30））。

2.2 user / assistant 消息

🎯 学习重点：易错点是把 content 字符串和 content blocks 当成两套协议；前者只是单个 text block 的简写。

• 模型按 user/assistant 交替轮次训练；连续同角色消息会被合并为一个轮次（来源: Messages API 参考，同上）。
• 单请求最多 100,000 条消息。
• content 可以是纯字符串，或 content block 数组（text / image / document / tool_use / tool_result / thinking 等）——字符串只是"单 text block"的简写。
• 若最后一条消息是 assistant，响应会从该内容续写（可用于约束响应开头；注意：截至 2026-08-30 该 prefill 手法在 4.6+/Mythos Preview 上已弃用/返回 400，见 track-core 已核验的 prompting best practices，来源: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices（访问于 2026-08-30））。

Bad vs Better（消息结构）：

3. 多模态输入（图片 / PDF / 文档）

🎯 学习重点：图片与 PDF 都会占上下文并按输入计费；页数、图数、像素和请求体上限是四条不同边界。

所有现役模型都接收文本+图片输入（截至 2026-08-30）。

3.1 图片

🎯 学习重点：掌握三种传法与 28×28 patch 计量；GIF 只取第一帧、截图超限报错是高频陷阱。

• 传法三种：base64（嵌请求体）、url（在线图）、file_id（Files API 上传后引用；多轮场景推荐，避免每轮重发字节）（来源: https://platform.claude.com/docs/en/build-with-claude/vision（访问于 2026-08-30））。
• 格式：JPEG / PNG / GIF / WebP；动图只取第一帧。
• 尺寸：单图最大 8000×8000；单请求图数上限 200K 窗口模型 100 张、其余 600 张；超过 20 张图触发更严的每图尺寸限制。
• 计量：⌈宽/28⌉ × ⌈高/28⌉ 视觉 token（模块 1）。两档分辨率：Claude 4.7+ 高分辨率档（长边 ≤2576px、最多 4784 视觉 token）；其余模型标准档（长边 ≤1568px、最多 1568 token）。超档自动缩放（不是线性烧 token）——但 computer use / browser use 截图例外，超限直接报错。
• 排版建议：图片放文本前面效果最好。

3.2 PDF / 文档

🎯 学习重点：600 页是 1M 上下文条件下的页数上限，较小窗口只有 100 页且仍可能先因 token 超窗。

• 传法：url / base64 / file_id；标准 PDF（无密码加密）。
• 上限：单请求 600 页（上下文 <1M token 时 100 页）、32MB 请求体；每页按"文本+图像"双通道处理（来源: https://platform.claude.com/docs/en/build-with-claude/pdf-support（访问于 2026-08-30））。
• 密排 PDF（小字、复杂表格）可能先撞上下文窗口再撞页数上限——大文档要走拆分/检索，不是硬塞。

多模态架构含义：图片/PDF 是"按视觉 token 计费的输入"，进入上下文窗口、参与 ITPM。高频场景（客服截图、发票）应该：预压缩/降采样 → Files API 或缓存 → 控制图数。

🔪 架构师犀利细节 02｜上限不能相加当容量：32MB 请求体、600 页、1M 上下文、单请求最多 600 张图是独立闸门，不代表一个请求能同时吃满四项。密排 PDF 常先撞 token，base64 还会放大传输体积；生产接入应在上传阶段先做页数、像素、字节和预估 token 四重校验，而不是等 API 返回 400。

4. Token 计量

🎯 学习重点：缓存场景总输入必须把 input_tokens、cache_creation_input_tokens、cache_read_input_tokens 相加，单看 input_tokens 会严重低估。

响应的 usage 字段是唯一的账本（来源: https://platform.claude.com/docs/en/api/messages 与 prompt-caching（访问于 2026-08-30））：

总输入 = cache_read + cache_creation + input。发送前预估用 Token Counting API（POST /v1/messages/count_tokens，来源: https://platform.claude.com/docs/en/api/overview（访问于 2026-08-30））。

🔪 架构师犀利细节 03｜窗口、限流、账单三本账：假设 usage 为 cache read 80K、cache creation 0、普通 input 20K，则上下文输入是 100K；多数模型的 ITPM 只扣 20K；账单则按 80K×0.1x 加 20K×1x 计。反模式是用一个“token 总量”指标同时做窗口报警、限流容量和成本核算；正解是保留四个原始 usage 字段并派生三套指标。

5. Stop Reasons：响应为什么停

🎯 学习重点：HTTP 200 不等于业务完成；必须按 stop_reason 路由，尤其区分自然结束、截断、工具调用和暂停续跑。

每个响应都带 stop_reason，它不是错误，是"本轮完成方式"（来源: https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons（访问于 2026-08-30））：

经典坑：工具结果之后不要追加 text block——Claude 学到的模式是"tool_result 之后用户会说话"，容易直接 end_turn 且内容为空（来源: 同上，"Empty responses with end_turn"）。

6. Streaming（流式输出）

🎯 学习重点：SSE 事件顺序、partial JSON 累积和“200 后仍可能流内报错”是实现题最常见失分点。

"stream": true 时，响应通过 SSE (server-sent events) 逐事件推送（来源: https://platform.claude.com/docs/en/build-with-claude/streaming（访问于 2026-08-30））：

1. message_start（含空 content 的 Message 骨架）
2. 每个 content block：content_block_start → 若干 content_block_delta → content_block_stop
3. 若干 message_delta（顶层变化，如最终 stop_reason）
4. message_stop

关键细节：

• delta 类型：text_delta（正文）、input_json_delta（工具入参的partial JSON，需累积到 content_block_stop 再解析）、thinking_delta / signature_delta（思考内容）。
• message_delta 里的 usage 是累计值。
• 流中途可能收到 error 事件（如 529 overloaded_error）——200 响应后仍会出错，错误处理要覆盖流内事件。
• 会有 ping 事件；版本策略下可能新增事件类型，代码要能优雅处理未知事件。
• 不想逐事件处理？SDK 提供 get_final_message() / finalMessage()：内部走流式、返回完整 Message——大 max_tokens 场景用它防 HTTP 超时。

架构意义：streaming 降低的是感知延迟 (TTFT)，不是总生成时长；长输出的可靠性问题（>10 分钟）官方建议直接流式或 Batch（模块 3）。

7. Rate Limits（速率限制）

🎯 学习重点：区分月度 spend limit 与 RPM/ITPM/OTPM；令牌桶连续回补，缓存读取通常不占 ITPM。

两类限制（来源: https://platform.claude.com/docs/en/api/rate-limits（访问于 2026-08-30））：

1. Spend limits（月度花费上限）：Start $500 / Build $1,000 / Scale $200,000；Custom 无上限（客户经理面议）。触顶后 429 且无 retry-after，次月 1 日 00:00 UTC 恢复。
2. Rate limits（RPM / ITPM / OTPM）：按模型类分别计量。Start 档示例（Build/Scale 递增）：

要点：

• 令牌桶 (token bucket) 算法：容量连续回补，不是整点重置——短时突发也可能触发 429。
• Cache-aware ITPM（多数模型）：cache_read_input_tokens 不计入 ITPM；只有 input_tokens + cache_creation_input_tokens 计入。2M ITPM + 80% 缓存命中 ≈ 有效 10M tokens/min。这是缓存的第一架构红利。
• 限流按模型独立：不同模型可同时各自打满。
• 用量激增可能触发加速限制 (acceleration limits) 429——爬坡要渐进。
• 限制是"最大允许"不是"保证供给"。

🔪 架构师犀利细节 04｜吞吐瓶颈取最小值：Start 档 Sonnet 5 同时受 1,000 RPM、2M ITPM、400K OTPM 约束。若平均每请求输入 10K、输出 500 token，则输入侧最多约 200 req/min，输出侧约 800 req/min，最终先被 ITPM 卡住；若输入前缀 80% 命中缓存且 cache read 不计 ITPM，输入侧理论上可提高到约 1,000 req/min，此时 RPM 成为瓶颈。容量题必须逐维相除后取最小值，不能只报 RPM。

8. 延迟与成本

🎯 学习重点：延迟要拆 TTFT 与总时长，成本要拆输入/输出/thinking；streaming 只改善感知延迟，不减少生成工作量。

8.1 延迟

🎯 学习重点：先通过路由、削减输入输出解决结构性延迟，再用 streaming 改善体验，不能把二者效果混为一谈。

• 度量：TTFT（time to first token） vs 基线延迟（来源: https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/reduce-latency（访问于 2026-08-30））。
• 家族相对延迟：Fable 5 Slower / Opus 5 Moderate / Sonnet 5 Fast / Haiku 4.5 Fastest（实际取决于 prompt 长度、输出长度、思考 effort）。
• 五个杠杆（按性价比排序）：

1. 换模型（同任务 Haiku 4.5 vs Fable 5 是数量级差异）
2. 削输入（大文档换检索式注入）
3. 削输出（要求简洁；max_tokens 是硬帽但会"砍半句"）
4. streaming（大幅改善感知延迟）
5. 降低 effort（adaptive thinking 模型的思考量直接影响时长）

• 注意：该文档仍演示 temperature 微调，但 4.7+ 模型已弃用非默认值（见 §10）——以 model-deprecations 页为准。

8.2 成本

🎯 学习重点：输出单价通常是输入的 5 倍，Batch、cache read 与 cache write 的系数方向必须记准。

• 输入/输出分开计价；输出 token 通常 5x 于输入——成本大头常在输出（含 thinking）。
• 三大折扣：Batch 50%（离线任务）、cache 读 0.1x（重复前缀）、（cache 写 1.25x 是投资不是折扣）。
• 架构公式：月成本 ≈ Σ[ (输入tok×单价) + (输出tok×5×单价) ] × 频次 × 缓存/Batch 系数。用 usage 实测校准，别拍脑袋。

Bad vs Better（成本/延迟架构）：

9. 一图：请求的账本与闸门

🎯 学习重点：能从一张图说明同一请求如何同时受上下文、限流、缓存、计费与停止原因控制。

10. 模型生命周期

🎯 学习重点：Active→Legacy→Deprecated→Retired 的含义及至少 60 天通知是治理题核心；云平台退役日程不能照搬 Anthropic 自营平台。

四级状态（来源: https://platform.claude.com/docs/en/about-claude/model-deprecations（访问于 2026-08-30））：

• Active：完全支持、推荐使用。
• Legacy：不再更新，未来可能弃用（当前 4.x 前代模型）。
• Deprecated：仍可用但不推荐；给出替换模型与退役日期。
• Retired：不可用，请求失败。

企业级事实（截至 2026-08-30）：

• 公开发布模型退役前至少 60 天邮件+文档通知。
• 最近退役：Opus 4.1（2026-08-05）、Sonnet 4 / Opus 4（2026-06-15）、3.7 Sonnet 与 3.5 Haiku（2026-02-19）……完整表见官方页。
• 审计手段：Console → Usage → Export CSV 按模型盘点存量使用。
• 参数也会退役：temperature / top_p / top_k 在 Opus 4.7 及之后模型非默认值直接 400；Python SDK v1.0+ 已移除这些参数。这是"模型升级 = 行为面变化"的最佳例证。
• 升级纪律：新模型上线先在影子流量/评估集上验证（模块 12），再切流；pinned snapshot ID 保证"同 ID 同行为"，但升级 ID 是主动决策。

11. 权衡 速查

🎯 学习重点：考试遇到架构选择题，要同时写“得到什么”和“付出什么”，避免只谈质量不谈成本、延迟和运维约束。

12. 常见错误

🎯 学习重点：优先记会直接造成 400、截断数据污染或容量误判的错误，而不只是提示词质量问题。

1. ❌ 硬编码 dated model ID 又不做退役盘点（应记录所有调用点的模型 ID，盯 deprecations 页）
2. ❌ 把 input_tokens 当总输入（缓存场景下它只是"断点之后"的部分）
3. ❌ Bedrock/Vertex 上的退役日期按 Anthropic 官网排期（云平台自定日程）
4. ❌ 新模型上继续传 temperature，上线即 400
5. ❌ 图片/PDF 无限塞：忘了它们按视觉 token 计费并挤占窗口
6. ❌ 忽略 stop_reason：max_tokens 截断的 JSON 直接喂给下游解析器
7. ❌ 用 prefill 约束输出（4.6+ 已弃用，改结构化输出，模块 05）

13. 重要英文术语表

🎯 学习重点：重点掌握成对术语：input/output、cache read/cache creation、deprecation/retirement、TTFT/总延迟。

完整分组版见：模块 02 重要英文词汇。

14. 认证相关性

🎯 学习重点：本模块常以“模型选型 + 容量估算 + 生命周期迁移”的综合场景题出现，答案必须能落到量化依据。

CCAR 考察 "advising, designing, and building Claude solutions"（见 00-certification-current-status/），本模块直接对应：

• 选型决策：什么负载选什么模型（价格/延迟/窗口/思考模式四轴）
• 容量设计：ITPM/OTPM/token bucket 与缓存对有效吞吐的影响
• 生命周期管理：退役通知纪律、审计、参数弃用（temperature 400 是新考点素材）
• 成本架构：Batch/缓存/streaming 的组合策略

注：官方域权重未公开核验（certification-status.md PENDING），本仓库不声称官方权重映射。

15. 下一步

🎯 学习重点：完成实验时应能用同一份模型矩阵解释质量、价格、延迟和限流四轴决策。

• 动手：labs/lab.md（无 key 部分：选型矩阵 + 限流预算推演）
• 代码：examples/model_matrix.py（无 key 可跑：内置截至 2026-08-30 的模型表 + 成本/延迟推演）
• 自测：questions/ + flashcards/flashcards-02.csv
• 下一模块：03-claude-api/——把请求真正发出去：认证、SDK、重试、缓存、Batch