← 返回博客

LLM usage 对账避坑:缓存读写与推理 Token 严禁重复相加

在跨大模型 API 对账时,各厂商对缓存与推理 Token 的定义存在包含与互斥差异。本文解析 OpenAI、Claude 与 Gemini 的 Usage 字段语义,通过合成算例展示互斥分桶计价方法,避免将子集与总量重复相加导致内部估算虚增,并提供缺失遥测与异常重试的标准对账流程。

为什么跨模型 API 对账总是算不平?

企业在接入多模型网关或汇总财务消耗时,常遇到账单金额与内部统计对不上的问题。最根本的原因在于:不同厂商在响应载荷中返回的 usage 字段,其集合包含关系完全不同。部分协议返回的总量字段已经包含了细分项,而另一些协议返回的则是互斥片段。如果开发者直接编写通用的累加逻辑,将所有带 token 字样的字段求和,就会造成严重的内部重复计算误差。

要建立严密的成本核算系统,必须坚持一个核心原则:原始 usage 响应按端点和版本原样入库归档,而在计价层,必须先将字段拆解映射为互斥的计量桶(普通输入、缓存读取、缓存写入、总输出),再分别匹配费率表达式进行乘加核对。

主流厂商 Usage 字段的集合关系差异

目前主流模型生态在 token 统计上的字段语义划分如下:

  1. OpenAI Responses 协议:总输入字段为 input_tokens,其子对象 input_tokens_details 中的 cached_tokens 与 cache_write_tokens 是总输入的细分子集,绝不能加到 input_tokens 之上;在输出方面,output_tokens 代表全部生成 token,output_tokens_details.reasoning_tokens 是模型思考推理所消耗的内部子集,同样已经包含在 output_tokens 中,严禁再次相加。

  2. Anthropic Messages 原生缓存协议:其输入采用互斥求和逻辑。官方文档明确规范总输入等于 cache_read_input_tokens、cache_creation_input_tokens 与基础 input_tokens 三者相加。此时的 input_tokens 仅代表未击中也未创建缓存的净基础输入,与 OpenAI 的语义截然相反。

  3. Google Gemini 协议:usageMetadata 中的 promptTokenCount 已经涵盖了 cachedContentTokenCount,不能二次累加;输出部分的 candidatesTokenCount 为候选输出,thoughtsTokenCount 为思考 token,二者与工具调用输入共同汇入 totalTokenCount。不能将 totalTokenCount 误当作输出 token 处理。

互斥分桶与合成对账演算

以基于 OpenAI Responses 字段规范构造的一组假设合成数据为例(注意:本算例为数学演示,不代表实际网络发票或实测账单):

假设单次请求返回 input_tokens 为 10000,其中 cached_tokens 为 6000,cache_write_tokens 为 2000(生命周期为 30 分钟),output_tokens 为 1000,其中 reasoning_tokens 为 400。若进行互斥分桶:普通基础输入为 10000 减去 6000 减去 2000,等于 2000;缓存读取桶为 6000;缓存 30 分钟写入桶为 2000;计费输出桶为 1000(其中 400 为推理思考,总量仍为 1000,不可算作 1400)。

根据公开目录基准表达式(以 gpt-6.2-sol 标准输入输出规则为例),声明基准单价假设为:基础输入 2 美元/百万、缓存读取 0.1 美元/百万、30分钟缓存写入 2.5 美元/百万、输出 10 美元/百万。代入互斥桶计算:2000 乘以 2 除以 100 万得 0.004 美元;6000 乘以 0.1 除以 100 万得 0.0006 美元;2000 乘以 2.5 除以 100 万得 0.005 美元;1000 乘以 10 除以 100 万得 0.01 美元。四项互斥分项离线求和基准成本为 0.0196 美元。若匹配 gpt-vip-1 分组倍率 0.1,折算估算额为 0.00196 美元。若此前误将 reasoning_tokens 叠加为 1400 输出,单次估算成本就会被错误放大。

缺失遥测与异常重试的对账规范

