模块 3 — Claude API 实战

目标：把模块 1/2 的概念变成可运维的生产调用：认证、SDK、请求/响应结构、错误处理与重试、超时与并发、prompt caching、Message Batches。模块结束你应能画出一张"带缓存与降级的调用链路图"。 所有接口事实以官方文档为准（截至 2026-08-30）。 📚 模块 03 重要英文词汇

1. 认证

🎯 学习重点：必考边界是 API key/WIF 与云平台 IAM 的差异；凭据隔离和轮换必须由 workspace 与密钥系统实现。

Claude API 是 https://api.anthropic.com 上的 RESTful API。每个请求的头部（来源: https://platform.claude.com/docs/en/api/overview（访问于 2026-08-30））：

要点：

• SDK 自动带头（key、version、content-type）；workspace-id 需要时自己传。
• Key 在 Console → Settings → Keys 生成，可选类型与过期时间；用 workspaces 隔离环境并按用途控费。
• 云平台（Bedrock/Vertex/Foundry）走各自 IAM，认证模型完全不同（这是平台迁移的真实成本之一）。
• 绝不把 key 写进代码/仓库——环境变量或密钥管理器。

🔪 架构师犀利细节 01｜认证迁移不是换 Header：Anthropic 自营 API 的 key/WIF、Bedrock、Vertex、Foundry 分别依赖不同身份与权限体系。反模式是让业务代码到处拼认证头；正解是把认证、endpoint、模型 ID 映射封装在 provider adapter，并用 workspace/云账号隔离环境、预算和最小权限。

2. API 面（截至 2026-08-30）

🎯 学习重点：能按实时生成、离线批量、发送前计数、模型发现和文件复用选择正确 endpoint。

正式 API（来源: API overview，同上）：

• Messages：POST /v1/messages（核心）
• Message Batches：POST /v1/messages/batches（异步批量，50% 折扣）
• Token Counting：POST /v1/messages/count_tokens（发送前估 token）
• Models：GET /v1/models（含 max_input_tokens/capabilities）
• Files：POST /v1/files（上传后 file_id 复用）
• Skills：/v1/skills

Beta：Agents / Sessions / Environments（Claude Managed Agents）。本模块聚焦 Messages + Batches + Count Tokens。

3. 请求/响应结构

🎯 学习重点：请求最小三件套是 model、max_tokens、messages；响应必须同时读取 content、stop_reason、usage 与 request-id。

3.1 最小请求

🎯 学习重点：max_tokens 必填且请求体有 32MB 硬上限；HTTP 成功后仍要检查内容块和停止原因。

# 认证头 x-api-key 从环境/密钥管理器注入(§1 表格);绝不硬编码进脚本
curl https://api.anthropic.com/v1/messages \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }'

（来源: https://platform.claude.com/docs/en/api/messages（访问于 2026-08-30））

请求要点：model + max_tokens（必填，也可为 0 做缓存预热）+ messages；可选 system、tools、tool_choice、stream、stop_sequences、temperature（4.7+ 弃用，见模块 2 §10）。请求体上限 32MB（超限 413 request_too_large）。

响应要点：content 是 block 数组（text / thinking / tool_use / redacted_thinking…），stop_reason、stop_sequence、usage（模块 2 §4 的账本）。每个响应带 request-id 头——报障必带。

3.2 SDK（Python / TypeScript）

🎯 学习重点：SDK 的核心价值是类型化异常、重试、超时、连接和流式管理，不只是少写几行 HTTP。

官方 SDK 的价值（来源: API overview + errors，同上）：自动头部管理、类型安全、内置重试与错误处理、streaming 支持、超时与连接管理（含 TCP keep-alive、非流式 10 分钟校验）。

Python（参考代码，需 pip install anthropic）：

import anthropic  # github.com/anthropics/anthropic-sdk-python

client = anthropic.Anthropic()  # 自动读 ANTHROPIC_API_KEY
message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(message.content[0].text)
print(message.usage)          # token 账本
print(message._request_id)    # 报障用

