多模型 API 网关中的 LLM 可观测性：跟踪、令牌分类账、租户分析和安全提示日志记录

当客户询问为什么某个工作流程昨天变得更慢、更昂贵或不太可靠时，合计请求计数和每月支出是不够的。如果多模型 API 网关将可观察性视为控制平面的一部分，则可以回答这个问题：每个请求都会得到跟踪，每个模型调用都会更新使用分类账，每个租户和工作流程都有归属，并且敏感内容默认受到保护。

本文介绍了网关中AI 使用分析和 LLM 可观测性的实用设计，该网关通过 OpenAI 兼容的 API 面向多个提供商。即使您不使用任何特定供应商，该模式也很有用：在网关处进行一次检测，标准化模型遥测，保留计费归属，并仅在明确的策略下捕获提示内容。

阅读器问题：“哪个租户、模型、提示或检索路径导致了更改？”

大多数团队最终都会面临同样的调试差距。应用程序日志显示某个功能失败。提供商仪表板显示令牌使用量有所增加。财务看到账单。这些视图本身都无法解释从租户请求到模型调用再到检索上下文以重试计费成本的完整路径。

目标不是另一个具有总代币的仪表板。目标是回答以下操作问题：

• 哪个租户或 API 密钥导致支出激增？
• 更改模型别名后延迟是否会增加？
• 重试或回退是否会造成重复计算成本？
• 哪个提示版本消耗的错误预算最多？
• RAG 工作流程是否会因为检索添加了太多上下文标记而变得昂贵？
• 是否可以支持在不阅读私人用户提示的情况下调试事件？

事实、建议和预测

事实： OpenTelemetry 记录了模型操作的生成式 AI 语义约定和属性，包括 chat、generate_content 和 text_completion 等操作名称。该文档警告 GenAI 输入和输出消息属性可能包含敏感信息或 PII，并且可能需要过滤或截断。主要模型提供商还公开可以支持提供商端协调的使用仪表板、API 或导出，尽管详细信息因提供商而异。

建议：使用 OpenTelemetry 进行与提供商无关的跟踪，但将网关拥有的业务维度保留在您自己的属性和分类帐中。默认情况下不存储原始提示或输出。首先存储元数据、哈希值、令牌计数、提示模板 ID、模式名称、错误类和安全标签。仅将内容捕获添加为选择加入、访问控制、短期保留调试功能。

预测：LLM 可观察性将不再是关于孤立的提供商仪表板，而是更多关于跨提供商控制平面。团队希望有一个地方可以调查跨模型的延迟、成本、质量、策略事件、租户行为和计费增量。

参考架构：观察整个请求路径

网关可以查看完整的请求生命周期，而不需要每个应用程序团队构建自定义遥测。有用的跟踪模型从一个用于传入客户请求的父范围和一个用于影响成本、延迟和质量的步骤的子范围开始。

推荐的跨度结构

• 网关请求范围：请求已接受、经过身份验证、授权、速率限制和路由。
• 模型调用范围：提供商、模型、操作、令牌使用、响应状态和延迟。
• 检索跨度：查询的索引、文档 ID 或哈希 ID、块计数、检索延迟和上下文令牌共享。
• 工具调用范围：工具名称、状态、延迟、错误类别和副作用分类。
• 重试跨度：重试原因、尝试次数、提供商状态和增量成本。
• 后备跨度：原始模型、后备模型、触发器、兼容性政策和最终结果。
• 护栏或审核范围：调用的策略、决策、标签以及输出是否被阻止或转换。
• 后处理范围：JSON 验证、架构修复、引文检查或最终格式化。

父跨度应携带稳定的相关标识符。子跨度应具有标准化的技术属性。使用分类账应该包含持久的计费和分析记录。避免将所有信息强行放入指标标签中；高基数值（例如租户 ID、提示哈希值和文档 ID）最好存储在跟踪、日志或分类帐表中，然后聚合到仪表板中。

标准化每次 LLM 调用中捕获的元数据

无论提供商如何，每个模型请求都应生成一致的记录。确切的架构会有所不同，但实际的最低限度如下所示：

