此页面由 Cloud Translation API 翻译。

开始使用 Gemini 3

Gemini 3 是我们迄今为止最智能的模型系列，建立在先进的推理技术基础上。它旨在通过掌握智能体工作流、自主编码和复杂的多模态任务，将任何想法变为现实。

本指南提供了一条整合的实用途径，可帮助您开始使用 Vertex AI 上的 Gemini 3，并重点介绍 Gemini 3 的主要功能和最佳实践。

快速入门

在开始之前，您必须使用 API 密钥或应用默认凭证 (ADC) 向 Vertex AI 进行身份验证。如需了解详情，请参阅身份验证方法。

安装 Google Gen AI SDK

Gemini 3 API 功能需要使用 Gen AI SDK for Python 1.51.0 版或更高版本。

pip install --upgrade google-genai

设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用

将 GOOGLE_CLOUD_PROJECT 值替换为您的 Google Cloud 项目 ID。 Gemini 3 Pro 预览版模型 gemini-3-pro-preview 仅在全球端点上提供：

export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

提交第一个请求

默认情况下，Gemini 3 Pro 使用动态思考功能来推理提示。如果不需要复杂的推理，您可以限制模型的 thinking_level，以获得更快、延迟更低的回答。低思考非常适合速度至上的高吞吐量任务，其延迟时间大致与 Gemini 2.5 Flash 相当，但可提供更出色的回答质量。

如需获得快速、低延迟的回答：

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3-pro-preview",
   contents="How does AI work?",
   config=types.GenerateContentConfig(
       thinking_config=types.ThinkingConfig(
           thinking_level=types.ThinkingLevel.LOW # For fast and low latency response
       )
   ),
)
print(response.text)

尝试复杂的推理任务

Gemini 3 在高级推理方面表现出色。对于多步规划、经过验证的代码生成或深度工具使用等复杂任务，请使用高思维水平。对于之前需要使用专业推理模型的任务，请使用这些配置。

对于较慢、需要高推理能力的任务：

from google import genai
from google.genai import types

client = genai.Client()

prompt = """
You are tasked with implementing the classic Thread-Safe Double-Checked Locking (DCL) Singleton pattern in modern C++. This task is non-trivial and requires specialized concurrency knowledge to prevent memory reordering issues.

Write a complete, runnable C++ program named `dcl_singleton.cpp` that defines a class `Singleton` with a private constructor and a static `getInstance()` method.

Your solution MUST adhere to the following strict constraints:
1. The Singleton instance pointer (`static Singleton*`) must be wrapped in `std::atomic` to correctly manage memory visibility across threads.
2. The `getInstance()` method must use `std::memory_order_acquire` when reading the instance pointer in the outer check.
3. The instance creation and write-back must use `std::memory_order_release` when writing to the atomic pointer.
4. A standard `std::mutex` must be used only to protect the critical section (the actual instantiation).
5. The `main` function must demonstrate safe, concurrent access by launching at least three threads, each calling `Singleton::getInstance()`, and printing the address of the returned instance to prove all threads received the same object.
"""

response = client.models.generate_content(
  model="gemini-3-pro-preview",
  contents=prompt,
  config=types.GenerateContentConfig(
      thinking_config=types.ThinkingConfig(
          thinking_level=types.ThinkingLevel.HIGH # Dynamic thinking for high reasoning tasks
      )
  ),
)
print(response.text)

新增的 API 功能

Gemini 3 引入了强大的 API 增强功能和新参数，旨在让开发者精细控制性能（延迟时间、费用）、模型行为和多模态保真度。

下表总结了可用的核心新功能和参数，并提供了指向其详细文档的直接链接：

新功能/API 变更	文档
模型：`gemini-3-pro-preview`	模型卡片 Model Garden
思考等级	思考型
媒体分辨率	图片理解视频理解音频理解文档理解
思路签名	思路签名
温度	API 参考文档
多模态函数响应	函数调用：多模态函数回答
流式函数调用	函数调用：流式函数调用

思考等级

借助 thinking_level 参数，您可以为模型生成回答指定思考预算。通过选择两种状态之一，您可以明确平衡回答质量与推理复杂性、延迟时间与费用之间的权衡取舍。

低：最大限度地缩短延迟时间并降低费用。最适合指令遵循或聊天。
高：最大限度地提高推理深度。默认值。动态思维。模型可能需要更长时间才能生成第一个 token，但输出内容会经过更全面的审核。

