Reliability and Routing2026年6月22日Big Y

AI API 可观测性日志：模型路由事件中应记录哪些内容

使用 AI API 可观测性日志，通过请求 ID、路由、重试、回退、token、延迟、成本和隐私安全元数据来排查模型路由事件。

AI API 可观测性 是让工程团队无需猜测就能重建一次模型路由故障的关键。用户报告超时，备用模型给出了不同答案，某个提供商返回 429，或者在上游切换后支出激增。事故复盘需要的不只是原始提示词和状态码。它需要一条日志记录，展示请求、路由、重试链、所选模型、延迟分布、使用量、成本，以及围绕已存储内容的隐私控制。

本指南是一份面向路由故障中 AI API 可观测性 日志的字段级清单。它面向使用 AI 网关、多提供商路由器或兼容层的团队，在这些场景中，一个应用请求可能会经过多个可能的上游路径。目标不是永久保存每一个提示词。目标是在控制敏感输入、输出、工具参数和客户标识符的同时，保留足够的元数据来证明发生了什么。

Flatkey 适合这个问题，因为其公开产品文案围绕一个 API 密钥、一个位于 https://router.flatkey.ai/v1 的 OpenAI 兼容 base URL、统一计费，以及用于管理密钥、用量和路由的单一仪表板。Flatkey 还提到了在上游账户之间自动切换和负载均衡。只有当日志能够在事后回答路由问题时，这些才是有价值的可靠性功能。

AI API 可观测性始于事故问题

在选择字段之前，先定义事故指挥官必须回答的问题。对于模型路由，AI API 可观测性应该让这些问题能够从一条请求记录或一条关联追踪中得到答案：

是哪个应用、环境、团队、密钥、工作流和客户可安全识别的负责人发送了请求？
请求时生效的是哪个端点族、请求的模型、路由策略和回退规则？
实际上是哪个提供方、模型、上游账户或路由返回了响应？
请求是否被重试、切换、限流、排队、阻止或中止？
是哪个状态码、提供方错误类别、限流响应头、超时或流事件改变了结果？
统计了多少输入、输出、缓存和推理 token，路由成本是多少？
隐私控制存储的是原始载荷、脱敏载荷、仅元数据，还是不记录日志？

如果日志无法回答这些问题，团队就会用 Slack 记忆、截图和提供方支持工单来补齐空缺。这会减慢修复速度，并让未来的路由变更更难以信任。

模型路由事件日志清单

下表是本文的核心 AI API 可观测性 资产。可将其作为 LLM API 日志、网关日志或数据仓库事件的实施清单。

字段组	要捕获的字段	在路由事件中为何重要	隐私说明
关联 ID	应用请求 ID、`X-Client-Request-Id`、提供方 `x-request-id`、W3C `traceparent`、网关日志 ID、事件 ID。	将面向用户的错误、网关决策、提供方请求、跟踪跨度和支持工单关联起来。	使用不透明 ID。不要将电子邮件、IP、租户名称或提示文本编码到跟踪字段中。
租户和所有者	项目、环境、API 密钥 ID 或哈希、团队、工作流、客户安全账号 ID、成本中心。	显示受影响的是谁，以及谁负责配额、成本和修复。	优先使用稳定的内部 ID，而不是原始客户名称或用户电子邮件。
请求的路由	端点族、请求的模型、提供方偏好、路由策略、回退策略、模型别名版本、目录/定价版本。	重建客户端请求了什么，以及当时路由器被允许执行什么操作。	除非已启用单独批准的调试模式，否则不要将提示放入路由对象中。
选定的路由	最终提供方、最终模型、上游账号或通道、相关时的区域、路由决策原因、策略规则 ID。	证明主模型是否提供了响应，或回退路径是否改变了行为或成本。	账号标识应为内部引用，而不是提供方密钥或完整凭据。
重试和回退链	尝试索引、重试次数、先前提供方/模型、失败类别、状态码、回退目标、最终结果。	防止盲目重试，并展示故障转移层是否按设计运行。	存储错误类别和安全摘录。若完整提供方错误正文可能回显提示内容，则不要存储。
延迟和流式传输	请求开始时间、网关耗时、提供方耗时、首个 token/块耗时、流已开始、流已完成、中止原因、客户端断开连接。	区分提供方延迟、网关路由时间、流式阻塞和客户端侧取消。	流式块属于内容。默认记录时间元数据，仅在受管控的调试模式下记录内容。
用量和成本	输入 token、输出 token、缓存 token、推理 token、相关时的图像/视频单元、请求数、条目、估算或最终成本。	说明当回退将流量切换到其他提供方、模型或服务层级时，对预算的影响。	常规仪表板按密钥、工作流和团队聚合；限制按用户查看。
响应形态	结束原因、工具调用 ID/名称、输出类型、响应状态、截断或不完整详情、服务层级。	显示模型是正常停止、调用了工具、遇到限制，还是返回了不完整响应。	工具参数和工具结果可能包含敏感数据。默认存储 ID 和名称。
错误和速率限制	HTTP 状态、提供方错误代码、超时类别、重试后等待时间、剩余/限制/重置请求头、剩余/限制/重置 token 请求头。	区分错误请求、认证失败、提供方事件、配额耗尽和速率限制风暴。	在放入广泛使用的分析工具之前，将提供方错误规范化为安全类别。
治理和保留	DLP 操作、策略 ID、内容日志模式、脱敏标志、载荷哈希、保留类别、删除资格。	让安全和合规能够验证内容为何被存储、脱敏、阻止或排除。	当原始内容不是已定义支持或审计工作流所必需时，默认仅记录元数据。