<前><代码>{ "request_id": "req_01J...", “trace_id”：“4bf92f3577b34da6a3ce929d0e0e4736”， “tenant_id”：“tenant_123”， "team_id": "team_456", "app_id": "support_bot", "gateway_key_id": "key_789", "操作": "聊天", “提供商”：“提供商名称”， “模型”：“提供商模型 ID”， "model_alias": "快速支持聊天", "prompt_template_id": "refund_policy_v5", "prompt_hash": "sha256:...", "response_schema": "support_answer_v2", “状态”：“已完成”， “错误类”：空， “延迟_毫秒”：1842， “输入令牌”：2110， “输出令牌”：384， “缓存输入令牌”：1200， "estimated_cost_usd": "0.00492", “final_billed_cost_usd”：空， "finish_reason": "停止", “重试次数”：0， “fallback_used”：假， “content_capture_policy”：“仅元数据” }

将两个想法分开：遥测解释发生了什么，而使用分类帐记录应该收费、核对和报告的内容。它们通过请求 ID 和跟踪 ID 互相引用，但它们不必位于同一存储系统中。

构建代币和成本分类账，而不仅仅是计数器

令牌计数器对于图表很有用，但不足以用于计费或事件调查。账本应该代表状态转换。当网关接受请求时创建一行，然后随着请求的进展更新它。

有用的账本状态

• 已接受：已通过身份验证和策略检查。
• 转发：请求已发送至提供商。
• 流式传输：提供商开始返回令牌。
• 已完成：响应成功完成。
• user_aborted：客户端在完成之前断开连接。
• 重试：已进行额外的提供商尝试。
• fallback_used：失败或策略匹配后选择了不同的模型或提供商。
• 失败：请求结束，没有可用的响应。
• 协调：比较并应用提供商方的使用情况或成本数据。

此状态模型有助于捕获常见的计费和分析错误：客户端断开连接时的流式响应、由提供商收费但对用户隐藏的重试尝试、计算错误模型的回退路径以及缓存提供商之间的会计差异。

使用 OpenTelemetry GenAI 约定，然后小心扩展

OpenTelemetry GenAI 语义约定为模型操作提供了可移植的词汇表。将这些约定用于常见属性，例如操作名称、提供程序、模型、请求参数、响应完成原因、令牌使用情况以及适用的错误状态。

但是，提供商中立的约定不会涵盖网关中的每个业务维度。添加网关拥有的属性或分类帐列：

• 租户 ID、团队 ID、经销商客户 ID 和应用 ID；
• 网关 API 密钥 ID 和密钥范围；
• 结算计划、支出限额和预算政策；
• 模型别名和路由策略版本；
• 提示模板 ID 和提示版本；
• 工作流程名称和工作流程步骤；
• 预计费用、最终计费费用和对帐状态。

权衡是基数。这些字段对于调查很有价值，但如果在任何地方用作指标标签，它们可能会使指标变得昂贵且嘈杂。一个实用的规则是：低基数聚合转到度量；高基数标识符进入跟踪、日志和分类账。

设计安全提示和输出日志记录

完整的提示日志记录使调试更加容易，但它增加了隐私、合规性、存储和内部风险暴露。更安全的默认设置是元数据优先的可观察性。

默认：仅元数据

对于大多数生产流量，存储：

• 提示模板 ID 和版本；
• 规范化提示和输出的哈希值；
• 输入、输出、缓存和上下文令牌计数；
• 响应架构名称和验证结果；
• 安全标签和政策决定；
• 错误摘要和提供程序错误类别；
• 检索元数据，而不是原始文档。

选择加入：受控内容捕获

如果您需要原始或经过编辑的内容进行深度调试，则需要明确的策略。良好的控制包括环境许可名单、租户同意、采样、最大有效负载长度、自动编辑、短保留窗口、加密、基于角色的访问、审核日志以及敏感事件的打破玻璃批准路径。

不要将密文视为完美。它降低了风险；它并没有消除它。对于受监管或高敏感度的工作负载，请考虑仅存储哈希值并在具有批准的测试数据的综合工具中重放问题。

将 RAG 可观察性添加为单独的层

检索增强生成可以改变质量和成本。当检索器返回太多块、陈旧文档或不相关上下文时，仅记录最终模型调用会隐藏根本原因。

对于每个检索步骤，捕获：

• 索引或集合名称；
• 检索策略和嵌入模型；
• 文档 ID 或哈希 ID；
• 块计数和总上下文标记；
• 检索延迟；
• 最高分分布（如果有）；
• 引文覆盖率；
• 最终答案中是否使用了检索到的上下文。

这可以让您区分“模型变得更糟”和“检索器开始发送低质量或过多的上下文”。它还有助于识别上下文令牌在总成本中占主导地位的工作流程。

协调网关使用情况与提供商计费

网关估算可立即提供。提供商端的计费数据通常较慢但更权威。两者都使用。