Gen AI SDK 示例

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3-pro-preview",
   contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
   config=types.GenerateContentConfig(
       thinking_config=types.ThinkingConfig(
           thinking_level=types.ThinkingLevel.HIGH # Default, dynamic thinking
       )
   ),
)
print(response.text)

OpenAI 兼容性示例

对于使用 OpenAI 兼容层的用户，标准参数会自动映射到 Gemini 3 等效参数：

reasoning_effort 映射到 thinking_level。
reasoning_effort 值 medium 映射到 thinking_level 高。

import openai
from google.auth import default
from google.auth.transport.requests import Request

credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])

client = openai.OpenAI(
    base_url=f"https://aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/global/endpoints/openapi",
    api_key=credentials.token,
)

prompt = """
Write a bash script that takes a matrix represented as a string with
format '[1,2],[3,4],[5,6]' and prints the transpose in the same format.
"""

response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    reasoning_effort="medium", # Map to thinking_level high.
    messages=[{"role": "user", "content": prompt}],
)

print(response.choices[0].message.content)

媒体分辨率

Gemini 3 引入了使用 media_resolution 参数对多模态视觉处理进行精细控制的功能。分辨率越高，模型读取细小文字或识别细微细节的能力就越强，但会增加 token 用量和延迟时间。media_resolution 参数用于确定为每个输入图片、PDF 页面或视频帧分配的词元数量上限。

您可以为每个媒体部分单独设置分辨率，也可以使用 generation_config 全局设置分辨率（设置为 low、medium 或 high）。如果未指定，模型会根据媒体类型使用最佳默认值。

	令牌
	Image	视频	PDF
`MEDIA_RESOLUTION_UNSPECIFIED`（默认）	1120	70	560
`MEDIA_RESOLUTION_LOW`	280	70	280
`MEDIA_RESOLUTION_MEDIUM`	560	70	560
`MEDIA_RESOLUTION_HIGH`	1120	280	1120

建议的设置

媒体分辨率	令牌数量上限	使用指南
`high`	1120	图片分析任务，以确保最高质量。
`medium`	560
`low`	图片：280 视频：70	足以应对大多数任务。注意：对于视频，`low` 每个帧最多为 70 个词元。

为每个单独的零件设置 `media_resolution`

您可以为每个媒体部分单独设置 media_resolution：

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
  model="gemini-3-pro-preview",
  contents=[
      types.Part(
          file_data=types.FileData(
              file_uri="gs://cloud-samples-data/generative-ai/image/a-man-and-a-dog.png",
              mime_type="image/jpeg",
          ),
          media_resolution=types.PartMediaResolution(
              level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_HIGH # High resolution
          ),
      ),
      Part(
          file_data=types.FileData(
             file_uri="gs://cloud-samples-data/generative-ai/video/behind_the_scenes_pixel.mp4",
            mime_type="video/mp4",
          ),
          media_resolution=types.PartMediaResolution(
              level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_LOW # Low resolution
          ),
      ),
      "When does the image appear in the video? What is the context?",
  ],
)
print(response.text)

全局设置 `media_resolution`

您还可以全局设置 media_resolution（使用 GenerateContentConfig）：

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
  model="gemini-3-pro-preview",
  contents=[
      types.Part(
          file_data=types.FileData(
              file_uri="gs://cloud-samples-data/generative-ai/image/a-man-and-a-dog.png",
              mime_type="image/jpeg",
          ),
      ),
      "What is in the image?",
  ],
  config=types.GenerateContentConfig(
      media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW, # Global setting
  ),
)
print(response.text)

思考签名

思路签名是加密 token，可在多轮对话期间（尤其是在使用函数调用时）保留模型的推理状态。

当思考模型决定调用外部工具时，它会暂停其内部推理过程。思路签名充当“保存状态”，让模型在您提供函数结果后能够无缝恢复其思维链。

如需了解详情，请参阅意念签名。

为什么意念签名很重要？

如果没有思路签名，模型会在工具执行阶段“忘记”其具体的推理步骤。传回签名可确保：

上下文连续性：模型会保留调用工具的原因。
复杂推理：支持多步骤任务，其中一个工具的输出会为下一个工具的推理提供信息。

思考特征在何处返回？

