Gemini 3 は、最先端の推論を基盤として構築された、Google 史上最もインテリジェントなモデル ファミリーです。エージェント ワークフロー、自律型コーディング、複雑なマルチモーダル タスクをマスターして、あらゆるアイデアを実現できるように設計されています。
このガイドでは、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 Garden |
| 思考レベル | 思考モード |
| メディアの解像度 | 画像の理解 動画の理解 音声の理解 ドキュメントの理解 |
| 思考シグネチャ | 思考シグネチャ |
| 温度 | API リファレンス |
| マルチモーダル関数レスポンス | 関数呼び出し: マルチモーダル関数レスポンス |
| ストリーミング関数呼び出し | 関数呼び出し: ストリーミング関数呼び出し |
思考レベル
thinking_level パラメータを使用すると、モデルのレスポンス生成の思考予算を指定できます。2 つの状態のいずれかを選択することで、レスポンスの品質と推論の複雑さ、レイテンシと費用のトレードオフのバランスを明示的に取ることができます。
- 低: レイテンシと費用を最小限に抑えます。指示の実行やチャットに最適です。
- 高: 推論の深さを最大化します。デフォルト。動的な思考。最初のトークンに到達するまでに時間がかかることがありますが、出力はより徹底的に審査されます。
生成 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_levelhigh にマッピングされます。
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 を使用)。指定しない場合、モデルはメディアタイプに基づいて最適なデフォルトを使用します。
| トークン | |||
|---|---|---|---|
| 画像 | 動画 | ||
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 に基づく推定値です。そのため、count_tokens API 呼び出しの結果が最終的に使用されたトークン数と一致しない場合があります。課金対象の正確な使用量は、レスポンスの usage_metadata 内で実行された後にのみ確認できます。media_resolution はトークン数に直接影響するため、長い動画や長いドキュメントなど、非常に長い入力に対応するには、解像度を下げる(低など)ことが必要になる場合があります。個々のパーツごとに 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)
思考シグネチャ
思考シグネチャは、マルチターンの会話中、特に関数呼び出しを使用している場合に、モデルの推論状態を保持する暗号化されたトークンです。
思考モデルが外部ツールを呼び出すと、内部推論プロセスが一時停止します。思考シグネチャは「保存状態」として機能します。関数結果を提供すると、モデルは思考の連鎖をシームレスに再開できます。
詳細については、思考シグネチャをご覧ください。
思考シグネチャが重要な理由
思考シグネチャがないと、モデルはツール実行フェーズで特定の推論ステップを「忘れて」しまいます。シグネチャを渡すことで、次のことが保証されます。
- コンテキストの継続性: モデルは、ツールが呼び出された理由を保持します。
- 複雑な推論: 1 つのツールの出力が次の推論の根拠となるマルチステップ タスクを可能にします。
思考シグネチャが返される場所
Gemini 3 Pro では、Gemini 2.5 で導入された思考シグネチャに対して、より厳格な検証と更新された処理が適用されます。モデルが会話を何度もやり取りしながらコンテキストを維持できるようにするために、その後のリクエストで思考シグネチャを返す必要があります。
- 関数呼び出しを含むモデル レスポンスは、常に思考シグネチャを返します。
- 並列関数呼び出しがある場合、モデル レスポンスから返される最初の関数呼び出し部分には思考シグネチャが含まれます。
- 関数呼び出しが連続している場合(マルチステップ)、各関数呼び出しにシグネチャがあり、クライアントはシグネチャを返すことが想定されています。
- 関数呼び出しのないモデル レスポンスでは、モデルによって返される最後の部分に思考シグネチャを返します。
思考シグネチャの処理方法
思考シグネチャを処理する主な方法は 2 つあります。生成 AI SDK または OpenAI API を使用して自動的に処理する方法と、API を直接操作する場合に手動で処理する方法です。
自動処理(推奨)
Google 生成 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}")
自動関数呼び出しの例
自動関数呼び出しで生成 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> in the <index of contents array> content block is missing a 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 は、次の機能もサポートしています。
- システム指示
- 構造化出力
- 関数呼び出し
- Google 検索によるグラウンディング
- コードの実行
- URL コンテキスト
- 思考モード
- コンテキストのキャッシュ保存
- トークンのカウント
- チャットの補完
- バッチ予測
- プロビジョンド スループット
- 動的共有割り当て
プロンプトのベスト プラクティス
Gemini 3 は推論モデルであるため、プロンプトの作成方法が変わります。
- 正確な指示: 入力プロンプトは簡潔にしてください。Gemini 3 は、明確で直接的な指示に最適に応答します。古いモデルで使用されている冗長または複雑すぎるプロンプト エンジニアリング手法では、過剰な分析になる可能性があります。
- 出力の冗長性: デフォルトでは、Gemini 3 は冗長性が低く、直接的で効率的な回答を好みます。ユースケースで会話調のペルソナが必要な場合は、プロンプトでモデルを明示的に誘導する必要があります(例: 「親しみやすく、おしゃべりなアシスタントとして説明してください」)。
移行に関する考慮事項
移行する際は、次の機能と制約を考慮してください。
- 思考レベル: Gemini 3 Pro 以降のモデルは、
thinking_levelパラメータを使用して、モデルが実行する内部推論の量(低または高)を制御し、回答の品質、推論の複雑さ、レイテンシ、費用を調整します。 - 温度設定: 既存のコードで
temperatureが明示的に設定されている場合(特に決定論的出力が低い値に設定されている場合)、このパラメータを削除して Gemini 3 のデフォルトの1.0を使用することをおすすめします。これにより、複雑なタスクで発生する可能性のあるループの問題やパフォーマンスの低下を回避できます。 - 思考シグネチャ: Gemini 3 Pro 以降のモデルでは、ターンで思考シグネチャが想定されているにもかかわらず指定されていない場合、モデルは警告ではなくエラーを返します。
- メディアの解像度とトークン化: Gemini 3 Pro 以降のモデルでは、メディアのトークン化にパン&スキャンではなく、可変シーケンス長が使用され、画像、PDF、動画の新しいデフォルトの解像度とトークン費用が設定されています。
- マルチモーダル入力のトークン数: マルチモーダル入力(画像、動画、音声)のトークン数は、選択した
media_resolutionに基づく推定値です。そのため、count_tokensAPI 呼び出しの結果が最終的に使用されたトークン数と一致しない場合があります。課金対象の正確な使用量は、レスポンスのusage_metadata内で実行された後にのみ確認できます。 - トークンの使用量: Gemini 3 Pro のデフォルトに移行すると、画像と PDF のトークン使用量が増加する可能性がありますが、動画のトークン使用量は減少する可能性があります。デフォルトの解像度が高くなったことでリクエストがコンテキスト ウィンドウを超えるようになった場合は、メディアの解像度を明示的に下げることをおすすめします。
- PDF とドキュメントの理解: PDF のデフォルトの OCR 解像度が変更されました。高密度ドキュメントの解析で特定の動作に依存していた場合は、新しい
media_resolution: "high"設定をテストして、精度が維持されることを確認してください。Gemini 3 Pro 以降のモデルでは、usage_metadataの PDF トークン数は DOCUMENT ではなく IMAGE モダリティで報告されます。 - 画像セグメンテーション: 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 万トークンの入力コンテキスト ウィンドウと最大 64,000 トークンの出力をサポートしています。
gemini-3-pro-previewは画像出力をサポートしていますか?いいえ。gemini-3-pro-previewは Gemini Live API をサポートしていますか?いいえ。
次のステップ
- Gemini 3 Pro の詳細を確認する。
- Gemini 3 Pro の概要ノートブック チュートリアルを試す。
- 関数呼び出しの詳細を確認する。
- 思考モードの詳細を確認する。