AI 原生开放教材

外观

AI 工程从零到一（中文）源码研读·中文原文 ↗原件 ↓仓库 ↗

生产可观测性、延迟与成本 ​

API 调用显示正常，也可能掩盖失败的任务。

类型： 构建 语言： Python 前置要求： RAG、检索与数据流水线；阶段 11，第 10 课；阶段 17，第 08、13 和 27 课 预计时间： 约 150 分钟

学习目标 ​

  • 区分系统可靠性、任务质量和业务结果
  • 为 Claude 请求和 agent 执行轨迹设计日志、指标和 trace
  • 诊断模型、检索、工具、队列和重试各环节的延迟
  • 衡量总成本和每个成功结果的成本
  • 根据服务目标定义告警和上线门禁

问题所在 ​

生产仪表盘显示 API 调用成功率为 99.9%，客户却仍在投诉。

模型返回 HTTP 200，但部分答案使用了过期来源。工具超时后，agent 一声不响地继续执行。长 prompt 因为开头附近放了时间戳而无法命中缓存。P95 延迟翻了一倍，平均值看起来却还能接受。更便宜的 模型降低了调用价格，却增加了重试和人工审核。

仪表盘衡量的是传输是否成功，产品成败取决于任务是否成功。可观测性必须把两者连接起来。

核心概念 ​

观察四个层级 ​

mermaid
flowchart TD
    B["Business outcome\nresolution, adoption, saved time"]
    Q["Task quality\nfactuality, completeness, safety"]
    T["Trajectory\nretrieval, tools, retries, approvals"]
    S["System\nlatency, errors, saturation, cost"]
    S --> T --> Q --> B

系统信号告诉你组件是否运行。执行轨迹信号告诉你应用做了什么。质量信号告诉你结果是否满足 任务要求。业务信号告诉你工作流是否创造了价值。

不要把它们压缩成一个“成功”字段。

日志、指标和 trace 各司其职 ​

日志记录离散事件：请求已接受、检索未返回候选结果、工具拒绝授权、输出未通过 schema 验证、 审核人发起升级。使用结构化字段，方便运维人员分组和过滤。

指标聚合一段时间内的行为：请求率、错误率、P95 延迟、token 用量、缓存命中、检索召回率、 任务通过率和每次成功的成本。它们驱动仪表盘和告警。

trace 连接完整执行轨迹。一条 trace 应通过父子 span 串起模型调用、检索、工具执行、验证、 重试和人工审批。没有 trace，缓慢的请求看起来只是一个不透明的整体。

跟踪语义契约 ​

捕获足够的信息，以便复现结果并进行分类：

  • trace、请求、会话和不暴露用户敏感信息的标识符
  • 应用、prompt、模型、工具、知识和 eval 版本
  • 输入类别和风险等级
  • token 数量及缓存读取或写入
  • 停止原因和工具名称
  • 工具耗时和结构化错误类别
  • 验证与政策决策
  • 评估器结果和人工编辑
  • 最终状态和下游结果

不要记录机密、原始凭证或不必要的个人数据。对于敏感输入，存储哈希、类别、数量或受访问控制 的引用，而不是明文。

分开系统成功与任务成功 ​

系统成功关注请求是否按照协议完成。任务成功关注输出是否满足既定评分规则。有效的 JSON 响应 可能在事实上是错的。agent 也可能正常结束，却没有完成请求的状态变更。

对于 agent 系统，两方面都要评估：

  • 最终状态：预期产物或系统状态是否存在？
  • 执行轨迹：工具、权限、证据和预算的使用是否正确？

单靠文本匹配无法判断这两点。

拆解延迟 ​

端到端延迟包括：

text
queue + context assembly + model + retrieval + tools + validation + retries + approval

为每个主要 span 跟踪 P50 和 P95。P50 描述典型路径，P95 暴露缓慢工具、长上下文、速率限制和 重试。

