本頁面由 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

設定環境變數，透過 Vertex AI 使用 Gen AI SDK

將 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 Card Model Garden
思考程度	思考
媒體解析度	圖片理解影片理解音訊理解文件理解
思想簽名	想法簽名
溫度參數	API 參考資料
多模態函式回應	函式呼叫：多模態函式回應
串流函式呼叫	函式呼叫：串流函式呼叫

思考程度

thinking_level 參數可讓您指定模型生成回覆時的思考預算。選取其中一個狀態，即可明確權衡回覆品質、推理複雜度、延遲時間和成本之間的取捨。

低：盡量縮短延遲時間並降低成本。最適合用於遵循指令或即時通訊。
高：盡可能深入推論。預設值，動態思考。模型可能需要較長時間才能產生第一個權杖，但輸出內容會經過更徹底的審查。

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 high。

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 參數，可精細控管多模態視覺處理作業。解析度越高，模型就越能讀取細小文字或辨識細節，但也會增加權杖用量和延遲時間。media_resolution 參數會決定每個輸入圖片、PDF 頁面或影片影格分配到的詞元數量上限。

您可以為個別媒體部分設定 low、medium 或 high 解析度，也可以使用 generation_config 全域設定。如未指定，模型會根據媒體類型使用最佳預設值。

	權杖
	圖片	影片	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	足以應付大多數工作。注意：影片的每個影格最多可有 70 個權杖。`low`

為個別零件設定 `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)

思想簽名

思想簽章是加密權杖，可在多輪對話期間保留模型的推理狀態，特別是在使用函式呼叫時。

思考模型決定呼叫外部工具時，會暫停內部推論程序。思維簽章可做為「儲存狀態」，讓模型在您提供函式結果後，順暢地繼續思維鏈。

詳情請參閱「想法簽章」。

為什麼思維簽章很重要？

如果沒有思維簽章，模型會在工具執行階段「忘記」具體的推論步驟。將簽章傳回可確保：

背景資訊連續性：模型會保留呼叫工具的原因。
複雜推理：可執行多步驟工作，其中一個工具的輸出結果會做為下一個工具的推理依據。

系統會在何處傳回想法簽章？

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。您不需要變更任何程式碼。

手動函式呼叫範例

使用 Gen 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 錯誤「<內容陣列的索引> 內容區塊缺少 thought_signature」。<Function Call>

多模態函式回應

透過多模態函式呼叫，使用者可以取得含有多模態物件的函式回應，進而更充分運用模型函式呼叫功能。標準函式呼叫僅支援以文字為基礎的函式回應：

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 以上版本，如果輪流對話時應提供想法簽章，但未提供，模型會傳回錯誤，而非警告。
媒體解析度和符記化：Gemini 3 Pro 和後續版本模型會使用可變序列長度進行媒體符記化，而非 Pan 和 Scan，且圖片、PDF 和影片有新的預設解析度和符記費用。
多模態輸入的權杖計數：多模態輸入 (圖像、影片、音訊) 的權杖計數是根據所選media_resolution估算而得。因此，count_tokens API 呼叫的結果可能與最終消耗的權杖不符。只有在回應的 usage_metadata 中執行後，才能取得準確的帳單用量。
詞元消耗量：遷移至 Gemini 3 Pro 預設值後，圖片和 PDF 的詞元用量可能會增加，但影片的詞元用量會減少。如果要求現在因預設解析度較高而超出內容視窗，建議明確降低媒體解析度。
PDF 和文件理解：PDF 的預設 OCR 解析度已變更。如果您依賴特定行為來剖析密集文件，請測試新的 media_resolution: "high" 設定，確保準確度不受影響。如果是 Gemini 3 Pro 和後續版本模型，usage_metadata 中的 PDF 權杖計數會改為在 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 萬個詞元的輸入脈絡窗口，以及最多 6 萬 4 千個詞元的輸出。
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`