Token 计数端点：七步决定何时调用
给每次生成请求都加一次 Token 计数，看起来稳妥，却未必是最好的工程设计。建议把计数端点当作准入检查：当结果会改变裁剪、路由或提交决策时调用；否则，优先保持请求路径简单。下面按接入顺序，把这项检查放到合适的位置。
一、先明确你要计算什么
调用前计数回答的是“这份输入有多大”，不是“整次生成最终花多少钱”。例如，Gemini 的计数方法返回输入 Token 数，生成后的用量元数据才包含实际输出。不要把输入计数写进总费用字段，也不要把预留输出额度当成已经发生的消耗。建议分别保存输入估计、输出预算和实际用量，避免预算与账单混淆。([ai.google.dev](https://ai.google.dev/gemini-api/docs/tokens?authuser=698580186))
二、确认端点，而不只是确认模型可用
不同接口的计数入口并不相同：Claude 使用 POST /v1/messages/count_tokens，OpenAI Responses 使用 POST /v1/responses/input_tokens，Gemini 提供 countTokens 方法。不要把某一家接口的路径和请求体直接套到另一家。([platform.claude.com](https://platform.claude.com/docs/en/api/messages/count_tokens?utm_source=openai))
在 CodeRelay Hub 这类按量付费、统一接入的多模型环境中，建议单独核验目标路由是否开放计数端点、接受哪些字段，以及需要什么权限。生成接口兼容，不应被当作计数接口也兼容的证据。把验证结果放进能力配置，而不是等线上请求失败后才发现差异。
三、先组装请求，再发送计数
不要只计算用户最后一句话。Claude 的计数接口支持结构化消息，以及系统提示、工具、图片和文档；OpenAI 的计数接口也支持指令、对话输入和工具等内容。只截取纯文本，会遗漏你真正准备发送的输入。([platform.claude.com](https://platform.claude.com/docs/en/build-with-claude/token-counting?q=count_tokens))
建议让生成与计数共用一份请求构建结果，再由适配层挑选计数接口支持的字段。检索片段应先完成去重与排序，工具描述应先确定版本。计数后若追加历史消息、替换附件或修改工具定义，就重新执行预算判断；不要继续使用旧结果批准新请求。
四、把调用放在会改变决策的节点
建议在以下节点调用，而不是机械地为所有请求增加前置检查：
- 长文档提交前：决定整份发送，还是拆分处理。
- 检索内容组装后：决定保留哪些证据，避免先计数再无限追加片段。
- 智能体收到大段工具结果后：决定压缩历史，还是继续下一轮。
- 切换模型或路由后：针对新的目标重新验证预算。
- 批处理启动前：识别异常大的任务，单独排队或退回处理。
对于长度稳定的短请求，建议先用生产用量验证其范围，再决定是否跳过逐次计数。关键问题是：如果计数结果变大，系统真的会采取不同动作吗？如果不会，这次检查就缺少明确用途。
五、把计数结果转换为准入规则
建议采用明确的应用侧规则：输入计数＋输出预留＋安全余量，不超过目标预算。预算应同时考虑目标模型的上下文限制、独立输出限制与团队设置的更低上限，不要把上下文容量全部分配给输入。
安全余量不是统一常数。Claude 文档明确说明，计数结果应视为估计，实际输入用量可能略有不同。因此，建议根据实际请求的偏差调整余量，而不是宣称一次预检就能保证生成成功。([platform.claude.com](https://platform.claude.com/docs/en/build-with-claude/token-counting?q=count_tokens))
超预算时，建议先删除重复检索片段，再缩短低优先级历史，最后考虑拆分任务或更换路由。保留当前任务、必要约束和证据来源；不要直接从序列化请求尾部截断，以免破坏结构。
六、缓存结果，但别把估算伪装成精确值
建议用目标模型标识、路由、计数相关参数和规范化请求内容共同生成缓存键。只按用户问题缓存不够稳妥，因为系统提示或工具定义可能已经变化。请求内容未变时可以复用结果；任何影响输入的变更都应使缓存失效。
计数超时或端点不支持时，建议按风险分级：临近上限的大请求进入拆分或延后流程；明显较短的请求可以依据保守估算继续。务必记录“远端计数”“本地估算”或“未计数”的来源，不要让零值同时代表空输入和计数失败。
七、用实际用量关闭反馈循环
建议在生成完成后，把预检计数与返回的实际输入用量关联保存，并记录模型、路由、请求构建版本和计数耗时。分别观察正常请求与异常请求，重点排查工具定义更新、附件变化和计数后追加内容等情况。日志尽量保存摘要与哈希，不要为排查偏差默认复制完整敏感提示。
最终目标不是“所有请求都数过”，而是让高风险请求在提交前得到处理，让低风险请求少走一步。把计数接入准入、裁剪和路由逻辑，才算完成这项能力。
欢迎在 CodeRelay Hub 开通免费工作空间。