🎯 学习重点：用“认证 → 调用 → 错误 → 重试 → 缓存/批量 → 可观测性”的顺序记忆生产 API 术语。 返回：模块 03 主讲义
🎯 学习重点：长期 key、短期身份和云 IAM 是不同信任模型，不能只替换请求头完成迁移。
API Key — API 密钥 — 长期凭据应由密钥管理器注入、定期轮换并按 workspace 限权。
x-api-key — API 密钥头 — Anthropic 自营 API 携带 key 的请求头，不应在日志中记录其值。
Authorization Bearer — Bearer 授权 — 用于携带 WIF 短期 token，与 x-api-key 二选一。
Workload Identity Federation (WIF) — 工作负载身份联合 — 用短期身份替代长期静态 key，降低凭据泄露窗口。
Workspace — 工作区 — 隔离成员、权限和用量归属，是环境与成本治理边界。
IAM — 身份与访问管理 — Bedrock、Vertex、Foundry 使用各自云 IAM，平台迁移必须重做权限映射。
Provider Adapter — 提供商适配层 — 封装 endpoint、认证和模型 ID 差异，避免业务代码绑定单一平台。
Least Privilege — 最小权限 — 凭据只获得完成任务所需的最小资源和操作范围。
🎯 学习重点：Messages 是核心生成接口，Count Tokens、Models、Files 与 Batches 分别承担配套职责。
RESTful API — REST 风格 API — 通过标准 HTTP 方法访问资源，仍需应用层处理重试、限流和业务完成状态。
Messages API — 消息 API — Claude 在线生成的核心 endpoint，输入历史由调用方负责提供。
Token Counting API — Token 计数 API — 在正式请求前估算输入，用于窗口准入和成本预估。
Models API — 模型 API — 查询模型能力与最大输入，适合构建动态能力矩阵。
Files API — 文件 API — 上传一次后通过 file_id 复用，减少多轮重复传输。
Anthropic Version — Anthropic API 版本 — 必需请求头，用于锁定 API 契约而非模型权重。
Request Body Limit — 请求体上限 — Messages 32MB、Batch 256MB、Files 500MB，超限返回 413。
Content Block — 内容块 — 响应 content 是 block 数组，不能假设第一项永远是最终文本。
Stop Reason — 停止原因 — 表示本轮完成方式，HTTP 200 不能替代对它的分支处理。
Request ID — 请求 ID — 每次响应的追踪主键，持续故障报障时必须保留。
🎯 学习重点：SDK 提供的不只是语法糖，而是类型、连接、重试和流式协议的统一实现。
SDK (Software Development Kit) — 软件开发工具包 — 封装认证头、类型、错误、重试、超时与连接管理。
Typed Exception — 类型化异常 — 让应用按错误类别分派，优于匹配易变的 message 字符串。
Connection Pooling — 连接池 — 复用网络连接降低握手成本，客户端生命周期应避免每请求重建。
TCP Keep-Alive — TCP 保活 — 帮助维持长连接，但不能替代应用层超时和重试预算。
Streaming — 流式传输 — 对长输出降低连接空闲与感知等待，最终仍需处理流内 error。
Final Message — 最终消息 — SDK 在内部消费事件流后返回的完整 Message，适合不想手工拼装 SSE 的调用方。
Timeout — 超时 — 表示等待期限到达，不一定代表服务端未执行或未计费。
🎯 学习重点：可重试性由故障语义决定，不由“请求失败了”统一决定。
Invalid Request Error — 无效请求错误 — 确定性请求问题应修复输入，原样重试只会重复失败。
Authentication Error — 认证错误 — 401 表示凭据无效，重试前必须恢复合法身份。
Permission Error — 权限错误 — 403 表示身份存在但无资源权限，应修授权而非换退避时间。
Rate Limit Error — 限流错误 — 429 可能是速率或预算上限，需结合 retry-after 与账户状态判断。
Overloaded Error — 过载错误 — 529 属瞬时服务压力，应退避并平缓恢复流量。
Request Too Large — 请求过大 — 413 需要拆分或缩小负载，重试同一请求无效。
Exponential Backoff — 指数退避 — 以 base×2^n 拉长重试间隔，降低持续故障时的请求压力。
Jitter — 抖动 — 给退避增加随机量，避免大量客户端在同一时刻再次冲击服务。
Retry-After — 建议重试等待 — 服务端给出的等待提示，应优先于客户端自定延迟。
Retry Budget — 重试预算 — 用最大次数和总时限限制放大效应，默认 2 次重试即最多 3 次尝试。
Retry Storm — 重试风暴 — 大量客户端同步重试导致负载进一步恶化的正反馈。
Fallback — 降级路径 — 重试耗尽后切换模型、排队或转人工，必须提前定义触发条件。
Idempotency — 幂等性 — Messages 无真实世界副作用，但重复尝试仍可能重复生成并计费。
🎯 学习重点：容量控制、成本归因和故障排查依赖不同指标，但应由同一请求追踪串联。
Client-Side Rate Limiting — 客户端限速 — 按 RPM/ITPM/OTPM 平滑发送，避免把服务端 429 当调度器。
Concurrency Limit — 并发上限 — 控制同时在途请求，不能用固定并发数代替 token 维度容量规划。
Acceleration Limit — 加速限制 — 流量突增可能触发额外 429，上线恢复需渐进爬坡。
Usage Attribution — 用量归因 — 将四类 token、模型、workspace 和业务请求关联，支持成本核算。
Distributed Tracing — 分布式追踪 — 用内部 trace ID 关联 request-id、重试尝试和下游动作。
Cost Anomaly — 成本异常 — 输入突涨可能来自缓存失效、历史膨胀或注入，应按 usage 字段定位。
🎯 学习重点：缓存收益由前缀稳定性、长度、TTL 和复用次数共同决定。
Prompt Caching — 提示缓存 — 复用稳定前缀以降低读取价格和多数模型的 ITPM 消耗。
Cache Control — 缓存控制 — 标记自动缓存或显式断点的请求配置，类型为 ephemeral。
Cache Breakpoint — 缓存断点 — 前缀写入位置，最多 4 个且读取向前回看最多 20 blocks。
Automatic Caching — 自动缓存 — 系统将断点放在最后可缓存 block，适合持续增长的多轮对话。
Explicit Breakpoint — 显式断点 — 精确控制 tools、system 或 RAG 内容的缓存边界。
TTL (Time to Live) — 生存时间 — 5m/1h 从请求开始计时，长响应会消耗可复用时间。
Cache Hit — 缓存命中 — usage 中出现 cache_read_input_tokens 才是可观测证据。
Cache Miss — 缓存未命中 — 前缀字节变化、长度不足或竞态都可能导致 miss。
Cache Warm-Up — 缓存预热 — 可用 max_tokens: 0 建立前缀缓存，但 Batch 不支持此参数。
Break-Even Point — 盈亏平衡点 — 5m 与 1h 写价不同，必须按预期复用次数判断是否回本。
🎯 学习重点：Batch 的核心是异步状态、业务对账和结果生命周期管理，而不只是 50% 折扣。
Message Batches — 消息批处理 — 最多 100,000 项或 256MB，适合用户不等待的离线负载。
Custom ID — 自定义 ID — 批内请求的业务对账键，格式限 1–64 位字母数字下划线或连字符。
Processing Status — 处理状态 — 应用轮询批次生命周期，而不是维持长 HTTP 连接。
Request Counts — 请求计数 — 反映各结果状态数量，适合进度与失败率监控。
Results URL — 结果地址 — 批次结束后下载 JSONL，结果保留 29 天且应及时归档。
JSONL — 逐行 JSON — 每行一个结果，便于流式处理大批输出而不整文件载入内存。
Asynchronous Validation — 异步验证 — 提交成功不代表每个 params 合法，应先用在线 API 做小样契约测试。
Batch Expiration — 批次过期 — 24 小时未完成的请求进入 expired，不能当同步 SLA 使用。
🎯 学习重点：SDK 默认行为、缓存系数与 Batch 限制会变化，实施前需对照当前官方文档。