Gemini 4 模型系列包含以下模型:
Gemini 4 Hydrogen (
gemini-4-hydrogen):专为日常编码和 Agentic Workflows、多模态分析以及工具使用而打造,兼顾速度和效率。Gemini 4 Carbon (
gemini-4-carbon):Google 的前沿模型,擅长在编码、金融、法律、网络安全和科学等领域处理复杂的现实任务。Gemini 4 Argon (
gemini-4-argon):Google 的前沿模型,擅长在编码、金融、法律、网络安全和科学等领域处理复杂的实际任务。
本指南介绍了如何发出第一个 Gemini 4 请求,说明了 Gemini 4 的新功能,并解释了从 Gemini 3.8 Flash 或 Gemini 3.1 Pro 迁移时会发生哪些变化。如需了解特定于模型的详细信息,请参阅 Gemini 4 Hydrogen 开发者指南、Gemini 4 Carbon 开发者指南和 Gemini 4 Argon 开发者指南。
快速入门
在开始之前,您必须使用 API 密钥或应用默认凭证 (ADC) 向 Gemini Enterprise Agent Platform 进行身份验证。如需了解详情,请参阅身份验证方法。
安装 Google Gen AI SDK
升级到最新的 google-genai SDK(Python 版为 >= 2.34.0,JavaScript/TypeScript 版为 @google/genai >= 2.32.0):
pip install --upgrade "google-genai>=2.34.0"
设置环境变量
请将 GOOGLE_CLOUD_PROJECT 替换为您的 Google Cloud 项目 ID。
Gemini 4 Hydrogen 和 Gemini 4 Carbon 可在 global 端点以及 us 和 eu 多区域中使用(Gemini 4 Argon 也可在 europe-west2 和 asia-southeast1 中使用):
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
提交第一个请求
Python
from google import genai
client = genai.Client()
response = client.models.generate_content(
model="gemini-4-hydrogen", # Or "gemini-4-carbon"
contents="How does AI work?",
)
print(response.text)
REST
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-carbon:generateContent \
-d '{
"contents": {
"role": "USER",
"parts": { "text": "How does AI work?" }
}
}'
Gemini 4 的新功能
Gemini 4 模型引入了以下功能和 API 变更:
统一的输入和输出 token 限制
Gemini 4 模型的统一限制为 1,048,576 个 token,其中包括输入和输出 token(输出包括思考、函数调用和最终回答)。输出最多可使用 1,048,576 个词元减去输入词元。默认情况下,单个同步请求最多可生成 65,536 个输出 token(对于 4 Carbon 和 4 Argon 上的非流式直接 HTTP 请求,则为 32,768 个 token)。
长解码
当单轮对话需要超过 65,536 个输出 token(或在 4 Carbon 和 4 Argon 上进行非流式前台调用时需要超过 32,768 个 token)时,例如正式证明、复杂的数学或科学问题,或多文件代码生成,Gemini 4 模型在 Interactions API 和 GenerateContent (v1beta1) 上均支持长解码,最多可达 1,048,576 个 token(减去输入 token)。借助最新的 Google Gen AI SDK(Python 版 google-genai >= 2.34.0、JavaScript/TypeScript 版 @google/genai >= 2.32.0、Go 版 >= 1.77.0、Java 版 >= 1.80.0),将 max_output_tokens 设置为大于 65,536(或在 4 Carbon 和 4 Argon 上进行非流式调用时大于 32,768)会自动遵循 continuation_token 跨片段返回单个回答或数据流。在 Interactions API 上,您还可以使用 background=true 运行服务器管理型异步长解码,或在存储 (store=true) 或无状态 (store=false) 循环中手动串联 continuation_token。
如需查看代码示例、SDK 版本要求和实现规则,请参阅 Gemini 4 Hydrogen 开发者指南、Gemini 4 Carbon 开发者指南或 Gemini 4 Argon 开发者指南。
思考等级
使用 thinking_level 控制模型在回答之前进行推理的程度。
Gemini 4 模型支持 LOW、MEDIUM(gemini-4-carbon 和 gemini-4-argon 的默认值)以及 HIGH(gemini-4-hydrogen、gemini-4-carbon-cyber-permissive 和 gemini-4-argon-cyber-permissive 的默认值)。gemini-4-hydrogen 还支持 XHIGH,以实现更深入的推理:
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-4-carbon",
contents="Design a lock-free ring buffer in Rust for multi-producer, single-consumer telemetry ingestion.",
config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(
thinking_level=types.ThinkingLevel.HIGH,
),
),
)
print(response.text)
隐式上下文缓存
Gemini 4 模型支持对 4,096 个或更多 token 的共享提示前缀进行隐式缓存,并且默认启用持久缓存。为了充分利用此功能,请将静态内容(例如代码库或长文档)放在提示的开头。
智能体视频理解
智能体视频理解已正式版。此功能默认处于关闭状态:上传的视频使用 media_processing="static"。如需开启此功能,请将 media_processing 设置为 "agentic"。
采样参数
与 Gemini 3 模型一样,Gemini 4 模型会忽略 temperature、top_p 和 top_k 的自定义值。如需控制输出,请使用 thinking_level 和结构化输出 (response_schema)。
从 Gemini 3 模型迁移
从 Gemini 3.8 Flash 迁移到 Gemini 4 Hydrogen,或从 Gemini 3.1 Pro 迁移到 Gemini 4 Carbon 或 Gemini 4 Argon 时,请注意 Gemini 4 模型在行为上的以下差异:
| 区 | Gemini 3 模型 | Gemini 4 模型 | 您需要采取的措施 |
|---|---|---|---|
| 输入和输出 token 限制 | 输入 (1,048,576) 和输出 (65,536) 限制是分开的 | 输入和输出(其中输出包括思考、函数调用和最终回答)的统一 token 数量上限为 1,048,576 个;默认的单次请求输出 token 数量上限为 65,536 个(4 Carbon 和 4 Argon 上的非流式直接 HTTP 请求为 32,768 个 token),使用长解码时最多可扩展到 1,048,576 个 token | 预算输入和输出。升级到最新的 Google Gen AI SDK,并在 Interactions API 或 GenerateContent 上将 max_output_tokens 设置为大于 65,536(或在自定义循环中使用 background=true 或 continuation_token),以输出超出单次请求限制的内容。 |
thinking_budget |
映射到思考等级 | 返回 HTTP 400 错误 |
使用 thinking_level。 |
thinking_level="MINIMAL" |
支持 | 返回 HTTP 400 错误 |
使用 LOW。 |
| 显式上下文缓存 | 支持 | 不支持 | 移除 cached_content 引用,并将静态内容(4,096 个或更多 token)放在提示的开头。 |
多轮和并行 thought_signature 处理 |
宽松的重复签名处理 | 并行轮次中只有第一个 functionCall 部分包含 thought_signature(在活跃轮次中省略该部分或将其复制到同级 functionCall 部分会返回 HTTP 400);从较早的轮次中剥离 thought_signature 值会降低推理质量,并可能导致 MALFORMED_FUNCTION_CALL 结束原因 |
在之前的所有轮次(functionCall 和最终 text 部分)中保留 thought_signature,并仅在平行轮次的第一个 functionCall 部分中保留。 |
| 代币结算 | 部分 token 会计费 | 模型处理的每个 token 都会计费,包括思考 token 以及使用接地功能时的内部工具系统指令和函数声明。“依托 Google 搜索进行接地”功能仍按查询计费。 | 查看费用估算。 |
如需从 gemini-3.8-flash 或 gemini-3.1-pro-preview 迁移,请执行以下操作:
将模型 ID 更改为
gemini-4-hydrogen(从gemini-3.8-flash更改)或gemini-4-carbon或gemini-4-argon(从gemini-3.1-pro-preview更改),并升级到最新的 Google Gen AI SDK(google-genai >= 2.34.0适用于 Python,@google/genai >= 2.32.0适用于 JavaScript/TypeScript)。请注意,输入和输出的总 token 数量上限为 1,048,576,单次请求的输出 token 数量上限为 65,536(对于 4 Carbon 和 4 Argon 上的非流式前台调用,上限为 32,768)。或者,您也可以在 Interactions API 或
GenerateContent上配置长解码,以获得更大的输出。将
thinking_budget和thinking_level="MINIMAL"替换为thinking_level,并设置为LOW、MEDIUM、HIGH或XHIGH(gemini-4-hydrogen支持XHIGH)。移除显式
cached_content引用。在所有之前的轮次(
functionCall和最终text部分)中保留thought_signature,并仅在并行工具调用轮次的第一个functionCall部分中保留它。移除了
temperature、top_p和top_k,这些参数没有任何作用。
Gemini 4 Carbon for cyber 和 Gemini 4 Argon Cyber Permissive
Gemini 4 Carbon for cyber 和 Gemini 4 Argon Cyber Permissive 是 Gemini 4 Carbon 和 Gemini 4 Argon 的版本,专为防御性网络安全应用场景而设计,仅限许可清单中的用户使用。如需了解差异和访问权限,请参阅适用于网络安全的 Gemini 4 Carbon 和 Gemini 4 Argon Cyber Permissive。
后续步骤
请参阅 Gemini 4 Hydrogen 开发者指南、Gemini 4 Carbon 开发者指南和 Gemini 4 Argon 开发者指南。
如需了解规格、支持的功能和位置,请参阅 Gemini 4 Hydrogen 模型页面、Gemini 4 Carbon 模型页面和 Gemini 4 Argon 模型页面。
试用 Gemini 4 Hydrogen 简介、Gemini 4 Carbon 简介和 Gemini 4 Argon 简介笔记本教程。
详细了解思考。