前置：模块 3（API 实战）、模块 8（agents）。本模块以 2026-08-30 的官方文档为准（docs.claude.com路径现已统一重定向到platform.claude.com/docs）。所有价格、限额、模型名均为易变事实，均标注「截至 2026-08-30」。
📘 重要英语词汇表
🎯 学习重点：必考结论是可用性由编排层设计，而不是模型自带；六个生产面必须形成闭环。
demo 与生产系统的差距不在模型，而在工程系统：环境如何隔离、配置与密钥如何流转、出错时谁负责兜底、花了多少钱能不能查、模型退役了怎么办。本模块把这道坎拆成六块：
架构师核心心法：生产系统的可用性不是模型自带的，是你的编排层设计出来的。 官方 SDK 自带的自动重试只是起点（默认仅重试 2 次，见 10.3），错误分类、超时预算、降级路径、人工升级都要你自己设计。
🎯 学习重点：掌握环境隔离、配置同源、密钥生命周期与版本留痕四条生产基线。
🎯 学习重点：易错点是 staging 应尽量复刻 prod 模型与配置，而数据必须脱敏或影子化。
| 环境 | 目的 | 模型策略 | 数据策略 | 观测粒度 |
|---|---|---|---|---|
| dev | 开发调试 | 便宜档（如 Haiku 级）+ 版本别名 | 合成/脱敏数据 | 全量日志（可含 prompt 体） |
| staging | 预发验证，接近生产 | 与 prod 相同模型 + 相同配置 | 脱敏或影子数据 | 与 prod 相同的采样率演练 |
| prod | 真实流量 | 版本锁定（见 10.5） | 真实数据 + 最小化记录 | 采样 + 脱敏（见 10.2） |
三条铁律：
anthropic-version、超时、重试参数必须同源管理，唯一差异是环境变量值。anthropic-version 头（如 2023-06-01，SDK 自动处理）；同一版本内 Anthropic 保留既有输入/输出参数不破坏，但可能追加可选字段——解析响应时不要因为「多了新字段」而崩。来源: https://platform.claude.com/docs/en/api/versioning（访问于 2026-08-30）🧨 犀利细节｜兼容性不仅是模型 ID：锁定模型却让 anthropic-version、超时或 prompt 版本在环境间漂移，仍然无法复现生产行为。响应解析应容忍新增可选字段；反模式是对未知字段报错，正解是只校验业务依赖字段并把完整版本组合写入 trace。
🎯 学习重点：所有环境差异应通过外部配置注入，且每次发布必须可还原当时配置版本。
生产 Claude 应用的配置分四层，自上而下：
代码内默认值 ← 环境变量 ← 配置中心/密钥管理器 ← 环境专属覆盖🎯 学习重点：必背不入库/日志/prompt、可轮换撤销审计、生产优先短时效凭证。
官方认证方式本身就把「secret 的生命周期」制度化了。截至 2026-08-30，Claude API 有三种认证方式：API key（静态 sk-ant- 前缀密钥，走 x-api-key 头，适合本地开发/脚本）、Workload Identity Federation（用云平台身份换短时效 token，官方定位就是「在生产负载、CI/CD、Kubernetes 上消除静态密钥」）、App Attest（iOS/macOS 应用直连场景）。来源: https://platform.claude.com/docs/en/manage-claude/authentication（访问于 2026-08-30）
由此推出生产三原则：
⚠️ 认证视角：官方同时建议用多个 workspace + 按 key 区分用量来隔离成本与爆炸半径（一个 key 泄露 ≠ 全组织额度暴露）。429 里甚至专门区分了「Claude Code workspace 超限」这一独立类别。来源: https://platform.claude.com/docs/en/api/rate-limits（访问于 2026-08-30）
🧨 犀利细节｜轮换必须支持重叠窗口：正解顺序是新凭证签发并注入 → 验证新凭证承接流量 → 撤销旧凭证；先撤销再部署会把安全操作变成可用性事故。service account 与 workspace 隔离还应让单凭证泄露只影响一个工作负载，而非全组织。
🎯 学习重点：区分「当前系统状态」与「历史决策追溯」，并让 logs、metrics、traces 共享关联 ID。
🎯 学习重点：必背 logs/metrics/traces 的最小字段，以及 request-id、Usage API、OpenTelemetry 三个官方抓手。
经典可观测性三支柱是 logs / metrics / traces。在 Claude 应用里它们的「最小充分集」是：
| 支柱 | 必须记录 | 官方抓手 |
|---|---|---|
| Logs | 结构化 JSON：时间戳、trace_id、request_id、模型、token usage、错误类型、耗时 | 每个响应都带 request-id 头（如 req_018EeWyXxfu5pfWkrYcMdjWG），报障时必须带上它 |
| Metrics | 延迟分位数（p50/p95/p99）、错误率（按 4xx/5xx/429 细分）、token 与成本、缓存命中率 | Usage & Cost Admin API 按模型/key/工作区输出用量与成本，用于对账与告警 |
| Traces | 一次用户请求穿过的完整链路：路由决策 → 检索 → 每次 Claude 调用（含工具轮次）→ 工具执行 → 返回 | Agent SDK 内建 OpenTelemetry 导出（traces/metrics/log events，OTLP 协议） |
来源: https://platform.claude.com/docs/en/api/errors（request-id，访问于 2026-08-30）；https://platform.claude.com/docs/en/manage-claude/usage-cost-api（访问于 2026-08-30）；https://code.claude.com/docs/en/agent-sdk/observability（访问于 2026-08-30）
🎯 学习重点：生产默认记录元数据，prompt/response、PII、凭证和第三方内容必须默认关闭或脱敏限存。
这是架构师最容易踩的合规坑。判断顺序：
该不该记？→ 这条数据 90 天后还需要吗？→ 泄露了会伤害用户吗？该记（生产默认开）：
request_id、trace_id、模型 ID、版本、调用方（哪个服务/feature）、环境usage 字段）、成本估算不能记 / 必须脱敏（默认关，开了要审计）：
脱敏的工程做法：在日志管道入口（而非每个调用点）做集中式过滤器——正则识别邮箱/卡号/密钥模式 → 替换为 *** 占位 → 结构化字段里只留长度/类型计数。宁可记「有一段疑似邮箱被脱敏」也不记原文。
🧨 犀利细节｜可观测字段与内容字段分开授权：request_id、token、错误类型和耗时足以支撑多数运营诊断；开放全文日志会把调试权限扩大成数据访问权限。正解是元数据管道常开，内容采样使用独立开关、加密存储、最短保留期与更窄访问角色。
🎯 学习重点：每个模型与工具调用都应成为 span，并携带耗时、usage、状态与跨系统关联 ID。
trace: user_request_7f3a
├── span: gateway (auth, parse, rate check)
├── span: orchestrator.plan
│ ├── span: retrieval.search (hybrid, top_k=10, 23ms)
│ └── span: claude.call #1 (sonnet, 1.2s, in=4200 out=180, cache_read=3800)
│ ├── span: tool:db_lookup (12ms)
│ └── span: claude.call #2 (retry after 529, in=4400 out=95)
├── span: fallback needed? → no
└── span: response.compose (validate JSON, redact, 8ms)要点：每个 Claude span 挂 request_id（可回查 Anthropic 侧）、token usage、缓存命中情况；每个工具 span 挂工具名与耗时（不挂敏感实参）；顶层 span 挂用户可读的 request_id 便于客诉对账。
🎯 学习重点：审计记录必须包含决策、配置、身份与对账锚点，而不只是最终响应正文。
可观测性回答「现在系统怎么样」；可审计性回答「过去某时某刻系统做了什么、依据什么」。生产 Claude 应用的审计底线：
AWS::AWSExternalAnthropic::Workspace）。来源: https://docs.aws.amazon.com/claude-platform/latest/userguide/monitoring.html（访问于 2026-08-30）🎯 学习重点：先分类错误，再在总预算内依次选择重试、熔断、降级或人工升级。
🎯 学习重点：状态码题最易错的是两种 429；必须读取retry-after与details.error_code。
截至 2026-08-30，官方错误分类与处置（来源: https://platform.claude.com/docs/en/api/errors，访问于 2026-08-30）：
| HTTP | error type | 含义 | 正确处置 |
|---|---|---|---|
| 400 | invalid_request_error | 请求格式/内容问题；自设 spend limit 触顶也返回 400 | 不重试，修请求或提额 |
| 401 | authentication_error | key 失效/过期 | 不重试，换凭证 |
| 403 | permission_error | key 无权访问该资源 | 不重试，查权限 |
| 404 | not_found_error | 资源不存在 | 不重试，查路径/ID |
| 429 | rate_limit_error | 限流；带 retry-after 头 | 等 retry-after 再重试 |
| 429 | rate_limit_error（无 retry-after，details.error_code = enforced_spend_limit_reached） | 月度 spend cap 触顶 | 重试无效！等下月或升 tier |
| 500 | api_error | 服务端内部错误 | 指数退避重试 |
| 504 | timeout_error | 处理超时 | 重试或改用 streaming |
| 529 | overloaded_error | API 过载 | 指数退避重试；流量要平缓爬坡 |
两条考试级细节：
retry-after，可通过 max-retries 配置或关闭。来源: https://platform.claude.com/docs/en/api/errors（访问于 2026-08-30）retry-after；spend cap 429 没有 retry-after，重试（含 SDK 自动重试）会一直失败到下月恢复——所以生产代码要读 error.details.error_code 区分这两者，前者降速、后者报警并切换预算/模型。来源: https://platform.claude.com/docs/en/api/rate-limits（访问于 2026-08-30）🧨 犀利细节｜嵌套重试会乘法放大：SDK 默认重试 2 次意味着一次应用调用最多产生 3 次尝试；若外层也按「失败后再试 2 次」包住整个调用，最坏可变成 3 × 3 = 9 次上游尝试。正解是统一重试所有权，或把 SDK 尝试数计入顶层预算与熔断统计。
🎯 学习重点：只对幂等瞬时故障做带 jitter 的指数退避，并从顶层 timeout budget 向下分配。
超时预算 (timeout budget) 是把「这次用户请求总共允许耗多久」显式化：总预算 = 首次尝试 + N 次重试 + 退避等待。每次尝试分到的超时 = 剩余预算的函数；预算耗尽就不再重试，直接走降级。这防止「层层各自 30 秒超时、叠加成 3 分钟」的放大事故。
指数退避 (exponential backoff) + 抖动 (jitter)：等待 = base × 2^attempt + 随机抖动，避免同批请求同步重试造成惊群 (thundering herd)。
只重试幂等且瞬时的：429（限流型）、500、502、529、连接错误。400/401/403/404 是确定性错误，重试烧钱不解决问题。
🎯 学习重点：降级必须显式标注、单独观测并能通过 half-open 探测自动恢复。
降级 指主路径失败时切换到「更便宜/更慢但可用」的替代路径：
降级要满足三件事：显式声明（响应里标注 degraded）、可观测（metrics 里单独计数）、可恢复（主路径恢复后自动切回，通常配半开探测）。
🎯 学习重点：必背 closed/open/half-open 三态，并说明熔断保护系统、retry 保护单请求。
熔断器 三态：closed（正常放行）→ open（连续失败超阈值，直接快速失败/走降级，不再打上游）→ half-open（冷却期后放一个探测请求，成功则回 closed）。它保护的不只是用户耐心，还有上游：529 过载时继续全量重试等于火上浇油——官方也建议「流量逐渐爬坡、保持平稳模式」以避免触发加速度限制。来源: https://platform.claude.com/docs/en/api/rate-limits（访问于 2026-08-30）
🎯 学习重点：不可逆、低置信、降级链打穿和合规复核四类场景必须能交还人类。
升级 是把决策权交还人类的设计。什么时候必须升：
升级设计要点：升级时携带结构化上下文（原始请求、已尝试的路径、失败原因、trace_id），让人工接得住而不是从零开始；升级事件进审计日志；升级率本身是一个监控指标（异常升高 = 系统性退化信号）。
🎯 学习重点：场景题不能承诺三者全优，必须给出主目标、牺牲项与量化验收指标。
这是模块 10 的决策核心：三个目标两两冲突，没有全赢方案，只有显式取舍。
🎯 学习重点：能解释重试、校验、模型档位如何分别改变成本、尾延迟与成功率。
成本 (Cost)
/ \
更便宜 更快/更稳
/ \
延迟 ——————————— 可靠性
(Latency) (Reliability)🎯 学习重点：必背缓存 1.25×/2×/0.1×、Batches 半价及上限、模型分层的 evals 决策法。
① Prompt caching（同前缀复用，降本+提速+提吞吐）
cache_control，系统自动把断点放在最后一个可缓存块并随对话前移——适合多轮对话）与 explicit breakpoints（逐块精确控制）。来源: https://platform.claude.com/docs/en/build-with-claude/prompt-caching（访问于 2026-08-30）cache_control 放在跨请求保持不变的最后一个块上。来源: https://platform.claude.com/docs/en/build-with-claude/prompt-caching（访问于 2026-08-30）🧨 犀利细节｜先算缓存盈亏平衡：以基础输入价为 1，5 分钟缓存一次写入后再命中一次的总成本是1.25 + 0.1 = 1.35，低于两次不缓存的2；1 小时缓存同场景是2 + 0.1 = 2.1，要到第三次使用才低于不缓存的3。因此 TTL 选择应由复用间隔和预计命中次数驱动，而不是一律选最长。
② Message Batches API（异步批处理，半价）
stream、fast mode（speed）、Threads、max_tokens: 0（缓存预热）等参数；共享上下文的批官方建议配 1 小时缓存 TTL 提命中率。来源: https://platform.claude.com/docs/en/build-with-claude/batch-processing（访问于 2026-08-30）🧨 犀利细节｜请求数与字节数取更严格上限：例如 50 万条任务仅按每批 100,000 请求计算至少要拆 5 批，但若任何批先达到 256 MB 就必须拆得更多。批处理编排要按子请求持久化状态并只重提失败项，不能把整批当成不可分割的一次事务。
③ 模型分层路由
当前在售四档（截至 2026-08-30，来源: https://platform.claude.com/docs/en/models/overview，访问于 2026-08-30）：
| 模型 | API ID | 输入/输出价 ($/MTok) | 定位 |
|---|---|---|---|
| Claude Fable 5 | claude-fable-5 | $10 / $50 | 长时 agent 的下一代智能，较慢 |
| Claude Opus 5 | claude-opus-5 | $5 / $25 | 复杂 agentic 编码与企业工作 |
| Claude Sonnet 5 | claude-sonnet-5 | $2 / $10 | 速度与智能的最佳组合 |
| Claude Haiku 4.5 | claude-haiku-4-5-20251001 | $1 / $5 | 最快、近前沿智能 |
分层路由 = 按任务难度把请求分给不同档位：意图分类/格式化 → Haiku 档；主回答 → Sonnet 档；复杂推理/多步 agent → Opus 档。决策依据是任务成功率（evals）× 单价，而不是「越大越好」。缓存写入价 = 基础输入价 ×1.25（5m），如 Sonnet 5 为 $2.50/MTok（截至 2026-08-30，来源: https://platform.claude.com/docs/en/build-with-claude/prompt-caching，访问于 2026-08-30）。
🎯 学习重点：把实时性、复用前缀、任务价值和限流类型映射到缓存、batch、模型与校验策略。
| 场景 | 首选 | 为什么 | 代价 |
|---|---|---|---|
| 客服实时对话 | Sonnet 档 + automatic caching | 延迟敏感；对话前缀稳定，缓存读取一折 | 首轮写入贵 25% |
| 夜间批量评估 10 万条 | Batches + 共享前缀 1h 缓存 | 不需要实时；直接半价再叠缓存 | 结果要等 ≤1h，不支持 stream |
| 高价值合同审查 | Opus/Fable 档 + 双模型校验 | 错误成本 >> token 成本 | 延迟与成本显著上升 |
| 长时自主 agent | 大上下文 + prompt caching + checkpoint | 多轮同前缀，缓存收益最大化 | 断点设计复杂；模型切换会丢缓存 |
| 限流频发（ITPM 顶格） | 加大缓存命中率（读不计 ITPM） | 变相扩容 | 缓存写入有额外成本 |
🎯 学习重点：升级闭环是锁版本 → 离线回归 → staging → 稳定哈希灰度 → 指标异常回滚。
🎯 学习重点：必背 Active/Legacy/Deprecated/Retired 与至少 60 天通知，并生产使用固定快照。
官方模型生命周期（截至 2026-08-30）：Active →（Legacy）→ Deprecated → Retired。Deprecated 模型仍可用但「可能不如 active 模型可靠」（官方原话警告）；Retired 后请求直接失败。公开发布模型至少提前 60 天通知退役。来源: https://platform.claude.com/docs/en/about-claude/model-deprecations（访问于 2026-08-30）
版本锁定策略：
claude-haiku-4-5-20251001 这类 pinned 版本）或显式版本配置项，而不是漂移的别名——保证「今天的行为 = 上周评估过的行为」🎯 学习重点：按稳定哈希切流量、新旧指标分标签，任何一档异常都能配置回滚。
灰度 指新模型版本按比例承接流量：
新版本流量 = 1% → 5% → 25% → 50% → 100%
每档观察：错误率 / 延迟 p95 / 成本 / 输出质量抽样 / 升级率
异常即回滚（旧版本还在，回滚是配置切换）关键设计：路由按稳定哈希（同一用户/会话固定走同一版本，避免体验抖动）；新旧版本的指标分标签对比而不是混在一起。
🎯 学习重点：golden dataset 要覆盖真实分布和边角案例，并比较质量、格式、工具正确率与成本。
升级不是「换了就能跑」，官方明确建议「远早于退役日期就用新模型充分测试应用」。回归评估要点（模块 12 展开）：
来源: https://platform.claude.com/docs/en/about-claude/model-deprecations（访问于 2026-08-30）
🎯 学习重点：能从网关、编排、工具、状态、可靠性、可观测与人工层解释完整请求路径。
读图要点：
🧨 犀利细节｜控制面故障不能拖垮数据面：指标、审计、熔断状态与升级队列是横切依赖；设计时要明确哪些是同步硬依赖、哪些可异步缓冲。反模式是日志后端变慢就阻塞用户请求；正解是关键审计保证落盘，非关键遥测有界缓冲并在丢弃时计数告警。
🎯 学习重点：从 key、环境、网关、日志、故障、缓存与版本七个维度把 demo 逐项生产化。
场景：企业内部知识助手，5000 员工使用，接内部 wiki 与工单系统。
🎯 学习重点：识别前端密钥、无环境隔离、全量日志和硬编码模型带来的失效半径。
问题清单（每条都对应本模块一节）：
🎯 学习重点：用服务端网关、分层路由、预算、熔断、脱敏、审计与人工升级形成纵深防御。
逐条修复：key 移到服务端并按 workspace 隔离（1+3）；dev/staging/prod 三环境 + 版本锁定（2）；日志只记元数据、原文加密限存（4）；429 看 retry-after、spend-cap 429 报警、529 退避 + 降级到次级模型（5）；stable 前缀 + automatic caching，缓存读取一折（6）；模型 ID 进配置 + 灰度 + 回归评估（7）。每个数字都有出处：见 10.3 与 10.4 引用的官方文档。
🎯 学习重点：每个决策都要明确一面收益、另一面代价和可验证的选择条件。
| 决策 | 选 A | 选 B | 张力 | 决策依据 |
|---|---|---|---|---|
| 静态 key vs Workload Identity Federation | 接入简单 | 无静态 secret 可泄露 | 便利 vs 安全 | 生产负载一律后者（官方定位） |
| 缓存 5m vs 1h TTL | 写入 1.25× | 写入 2× 但命中窗口长 | 写入成本 vs 命中率 | 流量间隔 <5m 选 5m；批处理选 1h |
| 实时 API vs Batches | 即时响应 | 半价 | 延迟 vs 成本 | 用户在等就实时；离线任务就 batch |
| 大模型一次到位 vs 小模型多轮 | 贵但稳 | 便宜但可能绕路 | 成本 vs 可靠性 | 用 evals 实测成功率×单价 |
| 多重试保成功 vs 快速失败降级 | 成功率↑ | 延迟↓ | 可靠性 vs 延迟 | 超时预算内重试，预算外降级 |
| 全量日志 vs 元数据日志 | 可回放 | 合规安全 | 可观测 vs 隐私 | 生产默认元数据，原文加密限存 |
| 激进升级 vs 版本锁定 | 吃到新能力 | 行为可预测 | 创新 vs 稳定 | 灰度 + 回归评估解锁升级 |
🎯 学习重点：高频错项是 spend-cap 重试、动态缓存断点、层层重试、全文日志、漂移别名与无声明降级。
retry-after，重试到天荒地老也失败；要读 error.details.error_code。来源: https://platform.claude.com/docs/en/api/rate-limits（访问于 2026-08-30）cache_control 断点放在每次变化的块上（时间戳/当次消息）——回看窗口找不到旧写入，永远全款写入永不命中。来源: https://platform.claude.com/docs/en/build-with-claude/prompt-caching（访问于 2026-08-30）stream: true 或 fast mode——直接校验错误；batch 不支持的参数是硬约束。来源: https://platform.claude.com/docs/en/build-with-claude/batch-processing（访问于 2026-08-30）🎯 学习重点：术语不仅要翻译，还要能说出触发条件、状态迁移与一个生产反模式。
🎯 学习重点：认证题重点落在错误分类、缓存计价、batch 适用性、三角权衡、密钥与生命周期。
本模块对应认证中「工程实践 / 生产部署 / 可靠性与成本」类考点：
cache_control 放哪；计算缓存写入/读取成本（1.25×/2×/0.1×）衔接：模块 11（安全）把本模块的网关/权限/PII 面深化为 prompt injection 与应用层强制；模块 12（评估与可观测性）把 10.5 的回归评估与 10.2 的监控指标展开成完整 evals 体系。📚 目录