AI 可观测性实施检查清单：5 步走向生产环境

只有当工程师能在上线或事故处理中据此采取行动时，AI 可观测性才真正有用。如果没有人能回答哪个请求验证失败、为什么触发了回退，或者成本激增是来自流量、重试还是模型变更，那么一个充满 token 数和延迟百分位数的仪表板也毫无意义。

这份 AI 可观测性实施检查清单将问题拆解为五个有序步骤：

1. 定义遥测契约。
2. 为每次模型尝试埋点。
3. 验证质量和成本。
4. 设置服务级目标和告警。
5. 在明确责任和治理下逐步上线。

顺序很重要。通常先做仪表板的团队，后面才会发现字段不一致、追踪中隐藏了重试，或者他们的成功指标把不可用输出也算作了健康请求。

如果你首先需要更全面的信号与仪表板设计地图，请阅读 LLM API 可观测性指南。本文聚焦于实施顺序以及每个阶段的退出标准。

AI 可观测性实施检查清单一览

步骤 1：在选择仪表板之前定义遥测契约

先从运维人员必须回答的问题入手，再定义能够支持这些问题的最小通用记录。该契约应能经受提供商变更和模型回退。特定于提供商的字段可以作为可选属性添加，但不应取代稳定的内部名称。

必需的请求级字段

为产品操作使用一个内部 request_id，为分布式追踪使用一个 trace_id。为每次提供商调用添加一个 attempt_id。

{
  "telemetry_schema_version": "1.0",
  "request_id": "req_...",
  "trace_id": "...",
  "attempt_id": "attempt_1",
  "environment": "production",
  "feature": "support_reply",
  "route_policy": "quality_primary_cost_fallback",
  "provider": "provider_a",
  "requested_model": "model_alias",
  "response_model": "resolved_model_version",
  "prompt_version": "support_reply_v12",
  "attempt_number": 1,
  "streaming": true,
  "status": "completed",
  "validation_status": "passed"
}

确切的供应商响应可能使用不同的名称。在边界处标准化这些字段，这样下游仪表板就不需要针对每个提供商分别查询。

OpenTelemetry 为 span、metric 和 event 维护 生成式 AI 语义约定。在适用的地方使用它们，但也要为内部遥测契约进行版本管理。语义约定可能会演进，而事故查询和历史对比必须始终保持可理解。

将有界维度与高基数证据分开

指标需要有界标签。好的维度包括：

• environment
• feature
• provider
• model_family
• route_policy
• status
• error_type
• validation_status

将请求 ID、trace ID、提供商请求 ID、用户 ID、prompt 指纹和错误消息保存在 trace 或日志中，而不是指标标签中。否则，单个部署就可能创建数百万条时间序列，并使监控系统变得比它所观察的应用更慢或更昂贵。

明确决定隐私模式

不要默认捕获原始 prompt。定义一个字段级策略，至少包含三种模式：

OWASP Logging Cheat Sheet 建议排除或保护敏感数据，例如访问令牌、密码和个人信息。将同样的原则应用于 AI 遥测：绝不要假设可观测性后端就是合适的 prompt 存档。

步骤 1 退出标准

• 存在一个用于请求、尝试、校验和成本事件的版本化 schema。
• 重试和回退使用独立的 attempt_id 值。
• 指标标签有上限限制。
• 提示词和输出捕获具有明确的隐私模式。
• 特定于提供商的字段映射到稳定的内部字段。
• 已分配 schema 所有权和变更评审。

步骤 2：埋点完整请求路径，而不是只埋一个 SDK 调用

Trace 应从面向用户的操作开始，并持续经过检索、路由、每次模型尝试、校验、工具执行和持久化。只埋最终的 SDK 调用会隐藏导致大多数生产事故的决策。

一个有用的 span 层级如下：

POST /assistant/run
├── load_context
├── select_route
├── model_attempt 1
│   ├── stream_first_token
│   └── tool_call weather_lookup
├── validate_output
├── model_attempt 2 fallback
│   └── stream_first_token
└── persist_result

