Skip to content

V1 Usage and Cost

weego edited this page Nov 15, 2026 · 1 revision

用量统计、费用估算与预算

简体中文 | English

适用版本:v1.0.0。这里的用量指模型请求上报的 token、运行指标及执行预算,不是账户余额,也不是供应商账单。

想知道什么 从哪里读取
一次原生 Agent 运行上报了多少 token 非流式 RunResult.usage
请求数、工具调用数、延迟和费用估算 summarize_trace() / agent.summarize_trace()
Codex CLI 返回了哪些计数 RunResult.usage 或 agent.last_backend_result.usage
可重连任务已用或预留多少预算 ExecutionHandle.budget()

读取单次运行的 token 和费用估算

接续快速开始中配置好的 agent。result_format="object" 返回 RunResult;trace=True 额外记录用于排查和汇总的事件:

from LightAgent import summarize_trace

result = agent.run("Give a one-sentence summary.", result_format="object", trace=True)
if result.error:
    print("Run error:", result.error)

if result.usage:
    print("Reported usage:", result.usage)
    # Illustrative USD rates per million tokens, not provider prices.
    summary = summarize_trace(
        result.trace, usage=result.usage,
        pricing={"input_per_million": 1.0, "output_per_million": 5.0},
    )
    print("Estimated USD:", summary.estimated_cost_usd)
else:
    print("Usage not reported; cost is unknown.")

原生路径累加已记录的模型请求用量:prompt_tokens 是输入,completion_tokens 是输出,total_tokens 是合计。汇总也接受 input_tokens 和 output_tokens 命名。一次运行可能有多次模型调用,例如工具返回后继续生成;不要将整次运行总量与同一次运行的逐请求用量再相加。

费用公式为 (输入 token × 输入单价 + 输出 token × 输出单价) / 1_000_000。单价由应用提供,单位是美元/百万 token。不会自动查询价格,也不单独计算缓存折扣、工具收费或不同模型的费率。混用模型时按各模型计价后再合计,实际对账以供应商记录为准。

离线示例:聚合两次模型请求

下面不调用模型,也无需 API key:

from LightAgent import summarize_trace

events = [
    {"type": "model_request", "data": {"usage": {"input_tokens": 100, "output_tokens": 25}}},
    {"type": "model_request", "data": {"usage": {"prompt_tokens": 60, "completion_tokens": 15}}},
]
summary = summarize_trace(events, pricing={"input_per_million": 1.0, "output_per_million": 5.0})
assert summary.usage == {"prompt_tokens": 160, "completion_tokens": 40, "total_tokens": 200}
assert summary.model_request_count == 2
assert summary.estimated_cost_usd == 0.00036
print(summary.to_dict())

TraceSummary 还包括延迟、错误、重试、工具和审批指标。agent.summarize_trace() 读取最近一次运行;要统计历史运行,保存各自的 result.trace 和 result.usage,按 Trace ID 去重。LightEvaluator(pricing=...) 可汇总多个评测用例的估算。没有确认上报覆盖率时,不把估算当成总费用。另见安全、观测与评测。

流式、Codex 与缺失数据

  • 缺失不是零。 RunResult.usage 为空表示没有可读用量。部分请求不报用量时,累计值也可能不完整。无用量时,Trace 汇总仍可能显示零 token 或零估算,应用应单独记录「未上报」。
  • 流式用量不是保证。 先完整消费迭代器,再读取 agent.summarize_trace()。统计取决于供应商是否返回用量,以及 v1.0.0 流式路径是否读到数据;不要依赖专门的 usage 流事件。需要稳定记录时优先使用非流式,并与供应商记录核对。
  • Codex 返回后端原始用量。 CLI 终止事件若含用量,会通过后端结果返回,常见字段为 input_tokens、output_tokens 和 cached_input_tokens。这些不是账户配额或金额;不要将缓存 token 另加到输入总量。外部后端不支持 stream=True,详见 Codex 指南。

持久任务预算

用持久执行示例得到的 handle 查询:

budget = handle.budget()
print("Used:", budget["used"])
print("Reserved:", budget["reserved"])
print("Unknown:", budget["unknown"])

used 是已记录消耗;reserved 是已预留但尚未结算的额度;unknown 记录各维度待核对的用量次数,不是 token 数。backend_calls 和 seconds 属于执行计量。token 和费用能否统计或实施硬限制取决于后端,未知结果应核对后结算,不记为零,也不盲目重跑。

Clone this wiki locally