Gemini API 预估 token 与使用量元数据的区分

如果你先调用 countTokens，再调用生成接口，两个结果不完全相同并不奇怪：前者是发送前对输入的 token 估算，后者是这次生成响应实际记录下来的使用量元数据。它们回答的是两个问题，不能互相替代。

官方地址：https://ai.google.dev/gemini-api/docs/tokens

要控制请求能不能装进输入预算，先看 countTokens；要分析一次生成实际消耗了多少输入、输出、缓存、工具调用或思考 token，读取响应里的 usageMetadata。

下面只讨论这两类数字的含义、字段关系和判断方式，不延伸到具体模型选型或价格计算。

先定位“预估值”和“实际记录”分别回答什么

countTokens 调用模型的 tokenizer，对准备提交的输入做计数，返回的是输入侧的 totalTokens。它适合放在发送前：例如长文本进入队列前先判断是否需要截断，或者在多轮会话拼接前估算上下文规模。

生成接口返回的 usageMetadata 则属于本次响应。传统 Generate Content 字段通常写成 promptTokenCount、candidatesTokenCount 和 totalTokenCount；如果请求使用缓存、工具或思考模型，还可能出现对应的细分字段。它不是“再次调用 countTokens 的结果”，而是服务端随这次生成记录的用量。

发送前用 countTokens 只判断输入能否接受

下面的示例使用当前 Google GenAI Python SDK。它只演示调用关系，密钥从环境变量读取；示例不在本机执行。

import os
from google import genai

# API key 放在环境变量中，避免把凭据写入源码或日志。
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
prompt = "请把这段客服记录整理成三条可执行的改进建议。"

# 只统计准备发送的输入，适合在真正生成前做长度预算。
count = client.models.count_tokens(
    model="gemini-3.8-flash",
    contents=prompt,
)
print("estimated_input_tokens:", count.total_tokens)

# 计数通过后再发送生成请求；生成结果中的 usage 要单独读取。
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=prompt,
)
usage = response.usage_metadata
print("prompt_tokens:", usage.prompt_token_count)
print("candidate_tokens:", usage.candidates_token_count)
print("total_tokens:", usage.total_token_count)

这段代码里的两个数字用途不同：count.total_tokens 是发送前的输入侧估算，usage.prompt_token_count 是生成请求记录的 prompt token 数，usage.candidates_token_count 是响应候选的输出 token 数。不要拿候选输出量去判断输入是否超限。

系统指令、缓存和工具会改变你看到的字段

计数时不能只盯着用户文本。系统指令也属于输入；如果准备提交的请求还包含工具声明、图片或文件，应该把同一份请求结构交给计数方法，而不是只数一段字符串。对于缓存内容，响应中的 cachedContentTokenCount 用来拆出缓存部分，而 promptTokenCount 仍表示有效 prompt 的总规模。

生成响应还可能包含 toolUsePromptTokenCount 和 thoughtsTokenCount。前者表示工具使用相关的 prompt token，后者用于思考模型的思考 token。它们不是候选文本长度，也不应被误加到输入字段里重复统计。

# 只读取存在的字段，兼容不同模型或 SDK 版本返回的可选元数据。
def usage_summary(usage):
    fields = (
        "prompt_token_count",
        "cached_content_token_count",
        "tool_use_prompt_token_count",
        "thoughts_token_count",
        "candidates_token_count",
        "total_token_count",
    )
    return {name: getattr(usage, name, None) for name in fields}

# 这里的 summary 用于日志或指标，不把 None 当成零参与计算。
print(usage_summary(response.usage_metadata))

用字段关系判断预算、排查和统计口径

如果你的目标是“请求是否接近上下文上限”，应先用与实际请求一致的内容调用 countTokens，再结合生成时的输出预算判断；如果目标是“为什么这次成本或用量比预期高”，则应保存响应中的细分元数据，尤其是缓存、工具和思考字段。

三个容易把 token 数字看错的地方

• 把预估输入当成完整账单：countTokens 只回答输入侧计数，不包含随后生成的候选输出。
• 把字段缺失当成零：不同模型或 SDK 版本可能不返回某些可选字段，记录时应保留“未提供”和“明确为 0”的区别。
• 重复相加总量：totalTokenCount 已包含请求相关的组成部分，做指标时直接使用它，同时单独保留各明细字段。

相关问题

为什么 countTokens 和 promptTokenCount 不一定相等？

两者处在不同接口和不同记录时点。若计数请求没有完整带上系统指令、工具、缓存或多模态内容，输入就不是同一份；生成过程还可能记录服务端实际处理的附加 prompt。因此，应比较请求结构，而不是只比较一段文本。

只想限制输入长度，应该记录哪个字段？

发送前记录 countTokens 返回的 totalTokens；生成后再保存 promptTokenCount 作为实际观测值。前者负责门槛判断，后者负责回溯分析。

记住这条分界即可：countTokens 是“准备发什么”的输入估算，usageMetadata 是“这次生成实际记录了什么”的用量明细。预算检查、上下文排查和用量统计分别使用对应字段，结果才不会互相污染。