在调试提供方之前先捕获 ID

AI API 可观测性 的首要任务是关联。OpenAI 的 API 参考建议在生产环境中记录请求 ID，并记录提供方生成的 x-request-id 值以及调用方提供的 X-Client-Request-Id 值。后者在超时或网络故障导致客户端无法收到提供方响应头时尤为重要。

对于网关来说，还要再加一层：一个能在内部重试和回退中保持不变的网关请求 ID。如果某个用户请求先尝试提供方 A，再尝试提供方 B，最后使用备用模型，那么网关 ID 应该将所有尝试绑定在一起。提供方请求 ID 应保持为每次尝试专用。Trace ID 应将这次 AI 调用与应用请求的其余部分绑定起来。

W3C Trace Context 定义了 traceparent 和 tracestate，用于在服务之间传播分布式追踪上下文。请使用这些头部进行追踪关联，而不是客户身份。W3C 的隐私部分表述得很明确：追踪字段不得携带个人可识别信息或其他敏感信息。

分别记录请求路由和选定路由

AI 网关监控中的一个常见错误是只记录最终的提供商和模型。这会丢失最重要的路由证据：客户端请求了什么，以及网关做出决策之前策略允许了什么。

请将这两个对象分开保留：

请求路由：端点家族、请求的模型或别名、路由策略、提供商偏好、回退策略、目录版本、定价版本，以及流式或批处理等请求模式。
选定路由：最终提供商、最终模型、上游账户或通道、相关时的区域、路由决策原因，以及策略规则 ID。

当回退响应有效但出人意料时，这种拆分就很重要。如果请求路由是启用了流式传输的 chat/completions，而在超时后选定路由切换到了另一个模型，事件复盘就能看到预期路径和实际路径。它还有助于财务部门理解为什么用量会出现在不同的模型或费用条目下。

Flatkey 采购方也应采用同样的评估模式。先从 AI API 网关需求清单开始，然后使用负载均衡与故障切换操作手册来定义在查看日志之前允许哪些路由变更。

记录重试与回退链

重试是完整日志变得昂贵的地方。如果唯一存储的字段是最终状态和最终模型，团队就无法判断一次请求是第一次尝试就成功，还是在一次重试后成功，或是在跨供应商的五次尝试后才成功。事件级的AI API 可观测性将重试和回退视为一条链。

每次尝试都应包含：

尝试索引和父网关请求 ID。
该次尝试的供应商、模型、上游账户和端点家族。
开始时间、持续时间、超时类别和流式状态。
状态码、供应商错误类别、供应商请求 ID 和限流元数据。
当该次尝试未结束整条链时的回退目标和决策原因。