TypeScript（参考代码，需 npm i @anthropic-ai/sdk）：

import Anthropic from "@anthropic-ai/sdk";  // github.com/anthropics/anthropic-sdk-typescript

const client = new Anthropic();  // 读 ANTHROPIC_API_KEY
const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello" }],
});
console.log(message.content);

SDK 细节：重试默认 2 次、指数退避、尊重 retry-after（见 §5）；Python SDK v1.0+ 已移除 temperature/top_p/top_k 参数（传了抛 TypeError，来源: https://platform.claude.com/docs/en/about-claude/model-deprecations（访问于 2026-08-30））。

4. 错误处理：错误码全表

🎯 学习重点：先按错误 type/HTTP 判定“修请求、修权限、等待还是退避”，再决定是否重试；request-id 是报障主键。

（来源: https://platform.claude.com/docs/en/api/errors（访问于 2026-08-30））

错误体恒为 JSON：顶层 error（type + message）+ request_id。SDK 抛类型化异常（Python anthropic.NotFoundError 等）——按具体类捕获，别字符串匹配。

🔪 架构师犀利细节 02｜429 不是一个故障：有 retry-after 的速率限制可以等待；无 retry-after 的 tier/spend cap 型 429 原样重试不会恢复。生产告警至少要按 status + error.type + retry-after 是否存在 + model + workspace 分维，否则“429 上升”无法判断是突发流量、预算触顶还是加速限制。

5. 重试与指数退避

🎯 学习重点：默认 2 次重试意味着最多 3 次尝试；确定性 4xx 不重试，瞬时故障才使用退避、抖动和预算。

官方 SDK 对瞬时故障（连接错误、429、5xx）自动重试：默认 2 次，指数退避，尊重 retry-after，可用 max_retries 配置或关闭（来源: errors 文档，同上）。

自己实现时的架构要点（examples/retry_backoff.py 无 key 可跑）：

• 指数退避：delay = base × 2^n + jitter（jitter 防止重试风暴同相共振）。
• 重试预算：设最大次数与总时限；幂等性——Messages 请求天然幂等（无服务端副作用），但计费不幂等，重试也烧 token。
• 区分错误类型是第一原则：确定性错误重试是浪费；spend-cap 429 重试是纯烧 CPU。
• 长任务（>10 分钟）别靠无限重试：换 streaming 或 Batch（官方建议，来源: errors "Long requests"，同上）。

🔪 架构师犀利细节 03｜成功率上升不等于成本不变：SDK 默认 2 次重试即一次逻辑调用最多发出 3 次 API 尝试。Messages 没有真实世界副作用，但已完成却因网络丢响应的尝试仍可能产生 token 与费用；反模式是把重试次数调大来“提高 SLA”，正解是同时设置次数预算、总时限、并发闸和每个逻辑请求的最大成本。

6. 超时与并发

🎯 学习重点：长输出用 streaming 或 Batch，吞吐按 RPM/ITPM/OTPM 三维限速；缓存首写并发会产生竞态 miss。

• 超时：SDK 校验非流式请求预计不超 10 分钟；网络可能掐掉空闲连接——大 max_tokens 用 streaming（get_final_message() 拿完整对象）或 Batch 轮询（不需要持续连接，来源: errors "Long requests"，同上）。
• 并发设计要点：

1. 客户端平滑限速（令牌桶在服务端连续回补，客户端也要匀速，模块 2 §7）
2. 独立调用并行发（不同模型限流独立；工具子任务可并行，模块 4）
3. 缓存竞态：缓存条目要等第一个响应开始才可读——同前缀的并行请求要么错峰，要么接受首批 miss（来源: https://platform.claude.com/docs/en/build-with-claude/prompt-caching（访问于 2026-08-30））
4. 流量突增触发加速限制 429：上线爬坡渐进

Bad vs Better（超时与并发）：

7. Token usage（工程视角）

🎯 学习重点：发送前 count_tokens，发送后持久化 usage 四字段；这两步分别服务准入判断与真实成本归因。