Gemini 3 Pro 对思维签名（最初在 Gemini 2.5 中引入）强制执行更严格的验证并更新了处理方式。为确保模型在多轮对话中保持上下文，您必须在后续请求中返回思考特征。

包含函数调用的模型响应始终会返回思维签名。
如果存在并行函数调用，模型响应返回的第一个函数调用部分将具有思考特征。
如果存在连续的函数调用（多步），每个函数调用都会有一个签名，并且客户端应将签名传递回
不包含函数调用的模型回答会在模型返回的最后一部分中返回思考签名。

如何处理思路签名？

您可以通过两种主要方式处理思维签名：自动处理（使用 Gen AI SDK 或 OpenAI API），或者手动处理（如果您直接与 API 互动）。

自动处理（推荐）

如果您使用的是 Google Gen AI SDK（Python、Node.js、Go、Java）或 OpenAI Chat Completions API，并且利用标准对话历史记录功能或附加完整的模型响应，系统会自动处理 thought_signatures。您无需对代码进行任何更改。

手动函数调用示例

使用生成式 AI SDK 时，系统会自动处理思维签名，方法是在后续模型请求中附加完整的模型响应：

from google import genai
from google.genai import types

client = genai.Client()

# 1. Define your tool
get_weather_declaration = types.FunctionDeclaration(
   name="get_weather",
   description="Gets the current weather temperature for a given location.",
   parameters={
       "type": "object",
       "properties": {"location": {"type": "string"}},
       "required": ["location"],
   },
)
get_weather_tool = types.Tool(function_declarations=[get_weather_declaration])

# 2. Send a message that triggers the tool
prompt = "What's the weather like in London?"
response = client.models.generate_content(
   model="gemini-3-pro-preview",
   contents=prompt,
   config=types.GenerateContentConfig(
       tools=[get_weather_tool],
       thinking_config=types.ThinkingConfig(include_thoughts=True)
   ),
)

# 4. Handle the function call
function_call = response.function_calls[0]
location = function_call.args["location"]
print(f"Model wants to call: {function_call.name}")

# Execute your tool (e.g., call an API)
# (This is a mock response for the example)
print(f"Calling external tool for: {location}")
function_response_data = {
   "location": location,
   "temperature": "30C",
}

# 5. Send the tool's result back
# Append this turn's messages to history for a final response.
# The `content` object automatically attaches the required thought_signature behind the scenes.
history = [
    types.Content(role="user", parts=[types.Part(text=prompt)]),
    response.candidates[0].content, # Signature preserved here
    types.Content(
        role="tool",
        parts=[
            types.Part.from_function_response(
                name=function_call.name,
                response=function_response_data,
            )
        ],
    )
]

response_2 = client.models.generate_content(
   model="gemini-3-pro-preview",
   contents=history,
   config=types.GenerateContentConfig(
        tools=[get_weather_tool],
        thinking_config=types.ThinkingConfig(include_thoughts=True)
   ),
)

# 6. Get the final, natural-language answer
print(f"\nFinal model response: {response_2.text}")

自动函数调用示例

在自动函数调用中使用 Gen AI SDK 时，系统会自动处理思考特征：


from google import genai
from google.genai import types

def get_current_temperature(location: str) -> dict:
    """Gets the current temperature for a given location.

    Args:
        location: The city and state, for example San Francisco, CA

    Returns:
        A dictionary containing the temperature and unit.
    """
    # ... (implementation) ...
    return {"temperature": 25, "unit": "Celsius"}

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="What's the temperature in Boston?",
    config=types.GenerateContentConfig(
            tools=[get_current_temperature],
    )
)

print(response.text) # The SDK handles the function call and thought signature, and returns the final text

OpenAI 兼容性示例

使用 OpenAI Chat Completions API 时，系统会自动处理思维签名，方法是在后续模型请求中附加完整的模型响应：

...
# Append user prompt and assistant response including thought signatures
messages.append(response1.choices[0].message)

# Execute the tool
tool_call_1 = response1.choices[0].message.tool_calls[0]
result_1 = get_current_temperature(**json.loads(tool_call_1.function.arguments))

# Append tool response to messages
messages.append(
    {
        "role": "tool",
        "tool_call_id": tool_call_1.id,
        "content": json.dumps(result_1),
    }
)

response2 = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=messages,
    tools=tools,
    extra_body={
        "extra_body": {
            "google": {
                "thinking_config": {
                    "include_thoughts": True,
                },
            },
        },
    },
)

