API 用量字段缺失和用量为零，统计时怎样避免都算成免费调用

usage.get('total_tokens') or 0 看起来方便，却把明确零值、缺字段和未知用量压成同一种数据。之后报告“有三次免费调用”，可能只是三次响应没有可用统计。用量台账应保留字段存在性，未知就写未知，不从空白推导免费。

先定义已知的条件

本文要求 usage 是对象，并且 total_tokens 是非负整数，才把总量记为 known。缺 usage、显式 null、缺总数字段分别保留原因。明确的零值合法，必须计入已知请求数。布尔值和负数按本地合同判无效，不借用 Python 中布尔等于整数的行为。

Responses 官方参考定义了 usage 相关字段，但不同接口、返回阶段和适配链路的统计可用性需要依据实际响应确认。本文不声称缺用量必然不计费，也不把本地台账当平台账单。示例仅消费合成字段，未核对任何真实账户费用。

四条记录怎样汇总

附件包括缺失、null、明确零和 total_tokens 为十二四种记录。预期已知 token 合计十二，已知请求二，未知请求二，明确零记录一。已知总量只代表已观测部分，报告标题应写清覆盖范围；不能把它直接除以全部请求数，然后称作真实平均成本。

失败反例是先统一填零再求和。合计数字仍可能恰好是十二，所以单独检查总和无法发现错误。必须同时断言 known 与 unknown 的数量，证明未知没有被吞掉。这也是为什么验收样本需要零值项：没有它，程序可能反过来把真实零也当缺失。

明细不能擅自补成总账

缓存输入、推理 token 或其他细项缺失时，保留缺失，不自动填零；同时不能把已知子项相加反推未提供的总项，除非协议明确保证它们完整且互斥。某个接口的输入输出字段名也不能直接移植到另一个接口，适配层应先明确来源与版本。

记录中宜保留原 usage 结构、归一结果与判定原因，避免之后更改规则时无法回放。统计导出可增加覆盖率，即已知请求占总请求的比例，但它描述观测完整性，不是服务成功率，更不是付费准确率。

出现用量未知时，可以排查流式最终事件是否保存、响应是否被裁剪和适配器是否遗漏字段；这些只是排查方向，不能在没有证据时指定原因。本文不配置服务端计量、网关限流或租户预算，只检查应用消费到的字段。上线前仍需按实际账户账单做独立对账，任何免费结论都需要对应计费证据，不能由一个缺字段产生。

配套文件与依据

本文的合成输入和参考结果可下载独立样本 a020.json，离线检查器 a020.py与样本放在同一目录后运行。检查器不调用模型接口。 使用 Python 3.12 或兼容版本，将上述文件下载到同一目录，执行 python a020.py。

一手资料1；一手资料2。资料核对日期：2026-10-24。