• 发送前：count_tokens 精确预估（模块 1）。
• 发送后：usage 四字段入库（模块 2 §4），它是成本归因、异常检测（输入突涨=缓存失效或注入）、预算熔断的数据源。
• 流式场景 message_delta.usage 是累计值（模块 2 §6）。

8. Prompt Caching（提示缓存）

🎯 学习重点：缓存的是逐字节稳定前缀，写入、读取、窗口占用和 ITPM 的计量口径必须分别回答。

（来源: https://platform.claude.com/docs/en/build-with-claude/prompt-caching（访问于 2026-08-30））

8.1 两种开启方式

🎯 学习重点：多轮对话优先自动缓存，精确控制 tools/system/RAG 前缀时使用显式断点；两者可混用但共享 4 个槽位。

1. 自动缓存：请求顶层加 cache_control: {"type": "ephemeral"}——系统自动把断点放到最后一个可缓存 block 并随对话前移。多轮对话首选。
2. 显式断点：在具体 content block 上加 cache_control（可设 ttl: "5m" / "1h"）——精细控制缓存什么。

8.2 机制（必须懂，否则缓存沉默失效）

🎯 学习重点：最多 4 个断点、向前回看 20 blocks、最小 token 门槛和 TTL 起算时刻是高频数字题。

• 缓存的是完整前缀：tools → system → messages 顺序拼接，断点及其之前的一切。
• 写入只发生在断点处；读取时从断点向前回看最多 20 个 block 找既有条目。
• 断点前任何字节变化 → hash 变 → miss。tool_choice 变化会作废 messages 缓存（tools/system 仍保留）。
• 计价：写 1.25x（5m）/ 2x（1h），读 0.1x，刷新免费；TTL 从请求开始计时（长响应会吃掉 TTL！流式 4 分钟的响应，后续同前缀请求要在响应完成约 1 分钟内进来）。
• 最多 4 个断点；自动缓存与显式断点可混用（自动占一个槽）。
• 最小可缓存长度按模型（512 / 1024 / 2048 / 4096 token 不等）——低于下限静默不缓存、不报错，验证方法：cache_creation_input_tokens 与 cache_read_input_tokens 同为 0 就是没缓存上。

🔪 架构师犀利细节 04｜先算回本，再谈命中率：同一前缀只调用两次时，5m 缓存成本系数是 1.25 + 0.1 = 1.35，低于两次不缓存的 2.0；1h 缓存则是 2 + 0.1 = 2.1，反而略贵。1h 写入至少需要两次后续读取才低于三次原价（2 + 0.2 < 3）。因此 1h 适合会复用多次但排队较久的批任务，不适合“一写一读”短会话。

8.3 该缓存什么

🎯 学习重点：排序原则是稳定且大的前缀靠前、每请求变化的内容靠后；时间戳放断点前会让缓存永久 miss。

tools 定义、大 system prompt、RAG 检索结果、多轮历史、few-shot 示例——稳定前缀靠前、易变内容靠后。经典错误：把每请求变化的 timestamp 放 system 尾部断点之前 → 永远 miss。

9. Message Batches（批量）

🎯 学习重点：Batch 用 50% 折扣换异步延迟；记住 100,000 请求/256MB、24 小时过期、结果保留 29 天。

（来源: https://platform.claude.com/docs/en/build-with-claude/batch-processing（访问于 2026-08-30））

9.1 模型

🎯 学习重点：用 custom_id 对账、轮询批状态、下载 JSONL；验证异步且结果顺序不能当业务顺序。

• 请求项 = custom_id（^[a-zA-Z0-9_-]{1,64}$）+ 完整 Messages params。
• 上限：100,000 请求或 256MB 先到为准；多数批次 <1 小时完成，24 小时过期；结果保留 29 天。
• 结果类型：succeeded / errored / canceled / expired（后两者不计费）。
• 全线 5 折；workspace 作用域；高吞吐可能小幅越过 spend limit。
• 不支持：stream、speed（Fast mode）、store/Threads、cache_hint、max_tokens: 0、research preview。验证是异步的——先用 Messages API 验证请求形状再入批。
• 共享上下文的批任务建议 1h 缓存 TTL（5m 大概率在批处理排队时过期）。

