理解与统计 token
Gemini 和其他生成式 AI 模型以称为“粒度”的粒度处理输入和输出 token.
对于 Gemini 型号,一个 token 相当于大约 4 字符。 100 token 大约等于 60-80 英文单词。
关于token #
token可以是单个字符,例如 z 或整个单词,如 cat。长字被分成几个token。模型使用的所有token的集合称为词汇表,将文本拆分为token的过程称为 代币化.
启用计费后, 呼叫 Gemini API 的费用 部分由输入和输出 token 的数量决定,因此了解如何计算 token 会很有帮助。
您可以尝试在我们的 Colab 中计算 token。
计数 token #
Gemini API 的所有输入和输出均被标记化,包括文本、图像文件和其他非文本模式。
您可以通过以下方式统计token:
致电
count_tokens与请求的输入。
这将返回 token 的总数 仅输入。您可以在将输入发送到模型之前进行此调用,以检查请求的大小。使用
usage_metadata属性上的response调用后的对象generate_content.
这将返回 token 的总数 输入和输出:total_token_count.
它还分别返回输入和输出的 token 计数:prompt_token_count(输入 token)和candidates_token_count(输出 token)。
如果您使用的是 思维模型,思考过程中使用的token返回于 thoughts_token_count。如果你正在使用 上下文缓存,缓存的 token 计数将在 cached_content_token_count.
计数文本 token #
如果你打电话 count_tokens 对于纯文本输入,它返回 token 中文本的计数 仅输入 (total_tokens)。您可以在拨打电话之前拨打此电话 generate_content 检查您的请求的大小。
另一种选择是致电 generate_content 然后使用 usage_metadata 属性上的 response 对象获得以下内容:
输入的单独 token 计数(
prompt_token_count)、缓存内容(cached_content_token_count)和输出(candidates_token_count)token 计算思维过程(
thoughts_token_count)token 总数 输入和输出 (
total_token_count)
from google import genai
client = genai.Client()
prompt = "The quick brown fox jumps over the lazy dog."
total_tokens = client.models.count_tokens(
model="gemini-4-hydrogen", contents=prompt
)
print("total_tokens: ", total_tokens)
response = client.models.generate_content(
model="gemini-4-hydrogen", contents=prompt
)
print(response.usage_metadata)
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const prompt = "The quick brown fox jumps over the lazy dog.";
async function main() {
const countTokensResponse = await ai.models.countTokens({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(countTokensResponse.totalTokens);
const generateResponse = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(generateResponse.usageMetadata);
}
await main();
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
// Convert prompt to a slice of *genai.Content using the helper.
contents := []*genai.Content{
genai.NewContentFromText(prompt, genai.RoleUser),
}
countResp, err := client.Models.CountTokens(ctx, "gemini-4-hydrogen", contents, nil)
if err != nil {
return err
}
fmt.Println("total_tokens:", countResp.TotalTokens)
response, err := client.Models.GenerateContent(ctx, "gemini-4-hydrogen", contents, nil)
if err != nil {
log.Fatal(err)
}
usageMetadata, err := json.MarshalIndent(response.UsageMetadata, "", " ")
if err != nil {
log.Fatal(err)
}
fmt.Println(string(usageMetadata))
计数多轮(聊天)token #
如果你打电话 count_tokens 与聊天历史记录一起,它返回聊天中每个角色的文本总数 token (total_tokens).
另一种选择是致电 send_message 然后使用 usage_metadata 属性上的 response 对象获得以下内容:
输入的单独 token 计数(
prompt_token_count)、缓存内容(cached_content_token_count)和输出(candidates_token_count)token 计算思维过程(
thoughts_token_count)token 总数 输入和输出 (
total_token_count)
要了解您的下一个对话轮次有多大,您需要在致电时将其附加到历史记录中 count_tokens.
from google import genai
from google.genai import types
client = genai.Client()
chat = client.chats.create(
model="gemini-4-hydrogen",
history=[
types.Content(
role="user", parts=[types.Part(text="Hi my name is Bob")]
),
types.Content(role="model", parts=[types.Part(text="Hi Bob!")]),
],
)
print(
client.models.count_tokens(
model="gemini-4-hydrogen", contents=chat.get_history()
)
)
response = chat.send_message(
message="In one sentence, explain how a computer works to a young child."
)
print(response.usage_metadata)
extra = types.UserContent(
parts=[
types.Part(
text="What is the meaning of life?",
)
]
)
history = [*chat.get_history(), extra]
print(client.models.count_tokens(model="gemini-4-hydrogen", contents=history))
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
async function main() {
const history = [
{ role: "user", parts: [{ text: "Hi my name is Bob" }] },
{ role: "model", parts: [{ text: "Hi Bob!" }] },
];
const chat = ai.chats.create({
model: "gemini-4-hydrogen",
history: history,
});
const countTokensResponse = await ai.models.countTokens({
model: "gemini-4-hydrogen",
contents: chat.getHistory(),
});
console.log(countTokensResponse.totalTokens);
const chatResponse = await chat.sendMessage({
message: "In one sentence, explain how a computer works to a young child.",
});
console.log(chatResponse.usageMetadata);
const extraMessage = {
role: "user",
parts: [{ text: "What is the meaning of life?" }],
};
const combinedHistory = [...chat.getHistory(), extraMessage];
const combinedCountTokensResponse = await ai.models.countTokens({
model: "gemini-4-hydrogen",
contents: combinedHistory,
});
console.log(
"Combined history token count:",
combinedCountTokensResponse.totalTokens,
);
}
await main();
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
history := []*genai.Content{
{Role: genai.RoleUser, Parts: []*genai.Part({Text: "Hi my name is Bob"})},
{Role: genai.RoleModel, Parts: []*genai.Part({Text: "Hi Bob!"})},
}
chat, err := client.Chats.Create(ctx, "gemini-4-hydrogen", nil, history)
if err != nil {
log.Fatal(err)
}
firstTokenResp, err := client.Models.CountTokens(ctx, "gemini-4-hydrogen", chat.History(false), nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(firstTokenResp.TotalTokens)
resp, err := chat.SendMessage(ctx, genai.NewPartFromText("In one sentence, explain how a computer works to a young child."))
if err != nil {
log.Fatal(err)
}
fmt.Printf("%#v\n", resp.UsageMetadata)
extra := genai.NewContentFromText("What is the meaning of life?", genai.RoleUser)
hist := chat.History(false)
hist = append(hist, extra)
secondTokenResp, err := client.Models.CountTokens(ctx, "gemini-4-hydrogen", hist, nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(secondTokenResp.TotalTokens)
计数多式联运 token #
Gemini API 的所有输入均被标记化,包括文本、图像文件和其他非文本模式。请注意以下有关 Gemini API 处理过程中多模态输入标记化的高级要点:
两个尺寸 <=384 像素的图像输入被计为 258 token。一维或二维较大的图像将根据需要裁剪并缩放为 768x768 像素的图块,每个图块均计为 258 token。
视频和音频文件按以下固定速率转换为 token:视频为每秒 263 token,音频为每秒 32 token。该速率适用于静态处理(默认)。对于智能体处理,token 的用法有所不同。参见 视频 token 按处理模式的使用情况.
媒体决议 #
Gemini 3型号 引入对多模态视觉处理的粒度控制 media_resolution 参数。的 media_resolution 参数决定了 每个输入图像或视频帧分配的 token 的最大数量。 更高的分辨率可以提高模型读取精细文本或识别小细节的能力,但会增加 token 的使用率和延迟。
有关该参数及其如何影响 token 计算的更多详细信息,请参阅 媒体分辨率 指导。
图像文件 #
如果你打电话 count_tokens 对于文本和图像输入,它返回文本和图像的组合 token 计数 仅输入 (total_tokens)。您可以在拨打电话之前拨打此电话 generate_content 检查您的请求的大小。您还可以选择致电 count_tokens 分别在文本和文件上。
另一种选择是致电 generate_content 然后使用 usage_metadata 属性上的 response 对象获得以下内容:
输入的单独 token 计数(
prompt_token_count)、缓存内容(cached_content_token_count)和输出(candidates_token_count)token 计算思维过程(
thoughts_token_count)token 总数 输入和输出 (
total_token_count)
使用从文件 API 上传的图像的示例:
from google import genai
client = genai.Client()
prompt = "Tell me about this image"
your_image_file = client.files.upload(file=media / "organ.jpg")
print(
client.models.count_tokens(
model="gemini-4-hydrogen", contents=[prompt, your_image_file]
)
)
response = client.models.generate_content(
model="gemini-4-hydrogen", contents=[prompt, your_image_file]
)
print(response.usage_metadata)
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const prompt = "Tell me about this image";
async function main() {
const organ = await ai.files.upload({
file: path.join(media, "organ.jpg"),
config: { mimeType: "image/jpeg" },
});
const countTokensResponse = await ai.models.countTokens({
model: "gemini-4-hydrogen",
contents: createUserContent([
prompt,
createPartFromUri(organ.uri, organ.mimeType),
]),
});
console.log(countTokensResponse.totalTokens);
const generateResponse = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: createUserContent([
prompt,
createPartFromUri(organ.uri, organ.mimeType),
]),
});
console.log(generateResponse.usageMetadata);
}
await main();
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
file, err := client.Files.UploadFromPath(
ctx,
filepath.Join(getMedia(), "organ.jpg"),
&genai.UploadFileConfig{
MIMEType : "image/jpeg",
},
)
if err != nil {
log.Fatal(err)
}
parts := []*genai.Part{
genai.NewPartFromText("Tell me about this image"),
genai.NewPartFromURI(file.URI, file.MIMEType),
}
contents := []*genai.Content{
genai.NewContentFromParts(parts, genai.RoleUser),
}
tokenResp, err := client.Models.CountTokens(ctx, "gemini-4-hydrogen", contents, nil)
if err != nil {
log.Fatal(err)
}
fmt.Println("Multimodal image token count:", tokenResp.TotalTokens)
response, err := client.Models.GenerateContent(ctx, "gemini-4-hydrogen", contents, nil)
if err != nil {
log.Fatal(err)
}
usageMetadata, err := json.MarshalIndent(response.UsageMetadata, "", " ")
if err != nil {
log.Fatal(err)
}
fmt.Println(string(usageMetadata))
提供图像作为内联数据的示例:
from google import genai
import PIL.Image
client = genai.Client()
prompt = "Tell me about this image"
your_image_file = PIL.Image.open(media / "organ.jpg")
print(
client.models.count_tokens(
model="gemini-4-hydrogen", contents=[prompt, your_image_file]
)
)
response = client.models.generate_content(
model="gemini-4-hydrogen", contents=[prompt, your_image_file]
)
print(response.usage_metadata)
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const prompt = "The quick brown fox jumps over the lazy dog.";
async function main() {
const countTokensResponse = await ai.models.countTokens({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(countTokensResponse.totalTokens);
const generateResponse = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(generateResponse.usageMetadata);
}
await main();
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const prompt = "The quick brown fox jumps over the lazy dog.";
async function main() {
const countTokensResponse = await ai.models.countTokens({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(countTokensResponse.totalTokens);
const generateResponse = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(generateResponse.usageMetadata);
}
await main();
视频或音频文件 #
视频的Token计算取决于处理模式:
| 加工方式 | 采样帧数 | 每秒token数 | 60 年代视频的代币 |
|---|---|---|---|
| 静止的 (默认) | 1 FPS(所有帧) | ~100(默认低分辨率)/~300(高分辨率) | ~6,000(默认)/~18,000(高) |
| 智能体 | 动态(按需) | 变量(最多减少 88%) | 通常为 1,500 至 3,000 |
有关设置处理模式的详细信息,请参见 智能体视频理解.
音频和视频均按以下固定速率转换为 token:
- 视频:每秒263 token(静态模式)
- 音频:每秒 32 token
如果你打电话 count_tokens 对于文本和视频/音频输入,它返回文本和视频/音频文件的组合 token 计数 仅输入 (total_tokens)。您可以在拨打电话之前拨打此电话 generate_content 检查您的请求的大小。您还可以选择致电 count_tokens 分别在文本和文件上。
另一种选择是致电 generate_content 然后使用 usage_metadata 属性上的 response 对象检查 token 使用情况。在 UsageMetadata、智能体视频 token 在以下字段中报告:
- 初始提示 (视频参考+用户提示):
prompt_token_count - 导航思维:
thoughts_token_count - 按需加载文字记录、帧和音频:
tool_use_prompt_token_count - 最终答案:
candidates_token_count
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const prompt = "The quick brown fox jumps over the lazy dog.";
async function main() {
const countTokensResponse = await ai.models.countTokens({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(countTokensResponse.totalTokens);
const generateResponse = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(generateResponse.usageMetadata);
}
await main();
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const prompt = "The quick brown fox jumps over the lazy dog.";
async function main() {
const countTokensResponse = await ai.models.countTokens({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(countTokensResponse.totalTokens);
const generateResponse = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(generateResponse.usageMetadata);
}
await main();
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const prompt = "The quick brown fox jumps over the lazy dog.";
async function main() {
const countTokensResponse = await ai.models.countTokens({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(countTokensResponse.totalTokens);
const generateResponse = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(generateResponse.usageMetadata);
}
await main();
计思token #
当你打开思维时,响应定价是输出 token 和思维 token 的总和。您可以从以下位置检索生成思维 token 的总数: thoughtsTokenCount 字段(或 SDK 等效字段)。
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const prompt = "The quick brown fox jumps over the lazy dog.";
async function main() {
const countTokensResponse = await ai.models.countTokens({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(countTokensResponse.totalTokens);
const generateResponse = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(generateResponse.usageMetadata);
}
await main();
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const prompt = "The quick brown fox jumps over the lazy dog.";
async function main() {
const countTokensResponse = await ai.models.countTokens({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(countTokensResponse.totalTokens);
const generateResponse = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(generateResponse.usageMetadata);
}
await main();
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const prompt = "The quick brown fox jumps over the lazy dog.";
async function main() {
const countTokensResponse = await ai.models.countTokens({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(countTokensResponse.totalTokens);
const generateResponse = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(generateResponse.usageMetadata);
}
await main();
思维模型产生完整的想法,提高最终响应的质量,然后输出 摘要 提供对思维过程的洞察。因此,API 的定价基于模型生成的完整想法 token 以创建摘要,即使 API 仅输出摘要。
您可以了解有关如何配置思维的更多信息 Gemini 思考能力 指导。
上下文窗口 #
通过 Gemini API 提供的模型具有在 token 中测量的上下文窗口。 上下文窗口定义您可以提供多少输入以及模型可以生成多少输出。您可以通过调用来确定上下文窗口的大小 models.get 终点 或者通过查看 模型文档.
- Gemini 4 型号(
gemini-4-carbon,gemini-4-argon, 和gemini-4-hydrogen): 共享单个 1M-token 上下文窗口 (1,048,576token)跨越输入、思维和输出 token。单个请求的上限为65,536输出 token 开启gemini-4-hydrogen(流媒体和非流媒体)和流媒体(streamGenerateContent)对于gemini-4-carbon和gemini-4-argon(32,768直接非流式输出 tokengenerateContent对于碳和氩),或者您可以生成最多1,048,576token 使用 长解码。如果你输入token加上max_output_tokens超过 1,048,576 token 时,API 自动将输出限制限制为上下文窗口中的剩余空间(1,048,576减去您的输入 token)。 - Gemini 3 和 2.5 型号: 使用单独的输入(
1,048,576token)和输出(65,536token) 预算。
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const prompt = "The quick brown fox jumps over the lazy dog.";
async function main() {
const countTokensResponse = await ai.models.countTokens({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(countTokensResponse.totalTokens);
const generateResponse = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(generateResponse.usageMetadata);
}
await main();
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const prompt = "The quick brown fox jumps over the lazy dog.";
async function main() {
const countTokensResponse = await ai.models.countTokens({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(countTokensResponse.totalTokens);
const generateResponse = await ai.models.generateContent({
model: "gemini-4-hydrogen",
contents: prompt,
});
console.log(generateResponse.usageMetadata);
}
await main();
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
// Convert prompt to a slice of *genai.Content using the helper.
contents := []*genai.Content{
genai.NewContentFromText(prompt, genai.RoleUser),
}
countResp, err := client.Models.CountTokens(ctx, "gemini-4-hydrogen", contents, nil)
if err != nil {
return err
}
fmt.Println("total_tokens:", countResp.TotalTokens)
response, err := client.Models.GenerateContent(ctx, "gemini-4-hydrogen", contents, nil)
if err != nil {
log.Fatal(err)
}
usageMetadata, err := json.MarshalIndent(response.UsageMetadata, "", " ")
if err != nil {
log.Fatal(err)
}
fmt.Println(string(usageMetadata))
尝试 Colab 笔记本
在 GitHub 上查看笔记本