长时间解码

借助长解码,Gemini 4 Argon 可以生成超过 6.4 万个 token,以执行深度推理任务,最多可生成统一的 100 万个 token 的上下文窗口(输入、思考和输出共用 1,048,576 个 token)。在 Interactions API 中,您可以启用后台执行的长解码,以便我们的服务器自动生成并将每个 6.4 万个跃点合并到一次互动中。

长解码的工作原理

单次模型调用最多可生成 6.4 万个 token。如果回答需要超过 6.4 万个 token,服务器会以 6.4 万个跃点为单位生成,并从上一个跃点停止的位置继续。每个跃点都会在同一互动 ID 下的 interaction.steps 中添加一个 model_output 步骤,因此您需要将这些步骤合并起来才能读取完整回答:

  1. 您可以使用 background: true 和 max_output_tokens(大于 65,536,最多为 100 万)创建互动。
  2. 服务器会生成第一个跃点,最多 6.4 万个 token。
  3. 服务器会从上一个跃点停止的位置开始下一个跃点,并重复此过程,直到模型完成或用完所有 max_output_tokens。
  4. 您可以轮询互动或流式传输互动,以获取结果。

Python

import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-argon",
    input="Write a complete, rigorous proof of the prime number theorem.",
    background=True,
    generation_config={
        "max_output_tokens": 262144,
        "thinking_level": "high",
    },
)

while interaction.status in ("in_progress", "queued"):
    time.sleep(5)
    interaction = client.interactions.get(id=interaction.id)

# Each hop adds a model_output step, so join the text of all of them.
text = "".join(
    content.text
    for step in interaction.steps
    if step.type == "model_output"
    for content in step.content
    if content.type == "text"
)
print(text)
print("Status:", interaction.status)
print("Usage:", interaction.usage)

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

let interaction = await client.interactions.create({
  model: "gemini-4-argon",
  input: "Write a complete, rigorous proof of the prime number theorem.",
  background: true,
  generation_config: {
    max_output_tokens: 262144,
    thinking_level: "high",
  },
});

while (interaction.status === "in_progress" || interaction.status === "queued") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await client.interactions.get(interaction.id);
}

// Each hop adds a model_output step, so join the text of all of them.
const text = interaction.steps
  .filter((step) => step.type === "model_output")
  .flatMap((step) => step.content ?? [])
  .filter((content) => content.type === "text")
  .map((content) => content.text)
  .join("");
console.log(text);
console.log("Status:", interaction.status);
console.log("Usage:", interaction.usage);

REST

# 1. Create the background interaction. It returns an ID right away.
ID=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-argon",
    "input": "Write a complete, rigorous proof of the prime number theorem.",
    "background": true,
    "generation_config": {"max_output_tokens": 262144, "thinking_level": "high"}
  }' | jq -r '.id')

# 2. Poll until the status is no longer in_progress or queued.
#    The REST response has no output_text field, so join the text of every model_output step.
while true; do
  RESP=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$ID" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
  STATUS=$(echo "$RESP" | jq -r '.status')
  if [[ "$STATUS" != "in_progress" && "$STATUS" != "queued" ]]; then
    echo "$RESP" | jq -r '[.steps[]? | select(.type == "model_output") | .content[]? | select(.type == "text") | .text] | join("")'
    echo "$RESP" | jq '{status, usage}'
    break
  fi
  sleep 5
done

输出限制

流式传输和非流式传输互动的默认输出 token 限制为 6.4 万个,因此回答最多 6.4 万个 token 时无需更改任何代码。如需生成超过 6.4 万个 token,请开启后台执行并提高 max_output_tokens。

互动创建方式 输出限制
background: false(流式传输或非流式传输) 65,536 个 token。如果值超过 65,536,则会返回 400 错误。长解码功能即将推出。
background: true,未设置 max_output_tokens 65,536 个 token
background: true,max_output_tokens 大于 65,536 您的 max_output_tokens,最多为 1,048,576 减去您的输入

何时使用长解码

大多数请求会在 6.4 万个 token 内完成。仅当一个回答需要比这更多的思考和输出时,才使用长解码。

工作负载 使用长解码? 原因
复杂的数学、科学、研究和正式证明 是 模型可以花费超过 6.4 万个 token 来探索和检查其推理。
最难的编码和智能体任务 是 某些任务在一个回答中需要超过 6.4 万个 token 的思考和代码。大多数编码和智能体任务会在 6.4 万个 token 内完成。
在输出限制处停止的评估工具 是 当模型花费整个 6.4 万个 token 的回答进行思考时,长解码可防止回答被截断。
聊天、问答、摘要、分类和提取 否 这些任务会在 3.2 万个 token 内完成。
请求固定长度,例如“写一本 70 万字的书” 否 模型不会遵循长度目标。
以许多短轮次调用工具的智能体 否 每个轮次都很短。每个轮次的大量输出会快速填满共享上下文窗口。
接近输入限制的提示 否 输出只能使用 1,048,576 个 token 减去您的输入。
对延迟时间敏感的请求 否 长解码可以运行几分钟。

设置较高的 max_output_tokens 可让模型有更多时间思考难题,但模型仍会决定要编写多少内容。如需控制模型使用的推理工作量,请设置 thinking_level。

选择运行长解码的方式

后台执行是在 Interactions API 上运行长解码的最简单方式。GenerateContent API 提供客户端续传功能,您的代码会启动每个跃点。它即将推出到 Interactions API,作为管理您自己的弹性的一种更高级选项。

