AI API 网关中的流式令牌记账：最终使用、取消和部分响应

建议：记录最新的累积使用值，如果出现回归，则发出可观察性事件。回归可能表明解析器错误、重复事件、提供程序更改或混合流。

Gemini 和 Vertex 风格的流媒体

Gemini 支持流式传输块以减少感知延迟。在 Vertex 风格的 SDK 中，流式传输可以公开异步流和聚合响应对象。网关应在可用时保留该聚合路径。

const StreamingResult =等待model.generateContentStream(request);
for等待（streamingResult.stream的const块）{
  前向块（块）；
  countDeliveredBytesOrText(块);
}
const 聚合=等待streamingResult.response；
SettleFromAggregateUsage(聚合);

建议：如果 SDK 提供完整的响应记录，请避免从可见块构建所有记帐。块是为了延迟。最终对象通常更适合计费和分析。

将客户端断开连接作为一流的记帐事件来处理

客户端断开连接是许多网关亏损或向客户收取过高费用的原因。浏览器选项卡关闭、移动网络中断或应用程序取消请求。网关注意到下游套接字已关闭，但上游提供程序可能仍在生成。

网关应该做出明确的策略选择：

• 立即取消上游：减少浪费的生成和提供程序成本，但可能会中断 UI 断开连接后后端仍需要结果的工作流程。
• 在后台继续上游：可以为服务器端使用者保留工作，但用户可能看不到生成和计费的所有令牌。
• 依赖于路由的行为：取消交互式聊天，继续执行类似作业的工作流程，并使设置对租户可见。

交互式流式传输的实际默认设置是在下游客户端断开连接时取消上游，然后将账本行标记为 client_aborted。如果最终使用在取消期间到达，则根据该权威使用进行结算。如果不是，请将行标记为估计或pending_reconciliation，而不是假装它是准确的。

downstream.on("close", async () => {
  if (!providerCompleted) {
    ledger.markClientAborted(requestId);
    等待上游.abort().catch(() => {
      ledger.emit("upstream_cancel_failed", requestId);
    });
  }
});

建议：公开透明的结算标签，例如 final、provider_reconciled、estimated、waived 或 pending_reconciliation。这比立即准确地显示每个流式调用更具防御性。

流期间的配额强制执行

准确的计费通常取决于最终的提供商使用情况，但配额执行不能总是等到最后。不应允许具有硬预算的租户无限期地进行流式传输，因为在飞行过程中无法获得确切的使用情况。

同时使用两种机制：

1. 预检预留：根据型号、请求的最大令牌数、租户政策和当前余额预留预计的最大值。
2. 流式传输压力检查：估计流式传输期间交付的输出，并在请求跨越配置的安全边界时停止。

这是一种控制机制，而不是最终法案。提供者可能会以与网关估计器不同的方式计算缓存令牌、推理令牌、多模式令牌或隐藏令牌。

权衡：实时估算有助于执行预算，但它们可能与提供商计费的代币有所不同。最终结算应使用权威提供商的使用情况（如果可用），对账应稍后调整估算。

捕获会计错误的可观察性事件

当网关发出目标事件而不是仅发出通用请求日志时，流式计费故障更容易调试。添加事件，例如：

• final_usage_missing：流在没有权威使用的情况下结束。
• cumulative_usage_regressed：累计令牌计数向后移动。
• stream_ending_without_stop_event：未观察到正常的提供商停止标记。
• aborted_after_provider_completion：提供者完成，但下游客户端在网关完成转发之前关闭。
• settled_from_estimate：租户分类账使用了估算值，因为最终使用情况不可用。
• reconciliation_adjusted_usage：提供商报告后来更改了该行。

事实：OpenTelemetry GenAI 语义约定建议使用提供商返回的使用信息进行流式响应（如果可用），并在无法高效或准确获取令牌计数时警告不要报告使用指标。

对于人工智能使用分析，这意味着仪表板应支持置信水平。混合最终值、估计值和调节值而没有标签的图表可能看起来很干净，但会误导财务和支持团队。

流式会计的一致性测试

不要依靠快乐路径聊天提示进行手动测试。每个提供者适配器都应该针对破坏账本的情况进行一致性测试：

• 正常流：最终使用到达，观察到停止事件，账本结算为最终。
• 工具调用流：工具调用增量被转发，使用情况被捕获，结构化元数据不会破坏令牌计数。
• 安全或拒绝停止：提供商提前停止，使用情况仍能正确解决。
• 强制客户端断开：部分输出后下游关闭；上游根据政策取消或继续。
• 部分输出后的上游 5xx：网关记录部分传送，并且不会将请求标记为完全成功。
• 最终使用前的网关超时：行变为估计或待对账。
• 缺少最终事件：适配器发出 final_usage_missing 并避免准确的计费标签。

这些测试应该断言状态转换、账本字段、发出的可观察性事件和下游行为。逐字节流兼容性还不够；会计副作用是合同的一部分。

实际实施清单

• 在分派上游请求之前创建使用分类账行。
• 在请求时存储租户、密钥、用户、模型、路由、提供商和请求标识符。
• 在支持的情况下启用提供商最终使用情况报告，例如兼容 OpenAI 的 stream_options.include_usage。
• 对于累积提供程序，存储最新的使用值而不是汇总事件。
• 在 SDK 提供聚合响应对象时保留它们。
• 单独跟踪交付的输出和提供商计费的使用情况。
• 断开连接时，根据路由策略取消上游并标记 client_aborted。
• 使用透明的结算状态：最终、估计、待核对、提供商核对或放弃。
• 发出特定于会计的可观察性事件。
• 稍后根据提供商的使用情况或成本报告（如有）进行协调，同时保留请求时的租户归属。

向租户展示什么

租户不需要每一个内部事件，但他们确实需要诚实的标签。有用的使用表可能会显示：

• 状态：最终、估计或核对。
• 请求结果：已完成、客户端中止、提供商错误或网关超时。
• 交付的输出：发送到客户端的近似文本或字节。
• 计费令牌：用于成本的提供商标准化使用量。
• 调整：任何以后的调节增量。

这种设计减少了支持的歧义。如果用户只看到部分响应，仪表板可以解释提供商是否已经完成、网关是否取消上游以及费用是最终费用还是估计费用。

建议与预测

建议：将流式请求视为状态机，在准确结算之前等待权威的最终使用，将交付的输出与计费使用分开，并诚实地标记估计行。提供程序适配器应该对提供程序特定的使用语义进行编码，而不是将每个流扁平化为通用字节代理。

预测：随着模型暴露更多隐藏的工作：推理令牌、缓存令牌折扣、多模式处理、工具使用跟踪和安全停止，流式会计将变得更加重要。已经将提供商计费的使用与客户端可见的输出分开的网关将比仅计算流文本的网关更容易适应。

可行的结论

如果您的网关支持流式传输，请立即审核一条路径：在前几个块之后强制客户端断开连接并检查分类帐行。如果它显示“成功”并且令牌计数看起来准确，那么您的分析可能在撒谎。

解决办法不是放弃流媒体。保持快速的用户体验，但使流完成、取消、提供者错误、丢失最终使用和协调明确的记账状态。这为产品团队提供了响应式输出，为财务团队提供了可辩护的成本，并为支持团队提供了足够的证据来解释部分响应，而无需猜测。

相关阅读

• 在每个模型调用背后设计计费分类账
• 加入跟踪、代币账本和安全使用分析
• 构建OpenAI兼容网关兼容性合约