这条链可防止网关掩盖真实故障模式。格式错误的请求应该直接失败，而不是在各个供应商之间循环。供应商返回 500 可能值得重试一次。配额限制可能切换到已批准的上游账户。面向客户的模型不匹配可能需要受控错误，而不是静默回退。

测量流式响应的延迟，而不仅仅是已完成的调用

流式响应需要的不只是总时长。Vercel 的 AI Gateway 可观测性文档指出，首个 token 的时间、请求持续时间、token 数量和花费都是网关指标。OpenTelemetry 的 GenAI 语义约定包括 gen_ai.response.time_to_first_chunk 和 gen_ai.request.stream。这些字段很有用，因为许多路由故障其实是流式故障：提供方接受了请求，但首个片段来得很晚，流被卡住了，或者客户端断开了连接。

至少记录请求开始时间、网关持续时间、提供方持续时间、首个 token 或片段的时间、流已开始标志、流已完成标志、中止原因以及客户端断开状态。对于非流式响应，同样的字段可以保持为 null 或 false。这样可以在 Chat Completions、Responses 以及提供方特定的端点家族之间保持一套统一的模式。

默认不要存储流片段。流片段属于响应内容，而响应内容可能包含用户数据、检索到的上下文、工具结果或受监管信息。对于常规的 AI API 可观测性，时间元数据通常就足以诊断卡顿。

将使用量和成本连接到路由决策

使用量和成本是事故字段，不只是财务字段。OpenAI 的 Responses API 示例包括输入、输出、缓存、推理和总 token 使用量。OpenAI 的组织使用情况端点支持按项目、用户、API 密钥、模型、批处理和服务等级分组；成本端点支持按项目、明细项和 API 密钥分组。Vercel 的 AI Gateway 文档同样描述了按项目和 API 密钥汇总的请求、token 计数、P75 持续时间、P75 TTFT 和成本。

对于 AI API 可观测性，尽可能在尝试级别捕获使用量和成本，并始终在最终请求级别捕获。回退可能在运维上是正确的，但在财务上会出人意料。若同一事件中没有模型、路由、使用量和成本，财务可能会先看到支出激增，而工程团队还来不及解释。

Flatkey 的公开定价和主页文案指向清晰定价、统一计费、使用分析，以及用于密钥、使用量和路由的仪表板。为此任务保存的一份 2026 年 6 月 18 日定价快照返回了 638 行模型记录、23 个供应商，以及包括 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages、Gemini generateContent、图像生成和 OpenAI video 在内的端点系列。请将这些计数视为带日期的证据，然后验证 live pricing page 和仪表板记录，以确认你的工作流中具体模型的情况。

默认使用仅元数据日志

原始提示词和响应是强大的调试工具，但它们也是有风险的日志。Cloudflare 的 AI Gateway 日志文档是一个很有参考价值的模式：它们描述了包含提示词、响应、提供商、时间戳、状态、令牌使用量、成本、持续时间和用户代理的请求日志，并且还记录了一个标头，该标头可以在保留元数据（例如令牌计数、模型、提供商、状态码、成本和持续时间）的同时，禁止存储原始请求和响应正文。

对于 LLM API 日志来说，这才是正确的默认姿态：默认收集元数据，然后在存储原始内容之前，要求显式进入调试模式或支持流程。OpenTelemetry GenAI 语义约定将输入消息、输出消息、系统指令、工具调用参数和工具调用结果标记为可能包含敏感信息的字段。你的日志策略也应该体现这一点。

一个实用的策略包含四种模式：

不记录日志：用于不得在瞬时处理之外保留的请求。
仅元数据：路由、ID、延迟、状态、用量、成本和脱敏标志。
脱敏载荷：在移除 PII 和密钥后保留的选定请求/响应字段。
原始载荷：针对特定事件或经客户批准的支持案例，进行短期、受访问控制的调试捕获。

示例路由日志事件

此模板有意采用“元数据优先”的方式。请根据你的日志系统调整字段名称，但要保留“请求路由、选定路由、尝试、用量、成本和隐私控制”之间的分离。