实际网络链路中,因客户端断流、网关超时或格式解析异常,可能导致请求未收到完整 usage 载荷。在账务对账表中:

首先,缺失 usage 的记录绝对不能默认填 0,必须标记为 unknown 状态并记录独立计数器。财务汇总时应明确列出已知小计与待对账异常请求数,避免给出虚假的精准结账数字。

其次,客户端由于超时发起的重试,必须遵循幂等性与请求凭据追踪规范。针对分布式代理与超时的处理方法,可参考 Agent 工具超时重试与幂等设计。每次网络底层重试都拥有唯一的 attempt ID,对账单应与实际发生的底层传输匹配,不得将重复投递的上游遥测合并累加为多倍消费。

权威来源与网关统一接入建议

核实对账逻辑时请参考官方一手文档:OpenAI Responses API 参考(developers.openai.com)、Anthropic Messages Prompt Caching 规范(platform.claude.com)及 Google AI Studio GenerateContent 指南(aistudio.google.com)。

跨厂商统一对账前,建议先通过少量灰度请求核对原始 usage 映射关系。开发者可接入标准化网关 APIBox,在统一接口规范下快速适配主流模型。立即通过 APIBox 控制台注册 获取令牌,使用统一接入点 https://api.apibox.cc/v1 发起请求。最新模型支持矩阵与费率分组可查阅 定价目录与充值说明。需特别注意:公开定价 API 仅作为计费目录凭证,不代表具体下游推理的性能与服务承诺,实际费用均需以账户控制台核销流水为准。

本文描述的是内部估算重复,不证明供应商重复扣款。费率快照核验于 2026-11-19;仅演示标准档纯文本输入及输出,不包括工具、存储、多模态、Batch 或其他 TTL。Claude 缓存写入须按 5 分钟与 1 小时分桶,Gemini 不应套用本计算器。原始 usage 限权保存,不留 API Key 或正文;账本保存账期、时区、attempt ID、价格版本与账单条目。

可运行的离线校验

仅为合成数据校验,不调用模型或重试生产请求。

from decimal import Decimal as D

# Fixed text-only catalog snapshot; not a generic billing adapter.
def estimate(base, read, write_30m, output):
    values = (base, read, write_30m, output)
    if any(type(v) is not int or v < 0 for v in values):
        raise ValueError("unknown or invalid token bucket")
    if base + read + write_30m > 272000:
        raise ValueError("outside this example's standard tier")
    rates = (D("2"), D("0.1"), D("2.5"), D("10"))
    return sum(D(v) * r for v, r in zip(values, rates)) / D("1000000") * D("0.1")

assert estimate(2000, 6000, 2000, 1000) == D("0.00196")
for bad in (True, -1, None, 1.5):
    try:
        estimate(bad, 6000, 2000, 1000)
    except ValueError:
        pass
    else:
        raise AssertionError("invalid input accepted")
print(estimate(2000, 6000, 2000, 1000))

来源与实时目录

常见问题

OpenAI 响应里的 reasoning_tokens 需要额外加到 output_tokens 里计算费用吗?

不需要。在 OpenAI Responses 协议规范中,output_tokens_details.reasoning_tokens 是 output_tokens 的细分子集,输出总量已包含这部分思考 Token,重复叠加会导致内部输出估算被虚增放大。

Claude 的 prompt 缓存与 OpenAI 的 cached_tokens 计算逻辑有何本质区别?

OpenAI 的 input_tokens 包含 cached_tokens(即总输入包含缓存读);而 Claude 原生 Messages API 的 input_tokens 仅代表未命中缓存的净基础输入,总输入等于基础 input_tokens、cache_read_input_tokens 和 cache_creation_input_tokens 三者相加。

流式传输中断或未返回 usage 载荷时,对账系统应如何记账?

绝对不可将缺失 usage 的记录直接计为 0,应打上 unknown 标签单独隔离,并在报表中展示已知成本小计与待核实请求总数,结合底层网关请求 ID 与流水条目排查核对。

立即体验,注册后即可使用 30+ 模型,一个 Key 全搞定

免费注册 →