print(response2.choices[0].message.tool_calls)

请参阅完整的代码示例。

人工处理

如果您直接与 API 互动或管理原始 JSON 载荷，则必须正确处理模型回答中包含的 thought_signature。

在发送对话历史记录时，您必须在收到签名时所在的精确位置返回该签名。

如果未返回正确的签名，Gemini 3 将返回 400 错误“<Function Call> 在 <index of contents array> 内容块中缺少 thought_signature”。

多模态函数响应

多模态函数调用功能可让用户获得包含多模态对象的函数响应，从而更好地利用模型的函数调用功能。标准函数调用仅支持基于文本的函数响应：

from google import genai
from google.genai import types

client = genai.Client()

# This is a manual, two turn multimodal function calling workflow:

# 1. Define the function tool
get_image_declaration = types.FunctionDeclaration(
   name="get_image",
   description="Retrieves the image file reference for a specific order item.",
   parameters={
       "type": "object",
       "properties": {
            "item_name": {
                "type": "string",
                "description": "The name or description of the item ordered (e.g., 'green shirt')."
            }
       },
       "required": ["item_name"],
   },
)
tool_config = types.Tool(function_declarations=[get_image_declaration])

# 2. Send a message that triggers the tool
prompt = "Show me the green shirt I ordered last month."
response_1 = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents=[prompt],
    config=types.GenerateContentConfig(
        tools=[tool_config],
    )
)

# 3. Handle the function call
function_call = response_1.function_calls[0]
requested_item = function_call.args["item_name"]
print(f"Model wants to call: {function_call.name}")

# Execute your tool (e.g., call an API)
# (This is a mock response for the example)
print(f"Calling external tool for: {requested_item}")

function_response_data = {
  "image_ref": {"$ref": "dress.jpg"},
}

function_response_multimodal_data = types.FunctionResponsePart(
   file_data=types.FunctionResponseFileData(
      mime_type="image/png",
      display_name="dress.jpg",
      file_uri="gs://cloud-samples-data/generative-ai/image/dress.jpg",
   )
)

# 4. Send the tool's result back
# Append this turn's messages to history for a final response.
history = [
  types.Content(role="user", parts=[types.Part(text=prompt)]),
  response_1.candidates[0].content,
  types.Content(
    role="tool",
    parts=[
        types.Part.from_function_response(
            name=function_call.name,
            response=function_response_data,
            parts=[function_response_multimodal_data]
        )
    ],
  )
]

response_2 = client.models.generate_content(
  model="gemini-3-pro-preview",
  contents=history,
  config=types.GenerateContentConfig(
      tools=[tool_config],
      thinking_config=types.ThinkingConfig(include_thoughts=True)
  ),
)

print(f"\nFinal model response: {response_2.text}")

流式函数调用

您可以使用流式传输部分函数调用实参来改善工具使用方面的流式传输体验。您可以通过将 stream_function_call_arguments 明确设置为 true 来启用此功能：

from google import genai
from google.genai import types

client = genai.Client()

get_weather_declaration = types.FunctionDeclaration(
  name="get_weather",
  description="Gets the current weather temperature for a given location.",
  parameters={
      "type": "object",
      "properties": {"location": {"type": "string"}},
      "required": ["location"],
  },
)
get_weather_tool = types.Tool(function_declarations=[get_weather_declaration])


for chunk in client.models.generate_content_stream(
   model="gemini-3-pro-preview",
   contents="What's the weather in London and New York?",
   config=types.GenerateContentConfig(
       tools=[get_weather_tool],
       tool_config = types.ToolConfig(
           function_calling_config=types.FunctionCallingConfig(
               mode=types.FunctionCallingConfigMode.AUTO,
               stream_function_call_arguments=True,
           )
       ),
   ),
):
   function_call = chunk.function_calls[0]
   if function_call and function_call.name:
       print(f"{function_call.name}")
       print(f"will_continue={function_call.will_continue}")

模型回答示例：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "functionCall": {
              "name": "get_weather",
              "willContinue": true
            }
          }
        ]
      }
    }
  ]
}

温度

Range for Gemini 3: 0.0 - 2.0 (default: 1.0)

对于 Gemini 3，强烈建议将 temperature 参数保留为默认值 1.0。

虽然之前的模型通常可以通过调整温度来控制创意与确定性，但 Gemini 3 的推理能力已针对默认设置进行了优化。

