开始使用 Gemini 4

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 迁移,请执行以下操作:

  1. 将模型 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)。

  2. 请注意,输入和输出的总 token 数量上限为 1,048,576,单次请求的输出 token 数量上限为 65,536(对于 4 Carbon 和 4 Argon 上的非流式前台调用,上限为 32,768)。或者,您也可以在 Interactions API 或 GenerateContent 上配置长解码,以获得更大的输出。

  3. 将 thinking_budget 和 thinking_level="MINIMAL" 替换为 thinking_level,并设置为 LOW、MEDIUM、HIGH 或 XHIGH(gemini-4-hydrogen 支持 XHIGH)。

  4. 移除显式 cached_content 引用。

  5. 在所有之前的轮次(functionCall 和最终 text 部分)中保留 thought_signature,并仅在并行工具调用轮次的第一个 functionCall 部分中保留它。

  6. 移除了 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。

后续步骤