后台执行 (Interactions API) 客户端续传 (GenerateContent API)
谁启动每个跃点 我们的服务器 生成式 AI SDK 或您自己的代码
每个请求的 token 数 您的 max_output_tokens,在一次互动中 每个流 6.4 万个,每个非流式传输请求 3.2 万个
运行时间 最长 24 小时 20 分钟
存储 需要 store: true 服务器上未存储任何内容。
适用场景 运行长解码的最简单方式 更精细地控制重试,以便您可以构建自己的退避、错误处理和弹性

如需使用客户端续传,请参阅使用 GenerateContent API 进行长解码。

流式传输长解码

如需在输出和思考总结到达时对其进行流式传输,请添加 stream: true 和 thinking_summaries: "auto"。长流可能会中断,因此您的客户端必须重新连接。请按照后台执行指南中的重新连接模式进行操作。长解码会添加以下规则:

  • 保存互动 ID: 从 interaction.created 事件中读取。
  • 保存每个 event_id: event_id 可以出现在 interaction.status_update 事件中,而不仅仅是文本增量中。
  • 使用 last_event_id 重新连接: 使用 interactions.get 和最后一个 stream: true 调用 event_id。流会在该事件之后继续。
  • 读取到末尾: 重新连接后,请先将流读取到末尾,然后再检查状态。即使互动完成,服务器也会重播错过的事件。
  • 设置较长的超时时间: 将 HTTP 读取超时时间设置为每个流 15 到 20 分钟。
  • 以 5,000 个 token 的数据块输出: 在前 6.4 万个 token(大约前 10 分钟)之后,流会以大约 5,000 个 token 的数据块发送输出。数据块之间的暂停是正常的。互动不会卡住,因此请保持连接处于打开状态。

后台状态

后台互动最多可以运行 24 小时。一旦状态不再是 in_progress 或 queued,请使用下表处理终端状态:

状态 含义 您需要采取的措施
completed 模型已完成。 合并 steps 中的 model_output 步骤并读取 usage。如需继续对话,请将此互动的 id 作为 previous_interaction_id 传递。
requires_action 模型请求调用工具。 运行该工具。然后使用此互动的 id 发送结果。
incomplete 模型已用完所有 max_output_tokens。如果模型仍在思考,文本可能为空。 使用更高的 max_output_tokens 再次发送请求。
failed 服务器无法完成,或者互动运行时间超过 24 小时。 重试请求。如果再次失败,请与支持团队分享互动 id。
cancelled 您已取消互动。 读取 usage 以查看已结算的 token。

如需停止正在运行的互动,请在 Python 中调用 client.interactions.cancel(id=interaction.id),在 JavaScript 中调用 client.interactions.cancel(interaction.id),或在 REST 中调用 POST /v1beta/interactions/{id}/cancel。

设置 max_output_tokens

max_output_tokens 设置了整个互动中思考和输出的组合限制。降低此值不会使模型思考得更简洁,而是会更快地截断回答。

您的工作负载 建议的 max_output_tokens
现有应用的限制低于 3.2 万 提高到 32,768。无需后台执行。
长编码和智能体任务 从 65,536(默认值)开始。无需后台执行。
复杂的推理、复杂的数学、科学和证明 设置 background: true 并从 262,144 开始,最多为 1,048,576 减去您的输入 token。

如需使用更少的 token,请降低 thinking_level。对于最难的推理任务,请使用 high。对于大多数编码和智能体工作,请使用 medium(默认值)。

统计 token 数量

interaction.usage 会报告所有跃点的总数。读取以下字段:total_input_tokens、total_cached_tokens、total_output_tokens、total_thought_tokens 和 total_tokens。

total_input_tokens 会将每个跃点的输入 token 相加。每个跃点都会将您的提示以及到目前为止生成的所有内容作为输入发送回模型,因此在每个后续跃点中,相同的 token 会再次被统计。例如,一个 1,000 个 token 的提示会生成 20 万个 token 的思考和输出,需要四个跃点:

跃点 发送给模型的输入 输入 token 数
1 提示 1000
2 提示 + 跃点 1 66,536
3 提示 + 跃点 1 和 2 132,072
4 提示 + 跃点 1 到 3 197,608
总计 397,216

total_input_tokens 报告大约 39.7 万个 token(重复的跃点输入会自动通过隐式缓存获得 95% 的折扣),即使实际上下文大小仅为大约 20.1 万个 token:1,000 个 token 的提示加上 20 万个 token 的思考和输出。

在流式传输期间,step.stop 和 interaction.status_update 事件都包含 usage(互动的累计值)。请读取最新的 usage 值,而不是将它们相加。

理解账单

您需要为每个跃点中的每个 token 付费,包括仅包含思考的跃点。

  • 缓存折扣: 隐式缓存会将每个跃点中重复的输入折扣 95%。在优惠期内,缓存输入的费用为每 100 万个 token 0.10 美元,而不是 2.00 美元。
  • 已取消和失败的互动: 您需要为互动结束前完成的所有工作付费。

问题排查

问题 原因和修复方法
输出在 6.4 万处停止 background 为 false,或者未设置 max_output_tokens。将 background: true 和 max_output_tokens 设置为大于 65,536。
400:“尚不支持在 background=false 的情况下使用大于 65536 的 max_output_tokens。” 尚不支持在没有后台执行的情况下进行长解码。设置 background: true。
400:“后台互动需要 store=true” 后台执行需要 store: true。
状态 incomplete,文本为空 模型已将所有 token 用于思考。提高 max_output_tokens 或降低 thinking_level。
上下文压缩过早开始 您的智能体框架或评估工具会读取 total_input_tokens。请参阅统计 token 数量。

限制

  • 没有后台执行,就无法进行长解码: background: false 的互动会在 65,536 个 token 处停止。即将推出支持。
  • 没有长度目标: 模型不会遵循 token 长度或字数目标。

后续步骤