更改温度（将其设置为低于 1.0）可能会导致意外行为，例如循环或性能下降，尤其是在复杂的数学或推理任务中。

支持的功能

Gemini 3 Pro 还支持以下功能：

提示最佳实践

Gemini 3 是一种推理模型，因此您需要改变提示方式。

精确的指令：输入提示应简洁明了。Gemini 3 最适合回答直接、清晰的指令。它可能会过度分析用于旧模型的冗长或过于复杂的提示工程技术。
输出详细程度：默认情况下，Gemini 3 的输出详细程度较低，更倾向于提供直接、高效的答案。如果您的使用情形需要更具对话性或“聊天”风格的角色，您必须在提示中明确引导模型（例如，“以友好健谈的助理身份解释此内容”）。

迁移注意事项

迁移时，请考虑以下功能和限制：

思考水平：Gemini 3 Pro 及更高版本的模型使用 thinking_level 参数来控制模型执行的内部推理量（低或高），并平衡回答质量、推理复杂性、延迟时间和费用。
温度设置：如果现有代码明确设置了 temperature（尤其是设置为较低值以实现确定性输出），建议移除此参数并使用 Gemini 3 的默认值 1.0，以避免在处理复杂任务时出现潜在的循环问题或性能下降。
思路签名：对于 Gemini 3 Pro 及更高版本的模型，如果某个对话轮次需要思路签名但未提供，模型会返回错误，而不是警告。
媒体分辨率和 token 化：Gemini 3 Pro 及更高版本的模型使用可变序列长度进行媒体 token 化，而不是平移和扫描，并且为图片、PDF 和视频设置了新的默认分辨率和 token 费用。
多模态输入的 token 数统计：多模态输入（图片、视频、音频）的 token 数是根据所选的 media_resolution 进行估算的。因此，count_tokens API 调用的结果可能与最终消耗的令牌不一致。只有在执行响应的 usage_metadata 后，才能获得准确的结算用量。
令牌消耗：迁移到 Gemini 3 Pro 默认设置可能会增加图片和 PDF 的令牌用量，但会减少视频的令牌用量。如果请求现在因默认分辨率更高而超出上下文窗口，建议明确降低媒体分辨率。
PDF 和文档理解：PDF 的默认 OCR 分辨率已更改。如果您之前依赖于密集文档解析的特定行为，请测试新的 media_resolution: "high" 设置，以确保准确性不受影响。对于 Gemini 3 Pro 及更高版本的模型，usage_metadata 中的 PDF token 数会归类到 IMAGE 模态，而不是 DOCUMENT 模态。
图像分割：Gemini 3 Pro 及更高版本的模型不支持图像分割。对于需要内置图像分割的工作负载，建议继续使用 Gemini 2.5 Flash，并将思考功能关闭。
多模态函数响应：对于 Gemini 3 Pro 及更高版本的模型，您可以在函数响应中包含图片和 PDF 数据。

常见问题解答

Gemini 3 Pro 的知识截止日期是什么？Gemini 3 的知识截止日期为 2025 年 1 月。
Google Cloud 上提供 gemini-3-pro-preview 的区域有哪些？全球。
上下文窗口有哪些限制？Gemini 3 Pro 支持 100 万个 token 的输入上下文窗口，以及最多 6.4 万个 token 的输出。
gemini-3-pro-preview 是否支持图片输出？不会。
gemini-3-pro-preview 是否支持 Gemini Live API？不会。

后续步骤

详细了解 Gemini 3 Pro。
不妨试试 Gemini 3 Pro 简介笔记本教程。
了解函数调用。
了解思考。

开始使用 Gemini 3 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

快速入门

安装 Google Gen AI SDK

提交第一个请求

尝试复杂的推理任务

新增的 API 功能

思考等级

Gen AI SDK 示例

OpenAI 兼容性示例

媒体分辨率

建议的设置

为每个单独的零件设置 media_resolution

全局设置 media_resolution

思考签名

为什么意念签名很重要？

思考特征在何处返回？

如何处理思路签名？

自动处理（推荐）

手动函数调用示例

自动函数调用示例

OpenAI 兼容性示例

人工处理

多模态函数响应

流式函数调用

温度

支持的功能

提示最佳实践

迁移注意事项

常见问题解答

后续步骤

开始使用 Gemini 3

为每个单独的零件设置 `media_resolution`

全局设置 `media_resolution`