Repository navigation
V1 Usage and Cost
简体中文 | 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() |
接续快速开始中配置好的 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=...) 可汇总多个评测用例的估算。没有确认上报覆盖率时,不把估算当成总费用。另见安全、观测与评测。
-
缺失不是零。
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 和费用能否统计或实施硬限制取决于后端,未知结果应核对后结算,不记为零,也不盲目重跑。
LightAgent Wiki - see the repository, releases, and issues.
- Installation and Your First Agent
- Tools and Integrations
- Memory, Sessions, and RAG
- Workflows and Multiple Agents
- Agent Backends and Codex
- Durable Execution, Jobs, and Subagents
- Safety, Observability, and Evaluation
- Usage, Cost Estimates, and Budgets
- Deployment, Migration, and Verification
- 安装与第一个 Agent
- 工具和集成
- 记忆、会话与 RAG
- 工作流与多 Agent
- 执行后端与 Codex
- 持久执行、Jobs 与 Subagents
- 安全、观测与评测
- 用量统计、费用估算与预算
- 部署、升级与验收
- Quick Start
- Core Concepts
- API Reference
- Examples Cookbook
- Migration Guide
- Tools
- Tool Generator
- Memory
- MCP
- Skills
- LightFlow
- Tree of Thought
- Self-Learning
- Multi-Agent
- Tracing and Debugging
- Langfuse Observability
- Model Providers
- browser-use Integration
- Testing and CI
- Deployment Guide
- Architecture
- Security
- Known Limitations
- FAQ
- FAQ 中文
- Roadmap
- Release Process
- Contributing