Gemini 4 Hydrogen は、日常的なコーディングやエージェントによるエンタープライズ ワークフローに、スピードと効率性に優れた最先端のインテリジェンスをもたらします。
このドキュメントでは、Hydrogen の主な機能、適用される API 規則、Gemini 3.8 Flash 以前の Gemini 3 Flash モデルから Hydrogen に移行する方法、クイックスタートについて説明します。Gemini 4 ファミリーの概要については、Gemini 4 を使ってみるをご覧ください。
Gemini 4 Hydrogen の主な機能
Gemini 4 Hydrogen には次の機能が含まれています。
- 入力トークンと出力トークンの統合上限: Hydrogen には、入力トークンと出力トークンの両方を含む 1,048,576 トークンの統合上限があります(出力には、思考、関数呼び出し、最終レスポンスが含まれます)。
- 最大 1,048,576 トークンの長いデコード: Hydrogen は、Interactions API と
GenerateContent(v1beta1)の両方で、1 つの 65,536 トークンのフォアグラウンド セグメント(ストリーミングまたは非ストリーミング)を超えて、最大 1,048,576 トークン(入力トークンを除く)まで生成を拡張します。Google Gen AI SDK は、セグメント間でcontinuation_tokenを自動的に処理します。また、非同期のサーバー管理バックグラウンド デコード(background=true)を実行したり、カスタム継続ループでcontinuation_tokenを管理したりすることもできます。 - 思考レベル: Hydrogen は
LOW、MEDIUM、HIGH(デフォルト)、XHIGHをサポートしています。 - 耐久性のあるキャッシュ保存を使用した暗黙的なキャッシュ保存: 暗黙的なキャッシュ保存は、4,096 トークン以上の共有プロンプト接頭辞に自動的に適用されます。耐久性のあるキャッシュ保存はデフォルトで有効になっています。明示的なコンテキスト キャッシュ保存はサポートされていません。
- Office ファイルと OpenDocument ファイルの入力: PDF と書式なしテキストに加えて、Hydrogen は Microsoft Office(
.docx、.dotx、.doc、.pptx、.ppt、.xlsx、.xls)と OpenDocument(.odt、.odp、.ods)のファイルをインラインまたは Cloud Storage からGenerateContentと Interactions API の両方で受け入れます。これには、マルチモーダルFunctionResponse部分内も含まれます。 - エージェント型動画理解: エージェント型動画理解は一般提供されており、デフォルトでオフになっています。
- 短期リリース ライフサイクル: Hydrogen は、45 日以上の廃止通知ポリシーの対象となる短期の一般提供(GA)リリースです。ライフサイクルの詳細については、モデルのバージョンとライフサイクルをご覧ください。
クイックスタート
始める前に、アプリケーションのデフォルト認証情報(ADC)または API キーを使用して Gemini Enterprise Agent Platform に対する認証を行う必要があります。詳細については、Agent Platform を使ってみるをご覧ください。
次のコードブロックで、PROJECT_ID はプロジェクト ID に置き換えます。
Agent Studio で試す
プロンプトをテストし、Agent Studio UI で gemini-4-hydrogen を構成する手順は次のとおりです。
- Google Cloud プロジェクトで Agent Studio を開き、Gemini グループで
gemini-4-hydrogenを選択します。 - [モデル設定] で、次のオプションを構成します。
- 思考レベル:
Low、Medium、High(デフォルト)、Extra highのいずれかを選択します。 - リージョン:
Global、us、euのいずれかを選択します。 - 出力トークンの上限:
32,768~1,048,576(デフォルトは1,048,576)の範囲で設定します。Agent Studio は、単一リクエストの上限を超えるレスポンスの継続トークンを自動的に処理します。
- 思考レベル:
インストール
最新の Google Gen AI SDK にアップグレードします。Interactions API で自動継続を行うには、Python の場合は google-genai >= 2.34.0、JavaScript/TypeScript の場合は @google/genai >= 2.32.0、Go の場合は >= 1.77.0、Java の場合は >= 1.80.0 が必要です(GenerateContent の場合、自動継続には Python の場合は >= 2.30.1、JavaScript/TypeScript の場合は >= 2.29.1、Go の場合は >= 1.74.0、Java の場合は >= 1.77.0、.NET の場合は >= 1.26.0、Kotlin の場合は >= 1.6.0 が必要です)。
pip install --upgrade "google-genai>=2.34.0"
基本的なリクエスト
Google Gen AI SDK または REST を使用して gemini-4-hydrogen にリクエストを送信します。
Python(GenerateContent)
from google import genai
from google.genai import types
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
response = client.models.generate_content(
model="gemini-4-hydrogen",
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="HIGH", # Default: "HIGH" (Valid: "LOW", "MEDIUM", "HIGH", "XHIGH")
),
),
)
print(response.text)
Python(Interactions API)
from google import genai
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
# Turn 1: Initial request (stored server-side by default)
turn1 = client.interactions.create(
model="gemini-4-hydrogen",
input="Design a lock-free ring buffer in Rust for multi-producer, single-consumer telemetry ingestion.",
store=True,
)
print(turn1.output_text)
# Turn 2: Continue the conversation using previous_interaction_id
turn2 = client.interactions.create(
model="gemini-4-hydrogen",
input="Add a bounded backpressure policy and unit tests for concurrent writers.",
previous_interaction_id=turn1.id,
)
print(turn2.output_text)
REST
curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-hydrogen:generateContent" \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Provide an architectural review of this Go interface."
}
]
}
],
"generationConfig": {
"thinkingConfig": {
"thinkingLevel": "HIGH"
}
}
}'
構造化出力
スキーマに準拠した JSON 出力を生成するには、response_mime_type と response_schema を構成します。
from pydantic import BaseModel, Field
from google import genai
from google.genai import types
class ArchitectureReview(BaseModel):
component: str = Field(description="Service or module name")
bottlenecks: list[str] = Field(description="Throughput or latency bottlenecks")
recommended_changes: list[str] = Field(description="Concrete refactoring steps")
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
response = client.models.generate_content(
model="gemini-4-hydrogen",
contents="Review a synchronous order-processing pipeline backed by a single primary database at 15,000 writes/sec.",
config=types.GenerateContentConfig(
response_mime_type="application/json",
response_schema=ArchitectureReview,
thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
),
)
print(response.text)
長いデコードの例
デフォルトでは、1 つのフォアグラウンド API セグメントで最大 65,536 個の出力トークン(ストリーミングまたは非ストリーミング)が生成されます。出力には、思考、関数呼び出し、最終レスポンスが含まれます。最大 1,048,576 トークン(入力トークンを除く)の補完を生成するには、Interactions API または GenerateContent で長いデコードを使用します。継続オプション、ステータス遷移、検証ルールについては、長いデコードをご覧ください。
Interactions API で長いデコードを使用する
google-genai >= 2.34.0(Python)、@google/genai >= 2.32.0(JavaScript / TypeScript)、Go >= 1.77.0、Java >= 1.80.0 では、セグメントが status="requires_continuation" を返すたびに、interactions.create() はセグメント間で continuation_token を自動的にフォローします。また、オプトアウト(automatic_continuation=False)して、カスタムの保存済み(store=True)ループまたはステートレス(store=False)ループを実行することもできます。
Python(SDK 自動)
from google import genai
client = genai.Client(
enterprise=True,
project="PROJECT_ID",
location="global",
)
# Automatic continuation is enabled by default in google-genai >= 2.34.0.
# Unary calls merge all segments into one Interaction with summed usage.
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Write a complete formal proof of the prime number theorem.",
generation_config={
"max_output_tokens": 256000,
"thinking_level": "high",
},
)
print(interaction.output_text)
print(f"Merged segment IDs: {interaction.continuation_ids}")
print(f"Initial input tokens: {interaction.usage.initial_input_tokens}")
# Streaming yields events across all segments in order. Intermediate segments
# emit interaction.completed with status="requires_continuation".
stream = client.interactions.create(
model="gemini-4-hydrogen",
input="Write a complete formal proof of the prime number theorem.",
stream=True,
generation_config={
"max_output_tokens": 256000,
"thinking_level": "high",
},
)
for event in stream:
if event.event_type == "step.delta" and getattr(event.delta, "text", None):
print(event.delta.text, end="", flush=True)
elif (
event.event_type == "interaction.completed"
and event.interaction.status != "requires_continuation"
):
print(f"\nFinal status: {event.interaction.status}")
# Optional: Delete each stored server segment (last segment first) before its 7-day TTL expires.
for segment_id in reversed(interaction.continuation_ids or [interaction.id]):
client.interactions.delete(id=segment_id)
# Set automatic_continuation=False to return after a single segment.
single_segment = client.interactions.create(
model="gemini-4-hydrogen",
input="Write a complete formal proof of the prime number theorem.",
generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
automatic_continuation=False,
)
Python(カスタムループ)
from google import genai
client = genai.Client(
enterprise=True,
project="PROJECT_ID",
location="global",
)
prompt = "Write a complete formal proof of the prime number theorem."
# Stored loop (store=True, default): chain previous_interaction_id + continuation_token
# without resending input.
segment = client.interactions.create(
model="gemini-4-hydrogen",
input=prompt,
store=True,
generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
automatic_continuation=False,
)
full_text = segment.output_text or ""
while segment.status == "requires_continuation" and segment.continuation_token:
segment = client.interactions.create(
model="gemini-4-hydrogen",
previous_interaction_id=segment.id,
continuation_token=segment.continuation_token,
generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
automatic_continuation=False,
)
full_text += segment.output_text or ""
# If status == "incomplete", max_output_tokens was exhausted; raise max_output_tokens to continue.
if segment.status == "incomplete" and segment.continuation_token:
segment = client.interactions.create(
model="gemini-4-hydrogen",
previous_interaction_id=segment.id,
continuation_token=segment.continuation_token,
generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
)
full_text += segment.output_text or ""
# Stateless loop (store=False): resend original input + continuation_token
# with no previous_interaction_id.
stateless_seg = client.interactions.create(
model="gemini-4-hydrogen",
input=prompt,
store=False,
generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
automatic_continuation=False,
)
stateless_text = stateless_seg.output_text or ""
while stateless_seg.status == "requires_continuation" and stateless_seg.continuation_token:
stateless_seg = client.interactions.create(
model="gemini-4-hydrogen",
input=prompt,
store=False,
continuation_token=stateless_seg.continuation_token,
generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
automatic_continuation=False,
)
stateless_text += stateless_seg.output_text or ""
REST(保存済み)
# Segment 1: Start a stored interaction (store=true by default)
curl -s -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
-d '{
"model": "gemini-4-hydrogen",
"store": true,
"input": "Write a complete formal proof of the prime number theorem.",
"generation_config": {
"max_output_tokens": 131072,
"thinking_level": "high"
}
}'
# Segment 2: When status is "requires_continuation", pass previous_interaction_id
# and continuation_token without resending input
curl -s -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
-d '{
"model": "gemini-4-hydrogen",
"store": true,
"previous_interaction_id": "SEGMENT_1_ID",
"continuation_token": "CONTINUATION_TOKEN",
"generation_config": {
"max_output_tokens": 131072,
"thinking_level": "high"
}
}'
REST(ステートレス)
# Segment 1: Stateless interaction (store=false)
curl -s -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
-d '{
"model": "gemini-4-hydrogen",
"store": false,
"input": "Write a complete formal proof of the prime number theorem.",
"generation_config": {
"max_output_tokens": 131072,
"thinking_level": "high"
}
}'
# Segment 2: Resend the original input and continuation_token (no previous_interaction_id)
curl -s -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
-d '{
"model": "gemini-4-hydrogen",
"store": false,
"input": "Write a complete formal proof of the prime number theorem.",
"continuation_token": "CONTINUATION_TOKEN",
"generation_config": {
"max_output_tokens": 131072,
"thinking_level": "high"
}
}'
非同期のサーバー管理実行(store=True を含む background=True)またはストリーミング チェックポイントからの復元(65,536 個の出力トークンから始まり、その後 5,000 トークンごとに interaction.status_update イベントが生成される)の場合は、次のパターンを使用します。
Python(バックグラウンド)
import time
from google import genai
client = genai.Client(
enterprise=True,
project="PROJECT_ID",
location="global",
)
# Start a server-managed background long decode (requires store=True)
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Write a complete formal proof of the prime number theorem.",
background=True,
store=True,
generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
)
while interaction.status in ("queued", "in_progress"):
time.sleep(10)
interaction = client.interactions.get(id=interaction.id)
print(f"Status: {interaction.status}")
print(interaction.output_text)
# Optional: Cancel an in-progress background interaction and resume later
# from its persisted checkpoint continuation_token (if >= 65,536 tokens decoded).
# cancelled = client.interactions.cancel(id=interaction.id)
# if cancelled.continuation_token:
# resumed = client.interactions.create(
# model="gemini-4-hydrogen",
# previous_interaction_id=cancelled.id,
# continuation_token=cancelled.continuation_token,
# background=True,
# generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
# )
REST(バックグラウンド)
# Start a server-managed background long decode (requires store=true)
curl -s -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
-d '{
"model": "gemini-4-hydrogen",
"background": true,
"store": true,
"input": "Write a complete formal proof of the prime number theorem.",
"generation_config": {
"max_output_tokens": 256000,
"thinking_level": "high"
}
}'
# Poll the interaction until status reaches completed, incomplete, failed, or cancelled
curl -s -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID"
# Optional: Cancel an in-progress background decode
curl -s -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID/cancel"
# Optional: Resume a cancelled background decode from its checkpoint continuation_token
curl -s -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
-d '{
"model": "gemini-4-hydrogen",
"background": true,
"store": true,
"previous_interaction_id": "INTERACTION_ID",
"continuation_token": "CONTINUATION_TOKEN",
"generation_config": {
"max_output_tokens": 256000,
"thinking_level": "high"
}
}'
Python(ストリーミング チェックポイント)
from google import genai
from google.genai import errors
client = genai.Client(
enterprise=True,
project="PROJECT_ID",
location="global",
)
# With default automatic_continuation=True, stream=True automatically
# reconnects from the latest interaction.status_update checkpoint (65,536
# output tokens, then every 5,000 tokens) if no output was yielded after the
# checkpoint. If a disconnect occurs after output was yielded since the last
# checkpoint, the SDK raises ContinuationInterruptedError so you can resume
# from err.continuation_token.
stream = client.interactions.create(
model="gemini-4-hydrogen",
input="Write a complete formal proof of the prime number theorem.",
stream=True,
store=True,
generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
)
try:
for event in stream:
if event.event_type == "step.delta" and getattr(event.delta, "text", None):
print(event.delta.text, end="", flush=True)
except errors.ContinuationInterruptedError as err:
# Resuming from a mid-segment checkpoint regenerates any output yielded
# after that checkpoint.
if err.interaction_id and err.continuation_token:
resumed_stream = client.interactions.create(
model="gemini-4-hydrogen",
previous_interaction_id=err.interaction_id,
continuation_token=err.continuation_token,
stream=True,
store=True,
generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
)
for event in resumed_stream:
if event.event_type == "step.delta" and getattr(event.delta, "text", None):
print(event.delta.text, end="", flush=True)
REST(ストリーミング チェックポイント)
# Start a streaming interaction; save interaction.id from interaction.created
# and the latest continuation_token from interaction.status_update SSE events
curl -N -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
-d '{
"model": "gemini-4-hydrogen",
"stream": true,
"store": true,
"input": "Write a complete formal proof of the prime number theorem.",
"generation_config": {
"max_output_tokens": 256000,
"thinking_level": "high"
}
}'
# Resume a dropped stream from the last saved checkpoint continuation_token
# (for store=false, resend the original input instead of previous_interaction_id)
curl -N -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
-d '{
"model": "gemini-4-hydrogen",
"stream": true,
"store": true,
"previous_interaction_id": "SEGMENT_ID",
"continuation_token": "CHECKPOINT_CONTINUATION_TOKEN",
"generation_config": {
"max_output_tokens": 256000,
"thinking_level": "high"
}
}'
GenerateContent で長いデコードを使用する
GenerateContent(v1beta1)で、ストリーミング リクエストまたは非ストリーミング リクエストに対して max_output_tokens を 65,536 より大きい値(最大 1,048,576)に設定します。Google Gen AI SDK は、finish_reason が CONTINUATION の場合、セグメント間で continuation_token を自動的にフォローします(オプトアウトするには、GenerateContentConfig で automatic_continuation=False を設定します)。または、カスタムループで continuation_token を渡すこともできます。
Python(SDK - 推奨)
from google import genai
from google.genai import types
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
# Automatic continuation is enabled by default in google-genai >= 2.30.1.
# Chunks across all continuation requests are yielded as a single stream.
for chunk in client.models.generate_content_stream(
model="gemini-4-hydrogen",
contents="Write a complete formal proof of the prime number theorem.",
config=types.GenerateContentConfig(
max_output_tokens=256000,
thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
),
):
print(chunk.text, end="")
# Set automatic_continuation=False to disable automatic continuation.
for chunk in client.models.generate_content_stream(
model="gemini-4-hydrogen",
contents="Write a complete formal proof of the prime number theorem.",
config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
automatic_continuation=False,
),
):
print(chunk.text, end="")
REST(カスタム継続ループ)
# Request 1: Initial request with maxOutputTokens > 65,536
curl -s -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-hydrogen:generateContent" \
-d '{
"contents": [{
"role": "user",
"parts": [{"text": "Write a complete formal proof of the prime number theorem."}]
}],
"generationConfig": {
"maxOutputTokens": 131072,
"thinkingConfig": {"thinkingLevel": "HIGH"}
}
}'
# Request 2: Resend the original request with top-level continuationToken
# from Request 1 (candidates[0].continuationToken)
curl -s -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-hydrogen:generateContent" \
-d '{
"contents": [{
"role": "user",
"parts": [{"text": "Write a complete formal proof of the prime number theorem."}]
}],
"continuationToken": "CONTINUATION_TOKEN",
"generationConfig": {
"maxOutputTokens": 131072,
"thinkingConfig": {"thinkingLevel": "HIGH"}
}
}'
必須の API ルールと動作規則
Hydrogen は、思考レベル、トークン上限、キャッシュ、生成パラメータ、マルチターン ツール実行について、次のセクションの規則を適用します。
思考レベル
Hydrogen は 4 つの thinking_level 値をサポートしています(thinking_budget と MINIMAL は HTTP 400 検証エラーを返します)。次の表に、各思考レベルと推奨されるワークロードを示します。
| 思考レベル | 推奨されるワークロード |
|---|---|
XHIGH |
深い推論、数学的証明、科学的分析、最も複雑なマルチファイル ソフトウェア エンジニアリング タスク。 |
HIGH(gemini-4-hydrogen のデフォルト) |
マルチステップのエージェント ツールループ、コード生成、アーキテクチャのリファクタリング、複雑なマルチモーダル分析。 |
MEDIUM |
一般的なコーディング、ツールの使用、ドキュメントの Q&A、動画の理解を、バランスの取れたレイテンシで実現します。 |
LOW |
高スループットの分類、ルーティング、要約、構造化メタデータの抽出。 |
トークンの上限、キャッシュ保存、課金
Hydrogen には、次のトークン、キャッシュ、メディア、課金ルールが適用されます。
- 統合された入力トークンと出力トークンの上限と単一リクエストの出力上限:
トークン予算とリクエストごとの上限は次のように機能します。
- モデルの全体的なトークン上限は
1,048,576トークンで、入力トークンと出力トークンの両方が含まれます(出力には思考、関数呼び出し、最終レスポンスが含まれます)。max_output_tokensは、生成の出力トークンの上限を制御します(最大1,048,576から入力トークンを差し引いた値)。max_output_tokensを1,048,576より大きく設定すると、HTTP400エラーが返されます。 - 意図しない長い完了を回避するため、デフォルトの出力予算と単一セグメントのフォアグラウンド制限(思考、関数呼び出し、モデル レスポンス)は、ストリーミング リクエストと非ストリーミング リクエストの両方で 65,536 トークンです。
HIGH(デフォルト)とXHIGHで生成された推論トークンはmax_output_tokensにカウントされ、ターン間で思考シグネチャを保持すると、マルチターン コンテキストに蓄積されます。思考と最終出力の両方に十分なmax_output_tokensを設定し、マルチターン コーディング ハーネスでコンテキスト圧縮のしきい値を過度に低く設定しないようにします。また、レイテンシに敏感なツールターンでthinking_level="MEDIUM"を設定します。
- モデルの全体的なトークン上限は
- 長いデコード: 単一セグメントのフォアグラウンド レスポンスは、最大 65,536 個の出力トークン(ストリーミングまたは非ストリーミング)を生成します。Interactions API または
GenerateContent(v1beta1)でシングルターンの出力を最大 1,048,576 トークン(入力トークンを除く)に拡張するには、長いデコードをご覧ください。 - コンテキスト キャッシュ保存: 明示的なコンテキスト キャッシュ保存はサポートされていません。暗黙的なキャッシュ保存(デフォルトで耐久性のあるキャッシュ保存が有効)は、4,096 トークン以上の共有プロンプト接頭辞に自動的に適用されるため、プロンプトの先頭に静的コンテンツを配置します。
- Office と OpenDocument の入力: Word(
application/vnd.openxmlformats-officedocument.wordprocessingml.document、application/vnd.openxmlformats-officedocument.wordprocessingml.template、application/msword、application/vnd.oasis.opendocument.text)、PowerPoint(application/vnd.openxmlformats-officedocument.presentationml.presentation、application/vnd.ms-powerpoint、application/vnd.oasis.opendocument.presentation)、Excel または OpenDocument スプレッドシート(application/vnd.openxmlformats-officedocument.spreadsheetml.sheet、application/vnd.ms-excel、application/vnd.oasis.opendocument.spreadsheet)ファイルをインラインで、または Cloud Storage URI(gs://)で渡します。GenerateContentのinlineDataまたはfileData(FunctionResponse部分内を含む)と、Interactions API のdocument入力(ツールの結果を含む)を使用します。 - エージェント動画: アップロードされた動画はデフォルトで
media_processing="static"になります。media_processing="agentic"を設定して、エージェント型動画処理を有効にします。 - トークンのカウントと課金: モデルが処理するすべてのトークンがカウントされ、課金されます。これには、思考トークン、内部ツールのシステム指示、グラウンディングを使用する際の関数宣言が含まれます。Google 検索によるグラウンディングも、引き続きクエリごとに課金されます。
パラメータ、関数呼び出し、チャットの検証
Hydrogen は、生成パラメータ、ツール呼び出し、思考シグネチャ、チャット履歴に次のルールを適用します。
- 無視されるサンプリング パラメータ(
temperature、top_k、top_p): バックエンドはカスタム値を無視します。thinking_levelで推論の深さを制御し、response_schemaで出力形式を制御します。 - サポートされていないパラメータ(
frequency_penalty、presence_penalty、candidate_countが1より大きい):frequency_penalty、presence_penalty、またはcandidate_countが1より大きい(candidateCountは1に固定)場合、HTTP400エラーが返されます。これらのパラメータをリクエストから削除します。 関数呼び出しと思考シグネチャ: ツール宣言、並列ツール呼び出し、マルチターン
thought_signatureリプレイは、次のルールに従います。- 回転対称: 各
FunctionResponseは、前のFunctionCallのid、name、順序と一致する必要があります。 - マルチモーダル
FunctionResponse部分: Office ドキュメント、スプレッドシート、プレゼンテーション、PDF、画像、音声、動画を、個別のユーザーターン部分として追加するのではなく、マルチモーダルFunctionResponse部分(または Interactions API のツール結果)に含めます。 - 並列関数呼び出し
thought_signatureの配置: モデルが 1 つのmodelターンで複数の並列functionCall部分を出力する場合、最初のfunctionCall部分にのみthought_signatureが含まれます。アクティブなユーザー ターンで最初のfunctionCall部分からthought_signatureを省略したり、後続の並列functionCall部分に複製したり、functionCallターンとfunctionResponseターンをインターリーブしたりすると、HTTP400エラーが返されます。すべての並列functionCall部分を 1 つのmodelターンに保持し、その後に一致するすべてのfunctionResponse部分を 1 つのuserターンに保持します。詳細については、思考シグネチャをご覧ください。 - ターン間の
thought_signatureの保持: アクティブなユーザー ターン内だけでなく、マルチターン チャット履歴の以前のすべてのターン(functionCallと最終的なtextの両方の部分)で、元のPart内のすべてのthought_signatureを返します。HTTP400署名の検証は、アクティブなユーザー ターン内のfunctionCallステップにのみ適用されますが、以前のターンからthought_signature値を削除したり、skip_thought_signature_validatorなどのバイパス値を代入したりすると、推論コンテキストが削除され、出力品質が低下し、MALFORMED_FUNCTION_CALLの終了理由が発生する可能性があります。 ツール前の形式: インライン指示を
\n\nで区切り、ツール呼び出しの前に非構造化テキストを配置しないようにします。ツール呼び出しの前に中間状態をログに記録するには、専用の関数宣言を使用します。{ "name": "update", "description": "Update working notes before tool execution", "parameters": { "type": "OBJECT", "properties": { "previous_step": {"type": "STRING"}, "plan": {"type": "STRING"}, "next_step": {"type": "STRING"} }, "required": ["previous_step", "plan", "next_step"] } }
- 回転対称: 各
チャット シーケンスの検証: マルチターン チャットのペイロードには、次の制約が適用されます。
- 履歴ペイロードの末尾を
modelロールのターンにすることはできません。 - 事前入力済みモデルターンはサポートされていません。
- 履歴ペイロードの末尾を
長いデコード
長いデコードでは、Interactions API または GenerateContent(v1beta1)のいずれかで、最大 1,048,576 トークン(入力トークンを除く)の生成を複数のセグメントに分割します。Interactions API では、各フォアグラウンド セグメント(stream=true または stream=false)が最大 65,536 個の出力トークンを生成し、暗号化された continuation_token を含む status="requires_continuation" を返します。または、background=true(store=true)を設定して、サーバーが継続ループを非同期で実行し、マージされた出力を 1 つの Interaction に保存することもできます。GenerateContent では、各ストリーミング セグメントまたは非ストリーミング セグメントは、continuation_token を含む finish_reason=CONTINUATION を出力する前に最大 65,536 個の出力トークンを生成し、finish_reason=STOP まで続行します。Agent Studio で、出力トークンの上限を 65,536 より大きく 1,048,576 以下に設定すると、継続トークンが自動的に処理されます。実行可能なコードサンプルについては、長いデコードのクイックスタートの例をご覧ください。
長いデコードを使用するタイミング
ほとんどのリクエストは、セグメントあたりの出力上限である 65,536 トークン内で完了します。1 つのレスポンスでそれ以上の出力が必要な場合にのみ、長いデコードを使用します。長いデコードにより、モデルは推論の余地が広がります。回答が長くなるわけではありません(推論の深さを制御するには thinking_level を使用します)。
| ワークロード | 長いデコードを使用しますか? | 理由 |
|---|---|---|
| 高度な数学、科学、研究、形式的証明 | はい | モデルは 65,536 個以上のトークンを使用して、推論を探索して確認できます。 |
| 最も困難なコーディング タスクとエージェント タスク | はい | 一部のタスクでは、1 つのレスポンスで 65,536 トークンを超える思考とコードが必要になります。ほとんどのコーディング タスクとエージェント型タスクは 65,536 トークン未満で完了します。 |
| 出力上限で停止する評価ハーネス | はい | 長いデコードにより、モデルが 65,536 トークンのセグメント全体を思考に費やした場合でも、回答が途中で切れることがなくなります。 |
| チャット、Q&A、要約、分類、抽出 | いいえ | これらのタスクは 65,536 トークンをはるかに下回るトークン数で完了します。 |
| 「70 万語の本を書いて」など、固定の長さを求めるリクエスト | いいえ | モデルが長さの目標に従っていない。 |
| 短いターンでツールを何度も呼び出すエージェント | いいえ | 各ターンは短いです。各ターンで大量の出力が生成されると、1,048,576 トークンの入力と出力の統合上限にすぐに達してしまいます。 |
| 入力上限の 1,048,576 トークンに近いプロンプト | いいえ | 出力で使用できるのは、1,048,576 トークンから入力を差し引いた分のみです。 |
| レイテンシの影響を受けやすいリクエスト | いいえ | 長いデコードは数分間実行されることがあります。 |
継続オプションを選択する
API サーフェス、ストレージ ポスチャー、ランタイム環境に基づいて、継続パターンを選択します。次の表のすべてのオプションは、gemini-4-hydrogen で同じ 1,048,576 トークンの上限(入力トークンを除く)に達します。
| 継続オプション | API サーフェス | 各セグメントを開始するユーザー | セグメントあたりのトークン数 | リクエストあたりの制限時間 | サーバー ストレージ | 最適な用途 |
|---|---|---|---|---|---|---|
| Google Gen AI SDK の自動継続(推奨) | Interactions API(v1beta1) |
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) |
最大 65,536(stream=true または stream=false) |
セグメントあたり 20 分 | デフォルトで 7 日間のサーバー ストレージ(store=true)、またはなし(store=false) |
ほとんどのステートフルまたはステートレスな Interactions API アプリケーション |
バックグラウンド サーバー管理ループ(background=true) |
Interactions API(v1beta1) |
Agent Platform サーバー ループ。コードが get をポーリングします。 |
サーバーサイドで最大 max_output_tokens まで管理 |
非同期(オープン クライアント ストリームは不要) | 7 日間のサーバー ストレージ(store=true が必要) |
非同期ジョブ、.NET / Kotlin 呼び出し元、単一レコードの永続性 |
カスタム フォアグラウンド保存ループ(store=true) |
Interactions API(v1beta1) |
コード(previous_interaction_id + continuation_token、input なし) |
最大 65,536(stream=true または stream=false。チェックポイントは 65,536 から始まり、その後 5,000 トークンごと) |
セグメントあたり 20 分 | 7 日間のサーバー ストレージ(store=true) |
REST 呼び出し元とカスタム チェックポイントの復元 |
カスタム フォアグラウンド ステートレス ループ(store=false) |
Interactions API(v1beta1) |
コード(元の input + continuation_token、previous_interaction_id なし) |
最大 65,536(stream=true または stream=false。チェックポイントは 65,536 から始まり、その後 5,000 トークンごと) |
セグメントあたり 20 分 | サーバー ストレージなし(データの保持ゼロのワークフロー) | ステートレス実行を必要とするカスタム REST ハーネス |
| Google Gen AI SDK の自動継続(推奨) | GenerateContent(v1beta1) |
Google Gen AI SDK: Python(>= 2.30.1)、JavaScript / TypeScript(>= 2.29.1)、Go(>= 1.74.0)、Java(>= 1.77.0)、.NET(>= 1.26.0)、Kotlin(>= 1.6.0) |
最大 65,536(generate_content_stream または generate_content) |
セグメントあたり 20 分 | サーバー ストレージなし(データの保持ゼロのワークフロー) | 既存の GenerateContent アプリケーション |
| カスタム継続ループ | GenerateContent(v1beta1) |
コード(元の contents + continuation_token) |
最大 65,536(streamGenerateContent または generateContent。チェックポイントは 65,536 から始まり、その後 5,000 トークンごと) |
セグメントあたり 20 分 | サーバー ストレージなし(データの保持ゼロのワークフロー) | 直接 REST GenerateContent 呼び出し元と評価ハーネス |
API バージョンと SDK の要件
長いデコードには、次の API バージョンと最小 SDK バージョンが必要です。
v1beta1API の要件(既知の問題): Interactions API とGenerateContent(generateContentとstreamGenerateContent)の両方での長いデコード(continuation_token)は、Agent Platform のv1beta1API(v1ではない)でのみサポートされています。Google Gen AI SDK は、http_options(またはinteractions.createのapi_version="v1")でapi_version='v1'が指定されていない限り、デフォルトでv1beta1を使用します。直接 REST 呼び出しを行う場合は、/v1beta1/エンドポイント パスを使用します。- SDK のバージョンと OpenAI との互換性: Interactions API で自動継続を使用するには、Python
google-genai >= 2.34.0、JavaScript/TypeScript@google/genai >= 2.32.0、Go>= 1.77.0、Java>= 1.80.0にアップグレードします(Interactions API で .NET と Kotlin を使用する場合は、background=trueまたはカスタム継続ループを使用します)。GenerateContentで自動的に継続するには、Python>= 2.30.1、JavaScript/TypeScript>= 2.29.1、Go>= 1.74.0、Java>= 1.77.0、.NET>= 1.26.0、Kotlin>= 1.6.0にアップグレードしてください。以前の SDK バージョンと OpenAI 互換性レイヤでは、継続トークンを使用して長い補完を取得できません。
Interactions API の継続ルール
Interactions API での長いデコードには、次のステータス遷移、チェーンルール、ストレージ動作が適用されます。
ステータス値と出力トークン予算
Interactions API リクエストで generation_config.max_output_tokens が省略されている場合、合計出力予算はデフォルトで 65,536 トークンになります(ストリーミング リクエストと非ストリーミング リクエストの両方で 65,536 トークンの単一セグメント フォアグラウンド上限に一致します)。フォアグラウンド モードと background=true モードの両方で、マルチセグメントの長いデコードを行う場合は、generation_config.max_output_tokens を 65,536 より大きく(1,048,576 から入力トークンを引いた値まで)設定します。サーバーは次のステータス値を返します。
requires_continuation:max_output_tokensの前に、セグメントあたりの出力上限である 65,536 トークンに達しました。デコードを続行するには、次のリクエストで返されたcontinuation_tokenを渡します。incomplete:max_output_tokensの合計予算が使い果たされました。max_output_tokensを増やさずにcontinuation_tokenを続行すると、HTTP400エラー(max_output_tokens has already been exhausted)が返されます。デコードを再開するには、次のリクエストでmax_output_tokensを増やします。completed: 生成が自然に終了し、continuation_tokenがクリアされました。
チェーン、モード切り替え、セグメント ストレージ
Interactions API の継続リクエストには、次のルールが適用されます。
- 保存された継続(
store=true、デフォルト):continuation_tokenを発行したセグメントidに設定されたprevious_interaction_idをcontinuation_tokenとともに渡し、inputを省略します(保存されたセグメントにはすでにターン入力が保持されています)。各continuation_tokenは、それを発行したセグメントのprevious_interaction_idと常にペアにします。すでにcompletedのインタラクションでcontinuation_tokenを渡すと、HTTP400エラーが返されます。 - ステートレス継続(
store=false):previous_interaction_idを省略し、すべてのセグメントでcontinuation_tokenとともに元のinputを再送信します。 - セグメント間で
storeモードを切り替える: デコードの途中で、保存済み(store=true)からステートレス(store=false)に切り替えるには、previous_interaction_idを省略し、continuation_tokenを指定して元のinputを再送信します。previous_interaction_idに保存された親インタラクションが存在しないため、ステートレス(store=false)から保存済み(store=true)への切り替えはサポートされていません。 - フォアグラウンドと
background=trueモードの切り替えと分岐: 保存された継続(store=true)は、セグメント間でフォアグラウンド(background=false)とバックグラウンド(background=true)の実行を切り替えることができます。これには、キャンセルされたbackground=trueインタラクションを、バックグラウンド モードまたはフォアグラウンド モードのいずれかで、チェックポイントcontinuation_token(65,536 出力トークンから開始し、その後 5,000 トークンごとに永続化)から再開することも含まれます。同じprevious_interaction_idとcontinuation_tokenを再利用すると、独立した分岐継続が作成されます。 - ターン境界の適用: ステータスが
requires_continuationまたはincompleteのセグメントから新しいユーザー ターン(新しいinputを含むprevious_interaction_id、continuation_tokenなし)を開始すると、HTTP400エラーが返されます。completedへのデコードを完了するか、最新のcompletedインタラクションから次のターンを分岐します。最後のセグメントがcompletedに到達すると、その最後のセグメントのidをprevious_interaction_idとして渡すことで、以前のすべてのセグメントにわたる会話履歴全体が再構築されます。 - セグメント間のパラメータの一貫性: 継続セグメントで
model、system_instruction、または関数宣言(tools)を変更すると、HTTP400エラーが返されます。thinking_levelと組み込みツールも、セグメント間で変更しないでください(既知の問題を参照)。 - 単一セグメントの
get、list、deleteの動作: フォアグラウンド モード(background=false)では、各セグメントは個別のInteractionリソースとして保存されます(interactions.get(id)はそのセグメントのみを返し、interactions.list()は各セグメントを個別に一覧表示し、interactions.delete(id)はそのセグメントのみを削除します。セグメントのチェーンを削除する場合は、最後のセグメントから逆順に削除します)。automatic_continuation=True(stream=False)を使用する Google Gen AI SDK では、interactions.create()は戻り時にすべてのセグメントをマージし、順序付けられたセグメント ID(interaction.idで終わる)をinteraction.continuation_idsに入力します。後続のセグメントが失敗した場合、呼び出しごとの数値timeoutを超えた場合、または再開可能なチェックポイントを過ぎて進行した後にストリームの途中でドロップした場合、SDK はpartial_interaction、continuation_token、interaction_id、continuation_idsを含むContinuationInterruptedErrorを発生させ、continuation_tokenから再開できるようにします。
GenerateContent のカスタムループ ルール
カスタム GenerateContent 継続ループでは、次のルールに従います。
max_output_tokensを 65,536 より大きい値(最大 1,048,576)に設定し、すべての継続リクエストで元のcontents、system_instruction、toolsを最新のcontinuation_token(REST のGenerateContentRequestの最上位フィールド、または Google Gen AI SDK のGenerateContentConfig)とともに再送信します。- 部分的なモデル出力を
contentsに追加したり、モデルに続行を求めるフォローアップ プロンプトを送信したりしないでください。 finish_reasonがCONTINUATIONで、continuation_tokenが存在する場合は、セグメントが思考(parts: [{"text": ""}])に 65,536 トークンすべてを消費した場合でも、ループを続行します。continuation_tokenが存在するときにfinish_reasonがMAX_TOKENSの場合は、次のリクエストでmax_output_tokensを増やします。STOPの後にのみ、蓄積された部分をマルチターンの履歴の単一のmodelターンに結合します。
トークンのカウント、圧縮、暗黙的なキャッシュ保存
継続セグメント間のトークンのカウントとキャッシュは次のように機能します。
- Interactions API では、
automatic_continuation=Trueを使用した非ストリーミングinteractions.create()呼び出しとサーバー管理のbackground=trueインタラクションにより、usage(total_input_tokens、total_cached_tokens、total_output_tokens、total_thought_tokens、total_tokens)のすべてのセグメントのトークン数が合計され、最初のセグメントのプロンプト数がusage.initial_input_tokensに保持されます。カスタム フォアグラウンド ループとストリーミングされたinteraction.completedイベントでは、各セグメントのusageはそのセグメントの差分のみを報告するため、セグメント間でusageフィールドを合計して、請求対象のトークンの合計を算出します。 GenerateContentでは、Python Google Gen AI SDK(generate_contentとgenerate_content_stream)は、最後のusage_metadataでセグメント全体の合計課金トークンを累積し、initial_prompt_token_countを保持します。カスタム REST ループでは、セグメント全体の最終的なprompt_token_count、cached_content_token_count、candidates_token_count、thoughts_token_countを合計します。- 各フォアグラウンド継続セグメントは、会話と以前に生成されたトークンを入力として再事前入力するため、
usage.total_input_tokens(Interactions API)とprompt_token_count(GenerateContent)はセグメント間で増加します。エージェント ハーネスでコンテキストの圧縮をトリガーするために、累積入力数を使用しないでください。代わりに、usage.initial_input_tokens(またはGenerateContentのinitial_prompt_token_count)を確認し、ターンが終了した後にのみ圧縮します(status="completed"またはcontinuation_tokenなし)。 - 各継続セグメントは、プロンプトと以前にデコードされたトークンを再事前入力し、セグメントが連続して実行されると、暗黙的なコンテキスト キャッシュ(4,096 トークン以上、デフォルトで永続的なキャッシュが有効)の対象になります。完了したセグメントは、後のセグメントが失敗またはキャンセルされた場合でも、各セグメントの終了時に課金されます。
3.8 Flash から Hydrogen に移行する
次の動作は、gemini-3.8-flash 以前の Gemini 3 Flash モデルとは異なります。
- Hydrogen には、入力と出力(出力には思考、関数呼び出し、最終レスポンスが含まれます)に個別の入力と出力の制限ではなく、1,048,576 トークンの統合制限があります。単一セグメントのフォアグラウンド出力は 65,536 トークン(ストリーミングまたは非ストリーミング)に制限されています。Interactions API または
GenerateContentでロングデコードを使用すると、最大 1,048,576 トークンまで拡張できます(Google Gen AI SDK で自動的に処理されます。Interactions API ではbackground=true、カスタムループではcontinuation_tokenを使用します)。 - デフォルトの
thinking_levelはHIGH(gemini-3.8-flashにMEDIUMから変更)で、XHIGHはディープ推論タスクでサポートされています(マルチターン コーディング ハーネスでHIGHとXHIGHの推論トレース用にコンテキスト圧縮のヘッドルームを残すか、レイテンシに敏感なターンでMEDIUMを設定します)。thinking_budgetとthinking_level="MINIMAL"は HTTP400エラーを返します。 - 明示的なコンテキスト キャッシュ保存(
cached_content)はサポートされていません。暗黙的なキャッシュ保存は、4,096 トークン以上(gemini-3.8-flashの 6,144 トークンから削減)で自動的に適用され、デフォルトで耐久性のあるキャッシュ保存が有効になります。 - Microsoft Office(
.docx、.dotx、.doc、.pptx、.ppt、.xlsx、.xls)と OpenDocument(.odt、.odp、.ods)ファイルは、インラインまたは Cloud Storage URI(gs://)でサポートされています。これには、マルチモーダルFunctionResponse部分内も含まれます。 - 並列関数呼び出しターンでは、厳格な
thought_signatureの配置が適用されます(並列ターンの最初のfunctionCall部分のみがthought_signatureを持ちます。アクティブなターンで省略したり、後続の兄弟functionCall部分に複製したりすると、HTTP400エラーが返されます)。また、ThinkingConfigでprefix_mismatch_behavior="DROP"が設定されていない限り、同じモデルのプロンプト プレフィックスの編集はデフォルトで HTTP400で失敗します。推論の品質を維持し、MALFORMED_FUNCTION_CALLの終了理由を回避するために、以前のすべてのターンでthought_signature部分(functionCall部分と最終的なtext部分の両方)を保持します。 - モデルが処理するすべてのトークンが課金されます。これには、グラウンディングを使用する場合の内部ツールシステム指示と関数宣言も含まれます。
並べて比較するには、Gemini 3 モデルから移行するをご覧ください。
client = genai.Client(
enterprise=True,
project="PROJECT_ID",
location="global", # Supports "global", "us", and "eu"
)
response = client.models.generate_content(
- model="gemini-3.8-flash",
+ model="gemini-4-hydrogen",
contents=prompt,
config=types.GenerateContentConfig(
- temperature=0.0,
- cached_content="projects/.../cachedContents/...", # Explicit caching unsupported
thinking_config=types.ThinkingConfig(
- thinking_budget=16384, # Returns HTTP 400 instead of mapping silently
- thinking_level="MINIMAL", # MINIMAL unsupported on Gemini 4 Hydrogen
+ thinking_level="HIGH", # Valid: "LOW", "MEDIUM", "HIGH" (default), "XHIGH"
+ # prefix_mismatch_behavior="DROP", # Optional: set if compacting or editing prior history
),
),
)
gemini-3.8-flash 以前の Gemini 3 Flash モデルから移行するには、次の操作を行います。
- モデル ID を
gemini-4-hydrogenに更新します。 - 最新の Google Gen AI SDK にアップグレードし、統合された入力トークンと出力トークンの上限を考慮する: Interactions API の自動継続(または
GenerateContentの>= 2.30.1Python />= 2.29.1JavaScript)のために、google-genai >= 2.34.0(Python)、@google/genai >= 2.32.0(JavaScript/TypeScript)、Go>= 1.77.0、または Java>= 1.80.0にアップグレードします。入力トークンと出力トークン(思考と関数呼び出しを含む)は、統合された 1,048,576 トークンの上限を共有します。Interactions API またはGenerateContentで 65,536 トークン(最大 1,048,576 トークン)を超える出力の場合は、max_output_tokensを 65,536 より大きく設定して、Google Gen AI SDK がセグメント間で自動的に継続するようにします(または、background=trueまたはカスタムcontinuation_tokenループを使用します)。 thinking_level構成を更新する:thinking_budgetとMINIMALを、LOW、MEDIUM、HIGH(gemini-4-hydrogenのデフォルト)、またはXHIGHに設定されたthinking_levelに置き換えます(Interactions API では、小文字の"low"、"medium"、"high"、または"xhigh"を使用します)。ワークロードがgemini-3.8-flashのデフォルトとしてMEDIUMに依存していた場合は、thinking_level="MEDIUM"を明示的に設定して、同等の推論レイテンシを維持します。- 明示的なキャッシュ保存を削除し、静的なプロンプト コンテンツ(4,096 トークン以上)をフロントロードして、自動的な暗黙的なキャッシュ保存を行います。
- マルチターンと並列
thought_signatureの保持とプレフィックスの圧縮を確認する: ターン間で署名を削除するのではなく、以前のすべてのターン(functionCallと最終textの両方の部分)でthought_signatureを保持します。並列ツール呼び出しターンの最初のfunctionCall部分でのみthought_signatureを保持します。アプリケーションがマルチターン チャット履歴の以前のターンを変更または圧縮する場合は、ThinkingConfigでprefix_mismatch_behavior="DROP"を設定します。 - 効果がない、またはサポートされていないパラメータを削除する: 無視された生成フィールドと拒否された生成フィールドを次のように削除します。
- 無視される
temperature、top_p、top_kを削除します。 frequency_penalty、presence_penalty、1より大きいcandidate_count値を削除します。- 会話履歴から事前入力済みモデルターンを削除します。
- 無視される
デベロッパー向けの概要チェックリスト
次のチェックリストを使用して、Hydrogen の統合を確認します。
既知の問題
Hydrogen の長いデコードには、次の既知の問題が適用されます。
- 長いデコードには
v1beta1が必要: Interactions API とGenerateContentAPI(generateContentとstreamGenerateContent)の両方での長いデコード(continuation_token)は、Agent Platform のv1beta1API(v1ではない)でのみサポートされています。Google Gen AI SDK は、http_options(またはinteractions.createのapi_version="v1")にapi_version='v1'が設定されていない限り、デフォルトでv1beta1を使用します。直接 REST 呼び出しを行う場合は、/v1beta1/エンドポイント パスを使用します。 - Interactions API の継続セグメント間でのパラメータの変更: 継続セグメント間で
model、system_instruction、または関数宣言を変更すると、HTTP400エラーが返されます。一方、デコード中にgeneration_config.thinking_levelまたは組み込みツール(google_search、code_execution、url_context)を変更しても、サーバー検証で拒否されることはありません。継続ループのすべてのセグメントで、thinking_levelと組み込みツールを変更しないようにします。
参考情報
Hydrogen の詳細については、次のリソースをご覧ください。