按组件记录延迟

单一的端到端耗时无法区分网络延迟、提供商生成时间、排队、校验或工具执行。至少应捕获：

• 用户可见总耗时
• 网关或队列延迟
• 提供商尝试耗时
• 流式响应的首个 token 时间
• 首个 token 与最后一个 token 之间的时间
• 校验耗时
• 工具调用耗时

对于流式传输，请明确定义首个 token 时钟。如果该指标旨在代表用户体验，那么应在你的服务接受请求时开始计时，而不是在路由完成之后。

让重试和回退可见

经过三次尝试后成功的响应，并不等同于第一次就成功。每次尝试发出一个 span，并包含：

• 尝试次数
• 重试或回退原因
• 上一个错误类别
• 退避时长
• 所选提供商和模型
• 熔断器状态
• 是否发出了任何部分内容

部分流式输出需要特别注意。如果字节已经到达客户端，悄悄将请求重放到另一个模型可能会重复内容或产生不一致的工具操作。Trace 应展示系统是停止、协调还是继续。使用 LLM API 回退路由实战手册 在启用自动故障转移之前定义该行为。

从规范化事件中发出指标

基于规范化的请求和尝试记录生成指标，而不是在每个集成中添加一次性计数器。最小指标集如下：

ai_requests_total
ai_attempts_total
ai_request_duration_seconds
ai_time_to_first_token_seconds
ai_input_tokens_total
ai_output_tokens_total
ai_validation_failures_total
ai_fallbacks_total
ai_estimated_cost_usd_total

提供商的 usage 对象可能不同，尤其是缓存 token 或推理 token。必要时，应将原始 usage 对象保存在受限的诊断存储中，但把跨提供商报告所需的字段映射到通用成本记录中。

步骤 2 退出标准

• 一次 trace 将产品操作连接到每一次模型尝试。
• 首个 token 和端到端延迟都有明确记录的开始点和结束点。
• 重试、回退和熔断器决策都是可见的。
• 工具调用具有子 span 和结果字段。
• 指标基于标准化、版本化的事件生成。
• 负载测试确认遥测不会造成不可接受的延迟或基数膨胀。

步骤 3：验证应用成功并核对成本

传输成功只是健康状况的一层。AI 响应可以返回 HTTP 200，但仍然因为空、格式错误、被拒绝、不受支持或执行不安全而未满足产品契约。

定义已验证成功的状态机

使用显式状态，而不是单一布尔值：

received
→ transport_succeeded
→ parsed
→ contract_validated
→ business_rule_validated
→ accepted

失败应在正确的阶段停止，例如：

transport_failed
parse_failed
schema_failed
tool_policy_failed
business_rule_failed
cancelled
timed_out

这使团队能够区分供应商可用性和应用质量。你的主要可靠性分母通常应是已接受的用户操作，而不是原始供应商响应。

先添加确定性验证器

在构建主观的模型评分之前，先实现能够产生可复现结果的检查：

• JSON 或 schema 解析
• 必填字段存在性
• 允许的工具名称和参数类型
• 当功能需要引用时，引用是否存在
• 拒绝状态处理
• 输出长度和格式限制
• 业务规则，例如有效的 ID、日期、货币或枚举值

将采样的离线评估与生产遥测通过稳定的 sample ID 关联起来。不要在指标标签中放入无限增长的评估文本。对于模型变更，使用可重复的 多模型提示测试工作流，这样就能将延迟和成本与已接受输出率一起比较。

计算每个已接受任务的成本

每次请求的 token 成本很有用，但每个已接受任务的成本才是更好的运营衡量指标：

cost_per_accepted_task =
  total_cost_of_all_attempts / accepted_user_operations

分子中应包括失败尝试、重试、回退和被拒绝的输出。否则，可靠性问题会表现为无法解释的利润率侵蚀。

维护两种成本状态：

1. 估算成本：根据响应使用量和版本化价格表立即计算。
2. 核对后的成本：在可用时，稍后根据供应商账单或使用量导出进行更新。

