AI 可观测性实施清单：20 个生产步骤
AI 可观测性实施清单应该回答一个比“API 是否在线？”更难的问题。生产环境中的 AI 功能即使返回 HTTP 200，也可能给出错误答案、使用过时的检索上下文、调用错误的工具、通过昂贵的回退重试、将敏感提示数据泄露到日志中，或者耗时过长而失去价值。
实际目标是将每个用户可见结果与产生该结果的模型尝试、检索步骤、工具调用、策略决策、延迟、token 使用量和成本关联起来。这需要传统应用遥测，再加上 AI 特有的上下文和评估信号。
本指南为 LLM 应用、智能体、检索增强生成系统和多模型网关提供分阶段实施计划。它保持供应商中立，并在可能的情况下使用 OpenTelemetry 概念。它还包含信号到决策映射、验收测试矩阵、七天上线计划、遥测契约、仪表化模式、告警运行手册和供应商评分卡，以便团队能够从需求推进到正式上线。
一句话理解 AI 可观测性
AI 可观测性是指：通过一组相关联的 trace、指标、日志、评估和用户结果，解释 AI 工作流的行为、质量、可靠性、安全性和成本的能力。
监控告诉你阈值发生了变化。可观测性帮助你确定为什么会变化，以及涉及了哪些请求、模型、提示、检索结果、工具、租户或发布版本。
将本指南中的 AI 可观测性实施清单用作发布门禁，而不是一次性的文档工作。每当你更换模型、提示、检索索引、工具 schema、路由策略或评估器时，都要重新执行一遍。
对于一个 AI 应用，一次请求可能包含多个不同的尝试：
用户操作
└─ 应用工作流
├─ 检索查询
├─ 模型尝试 1
├─ 工具调用
├─ 模型尝试 2
└─ 验证和用户可见结果
如果这些步骤无法在同一个 trace 或请求标识下关联起来，调试就只能靠猜测。
最小 AI 可观测性数据模型
数据模型是 AI 可观测性实施清单的基础，因为每个仪表板、告警、评估和事故查询都依赖一致的关联字段。
从一个工作流级别的 trace 开始，并为每个关键操作设置子 span。OpenTelemetry 将 trace、指标、日志和 baggage 定义为核心信号。其生成式 AI 语义约定为模型和智能体操作提供了不断发展的词汇，并且截至 2026 年 8 月 4 日，这些约定维护在专门的 OpenTelemetry 语义约定仓库中。由于这些约定可能会演进，请固定你实现时使用的版本，并保留一个小型内部兼容层，而不要把供应商特定的字段名散落在代码各处。
至少要捕获以下字段组。
| 字段组 | 记录内容 | 重要原因 |
|---|---|---|
| 关联 | trace_id、request_id、会话 ID、工作流、环境、版本 |
串联完整请求路径 |
| 路由 | 提供商、请求的模型、解析后的模型、区域、端点或路由别名 | 说明请求实际运行的位置 |
| 尝试 | 尝试次数、重试原因、回退来源和目标 | 将单个用户请求与多个可计费调用区分开来 |
| 性能 | 排队时间、首个 token 时间、总延迟、工具和检索延迟 | 定位慢速阶段 |
| 使用量 | 输入、缓存输入、输出、推理或提供商特定的使用字段 | 说明容量和成本 |
| 结果 | 状态、标准化错误类别、结束原因、验证结果 | 区分传输成功与任务成功 |
| 质量 | 评估器版本、评分、通过/失败、用户反馈、已接受结果 | 跟踪响应是否有用 |
| 治理 | 租户、策略决策、脱敏状态、保留类别 | 支持隐私和审计控制 |
避免将原始提示和响应视为必填字段。在许多系统中，它们应默认禁用，或仅存储在单独受控的评估数据集中。
将每个信号映射到一个运营决策
更多遥测数据并不一定更好。在添加属性、指标或仪表板之前，先明确它所支持的决策以及该决策的负责人。
| 信号 | 它回答的问题 | 典型决策 | 主要负责人 |
|---|---|---|---|
| 已接受完成率 | 工作流是否解决了客户任务？ | 回滚、更改提示词/模型，或调查下游故障 | 产品和 AI 工程 |
| p95 端到端延迟 | 完整体验是否足够快？ | 更改路由、降低检索/工具延迟，或调整流式输出 | 平台工程 |
| 首个 token 时间 | 流式输出是否感觉响应及时？ | 调整排队、提供商路由或提示词大小 | 平台工程 |
| 回退率 | 主路由是否健康且经济？ | 调查提供商健康状况、容量或路由策略 | 可靠性工程 |
| 每个已接受结果的成本 | 重试和低质量结果是否抵消了节省？ | 更改模型组合、缓存、提示词大小或验证 | 工程和 FinOps |
| 检索依据通过率 | 答案是否使用了授权且相关的上下文？ | 重建索引、过滤器、重排器或引用验证 | 搜索/RAG 负责人 |
| 工具对账失败 | 外部副作用是否安全完成？ | 暂停工具、对账状态，或修复幂等性 | 应用负责人 |
| 脱敏失败次数 | 敏感数据是否到达导出器？ | 停止导出、隔离遥测数据，或更新策略 | 安全/隐私 |
此表可防止一种常见失效模式：仪表板上有数十个图表，但没人知道某个变化应该触发什么操作。
一个实用的 Trace 形状
为用户可见的工作流使用一条 trace，而不是为每个提供方调用单独创建一条无关的 trace。根 span 应描述客户任务，而子 span 应描述促成结果的各项操作。
workflow: answer_support_question
attributes: tenant_class, release, accepted_outcome, final_status
├─ retrieval.search
│ attributes: index_version, top_k, authorization_result
├─ gen_ai.attempt
│ attributes: provider, requested_model, resolved_model, attempt=1
├─ tool.lookup_order
│ attributes: tool_schema_version, idempotency_key, result
├─ gen_ai.attempt
│ attributes: provider, resolved_model, attempt=2, fallback_reason
└─ evaluation.validate_answer
attributes: evaluator_version, pass, score_band
OpenTelemetry 的生成式 AI 语义约定仍在演进中。把它们当作共享词汇表，但要固定约定版本，记录任何本地扩展，并在预生产环境中测试升级。将 accepted_outcome 之类的业务结果保留在你自己的稳定应用命名空间中，这样语义约定的变更就不会破坏产品报表。
阶段 1：在添加仪表板之前定义结果
1. 命名工作流和可接受结果
不要从全局的提供方 token 图表开始。先从某个客户任务开始，例如：
- 支持答复被接受且无需升级处理；
- 代码补丁通过测试；
- 抽取结果匹配所需的 schema；
- 代理在无需人工恢复的情况下完成请求的操作；
- 生成的媒体通过产品审核门禁。
创建一个机器可读的 workflow 名称和一个 accepted_outcome 或等效结果。这将成为质量、成本和可靠性指标的分母。
2. 定义失败分类法
至少区分以下几类：
- 传输失败：超时、连接错误或上游 5xx；
- 容量失败：速率限制、配额、队列饱和或上下文限制；
- 契约失败：无效 JSON、缺失字段、不受支持的工具 schema 或流中断；
- 质量失败：答案无关、错误、不完整或缺乏依据；
- 安全失败：策略违规、提示注入成功或不安全的工具执行；
- 业务失败：技术上有效但用户拒绝或放弃的输出。
单一的 error=true 维度远远不够。它会掩盖你究竟需要基础设施改进、提示词变更、模型变更，还是产品变更。
3. 选择初始服务级指标
从一组能反映用户体验的小指标开始：
workflow availability = accepted workflow completions / eligible workflow starts
quality pass rate = evaluator-passing completions / evaluated completions
p95 end-to-end latency = p95(workflow completed - workflow started)
cost per accepted outcome = total workflow cost / accepted outcomes
将提供商可用性保留为诊断指标，而不是产品 SLI。即使提供商运行正常，如果检索、工具、验证或路由出现故障，你的工作流也可能失败。
阶段 2：为完整请求路径添加埋点
4. 为每个用户可见的工作流创建一个根 span
在应用边界生成根 trace，先于检索或模型路由开始。将该上下文贯穿于队列、worker、网关、工具服务和回调之中。
对子 span 使用以下场景：
- 检索和重排序；
- 每次模型尝试；
- 每次工具调用；
- 护栏或策略检查；
- 输出解析和验证；
- 回退选择；
- 持久化和下游交付。
5. 记录请求的路由和解析后的路由
客户端指定的模型不一定就是实际处理请求的模型。两者都要记录：
{
"ai.requested_model": "support-balanced",
"ai.resolved_provider": "provider-b",
"ai.resolved_model": "model-version-2026-07",
"ai.route_reason": "primary_rate_limited",
"ai.attempt": 2
}
这对于多提供商系统至关重要。它也让 模型回退策略 具备可审计性，而不再是不可见的。
6. 单独衡量流式传输
仅有总延迟并不能描述流式体验。需要捕获：
- 排队时长；
- 连接和提供商延迟；
- 首个 token 或首个有用事件的时间；
- 生成时长；
- 端到端完成时间；
- 客户端取消时间。
一次请求的总延迟可能可接受，但首个 token 的时间却很差。它也可能很快生成首个 token，然后卡住。
7. 让重试和回退成为一等尝试
永远不要用最终成功覆盖第一次失败的尝试。一个工作流 span 应该包含或关联每一次计费尝试，包括：
- 重试次数；
- 触发原因；
- 退避时长；
- 提供商和模型；
- token 数和成本；
- 部分输出状态；
- 最终处理结果。
这可以防止重试风暴被显示为“100% 成功”。
阶段 3：添加 AI 特定的质量上下文
8. 为提示词、工具、策略和评估器做版本管理
存储稳定标识符，而不仅仅是原始内容：
prompt_version
tool_schema_version
retrieval_index_version
policy_version
evaluator_version
route_policy_version
这些维度让你能够在变更前后比较一次发布。没有版本管理，质量下降就很难归因。
9. 追踪检索质量
对于检索增强生成，记录：
- 查询版本和过滤条件；
- 检索延迟；
- 文档或 chunk ID；
- 来源新鲜度；
- top-k 和重排序器版本；
- 空结果率；
- 访问控制决策；
- 引用或 grounding 验证结果。
不要将完整的私有文档放入通用 trace 存储中。除非调试策略明确允许内容采集，否则应存储受控引用或哈希。
10. 追踪工具调用和副作用
每个工具跨度都应包含工具名称、schema 版本、授权决策、延迟、规范化结果，以及它是否产生了外部副作用。
对于会产生副作用的工具，还应记录幂等性键和对账状态。当模型调用在工具已完成后超时，这一点尤为重要。
11. 结合在线和离线评估
在线信号很快，但噪声也大：点赞、放弃、重生成、纠正、升级人工处理或任务完成。离线评估更慢，但更可控：精心筛选的测试集、评分标准打分器、可执行测试和人工审查。
将这两类评估连接到相同的工作流和版本标识符。不要在未标注变更的情况下，把不同评估器版本的分数混合到同一条趋势线上。
第 4 阶段：控制隐私、安全与保留
12. 在收集前对遥测数据分类
定义三个级别：
- 元数据：路由、时间、token、状态、版本和 ID。
- 派生内容信号：长度、语言、安全类别、评估器分数或哈希。
- 原始内容：提示、响应、检索到的文本、工具参数和工具结果。
广泛收集元数据。只有在用例、用户告知、访问控制和保留策略支持时，才收集原始内容。
13. 在采集边界进行脱敏
只要可能，脱敏应在导出之前完成。覆盖以下内容：
- API 密钥、bearer token、cookie 和授权头；
- 电子邮件地址、电话号码、账号和政府身份证明标识；
- 工具参数或检索文档中的机密信息；
- 签名 URL 和数据库连接字符串；
- 共享可观测性存储中被禁止包含的租户特定内容。
对导出的属性使用白名单。黑名单最终总会漏掉一个新的含密字段。请遵循这份AI API 密钥管理指南中描述的同样原则。
14. 按数据类别设置保留和访问权限
原始内容不应继承与低风险指标相同的保留策略。应定义独立的存储、加密、访问角色、审计日志和删除流程。要测试删除，而不是假定一份策略文档就足够了。
NIST AI 风险管理框架及其生成式 AI 配置文件强调在整个系统生命周期内持续测量、文档化和风险管理。可观测性有助于提供证据，但不加区分的日志记录会带来新的隐私和安全风险。
15. 控制高基数维度
不要把用户 ID、trace ID、提示文本、文档 ID 或原始错误消息变成指标标签。将高基数数据保留在 trace 或日志中，然后再派生出有边界的指标，例如工作流、模型家族、错误类别、环境和区域。
第 5 阶段：构建指向行动的告警
16. 围绕影响用户的症状告警
针对以下症状触发页面告警：
- 已接受完成率低于目标；
- 质量通过率跌破发布护栏；
- p95 延迟或首 token 时间消耗了错误预算；
- 每个已接受结果的成本超过其上限；
- 不安全的副作用或策略失败；
- 回退率升至正常区间之上。
除非它们直接威胁面向用户的目标，否则将提供方错误、token 峰值和检索缺失用作诊断告警或仪表盘信号。
17. 使用燃尽率窗口进行 SLO 告警
静态阈值可能会产生噪声。错误预算燃尽率告警会询问服务消耗允许失败预算的速度有多快。Google 的 SRE 指南建议将更快的窗口与更慢的确认窗口结合起来，这样严重事故就能快速触发页面告警，而不会让每次短暂峰值都变得可操作。
18. 添加发布和路由注释
每个仪表盘都应显示 prompt、应用、路由、模型和评估器的发布信息。添加部署注释并比较 canary 与 control 群组。否则，团队只会看到曲线变化，却看不到到底是什么变了。
第 6 阶段：在全面推出前验证
19. 运行故障演练
至少测试以下内容：
- 上游超时；
- 速率限制和配额耗尽；
- 结构化输出格式错误；
- 部分流式传输中断；
- 检索未返回任何授权上下文；
- 工具成功但响应丢失；
- fallback 改变模型行为；
- 遥测导出器不可用；
- 脱敏规则收到未知字段。
确认工作流会安全失败，trace 保持连贯，并且告警能识别正确的负责人。
20. 分四个阶段推出
- Shadow: 在不改变路由或用户行为的情况下发出遥测。
- Canary: 对一小部分流量启用，并比较开销、基数和数据质量。
- 受控生产: 附加发布阈值和回滚规则。
- 全面生产: 在通过隐私、可靠性和成本检查后扩大范围。
OpenTelemetry 支持头采样和尾采样模式。在可行的情况下保留所有错误和稀有失败类别，然后对常规成功流量进行采样以控制成本。采样规则必须不会移除用于解释事故所需的那些精确 trace。
生产验收测试矩阵
验收测试证明 AI 可观测性实施清单 能在故障、隐私和遥测丢失场景下正常工作，而不只是对成功请求有效。
不要因为 spans 出现在 trace 查看器中就宣布可观测性已经完成。请运行受控测试，并为每个发布门保存证据。
| 测试 | 注入条件 | 所需遥测证据 | 通过条件 |
|---|---|---|---|
| 上游超时 | 强制主模型路由超过其截止时间 | 首次尝试 span、超时类别、重试或回退决策、最终结果 | 没有孤立 span；最终处置和总成本可见 |
| 速率限制 | 返回提供方 429 或耗尽测试配额 | 原始提供方代码、标准化容量类别、退避时长、路由变更 | 重试预算受限，告警指向路由负责人 |
| 无效结构化输出 | 返回格式错误的 JSON 或缺少必需字段 | 契约验证 span、验证器版本、修复尝试、最终通过/失败 | HTTP 成功不被计为已接受的成功 |
| 流中断 | 在第一个 token 后中断输出 | 首个 token 时间、部分输出标志、可计费用量、重试决策 | 防止重复内容和双重工具执行 |
| 空检索 | 不返回任何已授权文档 | 检索过滤条件、授权结果、空结果原因、回答策略 | 系统遵循已批准的无上下文行为 |
| 工具歧义 | 让工具完成，而模型请求超时 | 幂等键、副作用状态、协调结果 | 工具不会被执行两次，且状态可恢复 |
| 脱敏哨兵 | 在测试字段中插入合成密钥 | 本地检测事件，未导出密钥值 | 导出在离开边界前被阻止或脱敏 |
| 导出器故障 | 停止遥测目标端 | 导出器队列/丢弃指标和应用健康状况 | 用户流量仍保持在其可靠性预算内 |
| 采样检查 | 在高成功率流量中生成少量罕见错误 | 错误 traces 被保留；常规成功按配置采样 | 采样后，事故示例仍可搜索 |
| 发布回归 | 部署一个已知存在延迟或质量退化的金丝雀 | 发布注释、金丝雀 cohort、对照 cohort、SLI 比较 | 回滚阈值触发，并且可识别变更负责人 |
对于每项测试，记录负责人、测试日期、trace ID、预期告警、实际告警以及整改工单。这会把可观测性变成可重复的发布控制，而不是一次性的埋点项目。
七天实施计划
对于一个聚焦的团队，AI 可观测性实施清单可以作为一个为期七天的序列来实施，并且每天结束时都留下可审查的证据。
这个序列是刻意收窄的。它会在团队扩大覆盖范围之前，先交付一个值得信赖的纵向切片。
- 第 1 天 — 结果契约：选择一个高价值工作流，定义符合条件的启动、可接受的结果、失败类别和 SLI 公式。
- 第 2 天 — Trace 骨架：创建根工作流 span，并在应用程序、队列、网关、检索层和工具之间传播上下文。
- 第 3 天 — 模型尝试：捕获请求和解析后的路由、尝试、延迟、结束原因、提供商用量、重试和回退。
- 第 4 天 — 质量和成本：关联验证器结果、评估器版本、用户结果和归一化后的工作流成本。
- 第 5 天 — 隐私控制：对字段进行分类，实施允许列表导出，测试脱敏，设置保留期，并验证访问边界。
- 第 6 天 — SLO 和仪表板：构建最小仪表板，添加发布注释，定义燃尽率告警，并分配负责人。
- 第 7 天 — 故障演练：运行验收矩阵，修复缺口，开始金丝雀发布，并记录回滚条件。
在第七天结束时，目标不是实现全局仪表化。目标是一个生产工作流，其行为、质量、可靠性、安全性和成本都可以从头到尾被解释清楚。
发布所需的最小仪表板
仪表板是 AI 可观测性实施清单 的运营视图。它应当优先展示客户结果，其次才是基础设施细节。
保持首个运营视图足够小，以便在事故期间使用：
- 结果行：符合条件的启动、已接受完成、质量通过率，以及放弃或升级处理。
- 可靠性行：归一化错误、回退率、重试放大，以及错误预算消耗。
- 延迟行：端到端 p50/p95/p99、队列时间、首个 token 时间、检索延迟和工具延迟。
- 经济性行：输入/输出/缓存 token、总工作流成本，以及每个已接受结果的成本。
- 变更行：应用程序、提示、路由策略、模型、检索索引、工具 schema 和评估器发布。
- 调查链接：每种失败类别、发布、路由和受影响工作流的代表性 traces。
仪表板应支持从症状到 trace 的路径。如果某个告警显示质量下降，但团队无法在几次点击内访问受影响的工作流 traces，那么调查闭环就是不完整的。
AI 可观测性平台评估记分卡
商业评估应测试平台是否支持你的运营模型，而不是测试它是否拥有最长的功能列表。使用同一个已加仪表的试点工作负载对候选方案进行评分。
| 标准 | 权重 | 在试点中验证什么 |
|---|---|---|
| 工作流关联 | 20% | 一条 trace 连接模型尝试、检索、工具、验证和用户结果 |
| OpenTelemetry 互操作性 | 15% | 标准导入/导出可用；本地扩展仍可查询；数据可移植 |
| 质量和评估关联 | 15% | 在线反馈和带版本的离线评估与生产 traces 关联 |
| 隐私与治理 | 15% | 字段允许列表、脱敏、区域控制、访问角色、审计日志和删除测试 |
| 可靠性运维 | 15% | SLO、燃尽率告警、采样控制、发布注释以及事故演练支持 |
| 成本归因 | 10% | 提供商使用量、重试、回退、缓存 tokens 和已接受结果的单位成本可对账 |
| Agent/RAG/工具覆盖 | 5% | 检索和产生副作用的工具操作具有一等 span 和过滤器 |
| 运营成本 | 5% | 摄取、存储、查询、保留和工程开销符合预期规模 |
为每项标准使用 1–5 分评分，乘以权重，并要求提供试点中的书面证据。即使仪表板看起来很精致，如果平台无法保留你的遥测契约或导出你的数据，也会造成运营锁定。
可复制的遥测契约
让 AI 可观测性实施清单 迅速落地的最快方式，是将其转化为一个带版本的遥测契约。该契约定义每个工作流和模型尝试必须发出的内容、哪些字段是可选的、哪些值是允许的，以及哪些字段禁止进入高流量索引。
下面的示例使用内部命名空间。将其映射到固定版本的 OpenTelemetry GenAI 约定中，只需通过一个适配器完成，而不是让应用代码暴露在约定变更之下。
telemetry_contract:
version: "2026-08-04"
workflow_span:
required:
- ai.workflow.name
- ai.workflow.version
- ai.request.id
- deployment.environment
- service.version
- ai.outcome.status
- ai.outcome.accepted
- ai.latency.total_ms
optional:
- ai.tenant.tier
- ai.experiment.id
- ai.user.feedback
prohibited:
- end_user.email
- end_user.name
- raw.authorization_header
model_attempt_span:
required:
- ai.attempt.number
- ai.route.requested_model
- ai.route.resolved_provider
- ai.route.resolved_model
- ai.result.status
- ai.usage.input_tokens
- ai.usage.output_tokens
- ai.latency.first_token_ms
- ai.latency.total_ms
conditional:
- ai.fallback.reason
- ai.error.class
- ai.error.provider_code
- ai.usage.cached_input_tokens
content_capture:
default: "off"
allowed_when:
- approved_evaluation_dataset
- explicit_debug_session
controls:
- redact_before_export
- access_logged
- retention_approved
在代码审查中审查这份合同，就像审查一个 API schema 一样。新的模型提供商、agent 工具、fallback 策略或 evaluator 在其 telemetry 字段映射到该合同并通过相同的验收测试之前，不应上线。
单个 AI 工作流的埋点模式
不要让每个团队独立发明 span 名称和属性。提供一个小型封装器，用于创建根工作流 span、记录子尝试、捕获标准化结果，并在导出前应用脱敏。
这个 Python 示例是有意与提供商无关的。内部属性名称应在封装器或 collector 层转换为你固定的 OpenTelemetry 语义约定版本。
from opentelemetry import trace
tracer = trace.get_tracer("checkout-assistant")
def run_ai_workflow(request, router, evaluator):
with tracer.start_as_current_span("ai.workflow.checkout_help") as workflow_span:
workflow_span.set_attribute("ai.workflow.name", "checkout_help")
workflow_span.set_attribute("ai.workflow.version", "2026-08-04")
workflow_span.set_attribute("ai.request.id", request.request_id)
result = None
for attempt_number in range(1, 3):
with tracer.start_as_current_span("ai.model.attempt") as attempt_span:
route = router.resolve(request, attempt_number)
attempt_span.set_attribute("ai.attempt.number", attempt_number)
attempt_span.set_attribute("ai.route.requested_model", request.model)
attempt_span.set_attribute("ai.route.resolved_provider", route.provider)
attempt_span.set_attribute("ai.route.resolved_model", route.model)
result = route.generate(request)
attempt_span.set_attribute("ai.result.status", result.status)
attempt_span.set_attribute("ai.usage.input_tokens", result.input_tokens)
attempt_span.set_attribute("ai.usage.output_tokens", result.output_tokens)
if result.status == "ok":
break
attempt_span.set_attribute("ai.error.class", result.error_class)
evaluation = evaluator.score(request, result)
workflow_span.set_attribute("ai.outcome.status", result.status)
workflow_span.set_attribute("ai.outcome.accepted", evaluation.accepted)
workflow_span.set_attribute("ai.evaluator.version", evaluation.version)
workflow_span.set_attribute("ai.quality.score", evaluation.score)
return result
生产代码还应记录持续时间、首 token 时间、fallback 原因、取消、流式传输错误和异常。关键的设计选择是层级结构：一个客户工作流包含一个或多个可计费尝试，而工作流记录最终被接受的结果。
告警策略与首次响应运行手册
如果仪表板没有响应规则，AI 可观测性实施清单 就是不完整的。每个上线指标都需要一个触发条件、一个负责人和一个首个诊断查询。
| 告警 | 示例触发条件 | 首要问题 | 立即行动 |
|---|---|---|---|
| Accepted-outcome burn | 快速和缓慢的错误预算消耗 | 哪个工作流、发布、路由或租户发生了变化？ | 暂停发布或回滚相关发布 |
| Latency regression | p95 工作流延迟突破 SLO | 队列、检索、模型还是工具延迟发生了变化？ | 绕过较慢的阶段或降低负载 |
| Fallback surge | 回退率超过其正常区间 | 主提供方是否发生故障、限流或超时？ | 检查规范化和原始提供方错误 |
| Cost-per-outcome spike | 成本上升而接受率保持平稳或下降 | 重试次数、输出长度或高成本路由是否在增加？ | 限制重试并恢复之前的路由策略 |
| Quality-score drop | 在线或抽样评估器通过率下降 | 提示词、检索、模型或评估器版本是否发生变化？ | 将发布批次与上一个健康批次进行比较 |
| Tool uncertainty | 副作用结果无法核对 | 工具是在超时或取消之前完成的吗？ | 停止自动重试并进入核对流程 |
| Telemetry loss | 预期的 span 或用量完整性下降 | 是仪表化出问题，还是导出背压在上升？ | 将缺失的遥测视为一次运行事件 |
值班视图应当能从告警直接链接到按工作流、发布、请求的模型、已解析路由和错误类别过滤后的 traces。若响应人员在事故期间必须手动重建这些过滤条件，则系统尚未具备上线就绪状态。
所有权与生产交接
在上线前将清单分配给明确命名的角色。没有明确决策人的共同所有制，通常会产生人人都能查看、却无人维护的仪表板。
| 职责 | 负责角色 | 所需交接证据 |
|---|---|---|
| 工作流结果定义 | 产品或 AI 功能负责人 | 接受结果规则和拒绝示例 |
| Span 和指标模式 | 平台或可观测性负责人 | 版本化遥测契约和模式测试 |
| 路由和回退字段 | 网关或可靠性负责人 | 请求/解析路由和尝试验证 |
| 质量评估器 | AI 工程负责人 | 评估器版本、数据集、阈值、已知限制 |
| 隐私和保留 | 安全或隐私负责人 | 数据分类、脱敏测试、保留审批 |
| SLO 和告警 | 服务负责人 | SLO 文档、值班规则、仪表板、运行手册 |
| 成本分摊 | 工程财务负责人 | 用量完整性和每个结果成本的核对 |
| 发布就绪度 | 工程负责人 | 已完成的验收矩阵和回滚触发条件 |
在上线后安排一次 30 天复盘。移除未使用的字段，将反复有用的调试查询提升为仪表盘视图，审查基数和存储成本，并在工作流行为发生变化时更新契约。
可复制的 AI 可观测性实施清单
将此清单用作上线门槛：
- [ ] 定义每个工作流和可接受的客户结果。
- [ ] 定义传输、容量、契约、质量、安全和业务故障。
- [ ] 选择可用性、质量、延迟和每次结果成本的 SLI。
- [ ] 批准包含必需、可选和禁止字段的版本化遥测契约。
- [ ] 为每个用户可见的工作流创建一个根 trace。
- [ ] 让上下文在队列、工具、检索和网关之间传递。
- [ ] 记录请求的和已解析的提供商/模型路由。
- [ ] 为每次重试和回退尝试创建单独的 span。
- [ ] 捕获队列时间、首 token 时间和总延迟。
- [ ] 捕获提供商报告的 token 使用量和归一化成本。
- [ ] 对 prompts、工具、检索索引、策略、路由和评估器进行版本管理。
- [ ] 记录检索引用、新鲜度、授权和 grounding 结果。
- [ ] 记录工具授权、幂等性、结果和副作用状态。
- [ ] 将用户反馈和离线评估结果与 traces 关联。
- [ ] 将遥测分类为元数据、派生信号或原始内容。
- [ ] 在导出前对密钥和敏感字段进行脱敏。
- [ ] 按数据类别应用单独的保留和访问策略。
- [ ] 避免在指标标签中使用高基数值。
- [ ] 针对影响用户的 SLO 和错误预算消耗设置告警。
- [ ] 标注发布并比较金丝雀与对照组。
- [ ] 运行故障、隐私、采样和导出器宕机场景演练。
- [ ] 为发布门禁保存验收测试证据和 trace ID。
- [ ] 使用一个加权试点评分卡比较可观测性平台。
- [ ] 为结果、schema、隐私、SLO、质量和成本指定负责的所有者。
- [ ] 将每个需要值班响应的告警链接到首响 runbook 和 trace 查询。
常见的 AI 可观测性错误
在没有数据策略的情况下记录 prompts
原始 prompts 在调试期间看起来很有用，但它们可能包含客户数据、密钥、受版权保护的材料或受监管信息。请从元数据开始，只在有正当理由时才启用受控内容捕获。
按每次请求而不是按结果来衡量成本
一个验证失败的廉价请求并不便宜。重试、回退和人工纠正都应计入工作流成本。同样的原则也适用于 prompt 缓存 ROI：优化被接受的任务，而不是孤立的 token 速率。
将每次模型调用都视为独立事件
Agent 和 RAG 系统是工作流。如果模型、检索和工具 spans 没有关联，团队就无法重建因果关系。
依赖单一提供商仪表盘
提供商仪表盘对于上游使用量和错误很有用，但它们看不到你的完整应用结果、检索系统、工具执行、用户反馈或跨提供商回退路径。
在定义决策之前就为一切埋点
遥测有运行成本。每个字段都应支持调试、告警、评估、治理或优化决策。删除没人使用的字段。
AI 网关在何处发挥作用
LLM 网关可以作为有用的关联与策略边界，因为多个应用和提供商都会经过这一个控制点。它可以在将遥测导出到可观测性栈之前，统一路由、尝试、用量、延迟和错误元数据。
网关并不是完整的解决方案。应用代码仍然负责工作流结果、检索上下文、工具语义、用户反馈和业务转化。最强的设计是将网关遥测与这些应用层信号结合起来。
Flatkey 为多个 AI 模型提供一个兼容 OpenAI 的访问层。如果你的团队正在整合提供商集成，了解 Flatkey，并使用这份清单来定义围绕你的应用和路由层的遥测契约。
常见问题
我应该先为 AI 可观测性实施什么？
先从AI 可观测性实施清单开始：为每个客户工作流设置一个根 trace、模型尝试子 span、请求和解析后的模型字段、延迟、用量、标准化错误，以及一个已接受结果信号。如果你的隐私政策允许，再添加原始提示词捕获。
OpenTelemetry 对 LLM 可观测性来说够用吗？
OpenTelemetry 为 traces、metrics 和 logs 提供了与传输无关的基础，以及不断演进的生成式 AI 语义约定。你仍然需要工作流定义、评估、隐私控制、SLO、仪表板和事件响应流程。
提示词和响应应该存储在 traces 中吗？
默认不应该。先使用元数据、版本、哈希和派生质量信号。只有在受控系统中、具备明确目的、访问策略、保留期限和删除流程时，才存储原始内容。
哪些 AI 可观测性指标最重要？
先从已接受完成率、质量通过率、端到端 p95 延迟、流式输出的首个 token 时间、回退率以及每个已接受结果的成本开始。等这些指标可信之后，再添加工作流特定指标。
我如何监控多个 AI 提供商？
在各提供商之间使用一套稳定的遥测 schema。记录每次尝试的请求路由和解析后的提供商/模型，在不丢弃原始提供商代码的情况下标准化错误，并将所有尝试关联到同一个工作流 trace 下。
