对于需要长时间生成、无需客户端持续保持连接的 Agent 任务,可通过 Interactions API 的 background=True 启动服务器托管长解码,再用 Interaction ID 查询状态;此模式必须启用 store=True。
适合的任务:超长报告、代码或证明生成;由任务队列提交、稍后查询结果的异步 Agent 作业。
不适合的任务:需要立即返回短结果,或工作流要求服务器不存储 Interaction 的任务。
适用的模型版本:gemini-4-hydrogen。
适用的客户端、Agent 或 API:Google Cloud Gemini Enterprise Agent Platform Interactions API;Python Google Gen AI SDK。
推荐的推理档位和参数:长解码可将 max_output_tokens 设为高于 65,536 的值,最高不超过 1,048,576 减去输入 token 数;示例用 HIGH。输入和输出共用 1,048,576 token 上限。
以下示例启动一个后台 Interaction 并轮询至结束。将 PROJECT_ID 替换为 Google Cloud 项目 ID;调用前需通过 ADC 或 API key 完成 Agent Platform 身份验证。
import time
from google import genai
client = genai.Client(
enterprise=True,
project="PROJECT_ID",
location="global",
)
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="撰写一份完整的系统迁移实施方案,并列出风险、回滚步骤和验收项。",
background=True,
store=True,
generation_config={
"max_output_tokens": 256000,
"thinking_level": "high",
},
)
while interaction.status in ("queued", "in_progress"):
time.sleep(10)
interaction = client.interactions.get(id=interaction.id)
print(f"Status: {interaction.status}")
print(interaction.output_text)安装或升级 SDK:
pip install --upgrade "google-genai>=2.34.0"在 Google Cloud 项目中准备 Agent Platform 访问,并通过 ADC 或 API key 认证。
安装 google-genai 2.34.0 或更高版本。该版本的 Interactions API 支持 SDK 自动续接;后台模式由服务端托管续接。
创建 Interaction 时设置 background=True 与 store=True,并把 max_output_tokens 设为大于 65,536 的预算。
保存返回的 Interaction ID。后台执行期间,使用 client.interactions.get(id=...) 轮询 queued 或 in_progress 状态。
任务结束后检查状态并读取 output_text。如果任务需要中止,可取消后台 Interaction;达到检查点后,服务会保存 continuation_token,后续可从该点恢复。
Google Cloud 文档给出的后台模式示例明确使用 background=True、store=True、max_output_tokens=256000,并对 queued、in_progress 状态每 10 秒调用一次 interactions.get()。
后台模式的续接由 Agent Platform 服务端执行,不要求客户端持续保持单个请求流;该模式要求存储 Interaction,默认服务端存储期限为 7 天。
后台模式下可从已取消任务的检查点续跑;检查点从已解码 65,536 token 起保存,此后每增加 5,000 token 保存一次。
长解码在 Agent Platform 上仅支持 v1beta1。Google Gen AI SDK 默认使用 v1beta1;如显式切换到 v1,长解码不受支持。
来源:Gemini 4 Hydrogen 开发者指南,页面最后更新于 2026-11-12 UTC。
background=True 需要 store=True,不适用于要求零服务端存储的工作流;Interactions API 的 stateless 模式需用 store=False 并由调用方管理续接。
max_output_tokens 计入思考、工具调用和最终回答。模型输入与输出总计最多 1,048,576 token,单段前台输出上限为 65,536 token;后台托管续接可跨段完成长输出。
长解码只支持 Agent Platform v1beta1。部署时不要把 SDK 的 API 版本覆盖为 v1。
默认 Interaction 保留 7 天;应按任务的数据保留要求处理作业记录。来源示例也提供按倒序删除各 segment 的方式。
文档将 Hydrogen 标注为短周期 GA 模型,并说明至少提前 45 天通知退役;生产工作流应留意模型生命周期公告。
按示例启动后台 Interaction,并分别确认首次创建返回 Interaction ID、处理中状态可查询、结束状态可读取输出。若验证取消与恢复,需在任务运行期间调用取消接口,再使用返回的 continuation_token 和该 Interaction 继续创建请求。本文是文档配置步骤的整理,未在实际 Google Cloud 项目中执行请求。
Gemini 4 Hydrogen