🔪 架构师犀利细节 05｜批量不是“大号同步调用”：100,000 项和 256MB 取先到者，且单项验证在提交后异步发生；结果必须以 custom_id 关联，不能依赖返回顺序。反模式是把未经验证的请求一次塞满整批；正解是先用 Messages API 做小样契约测试，再按可重放分片提交并持久化 batch_id/custom_id。

9.2 什么任务该进 Batch

🎯 学习重点：用户不等待、允许小时级完成且能管理结果生命周期的任务，才是 Batch 候选。

不需要即时响应的一切：大规模评估（模块 12）、内容审核、数据集加工、批量生成。架构判断：同步链路上每个"用户不等待"的调用都是 Batch 候选。

10. Bad vs Better：整条调用链

🎯 学习重点：综合题应覆盖 SDK、分类重试、缓存、Batch/streaming、request-id 与 usage，而不是只给一个 API 调用示例。

Bad：裸 curl 逻辑搬到生产——无 SDK、无重试、401/429/500 一律 catch-all 重试 3 次、每轮重发全部历史、无缓存、批量任务循环调同步 API、错误只打一行 log。

Better：

• SDK（自动头/重试/超时）+ 类型化异常处理 + request-id 全链路记录
• 重试策略按错误类型分叉（§5 图）；带预算与降级链
• 稳定前缀显式断点缓存（省 0.9x 输入价 + 不占 ITPM）
• 离线任务全走 Batch（5 折）；长输出走 streaming final message
• usage 入库做成本异常检测

11. 权衡 速查

🎯 学习重点：每个可靠性或成本杠杆都有对应代价，答案要明确延迟、依赖、写入溢价或流量放大。

12. 常见错误

🎯 学习重点：高频坑集中在错误误重试、缓存静默 miss、Batch 参数不支持和流内错误漏处理。

1. ❌ 字符串匹配错误 message 而不是按 type/SDK 异常类分派
2. ❌ spend-cap 429 当普通限流退避重试（无 retry-after，重试到天亮也无效）
3. ❌ 时间戳/随机 ID 混进缓存前缀 → 永远 miss 还以为缓存坏了
4. ❌ 缓存没上却不知道（不看 usage 双字段是否全 0）
5. ❌ Batch 里塞 stream: true 或 max_tokens: 0（直接验证错误）
6. ❌ custom_id 不符合 ^[a-zA-Z0-9_-]{1,64}$（整批验证失败）
7. ❌ 流式响应只处理 text_delta，没处理 error 事件与未知事件
8. ❌ 重试无预算 + 计费不幂等被忽略（重试也烧钱）

13. 重要英文术语表

🎯 学习重点：重点掌握 retry/backoff/jitter、cache breakpoint/TTL、batch/custom_id 三组关联词。

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

14. 认证相关性

🎯 学习重点：认证题常与环境隔离结合，可靠性题常与错误分类结合，成本题常要求量化缓存与 Batch。

• 重试/退避/错误分派是故障处理能力域的必考直觉（哪些错该重试、哪些不该）
• caching 与 Batch 是成本架构域的两大杠杆（0.1x 与 5 折的量化）
• request-id、usage 入库对应可观测性（模块 12 深入）
• 认证方式（key vs WIF）与 workspace 隔离对应企业部署模型

15. 下一步

🎯 学习重点：完成实验后应能画出包含认证、限速、重试、缓存、降级和可观测性的生产调用链。

• 动手：labs/lab.md；代码：examples/api_walkthrough.py（无 key 校验模式可跑；有 key 可实发）、examples/retry_backoff.py（无 key，退避策略模拟）
• 自测：questions/ + flashcards/flashcards-03.csv
• 下一模块：04-tool-use/——让 Claude 操作真实世界