{
  "gateway_request_id": "gw_01jz_route_abc",
  "app_request_id": "req_9a7c",
  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "client_request_id": "7c2c1b3a-4b55-4e36-bd47-8d1c2e2f2e11",
  "owner": {
    "project": "checkout-ai",
    "environment": "production",
    "api_key_id": "key_hash_6f12",
    "team": "platform",
    "workflow": "customer-chat"
  },
  "requested_route": {
    "endpoint_family": "chat_completions",
    "model": "primary-chat-model",
    "stream": true,
    "route_policy_id": "chat-prod-v8",
    "fallback_policy_id": "chat-prod-safe-fallback-v3",
    "catalog_version": "2026-06-18"
  },
  "selected_route": {
    "provider": "provider_b",
    "model": "backup-chat-model",
    "upstream_account": "acct_pool_2",
    "decision_reason": "primary_timeout",
    "policy_rule_id": "fallback_on_timeout_once"
  },
  "attempts": [
    {
      "index": 1,
      "provider": "provider_a",
      "model": "primary-chat-model",
      "provider_request_id": "req_provider_a_123",
      "status_code": 504,
      "error_class": "timeout",
      "duration_ms": 12000,
      "fallback_target": "provider_b"
    },
    {
      "index": 2,
      "provider": "provider_b",
      "model": "backup-chat-model",
      "provider_request_id": "req_provider_b_456",
      "status_code": 200,
      "duration_ms": 2400,
      "time_to_first_chunk_ms": 620,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "input_tokens": 1284,
    "output_tokens": 312,
    "cached_input_tokens": 0,
    "reasoning_output_tokens": 0
  },
  "cost": {
    "currency": "usd",
    "estimated_amount": 0.0048,
    "line_item": "backup-chat-model"
  },
  "privacy": {
    "content_logging_mode": "metadata_only",
    "payload_redacted": true,
    "retention_class": "30_day_incident_metadata"
  }
}

这些字段名称只是示例，不是 Flatkey API 合同。可用它们来测试你的网关、数据仓库和事件处理工具是否能够在不需要原始内容的情况下回答路由相关问题。

10 分钟分诊工作流

当模型路由事故开始时，AI API 可观测性工作流应该足够简短，让值班工程师能在压力下完成：

查找关联请求：按应用请求 ID、网关请求 ID、用户可见错误 ID、提供方请求 ID 或 trace ID 搜索。
比较请求的路由与选定的路由：确认请求的模型、路由策略、回退规则、最终提供方和最终模型。
读取尝试链：识别首次失败、重试次数、回退目标和最终结果。
检查限流和配额上下文：当提供方返回 429 或出现 token 压力时，查看 remaining、limit 和 reset 头信息。
区分延迟与流式传输：比较网关耗时、提供方耗时、首个 chunk 到达时间、流结束时间和客户端断开连接时间。
核对使用量和成本：查看 token 数量、服务层级、成本条目以及团队/密钥归属。
审查隐私模式：确认日志是仅元数据、已脱敏、原始，还是有意省略。
决定路由操作：回滚策略、禁用路由、降低流量权重、提高配额、排队后台工作，或在失败时关闭。

事故结束后，把同样的步骤转化为仪表盘视图。最快的审查发生在工程、支持和财务都能检查同一种事件结构时。

Flatkey 如何契合 AI API 可观测性

Flatkey 的定位是面向那些希望拥有一个 API key、一个兼容的路由端点、清晰的定价、统一的计费，以及一个用于查看 key、用量和路由的仪表板的团队。对于本文而言，相关的验证路径很实际：将一个预生产客户端指向 https://router.flatkey.ai/v1，通过一个非生产 key 发送请求，在可行的情况下触发受控故障，并确认仪表板中出现了哪些用量、路由、错误和成本记录。

使用按 key 的 AI 用量跟踪来区分预生产、生产、客户和工作流流量。使用 AI API 配额管理来避免回退机制消耗共享预算。当路由变更需要财务负责人时，使用按团队归因 AI API 成本。

行动号召很简单：如果你的团队想在一个 key 之下测试 AI API 可观测性，获取一个 key，通过 Flatkey 运行一条预生产路由，并在依赖生产环境中的自动切换之前，检查日志是否回答了上面的事故问题。