每日对账作业应将网关分类帐行与提供商使用 API、成本 API、仪表板导出或发票导出进行比较。按提供商、模型、项目和时间窗口对增量进行分组。分别跟踪输入令牌、输出令牌、缓存令牌、请求计数和成本的差异。

常见的调节差异

• 流式传输断开连接：网关可能会发现客户端已中止，而提供商仍在对生成的令牌进行计费。
• 重试：即使只返回一次最终响应，多次尝试也可能需要付费。
• 提示缓存：提供商可能会以不同方式公开缓存令牌记账。
• 舍入：每个请求的微小差异可能会在规模上变得明显。
• 批量或分级折扣：提供商发票可能会应用实时估算尚不知道的定价。
• 提供商端变更：模型定价、代币化行为或计费导出可能会随着时间的推移而发生变化。

当对账发现增量时，请避免默默地覆盖您的分类账。存储原始估算、提供商调节值、调节源以及原因代码（如果已知）。

回答操作问题的仪表板

从读者问题开始仪表板，而不是虚荣指标。有用的视图包括：

• 每个租户、团队、应用和工作流程的成本；
• 每个成功任务的成本，而不仅仅是每个请求的成本；
• 按提供商、型号和型号别名划分的 p50、p95 和 p99 延迟；
• 按路线划分的回退率和重试率；
• 超时率和提供商错误类别趋势；
• 缓存命中率和缓存令牌节省估算；
• 结构化输出验证失败率；
• 按错误预算消耗排名最高的提示版本；
• RAG 上下文令牌按工作流程共享；
• 护栏块和快速注入分类器命中。

对于警报，请结合技术和业务信号。突然的租户支出激增可能比全球延迟的小幅增加更为紧急。模型别名更改后的回退率跳跃可能表明存在兼容性问题。重复的 401、429 或 5xx 响应可能表明存在关键问题、配额耗尽或提供商不稳定。

兼容 OpenAI 的代理的最小实现流程

对于 /chat/completions 代理，流程可以很简单：

1. 接收请求并分配 request_id 和跟踪上下文。
2. 验证网关密钥并解析租户、团队、应用和政策范围。
3. 创建父网关范围。
4. 创建一个状态为已接受的账本行。
5. 将模型别名解析为提供程序模型和路由策略版本。
6. 记录元数据：操作、提示模板 ID、架构名称、提示哈希和内容捕获策略。
7. 在适用的情况下使用 GenAI 语义属性启动模型调用范围。
8. 将请求转发给选定的提供商。
9. 对于流式传输，当第一个块到达时更新状态，并在提供程序响应允许的情况下准确地计算使用情况。
10. 完成后，解析提供程序的使用情况、完成原因、状态和错误类别。
11. 使用代币、预估成本、重试/回退详细信息和最终请求状态更新账本。
12. 从账本和跨度数据中发出指标。
13. 将日常对账和商店提供商确认的成本与原始估算分开进行。

推出清单

• 定义规范请求 ID 和跟踪 ID。
• 采用 OpenTelemetry GenAI 属性进行通用模型遥测。
• 创建包含请求状态转换的网关使用分类账。
• 标准化提供商、模型、模型别名、租户、应用和工作流程维度。
• 不要将高基数调查数据放在指标标签中。
• 默认禁用原始提示和输出捕获。
• 添加明确的采样、编辑、保留和访问控制政策。
• 捕获 RAG 工作流程的检索元数据。
• 构建成本、延迟、可靠性、验证和租户行为信息中心。
• 使网关估算与提供商的使用情况和成本导出保持一致。
• 针对支出高峰、延迟回归、回退跳转、验证失败和安全相关事件发出警报。

结论

多模型网关是实现 LLM 可观察性的正确位置，因为它可以在请求到达任何提供商之前看到请求，并且可以附加提供商不知道的业务上下文。最强大的设计并不是“记录一切”。它是一个分层模型：用于执行的提供商中立跟踪、用于计费的持久令牌和成本分类账、用于治理的租户分析、用于检索质量的 RAG 元数据以及用于安全调试的隐私优先提示日志记录。

从元数据、状态转换和协调开始。仅当策略、保留和访问控制准备就绪时才添加内容捕获。该序列为开发人员提供了调试延迟、质量和支出所需的证据，而无需将可观察性转变为新的数据暴露风险。

相关阅读

• LLM API 路由中的重试和回退行为
• 提示缓存和批量成本控制模式
• 团队 API 密钥管理和支出限制