为每个估算存储 price_version 或所用的生效时间戳。若没有这些信息，在价格更新后，历史成本变化将无法解释。有关财务和运营设计，请参阅 AI API 支出管理指南。

步骤 3 退出标准

• 已接受的成功与 HTTP 成功是分开的。
• 确定性验证器覆盖关键产品契约。
• 评估样本可以与生产请求关联。
• 成本包括每一次尝试，包括被拒绝的输出。
• 估算成本和对账后的成本是不同的字段。
• 价格版本会被保留用于历史分析。

步骤 4：围绕用户结果设定 SLO 和告警

告警应描述用户伤害或快速变化的运营风险。单个提供方错误并不一定会伤害用户，只要回退能在延迟预算内成功。相反，即使提供方完全可用，也可能产生不可用的结果。

从四个服务级指标开始

按功能和风险等级设定目标。同步编码助手、后台文档分类器和支付支持工作流不应共享相同的延迟或验证目标。

使用消耗速率和变更告警

静态阈值会产生噪声。将它们与时间窗口和基线配对：

• 快速消耗：验证成功率在 5–15 分钟内明显下降。
• 慢速消耗：错误预算在数小时内耗尽。
• 变更告警：在部署或路由策略更新后，首次尝试成功率下降。
• 成本异常：在流量保持稳定时，每个已接受任务的成本上升。
• 路由异常：回退占比或提供方组合意外变化。
• 质量异常：模式、工具策略或业务规则失败超过基线。

每个告警都应链接到首个诊断视图，显示部署版本、路由策略、提供方、模型、错误类别、验证阶段、重试次数和成本差异。

在值班呼叫前编写运行手册

对于每个告警，定义：

1. 由谁负责。
2. 它意味着什么用户影响。
3. 首先打开哪个查询或追踪视图。
4. 检查哪些最近的变更。
5. 允许采取哪种安全缓解措施：回滚、禁用某条路由、降低并发、打开熔断器，或切换到已验证的回退方案。
6. 什么证据可以关闭事件。

步骤 4 退出标准

• SLO 按功能或风险等级定义。
• 验证成功率和首次尝试成功率都可见。
• 告警使用时间窗口、基线或错误预算消耗。
• 成本和回退异常有专门告警。
• 每个告警都链接到运行手册和首个诊断查询。
• 在值班演练期间测试告警归属。

步骤 5：通过治理推广可观测性

仪表化是一项生产环境变更。应逐步推出，测量其开销，并让数据生命周期成为实施的一部分，而不是后续才补充的策略。

采用分阶段发布

1. 本地和测试：使用合成提示验证字段名称、父子跨度、脱敏和校验器。
2. 影子遥测：发送生产形态的事件，但不触发告警，也不影响路由决策。
3. 小规模金丝雀：为一部分受限的生产流量启用遥测，并检查基数、摄取成本和追踪完整性。
4. 功能发布：按产品功能或路由逐步扩大，而不是一次覆盖所有工作负载。
5. 运营启用：仅在存在基线数据和运行手册之后，再启用 SLO 报告和告警。

在金丝雀阶段测量遥测开销。应包括客户端批处理、导出器失败、队列压力，以及可观测性后端不可用时会发生什么。模型请求不应因为非关键遥测导出器故障而失败。

管理保留和访问

按数据类别定义保留策略：

• 聚合指标通常可以保留更久。
• 请求元数据应有文档化的运营保留期限。
• 脱敏样本应采用更短的保留时间和更窄的访问范围。
• 原始提示或输出如果被允许存在，则需要明确用途、加密、审计日志、删除行为和事件处理流程。

确保 API 密钥和供应商凭证不进入任何遥测路径。遵循一种安全 API 密钥管理模式，将密钥存放在服务器端，并防止将请求头或环境变量序列化到事件中。

将 schema 和仪表板视为代码

将遥测 schema、校验器规则、SLO 定义、仪表板和告警与应用一起版本化。路由策略变更应在同一版本发布中同时更新实现和可观测性。

