用 Python 为 Claude 请求建立费用账本
教程通过包装 Claude API 调用,逐次记录普通输入、缓存写入、缓存读取和输出 Token,并按配置费率计算成本。日志可用于追查具体功能、用户或提示词产生的费用,避免遗漏缓存计费项。
AI 深度解读
Claude API 的账单容易记少,问题可能出在调用日志:新输入、缓存写入、缓存读取都属于输入,却按三种价格收费。原文给出的办法很直接:在 Python 客户端外包一层,每次请求记录 token 拆分、业务功能和估算费用,再按天汇总。
这套方法对排查 AI 功能成本很有用,但示例代码只是起点。原文的缓存价格比较还有口径不一致的问题,需要把「日志能发现什么」和「示例证明了什么」分开看。
为什么只记输入和输出会漏账
按原文的说明,Claude Messages API 返回的 usage 有四个计费字段:
input_tokens:新输入的 token。cache_creation_input_tokens:写入提示词缓存的 token。cache_read_input_tokens:从缓存读取的 token。output_tokens:模型生成的 token。
原文将它与 OpenAI 的统计方式作了区分:后者在一个提示词总量中标出缓存部分,Claude 则分别报告三类输入。照搬只处理输入、输出两列的日志,很容易漏掉缓存写入。
作者称,以下 Claude Sonnet 5.5 价格核对于 2026 年 11 月 10 日,单位都是美元/百万 token:新输入为 2.00,5 分钟缓存写入为 2.50,1 小时写入为 4.00,缓存读取为 0.10,输出为 10.00。这些是原文提供的价格口径,不能当作本文独立核验的现行报价。
原文举了一次请求:新输入 10,000、缓存写入 50,000、缓存读取 40,000、输出 1,000。按 5 分钟写入计价,四项分别是 $0.02、$0.125、$0.004、$0.01,合计 $0.159。
缓存写入接近总费用的八成。漏掉它,日志里的账就会明显偏低。
缓存读取便宜,不代表包含缓存写入的那次请求也便宜。
真正要观察的是,同一段提示词后续有没有被反复读取,以及写入费用能否被这些读取摊薄。
包装器最重要的字段,其实是业务名称
原文让开发者先运行 pip install anthropic,设置环境变量 ANTHROPIC_API_KEY,再把包装器保存为 claude_tracker.py。
调用时,将 client.messages.create(model=..., messages=...) 换成 track_message("your-model-id", messages, feature="support_reply", max_tokens=1024)。Messages API 要求的 max_tokens 继续透传,包装器返回原始响应。
每次成功调用后,它向 claude_costs.jsonl 追加一条 JSON,记录 UTC 时间、feature、模型、latency_ms、四类 token 数和保留六位小数的 cost_usd,不保存提示词与回答正文。
其中最值得照搬的是 feature。用 support_reply、summariser、nightly_report 这样的产品功能命名,后续才能回答「哪个功能在花钱」。如果只记文件名或函数名,业务归因仍要人工补做。
下面这段原始代码负责把四类用量换成费用:
def _cost_usd(usage, rates, cache_ttl="5m"):
fresh = usage.input_tokens or 0
write = _cache_write_tokens(usage)
read = getattr(usage, "cache_read_input_tokens", 0) or 0
output = usage.output_tokens or 0
write_rate = (
rates["cache_write_1h_per_million"]
if cache_ttl == "1h"
else rates["cache_write_5m_per_million"]
)
cost = (
fresh * rates["input_per_million"]
+ write * write_rate
+ read * rates["cache_read_per_million"]
+ output * rates["output_per_million"]
) / 1_000_000
return fresh, write, read, output, cost
要盯住的是 cache_ttl == "1h":这里的 TTL 只决定日志采用哪档价格,并不会替请求开启一小时缓存。它必须与实际请求里的缓存设置对应。
这段代码还依赖原文的 _cache_write_tokens() 辅助函数,不能单独复制运行。辅助函数优先读取 cache_creation_input_tokens;没有有效值时,再把 cache_creation 下的 ephemeral_5m_input_tokens 和 ephemeral_1h_input_tokens 相加。
按上述价格,1 小时写入比 5 分钟贵 60%。TTL 填错,token 数仍可能正确,金额却会失真。另一个边界是:代码将两类写入合并后统一定价;如果同一次响应包含不同 TTL 的写入,就需要分别计算。
日志该用来找异常,而不是继续堆数字
原文建议先看三份日报:最近 24 小时各功能总费用、最贵的 10 次调用,以及费用相比过去 7 天日均值翻倍的功能。
它们分别回答钱花在哪里、先排查哪次请求、哪里突然失控。比起先做一个复杂看板,这几项更容易形成实际动作。
缓存写入就是一个具体入口。如果相同业务每天都有大量写入,却很少读取,可以检查提示词前缀是否不断变化。作者举出的可能原因,是在前面插入时间戳或用户 ID。这里应把日志模式视为排查线索,不能直接断言一定是缓存失效;不同请求也可能确实没有可复用内容。
还有两个用量解释上的陷阱。
其一,按原文说明,extended thinking 消耗的 token 包含在 output_tokens 里。用户看到的回答很短,输出计费量仍可能很高。某功能输出量突然上涨时,应检查是否开启了 thinking。
其二,流式调用需要单独处理。原文要求使用 client.messages.stream(model=..., messages=..., max_tokens=...),通过 stream.get_final_message() 取得最终消息,再把 message.usage 交给 _cost_usd()。
流式用量应按一次完整请求记录,不能每个 chunk 都记一笔总账。
原包装器直接调用 client.messages.create(),并没有实现这条流式路径。日常 AI 编程工具如果使用流式输出,需要补上最终用量采集,不能只替换函数名。
我的判断
方向是对的:先保留每次请求的用量拆分,再讨论换模型、改提示词,优化才有依据。但原文没有提供团队上线后的节省比例或对照实验,属于实现教程与经验建议。
它的数字比较也有两处问题。
第一,原文用 $0.159 的缓存请求,对比 60,000 新输入加 1,000 输出、合计 $0.13 的无缓存请求。但前者三类输入合计是 100,000 token,后者只有 60,000。两者并非同一输入规模,不能据此证明缓存方案更贵。
第二,原文称后续请求写入接近零、读取接近 50,000 时,费用约为 $0.034。若保留 10,000 新输入和 1,000 输出,按它自己的费率应是 $0.035;$0.034 对应读取 40,000。要么输入发生了变化,要么示例算错,原文没说清。
工程上,这也是一个最小实现。请求异常发生在写日志之前,失败调用不会留下这条记录;缺少 usage 时,只写入提示信息。模型参数虽然可换,默认价格却固定为 SONNET_55_RATES,换模型时必须同步传入对应费率。
此外,原文声称日志能追到具体用户,但实际记录只有 feature,没有用户标识。要做按用户预算控制,还得补充归因字段。单个 JSONL 文件适合先观察,在多进程或多实例服务里则需要考虑日志汇集。
能拿来做什么
- 给已有 Claude 功能补上统一调用入口,用业务名称填写
feature,先连续记录7天,再决定优先优化哪个功能。 - 排查固定长提示词的缓存收益时,同时看写入量和读取量,并在相同输入规模下比较成本,避免只看单次总金额。
- 为流式调用补齐最终消息的
usage采集;开启 thinking 后,用output_tokens解释费用变化,别按可见回答长度估算。 - 如果服务端使用 Node,可以沿用这套字段拆分和业务归因方式;具体采集位置应按所用 SDK 的响应结构实现,费用表也要与实际模型对应。