长输出
长解码让 Gemini 4 型号(gemini-4-carbon, gemini-4-argon, 和 gemini-4-hydrogen)生成超过深度推理任务的单请求输出限制,最高可达统一的 1M-token 上下文窗口(1,048,576 token 在输入、思维和输出之间共享)。
仅更改模型 ID 并不能启用长解码。无需额外设置,输出停止在 64K token 上 gemini-4-hydrogen (流式和非流式),以及 64K token 用于流式或 SDK 调用,32K token 用于直接非流式 REST 调用 gemini-4-carbon 和 gemini-4-argon。打开长解码的最快方法是升级 Google GenAI SDK 并设置 max_output_tokens 大于 65,536. 本指南介绍了解码的工作时间、何时使用以及如何使用 generateContent.
解码需要多长时间 #
单个流请求、SDK 请求或 gemini-4-hydrogen 非流式 REST 请求最多生成 64K token,而直接非流式 REST 请求生成 gemini-4-carbon 或 gemini-4-argon 生成最多 32K token。当响应需要更多 token 时,模型会跨多个请求和响应跃点生成响应,每个跃点从前一跃点停止的位置继续。
- 统一输入输出token限制: 输入、思考、函数调用、最终响应共享一个1M-token窗口。输出最多可使用 1,048,576 减去输入 token。
- 每个跃点的上限: 一跳返回最多 65,536 输出 token(或者在直接非流式 REST 调用上最多返回 32,768)
gemini-4-carbon和gemini-4-argon). - 继续信号: 如果模型达到上限并且还剩下 token,则响应以以下内容结束
finish_reason: CONTINUATION和一个continuation_token. - 下一跳: 客户端再次使用 token 发送相同的请求。模型从停止的地方继续。
- 所有跃点的总计:
max_output_tokens将所有跃点的总思维和输出 token 设置在一起。 - 停止信号: 当模型使用所有
max_output_tokens,响应结束于finish_reason: MAX_TOKENS.
在困难问题上,跳跃可以将其所有 token 花在内部思考上,并返回带有 continuation_token。这是正常的,最终答案会在稍后的跳跃中到达。
默认输出限制 #
如果没有长解码,单个请求将在以下每个请求限制处停止:
- 流式请求、非流式请求通过Google GenAI SDK(
generate_content),以及所有gemini-4-hydrogen呼叫: 默认为 64K (65,536) 输出 token。 - 直接非流式 REST 调用(
generateContent) 上gemini-4-carbon和gemini-4-argon: 默认为 32K (32,768) 输出 token。设置max_output_tokens在对 Carbon 或 Argon 进行非流式 REST 调用时大于 32,768continuation_token返回一个400错误。
| 你如何称呼模型 | 无长解码的输出限制 | 启动时长解码 | 该怎么办 |
|---|---|---|---|
| Google GenAI SDK,最新版本 | 64K | 是的,SDK 继续为您服务 | 套装 max_output_tokens. |
| Google GenAI SDK,旧版本,非流式传输 | 64K | 否 | 升级 SDK。 |
REST streamGenerateContent | 64K | 是的,用你自己的循环 | 写一个循环。参见 选项 2. |
REST generateContent | 64K (gemini-4-hydrogen) 或 32K (gemini-4-carbon, gemini-4-argon) | 是的,用你自己的循环 | 写一个循环。参见 选项 2. |
何时使用长解码 #
大多数请求在单个请求限制内完成(64K token 或 32K token,用于直接非流式 REST 调用) gemini-4-carbon 和 gemini-4-argon)。当响应需要比单个请求允许的更多组合思考和输出 token 时,请使用长解码。提高 max_output_tokens 为模型提供了更高的上限来推理难题,而不是让标准答案变得更长。
| 工作量 | 使用长解码? | 为什么 |
|---|---|---|
| 硬数学、科学、研究和形式证明 | 是的 | 该模型可以花费超过 64K token 来探索和检查其推理。 |
| 最困难的编码和智能体任务 | 是的 | 有些任务需要比 64K token 多的思考和代码一次响应。大多数编码和智能体任务在 64K 下完成。 |
| 在输出限制处停止的评估线束 | 是的 | 当模型花费整个 64K 或 32K 请求进行思考时,长解码可以防止答案被切断。 |
| 聊天、问答、总结、分类、提取 | 否 | 这些任务在 32K token 下很好地完成。 |
| 固定长度的请求,例如“写一本700,000字的书” | 否 | 该模型不遵循长度目标。 |
| 智能体在多次短回合中调用工具 | 否 | 每个回合都很短。每转的大输出快速填充统一的 1M 输入和输出窗口。 |
| 接近 1M 输入限制时提示 | 否 | 输出只能使用 1M 减去您的输入。 |
| 延迟敏感的请求 | 否 | 长解码可能会运行几分钟。 |
设定高 max_output_tokens 给了模型在难题上思考更长时间的空间,但模型仍然决定写多少。要控制模型使用多少推理工作,请设置 thinking_level.
开启长解码 #
您可以使用 Google GenAI SDK(针对大多数应用程序推荐选项 1,)自动运行长解码,或编写您自己的连续循环(选项 2)。两个选项均支持完整的 1M-token 上下文窗口。
| 选项 1:Google GenAI SDK(推荐) | 选项 2:您自己的流循环 | 选项 2:您自己的非流循环 | |
|---|---|---|---|
| 每个跳跃由谁开始 | SDK。你设定 max_output_tokens. | 您的代码,在每个检查点或在丢弃流之后 | 您的代码,每个 64K token (gemini-4-hydrogen) 或 32K token (gemini-4-carbon, gemini-4-argon) |
| 每个请求的token | 64K 每跳 | 每个流的 64K,在碳和氩上的 32K 之后(或在氢上的 64K 之后)每个 5K token 有一个检查点 | 64K (gemini-4-hydrogen) 或 32K (gemini-4-carbon, gemini-4-argon)根据要求 |
| 每个请求的时间限制 | 20 分钟 | 20 分钟 | 20 分钟 |
| 存储 | 无服务器存储 | 无服务器存储 | 无服务器存储 |
| 最适合 | 大多数应用 | REST 调用者和自定义流式传输工具 | 简单的评估工具 |
加密的 continuation_token 在请求之间携带模型的状态,因此服务器上不会存储任何内容。
选项 1:使用 Google GenAI SDK(推荐) #
在最新的Google GenAI SDK中, automatic_continuation 默认情况下,流式和非流式调用均启用,因此您无需设置它。当你设置 max_output_tokens 超过每个请求上限时,SDK 会自动运行连续跳跃并返回一个组合响应。
- 升级 SDK。
pip install -U "google-genai>=2.30.1"
npm install "@google/genai@>=2.29.1"
- 套装
max_output_tokens大于 65,536.
from google import genai
from google.genai import types
client = genai.Client() # Reads GEMINI_API_KEY
response = client.models.generate_content(
model="gemini-4-carbon",
contents="Write a complete, rigorous proof of the prime number theorem.",
config=types.GenerateContentConfig(
max_output_tokens=262_144, # Total thinking and output for all hops
thinking_config=types.ThinkingConfig(thinking_level="high"),
automatic_continuation=True, # Default. Shown for clarity.
),
)
print(response.text)
print("Finish reason:", response.candidates[0].finish_reason)
print("Prompt size:", response.usage_metadata.initial_prompt_token_count)
print("Billed tokens:", response.usage_metadata.total_token_count)
import { GoogleGenAI, ThinkingLevel } from "@google/genai";
const ai = new GoogleGenAI({}); // Reads GEMINI_API_KEY
const response = await ai.models.generateContent({
model: "gemini-4-carbon",
contents: "Write a complete, rigorous proof of the prime number theorem.",
config: {
maxOutputTokens: 262144, // Total thinking and output for all hops
thinkingConfig: { thinkingLevel: ThinkingLevel.HIGH },
automaticContinuation: true, // Default. Shown for clarity.
},
});
console.log(response.text);
console.log("Finish reason:", response.candidates?.[0]?.finishReason);
console.log("Prompt size:", response.usageMetadata?.initialPromptTokenCount);
console.log("Billed tokens:", response.usageMetadata?.totalTokenCount);
请记住以下几点:
- 流媒体:
generate_content_stream(Python)和generateContentStream(JavaScript)也继续为您服务。如果流在检查点后丢失,则 SDK 从该检查点恢复。 - 超时: 超时和重试适用于每一跳,而不是整个运行。
- 手动控制: 要自己运行循环,请设置
automatic_continuation=False(Python)或automaticContinuation: false(JavaScript)。然后按照选项 2. - 用途: 使用字段显示所有跃点的总和。要获取提示的大小,请阅读
initial_prompt_token_count。参见 计数 token.
选项 2:编写自己的循环 #
如果您直接调用 REST、使用没有最新 SDK 的语言或需要完全控制,请编写自己的循环。您还可以参考我们的 Google GenAI SDK 实现 Python 和 JavaScript/TypeScript 作为参考。
请遵循以下规则:
- 在每一跳上发送相同的请求。 发送原件
contents,system_instruction,tools, 和generation_config。保留max_output_tokens一样的。 - 不要将部分输出添加到
contents. 该continuation_token承载模型的状态,包括其思维。 - 仅发送最新的token。 每个 token 都包含所有早期进度。
- 继续同时
finish_reason是CONTINUATION. 因任何其他完成原因而停止。 - 在最后一跳之后连接零件。 将所有跃点的部分组合成对话历史记录的一个模型回合。
from google import genai
from google.genai import types
client = genai.Client() # Reads GEMINI_API_KEY
PROMPT = "Write a complete, rigorous proof of the prime number theorem."
parts = []
token = None
while True:
response = client.models.generate_content(
model="gemini-4-carbon",
contents=PROMPT, # The original contents on every request
config=types.GenerateContentConfig(
max_output_tokens=262_144, # The same total on every request
thinking_config=types.ThinkingConfig(thinking_level="high"),
automatic_continuation=False, # You run the loop
continuation_token=token,
),
)
candidate = response.candidates[0]
if candidate.content and candidate.content.parts:
parts.extend(candidate.content.parts)
token = candidate.continuation_token
if candidate.finish_reason != types.FinishReason.CONTINUATION or not token:
break
print("".join(p.text for p in parts if p.text and not p.thought))
print("Finish reason:", candidate.finish_reason)
import { GoogleGenAI, ThinkingLevel } from "@google/genai";
const ai = new GoogleGenAI({}); // Reads GEMINI_API_KEY
const PROMPT = "Write a complete, rigorous proof of the prime number theorem.";
const parts = [];
let token = undefined;
let candidate = undefined;
while (true) {
const response = await ai.models.generateContent({
model: "gemini-4-carbon",
contents: PROMPT, // The original contents on every request
config: {
maxOutputTokens: 262144, // The same total on every request
thinkingConfig: { thinkingLevel: ThinkingLevel.HIGH },
automaticContinuation: false, // You run the loop
continuationToken: token,
},
});
candidate = response.candidates?.[0];
if (candidate?.content?.parts) {
parts.push(...candidate.content.parts);
}
token = candidate?.continuationToken;
if (candidate?.finishReason !== "CONTINUATION" || !token) {
break;
}
}
console.log(parts.filter((p) => p.text && !p.thought).map((p) => p.text).join(""));
console.log("Finish reason:", candidate?.finishReason);
# Hop 1: send the request with max_output_tokens.
curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-carbon:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"role": "user", "parts": [{"text": "Write a complete, rigorous proof of the prime number theorem."}]}],
"generationConfig": {
"maxOutputTokens": 262144,
"thinkingConfig": {"thinkingLevel": "high"}
}
}'
# Hop 2: if finishReason is CONTINUATION, send the same request plus the token.
curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-carbon:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"role": "user", "parts": [{"text": "Write a complete, rigorous proof of the prime number theorem."}]}],
"generationConfig": {
"maxOutputTokens": 262144,
"thinkingConfig": {"thinkingLevel": "high"}
},
"continuationToken": "TOKEN_FROM_HOP_1"
}'
完全花在思考上的一跳返回空 text 使用 finishReason: "CONTINUATION"。将此视为正常进度并请求下一跳:
{
"candidates": [{
"content": {"role": "model", "parts": [{"text": ""}]},
"finishReason": "CONTINUATION",
"continuationToken": "CiQ4ZmQ3..."
}],
"usageMetadata": {
"promptTokenCount": 142,
"candidatesTokenCount": 0,
"thoughtsTokenCount": 32768,
"totalTokenCount": 32910
}
}
流媒体循环 还需要一项规则。第一个 32,768 token 上后 gemini-4-carbon 和 gemini-4-argon (或在 65,536 token 之后 gemini-4-hydrogen,从第二跳开始),流每个 5,000 token 发送一个检查点 token。将新块保留在待处理列表中。当一个块有一个 continuation_token,将挂起的块移动到提交的输出并保存 token。如果流丢失,则丢弃挂起的块并从最后一个 token 恢复。如果流在第一个检查点之前丢失,请再次发送原始请求。
套装 max_output_tokens #
max_output_tokens 设置所有跃点的思维和输出的组合限制。降低它并不会让模型思考得更简洁,反而会更快地切断响应。
| 你的工作量 | 推荐 max_output_tokens |
|---|---|
| 限制低于 32K 的现有应用程序 | 将其提高到 32,768. |
| 长编码和智能体任务 | 从 65,536. 开始 |
| 硬数学、科学、研究和证明 | 测试从 262,144 到 1,048,576 的值减去您的输入 token。 |
要使用更少的 token,请降低 thinking_level。使用 high 用于最困难的推理任务。使用 medium (默认)适用于大多数编码和智能体工作。使用 low 对于不太复杂的任务。
处理长时间运行的请求 #
由于 Gemini 4 模型在解决难题时比 Gemini 3.x 模型考虑的时间更长,因此您应该增加客户端超时,以便长请求不会过早断开连接。
- 非流式通话: 服务器在 10 分钟后关闭连接。
- 流媒体通话: 服务器在 20 分钟后关闭流。
- 客户端超时: 将 HTTP 读取超时设置为 20 分钟。 3 分钟或 5 分钟超时会提前停止请求。
在 Python 中,设置客户端的超时时间(以毫秒为单位):
client = genai.Client(http_options=types.HttpOptions(timeout=1_200_000)) # 20 minutes
对于客户端轮询的作业,Interactions API 在服务器上运行长解码。参见 后台执行.
当模型使用所有输出时恢复 token #
当响应结束时 MAX_TOKENS,它仍然包括一个 continuation_token。你有两个选择:
- 继续: 使用 token 和更高版本发送相同的请求
max_output_tokens。该值必须高于目前使用的 token。否则,API 返回 400 错误。 - 重新开始: 发送具有更高级别的原始请求
max_output_tokens并且没有 token。您支付两次运行的费用。
计数 token #
通过自动继续, usage_metadata 报告所有跃点的总数。 SDK 将每个计数字段相加: prompt_token_count, cached_content_token_count, candidates_token_count, thoughts_token_count, 和 total_token_count.
prompt_token_count 将每一跳的输入token相加。每个跃点都会将您的提示以及迄今为止生成的所有内容发送回模型作为输入,因此在以后的每个跃点中都会再次计算相同的 token。例如,对于 Google GenAI SDK,产生 200,000 token 思考和输出的 1,000-token 提示需要四跳:
| 啤酒花 | 发送到模型的输入 | 输入 token |
|---|---|---|
| 1 | 提示 | 1,000 |
| 2 | 提示+跳跃1 | 66,536 |
| 3 | 提示 + 跳跃 1 和 2 | 132,072 |
| 4 | 提示 + 跳转 1 到 3 | 197,608 |
| 总计 | 397,216 |
prompt_token_count 关于 397,000 token 的报告(重复的跳跃输入通过隐式缓存自动折扣 95%),以及 total_token_count 报告有关 597,000 token,即使实际上下文大小仅约为 201,000 token:1,000-token 提示加上 200,000 token 的思考和输出。开 gemini-4-carbon 和 gemini-4-argon,非流式 REST 循环使用 32K 跳数,因此相同输出需要七跳并报告 695,128 输入 token (gemini-4-hydrogen 对流式传输和非流式传输使用 64K 跃点)。
| 你如何称呼模型 | 什么 usage_metadata 节目 | 为了成本 | 对于提示尺寸 |
|---|---|---|---|
| Google GenAI SDK,自动继续(默认) | 所有跃点的总计 | 按原样阅读用法字段。 | 阅读 usage_metadata.initial_prompt_token_count (Python)或 usageMetadata.initialPromptTokenCount (JavaScript)。 |
SDK 与 automatic_continuation=False,或休息 | 每个响应一跳 | 跨跃点添加每个字段。 | 阅读 prompt_token_count 从第一跳开始。 |
prompt_token_count 和 total_token_count 是每一跳的总和,而不是上下文的大小。不要使用它们来决定何时总结或修剪您的对话历史记录(上下文压缩),或强制执行上下文限制。要估计上下文大小,请将表中的提示大小添加到 candidates_token_count 和 thoughts_token_count.
在运行长解码之前更新您的智能体框架、评估工具或代理:
- 智能体及评估工具: 如果您的代码压缩上下文或在 token 限制处停止运行,请使用
initial_prompt_token_count(或者第一跳的prompt_token_count在 REST 中)而不是求和prompt_token_count。在一跳中完成的响应在两个字段中报告相同的值,因此简短的测试不会显示问题。 - 调用 REST 的代理和网关: 每个 REST 响应仅报告其自己的跃点。添加跨跃点的每个字段以计算成本,并保留第一个跃点
promptTokenCount作为提示尺寸。否则,对于同一请求,您的用户看到的数字与 SDK 用户看到的数字不同。 - 日志和序列化响应: SDK 计算
initial_prompt_token_count在客户端上。它不在 REST 响应或 SDK 的 JSON 输出中,例如model_dump()。如果稍后需要,请将其保存为单独的值。
如果您在自己的循环中进行流式传输, usage_metadata 在每个流中是累积的。仅保留每个流的最后一个值,然后跨跃点添加值。
了解计费 #
您为每一跳中的每个 token 付费,包括仅包含思考的跳数。
- 缓存折扣: 隐式缓存将每一跳中的重复输入折扣 95%。在推出期间,缓存输入的成本为每 1M token(而不是 $2.00)$0.10。
- 缓存过期: 如果不使用 15 到 20 分钟,缓存就会过期。跳跃之间的长时间暂停会再次收取全部输入速率。
- 失败的非流跃点: 您只需在回复完成后付费。失败或丢弃的请求成本为 $0.
- 丢弃的流: 在第一个检查点(碳和氩上为 32K token,或氢上为 64K token)之前掉落的流将花费 $0. 之后,您最多需要支付最后一个检查点 token,因为您可以从中恢复。
问题排查 #
| 症状 | 原因和修复 |
|---|---|
输出在 64K 或 32K 处停止 CONTINUATION | 该模型还剩下 token,但没有继续请求。升级SDK或添加循环。 |
输出在 64K 或 32K 处停止 MAX_TOKENS | max_output_tokens 未设置或太低。设置为大于65,536. |
空文本与 MAX_TOKENS | 该模型在思维上全部采用了token。提高 max_output_tokens 或更低 thinking_level. |
| 400:“继续 token 已使用输出 token...” | max_output_tokens 不高于目前使用的token。举起它。 |
错误为 thinking_level: "minimal",或对于 thinking_budget 使用 thinking_level | Gemini 4 型号(gemini-4-carbon, gemini-4-argon, 和 gemini-4-hydrogen)不支持 minimal。使用 low, medium, 或 high (加上 xhigh 在 gemini-4-hydrogen)。套装 thinking_level 或 thinking_budget,不是两者。 |
警告: thinking_budget, temperature, top_p, 或 top_k | Gemini 4 型号忽略或映射这些字段。使用 thinking_level,并删除采样参数。 |
| 请求在 3 或 5 分钟后结束 | 客户端超时时间太短。将其设置为 20 分钟。 |
| 上下文压缩开始得太早 | 线束读取输入的总和。阅读 initial_prompt_token_count 相反。 |
限制 #
- OpenAI 兼容性端点: 长解码不可用。输出在每个请求上限处停止。
- 较旧的 SDK: 低于注释中最低值的版本不会自动继续。
- 长度: 该模型不遵循 token 长度或字数目标。
清单 #
- 将Google GenAI SDK升级到最低版本。
- 套装
max_output_tokens大于 65,536. - 使用
thinking_level(low,medium, 或high),不thinking_budget. - 将 HTTP 读取超时设置为 20 分钟。
- 使用
initial_prompt_token_count用于上下文大小和压缩。 - 在进行大型评估之前运行一个提示作为测试。