对于流式体验，还要包括首次产生有用输出的时间。首 token 时间可能很好看，但用户仍在等待引用、 工具结果或最终通过验证的答案。

对于后台和批处理系统，衡量是否按期限完成以及吞吐量。如果整个作业能在业务时间窗口内完成， 单个批处理项耗时 30 秒也可以接受。

根据证据优化 ​

常见的延迟优化手段：

  • 把简单工作路由给速度更快且能力合适的模型
  • 减少无关上下文
  • 把稳定的 prompt 前缀放在适合缓存的位置
  • 检索更少、更优的候选结果
  • 并发运行相互独立的工具调用
  • 把非交互式工作负载移到批处理
  • 强制执行时间、轮数和重试预算
  • 在新鲜度允许时缓存确定性的工具结果

每种手段都可能改变质量或安全性。应在有代表性的评估集上评估这些取舍。

衡量每个成功结果的成本 ​

token 价格只是其中一项。

text
total cost = model + cache writes and reads + tools + infrastructure + review + correction
cost per success = total cost / accepted task outcomes

失败的请求仍会产生成本，安全拒绝、重试、审核时间和事故纠正也一样。分别报告输入、输出、缓存 和工具成本，让团队知道该从哪里着手。

选择模型或架构变体时，应比较每个成功结果的成本。

理解 prompt 缓存的形态 ​

prompt 缓存会复用稳定前缀。靠前位置的变化可能导致后续所有内容失效。如果当前文档支持这种 缓存布局，应把稳定的工具定义、系统指令和大型参考材料放在动态用户内容之前。

跟踪缓存读取和缓存写入 token。只有缓存功能开关、没有命中率指标，算不上优化。

工具定义、模型设置、思考配置和其他请求变化都可能影响缓存行为。具体细节会变化，应以当前 官方文档为准进行验证。

构建可操作的告警 ​

告警应服务于用户或运维人员需要作出的决策，别让指标稍有波动就触发告警。

好的告警包括：

  • 任务通过率在有意义的时间窗口内低于 SLO
  • 安全控制失效或出现未授权操作尝试
  • P95 延迟超出用户容忍范围
  • 检索新鲜度延迟
  • 某类工具错误激增
  • 部署后缓存命中率崩塌
  • 每次成功的成本超出预算
  • 评估器意见不一致或标签漂移

每条告警都需要负责人、runbook、证据链接和升级路径。如果没人知道收到告警后该做什么，它就 只是仪表盘上的装饰。

通过渐进上线控制证据风险 ​

离线评估只能覆盖一部分情况。生产流量还会带来新的查询、数据、负载和集成。

采用：

  1. 不影响用户的影子评估
  2. 按租户或流量比例进行小范围 canary
  3. 带自动回滚保护的逐步扩大
  4. 质量、延迟、成本和安全门禁通过后全面上线

与稳定基线比较，并按任务类别分层。整体提升可能掩盖高风险分层中的严重回归。

动手构建 ​

交互实验 ​

figure
26-latency-cost-slo

使用 SLO 探索器分别调整任务成功率、缓存率、重试成本、P50 和 P95。你会看到，有些变体的调用 价格更低或传输状态正常，却仍无法通过用户体验、质量或每次成功成本门禁。

实践实验 ​

加入一条成本低但失败的 trace，观察单价下降时每次成功的成本如何上升。然后找出第一道应该 阻止上线的门禁。

交付产物 ​

outputs/release-scorecard.json 填写了基线和候选方案对比， 并设置了相互独立的质量、延迟、缓存和经济性门禁。

验证 ​

复现并测试聚合逻辑：

bash
cd certifications/claude/lessons/26-production-observability-latency-and-cost/code
python3 main.py
python3 -m unittest discover tests -v

测验会检查故障诊断和上线决策。

综合项目关联 ​

把这份评分卡带入 Architect Professional 综合项目的评估、可观测性和 canary 门禁部分。

实验只用 Python 聚合合成 trace 记录。