为以下内容指定负责人：

• Schema 演进
• 脱敏规则
• 成本定价表
• 校验器版本
• 仪表板正确性
• 告警调优
• 数据保留和访问审查

步骤 5 退出标准

• 影子和金丝雀阶段已完成，且没有不安全的提示捕获。
• 已测试遥测开销和导出器失败行为。
• 按数据类别记录了保留和基于角色的访问。
• 已排除密钥和授权请求头。
• Schema、校验器、仪表板和告警已纳入版本控制。
• 有指定负责人在模型或路由更新后审查遥测变更。

AI 可观测性 30 天发布计划

该计划是刻意按顺序推进的。如果在最后一周期间遥测契约发生变化，请暂停告警激活并先修复 schema。基于不一致数据进行分页告警会产生虚假的信心。

常见实施错误

将 HTTP 200 视为成功

修复： 在操作变为 accepted 之前，先进行解析、契约、工具策略和业务规则验证。

把重试隐藏在一个模型 span 中

修复： 每次尝试都创建一个子 span 和一条成本记录。保留重试或回退的原因。

默认记录每个 prompt

修复： 默认只保留元数据遥测。仅针对明确的用例添加经过抽样、脱敏的内容。

使用请求 ID 作为指标标签

修复： 将高基数标识符保留在追踪和日志中。指标使用有界维度。

在没有价格版本的情况下估算成本

修复： 为每个估算附加价格表版本或生效时间戳，并在之后进行核对。

在没有用户上下文的情况下对提供商错误发出告警

修复： 针对已验证成功、延迟、错误预算消耗和不安全的成本变化进行分页告警。除非提供商错误导致用户影响，否则将其用作诊断信息。

常见问题

什么是 AI 可观测性？

AI 可观测性是通过指标、追踪、结构化事件、验证结果、路由决策、令牌使用和成本，将模型请求与应用结果连接起来的实践。它扩展了普通 API 监控，因为一次 AI 请求在技术上可能成功，但对产品而言却不可用。

AI 可观测性仪表板应包含什么？

从已验证成功率、首次尝试成功率、端到端延迟、首个 token 时间、重试和回退占比、验证失败、令牌使用量以及每个已接受任务的成本开始。添加提供商和模型视图用于诊断，但保持主仪表板与面向用户的功能对齐。

是否应该记录 prompt 和模型输出？

默认不应如此。正常生产运行应使用仅元数据遥测。如果确实需要内容样本，请应用脱敏、抽样、加密、短期保留、访问控制和明确用途。绝不要记录密钥或授权头。

如何监控流式 AI 响应？

衡量首个 token 时间、从首个到最后一个 token 的时间、取消状态、输出的字节数或 token 数，以及在失败之前部分内容是否已到达用户。在流式传输开始后，为重试和回退定义安全行为。

如何监控 AI API 成本？

在可用时记录输入、输出、缓存及其他由提供商报告的使用情况；使用版本化价格表计算即时估算；并将其与提供商账单数据进行核对。按已接受的任务跟踪成本，以便失败尝试和被拒绝的输出仍然可见。

应在何处埋点多模型网关？

同时对应用操作和网关进行埋点。应用知道输出是否有用；网关知道是哪个模型、提供商、路由、重试、回退和使用记录生成了该输出。使用共享的请求和 trace ID 将两层关联起来。

将检查清单付诸实践

实现有用的 AI 可观测性的最快路径，不是安装更多仪表板，而是就什么构成一次成功的用户操作达成一致，追踪为此贡献的每一次尝试，并让质量、成本和路由决策在同一条证据链中可见。

Flatkey 通过一个 API 密钥和端点，提供通往多个 AI 模型的 OpenAI 兼容路径。如果你的团队正在评估多模型架构，请先查看 Flatkey 集成指南，然后将这份检查清单应用到第一个生产功能。在定义成本基线和回退路由之前，你也可以先查看 当前的模型访问与定价。