bash
cd certifications/claude/lessons/26-production-observability-latency-and-cost/code
python3 main.py
python3 -m unittest discover tests -v

第 1 步：表示一条任务执行轨迹 ​

Trace 存储紧凑的端到端记录：变体、延迟、token 数量、成本、系统结果、任务结果、缓存状态和 错误类别。生产 trace 应包含子 span 和受访问控制的引用，而不是单个扁平对象。

第 2 步：聚合时不隐藏故障 ​

summarize 分别报告系统成功和任务成功。它计算最近秩 P50 和 P95、缓存读取率、错误类别、 总成本和每次任务成功的成本。失败尝试仍计入成本分子。

第 3 步：比较变体 ​

by_variant 按变体拆分结果，避免启用缓存或路由的方案与基线混在一起取平均值。把质量、延迟 和成本放在一起比较。

第 4 步：评估服务目标 ​

evaluate_objectives 应用任务成功率下限以及延迟和成本上限。变体必须通过每一道必要门禁。 不能用更低的成本抵消安全或质量故障。

上手使用 ​

先提出一个生产问题：“为什么任务成功率在发布后下降？”

按应用和发布版本过滤 trace，再按输入类别分层。先检查系统错误，再检查检索和工具 span，接着 检查验证器和评估器结果。比较 prompt、模型、知识和工具版本，找出执行轨迹最早偏离基线的位置。

如果 P95 延迟上升而 P50 保持稳定，应检查慢路径行为：重试、速率限制、大输入、工具超时和等待 审批。如果 token 价格稳定而成本上升，应检查调用次数、上下文长度、缓存命中和审核。

维护一份发布评分卡：

门禁基线候选方案要求
任务通过率高风险分层中不能回归
安全通过率硬性控制达到 100%
P95 延迟在 SLO 范围内
每次成功的成本在预算内
检索召回率在容许范围内
人工审核时间不得隐藏工作流负担

考试决策模式 ​

如果 API 成功率很高，但用户报告结果很差，应增加或检查语义质量和执行轨迹证据。如果错误答案 出现在文档刷新之后，应先追踪检索，再更换模型。

优先选择符合以下特征的答案：

  • 结合使用日志、指标和 trace
  • 分开传输成功、任务成功和业务成功
  • 监控 P95，而不只看平均值
  • 比较每个成功结果的成本
  • 对 prompt、模型、工具和知识进行版本管理
  • 以质量、延迟、成本和安全性作为上线门禁
  • 为每条告警指定负责人和 runbook

常见陷阱 ​

默认记录完整 prompt ​

这可能泄露个人数据、机密或受监管内容。只记录必要且安全的证据，并对敏感引用实施访问控制。

使用单一聚合质量分数 ​

它可能掩盖不同语言、风险等级、任务或客户中的回归。应该分层分析。

使用平均延迟 ​

少量慢请求可能在平均值保持稳定时破坏用户体验。跟踪尾部延迟和超时率。

使用每次调用的成本 ​

它会奖励廉价的失败。使用每个被接受结果的成本，并把审核和纠正计入其中。

练习 ​

  1. 扩展实验，为检索和两个工具增加子 span。
  2. 增加输入风险分层，并证明整体改善可能掩盖严重回归。
  3. 创建缓存失效实验，衡量命中率、P95 和成本。
  4. 为工具授权故障设计一条带负责人和 runbook 的告警。
  5. 编写一项 canary 政策，任何硬性控制失败时自动回滚。

关键术语 ​

术语人们常说的意思实际含义
日志调试文本带有安全证据和标识符的结构化事件
指标任意数字用于理解或控制行为的一段时间聚合值
Trace一个请求 ID完整执行轨迹中相互关联的耗时和结果
任务成功HTTP 200请求的结果满足评分规则和约束
P95 延迟最慢请求95% 的已测请求在该值或更低值内完成
每次成功的成本模型价格总预期成本除以被接受的任务结果数

延伸阅读 ​