Gemini 4 Hydrogen bietet modernste Intelligenz mit Geschwindigkeit und Effizienz für alltägliche Programmier- und agentische Unternehmensworkflows.
In diesem Dokument werden die wichtigsten Funktionen von Hydrogen, die von der API erzwungenen API-Konventionen, die Migration von Gemini 3.8 Flash und früheren Gemini 3 Flash-Modellen sowie eine Kurzanleitung behandelt. Eine Übersicht über die Gemini 4-Familie finden Sie unter Erste Schritte mit Gemini 4.
Wichtige Funktionen in Gemini 4 Hydrogen
Gemini 4 Hydrogen bietet die folgenden Funktionen:
- Einheitliches Limit für Eingabe- und Ausgabetokens: Hydrogen hat ein einheitliches Limit von 1.048.576 Tokens, das sowohl Eingabe- als auch Ausgabetokens umfasst. Die Ausgabe umfasst dabei Denkprozesse, Funktionsaufrufe und die endgültige Antwort.
- Lange Decodierungen mit bis zu 1.048.576 Tokens: Hydrogen erweitert die Generierung über ein einzelnes Vordergrundsegment mit 65.536 Tokens (Streaming oder Nicht-Streaming) hinaus auf bis zu 1.048.576 Tokens (abzüglich Ihrer Eingabetokens) sowohl in der Interactions API als auch in
GenerateContent(v1beta1). Das Google Gen AI SDK verarbeitetcontinuation_tokenautomatisch segmentübergreifend. Alternativ können Sie asynchrone, vom Server verwaltete Hintergrunddecodierungen (background=true) ausführen odercontinuation_tokenin einer benutzerdefinierten Fortsetzungsschleife verwalten. - Denkstufen: Hydrogen unterstützt
LOW,MEDIUM,HIGH(Standard) undXHIGH. - Implizites Caching mit langlebigem Caching: Implizites Caching wird automatisch auf freigegebene Prompt-Präfixe mit 4.096 Tokens oder mehr angewendet. Langlebiges Caching ist standardmäßig aktiviert. Explizites Kontext-Caching wird nicht unterstützt.
- Office- und OpenDocument-Dateieingaben: Neben PDF- und Nur-Text-Dateien akzeptiert Hydrogen Microsoft Office- (
.docx,.dotx,.doc,.pptx,.ppt,.xlsx,.xls) und OpenDocument-Dateien (.odt,.odp,.ods) inline oder aus Cloud Storage, sowohl inGenerateContentals auch in der Interactions API, einschließlich in multimodalenFunctionResponse-Teilen. - Agentisches Videoverständnis: Das agentische Videoverständnis ist allgemein verfügbar und standardmäßig deaktiviert.
- Kurzfristiger Release-Lebenszyklus: Hydrogen ist ein kurzfristiger, allgemein verfügbarer Release, für den eine Richtlinie zur Einstellung mit einer Frist von mindestens 45 Tagen gilt. Weitere Informationen zum Lebenszyklus finden Sie unter Modellversionen und Lebenszyklus.
Kurzanleitung
Bevor Sie beginnen, müssen Sie sich bei der Gemini Enterprise Agent Platform mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) oder einem API-Schlüssel authentifizieren. Weitere Informationen finden Sie unter Erste Schritte mit der Agent Platform.
Ersetzen Sie in den folgenden Codeblöcken PROJECT_ID durch Ihre Projekt-ID.
In Agent Studio ausprobieren
So testen Sie Prompts und konfigurieren gemini-4-hydrogen in der Agent Studio-Benutzeroberfläche:
- Öffnen Sie Agent Studio in Ihrem Google Cloud -Projekt und wählen Sie
gemini-4-hydrogenin der Gemini-Gruppe aus. - Konfigurieren Sie unter Modelleinstellungen die folgenden Optionen:
- Denkstufe: Wählen Sie
Low,Medium,High(Standard) oderExtra highaus. - Region: Wählen Sie
Global,usodereuaus. - Tokenausgabelimit: Legen Sie einen Wert zwischen
32,768und1,048,576fest (Standardwert:1,048,576). Agent Studio verarbeitet Fortsetzungstokens automatisch für Antworten, die das Limit für einzelne Anfragen überschreiten.
- Denkstufe: Wählen Sie
Installation
Führen Sie ein Upgrade auf das neueste Google Gen AI SDK durch. Für die automatische Fortsetzung in der Interactions API ist google-genai >= 2.34.0 für Python, @google/genai >= 2.32.0 für JavaScript/TypeScript, >= 1.77.0 für Go oder >= 1.80.0 für Java erforderlich (auf GenerateContent ist für die automatische Fortsetzung >= 2.30.1 für Python, >= 2.29.1 für JavaScript/TypeScript, >= 1.74.0 für Go, >= 1.77.0 für Java, >= 1.26.0 für .NET oder >= 1.6.0 für Kotlin erforderlich):
pip install --upgrade "google-genai>=2.34.0"
Einfache Anfrage
Senden Sie mit dem Google Gen AI SDK oder REST eine Anfrage an 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"
}
}
}'
Strukturierte Ausgabe
Wenn Sie eine JSON-Ausgabe generieren möchten, die einem Schema entspricht, konfigurieren Sie response_mime_type und 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)
Beispiele für lange Decodierungen
Standardmäßig generiert ein einzelnes Vordergrund-API-Segment bis zu 65.536 Ausgabetokens (Streaming oder Nicht-Streaming). Die Ausgabe umfasst Thinking, Funktionsaufrufe und die endgültige Antwort. Wenn Sie Vervollständigungen mit bis zu 1.048.576 Tokens (abzüglich Ihrer Eingabe-Tokens) generieren möchten, verwenden Sie lange Decodierungen entweder mit der Interactions API oder mit GenerateContent. Informationen zu Fortsetzungsoptionen, Statusübergängen und Validierungsregeln finden Sie unter Lange Decodierungen.
Lange Decodierungen mit der Interactions API verwenden
In google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0 und Java >= 1.80.0 folgt interactions.create() automatisch continuation_token über Segmente hinweg, wenn ein Segment status="requires_continuation" zurückgibt. Sie können auch die Option automatic_continuation=False deaktivieren, um eine benutzerdefinierte gespeicherte (store=True) oder zustandslose (store=False) Schleife auszuführen:
Python (SDK automatisch)
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 (benutzerdefinierte Schleife)
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 (gespeichert)
# 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 (zustandslos)
# 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"
}
}'
Verwenden Sie für die asynchrone, vom Server verwaltete Ausführung (background=True mit store=True) oder die Wiederherstellung aus Streaming-Prüfpunkten (interaction.status_update-Ereignisse, die ab 65.536 Ausgabetokens und danach alle 5.000 Tokens ausgegeben werden) die folgenden Muster:
Python (Hintergrund)
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 (Hintergrund)
# 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 (Streaming-Prüfpunkte)
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 (Streaming-Prüfpunkte)
# 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"
}
}'
Lange Decodierungen mit GenerateContent verwenden
Legen Sie auf GenerateContent (v1beta1) max_output_tokens größer als 65.536 (bis zu 1.048.576) für Streaming- oder Nicht-Streaming-Anfragen fest. Das Google Gen AI SDK folgt automatisch continuation_token über Segmente hinweg, wenn finish_reason auf CONTINUATION gesetzt ist (setzen Sie automatic_continuation=False in GenerateContentConfig, um dies zu deaktivieren). Alternativ können Sie continuation_token in einer benutzerdefinierten Schleife übergeben:
Python (SDK – empfohlen)
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 (benutzerdefinierte Fortsetzungsschleife)
# 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"}
}
}'
Obligatorische API-Regeln und Verhaltenskonventionen
Hydrogen erzwingt die Konventionen in den folgenden Abschnitten für Denkebenen, Tokenlimits, Caching, Generierungsparameter und die Ausführung von Tools mit mehreren Durchgängen.
Denkaufwand
Hydrogen unterstützt vier thinking_level-Werte (thinking_budget und MINIMAL geben einen HTTP-400-Validierungsfehler zurück). In der folgenden Tabelle sind die einzelnen Denkebenen und die empfohlenen Arbeitslasten aufgeführt:
| Denkaufwand | Empfohlene Arbeitslasten |
|---|---|
XHIGH |
Deep Reasoning, mathematische Beweise, wissenschaftliche Analysen und die komplexesten Softwareentwicklungsaufgaben mit mehreren Dateien. |
HIGH (Standardeinstellung auf gemini-4-hydrogen) |
Mehrstufige agentische Tool-Schleifen, Codegenerierung, architektonisches Refactoring und komplexe multimodale Analyse. |
MEDIUM |
Allgemeine Programmierung, Toolnutzung, Fragen und Antworten zu Dokumenten und Videoverständnis mit ausgewogener Latenz. |
LOW |
Klassifizierung, Routing, Zusammenfassung und Extraktion strukturierter Metadaten mit hohem Durchsatz. |
Tokenlimits, Caching und Abrechnung
Für Hydrogen gelten die folgenden Regeln für Tokens, Caching, Medien und Abrechnung:
- Einheitliches Limit für Eingabe- und Ausgabetokens und Ausgabelimits pro Anfrage:
Tokenbudgets und Limits pro Anfrage funktionieren so:
- Das Gesamt-Tokenlimit des Modells beträgt
1,048,576Tokens und umfasst sowohl Eingabe- als auch Ausgabe-Tokens (wobei die Ausgabe Thinking, Funktionsaufrufe und die endgültige Antwort umfasst).max_output_tokenssteuert die Obergrenze für die Ausgabe-Tokens für die Generierung (bis zu1,048,576minus Ihrer Eingabe-Tokens). Wenn Siemax_output_tokensgrößer als1,048,576festlegen, wird ein HTTP-400-Fehler zurückgegeben. - Um unbeabsichtigt lange Ausgaben zu vermeiden, beträgt das Standardausgabebudget und das Limit für ein einzelnes Segment im Vordergrund (Thinking, Funktionsaufrufe und Modellantwort) 65.536 Tokens für Streaming- und Nicht-Streaming-Anfragen.
- Reasoning-Tokens, die mit
HIGH(Standard) undXHIGHgeneriert werden, werden aufmax_output_tokensangerechnet und im Kontext mit mehreren Runden akkumuliert, wenn Sie Thought-Signaturen über mehrere Runden hinweg beibehalten. Legen Siemax_output_tokenshoch genug für die Denkprozesse und die endgültige Ausgabe fest, vermeiden Sie zu niedrige Schwellenwerte für die Kontextkomprimierung in Multi-Turn-Coding-Harnesses oder legen Siethinking_level="MEDIUM"für latenzempfindliche Tool-Turns fest.
- Das Gesamt-Tokenlimit des Modells beträgt
- Lange Decodierungen: Vordergrundantworten mit einem Segment generieren bis zu 65.536 Ausgabetokens (Streaming oder Nicht-Streaming). Informationen zum Erweitern der Single-Turn-Ausgabe auf bis zu 1.048.576 Tokens (abzüglich Eingabetokens) in der Interactions API oder
GenerateContent(v1beta1) finden Sie unter Lange Decodierungen. - Kontext-Caching: Explizites Kontext-Caching wird nicht unterstützt. Das implizite Caching (mit standardmäßig aktiviertem langlebigem Caching) wird automatisch auf freigegebene Prompt-Präfixe mit mindestens 4.096 Tokens angewendet. Platzieren Sie statische Inhalte daher am Anfang des Prompts.
- Office- und OpenDocument-Eingaben: 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) und Excel- oder OpenDocument-Tabellendateien (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,application/vnd.ms-excel,application/vnd.oasis.opendocument.spreadsheet) inline oder per Cloud Storage-URI (gs://) mitinlineDataoderfileDatainGenerateContent(einschließlich inFunctionResponse-Teilen) unddocument-Eingaben (einschließlich Tool-Ergebnissen) in der Interactions API übergeben. - Agentisches Video: Hochgeladene Videos werden standardmäßig auf
media_processing="static"gesetzt. Legen Siemedia_processing="agentic"fest, um die agentische Videoverarbeitung zu aktivieren. - Tokenzählung und Abrechnung: Jedes vom Modell verarbeitete Token wird gezählt und abgerechnet. Dazu gehören auch Thinking-Tokens, interne Toolsystemanweisungen und Funktionsdeklarationen, wenn die Fundierung verwendet wird. Die Fundierung mit der Google Suche wird weiterhin pro Abfrage abgerechnet.
Parameter, Funktionsaufrufe und Chatvalidierung
Hydrogen erzwingt die folgenden Regeln für Generierungsparameter, Toolaufrufe, Gedankensignaturen und den Chatverlauf:
- Ignorierte Sampling-Parameter (
temperature,top_k,top_p): Das Backend ignoriert benutzerdefinierte Werte. Mitthinking_levelkönnen Sie den Detailgrad der Problemlösung und mitresponse_schemadas Ausgabeformat steuern. - Nicht unterstützte Parameter (
frequency_penalty,presence_penaltyundcandidate_countgrößer als1): Wenn Siefrequency_penalty,presence_penaltyodercandidate_countgrößer als1übergeben (candidateCountist auf1festgelegt), wird ein HTTP-Fehler400zurückgegeben. Entfernen Sie diese Parameter aus Ihren Anfragen. Funktionsaufrufe und Gedankensignaturen: Tooldeklarationen, parallele Toolaufrufe und
thought_signature-Wiederholungen mit mehreren Runden folgen diesen Regeln:- Symmetrie der Abbiegungen: Jede
FunctionResponsemuss mit derid, dernameund der Reihenfolge der vorherigenFunctionCallübereinstimmen. - Multimodale
FunctionResponse-Teile: Fügen Sie Office-Dokumente, Tabellen, Präsentationen, PDFs, Bilder, Audio und Video in multimodaleFunctionResponse-Teile (oder Tool-Ergebnisse in der Interactions API) ein, anstatt sie als separate Teile des Nutzerbeitrags anzuhängen. - Platzierung von parallelen Funktionsaufrufen (
thought_signature): Wenn das Modell mehrere parallelefunctionCall-Teile in einer einzelnenmodel-Runde ausgibt, enthält nur der erstefunctionCall-Teil denthought_signature. Wenn Siethought_signatureim erstenfunctionCall-Teil im aktiven Nutzer-Turn weglassen, es in nachfolgenden parallelenfunctionCall-Teilen duplizieren oderfunctionCall- undfunctionResponse-Turns verschachteln, wird ein HTTP-400-Fehler zurückgegeben. Behalten Sie alle parallelenfunctionCall-Teile in einem einzigenmodel-Turn bei, gefolgt von allen übereinstimmendenfunctionResponse-Teilen in einem einzigenuser-Turn. Weitere Informationen finden Sie unter Thought-Signaturen. thought_signature-Erhaltung über mehrere Runden: Geben Sie jedethought_signatureinnerhalb ihrer ursprünglichenPartüber alle vorherigen Runden im Chatverlauf mit mehreren Runden (sowohlfunctionCall- als auch endgültigetext-Teile) zurück, nicht nur innerhalb der aktiven Nutzerrunde. Die HTTP-400-Signaturvalidierung gilt zwar nur fürfunctionCall-Schritte innerhalb des aktiven Nutzerturns, aber das Entfernen vonthought_signature-Werten aus früheren Turns oder das Ersetzen durch Bypass-Werte wieskip_thought_signature_validatorentfernt den Reasoning-Kontext, verschlechtert die Ausgabequalität und kann zuMALFORMED_FUNCTION_CALL-Beendigungsgründen führen.Formatierung vor dem Toolaufruf: Trennen Sie Inline-Anweisungen mit
\n\nund vermeiden Sie unstrukturierten Text vor Toolaufrufen. Wenn Sie den Zwischenstatus vor einem Toolaufruf protokollieren möchten, verwenden Sie eine dedizierte Funktionsdeklaration:{ "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"] } }
- Symmetrie der Abbiegungen: Jede
Validierung der Chatsequenz: Für Multi-Turn-Unterhaltungen gelten die folgenden Einschränkungen:
- Verlaufsnutzlasten dürfen nicht mit einem Rollenwechsel von
modelenden. - Vorausgefüllte Modellantworten werden nicht unterstützt.
- Verlaufsnutzlasten dürfen nicht mit einem Rollenwechsel von
Lange Decodierungen
Bei der langen Decodierung wird eine Generierung von bis zu 1.048.576 Tokens (abzüglich Ihrer Eingabetokens) auf mehrere Segmente aufgeteilt, entweder über die Interactions API oder GenerateContent (v1beta1). Bei der Interactions API generiert jedes Vordergrundsegment (stream=true oder stream=false) bis zu 65.536 Ausgabetokens und gibt status="requires_continuation" mit einem verschlüsselten continuation_token zurück. Alternativ können Sie background=true (store=true) festlegen, damit der Server die Fortsetzungsschleife asynchron ausführt und die zusammengeführte Ausgabe in einem Interaction speichert. Bei GenerateContent generiert jedes Streaming- oder Nicht-Streaming-Segment bis zu 65.536 Ausgabetokens, bevor finish_reason=CONTINUATION mit continuation_token ausgegeben wird. Dies wird bis finish_reason=STOP fortgesetzt. Wenn Sie in Agent Studio das Tokenausgabelimit auf einen Wert zwischen 65.536 und 1.048.576 festlegen, werden Fortsetzungstokens automatisch verarbeitet. Ausführbare Codebeispiele finden Sie in den Beispielen für die Kurzanleitung zur langen Decodierung.
Wann sollte die lange Decodierung verwendet werden?
Die meisten Anfragen werden innerhalb des Ausgabelimits von 65.536 Tokens pro Segment abgeschlossen. Verwenden Sie die lange Decodierung nur, wenn eine Antwort mehr Ausgabe erfordert. Die lange Decodierung gibt dem Modell mehr Raum zum Schlussfolgern. Die Antworten werden dadurch nicht länger. Verwenden Sie thinking_level, um die Tiefe des Schlussfolgerns zu steuern.
| Arbeitslast | Lange Decodierung verwenden? | Warum |
|---|---|---|
| Schwierige Mathematik, Naturwissenschaften, Forschung und formale Beweise | Ja | Das Modell kann mehr als 65.536 Tokens verwenden,um seine Logik zu prüfen. |
| Die schwierigsten Coding- und agentischen Aufgaben | Ja | Für manche Aufgaben sind mehr als 65.536 Tokens für Denkprozesse und Code in einer Antwort erforderlich. Die meisten Coding- und agentischen Aufgaben werden mit weniger als 65.536 Tokens abgeschlossen. |
| Bewertungssysteme, die beim Ausgabelimit stoppen | Ja | Die lange Decodierung verhindert abgeschnittene Antworten,wenn das Modell ein ganzes Segment mit 65.536 Tokens für den Thinking-Modus verwendet. |
| Chat, Fragen und Antworten, Zusammenfassung, Klassifizierung und Extraktion | Nein | Diese Aufgaben werden mit deutlich weniger als 65.536 Tokens abgeschlossen. |
| Anfragen nach einer festen Länge, z. B. „Schreib ein Buch mit 700.000 Wörtern“ | Nein | Das Modell hält sich nicht an die Längenvorgaben. |
| Für KI-Agenten, die Tools in vielen kurzen Schritten aufrufen | Nein | Jeder Zug ist kurz. Große Ausgaben in jeder Runde füllen das einheitliche Eingabe- und Ausgabelimit von 1.048.576 Tokens schnell. |
| Prompts, die nahe am Eingabelimit von 1.048.576 Tokens liegen | Nein | Die Ausgabe kann nur 1.048.576 Tokens abzüglich Ihrer Eingabe verwenden. |
| Latenzempfindliche Anfragen | Nein | Die lange Decodierung kann mehrere Minuten dauern. |
Fortsetzungsoption auswählen
Wählen Sie ein Fortsetzungsmuster basierend auf Ihrer API-Oberfläche, Ihrem Speicherstatus und Ihrer Laufzeitumgebung aus. Alle Optionen in der folgenden Tabelle erreichen das gleiche Limit von 1.048.576 Tokens (abzüglich Eingabe-Tokens) für gemini-4-hydrogen.
| Fortsetzungsoption | API-Oberfläche | Wer startet die einzelnen Segmente? | Tokens pro Segment | Zeitlimit pro Anfrage | Serverspeicher | Optimal für |
|---|---|---|---|---|---|---|
| Automatische Fortsetzung des Google Gen AI SDK (empfohlen) | Interactions API (v1beta1) |
Google Gen AI SDKs: Python (google-genai >= 2.34.0), JavaScript/TypeScript (@google/genai >= 2.32.0), Go (>= 1.77.0) und Java (>= 1.80.0) |
Bis zu 65.536 (stream=true oder stream=false) |
20 Minuten pro Segment | Standardmäßig 7 Tage Serverspeicher (store=true) oder kein Serverspeicher (store=false) |
Die meisten zustandsorientierten oder zustandslosen Interactions API-Anwendungen |
Vom Server verwaltete Schleife im Hintergrund (background=true) |
Interactions API (v1beta1) |
Agent Platform-Serverschleife; Ihr Code fragt get ab |
Serverseitig verwaltet bis zu max_output_tokens |
Asynchron (kein offener Clientstream erforderlich) | 7-Tage-Serverspeicher (store=true erforderlich) |
Asynchrone Jobs, .NET-/Kotlin-Aufrufer und Persistenz einzelner Datensätze |
Benutzerdefinierte gespeicherte Schleife im Vordergrund (store=true) |
Interactions API (v1beta1) |
Ihr Code (previous_interaction_id + continuation_token, kein input) |
Bis zu 65.536 (stream=true oder stream=false; Prüfpunkte ab 65.536 und danach alle 5.000 Tokens) |
20 Minuten pro Segment | 7 Tage Serverspeicher (store=true) |
REST-Aufrufer und benutzerdefinierte Prüfpunktwiederherstellung |
Benutzerdefinierte zustandslose Schleife im Vordergrund (store=false) |
Interactions API (v1beta1) |
Ihr Code (ursprünglicher input + continuation_token, kein previous_interaction_id) |
Bis zu 65.536 (stream=true oder stream=false; Prüfpunkte ab 65.536 und danach alle 5.000 Tokens) |
20 Minuten pro Segment | Keine Serverspeicherung (Zero Data Retention-Workflows) | Benutzerdefinierte REST-Harnesses, die eine zustandslose Ausführung erfordern |
| Automatische Fortsetzung des Google Gen AI SDK (empfohlen) | GenerateContent (v1beta1) |
Google Gen AI SDKs: Python (>= 2.30.1), JavaScript/TypeScript (>= 2.29.1), Go (>= 1.74.0), Java (>= 1.77.0), .NET (>= 1.26.0) und Kotlin (>= 1.6.0) |
Bis zu 65.536 (generate_content_stream oder generate_content) |
20 Minuten pro Segment | Keine Serverspeicherung (Zero Data Retention-Workflows) | Vorhandene GenerateContent-Anwendungen |
| Benutzerdefinierte Fortsetzungsschleife | GenerateContent (v1beta1) |
Ihr Code (ursprünglicher contents + continuation_token) |
Bis zu 65.536 (streamGenerateContent oder generateContent; Prüfpunkte ab 65.536 und danach alle 5.000 Tokens) |
20 Minuten pro Segment | Keine Serverspeicherung (Zero Data Retention-Workflows) | Direkte REST-GenerateContent-Aufrufer und Bewertungstestsysteme |
API-Version und SDK-Anforderungen
Für lange Decodierungen sind die folgende API-Version und die folgenden SDK-Mindestversionen erforderlich:
v1beta1API-Anforderung (bekanntes Problem): Die lange Decodierung (continuation_token) sowohl für die Interactions API als auch fürGenerateContent(generateContentundstreamGenerateContent) wird auf der Agent Platform nur in derv1beta1API (nicht in derv1) unterstützt. Das Google Gen AI SDK verwendet standardmäßigv1beta1, es sei denn,api_version='v1'wird inhttp_options(oderapi_version="v1"aufinteractions.create) angegeben. Verwenden Sie für direkte REST-Aufrufe den Endpunktpfad/v1beta1/.- SDK-Versionen und OpenAI-Kompatibilität: Wenn Sie die automatische Fortsetzung in der Interactions API nutzen möchten, führen Sie ein Upgrade auf Python
google-genai >= 2.34.0, JavaScript/TypeScript@google/genai >= 2.32.0, Go>= 1.77.0oder Java>= 1.80.0durch. Für .NET und Kotlin in der Interactions API verwenden Siebackground=trueoder eine benutzerdefinierte Fortsetzungsschleife. Wenn SieGenerateContentautomatisch weiterverwenden möchten, führen Sie ein Upgrade auf Python>= 2.30.1, JavaScript/TypeScript>= 2.29.1, Go>= 1.74.0, Java>= 1.77.0, .NET>= 1.26.0oder Kotlin>= 1.6.0durch. Frühere SDK-Versionen und die OpenAI-Kompatibilitätsebene können keine langen Vervollständigungen mit Fortsetzungstokens abrufen.
Fortsetzungsregeln für die Interactions API
Für lange Decodierungen in der Interactions API gelten die folgenden Statusübergänge, Verkettungsregeln und Speicherverhaltensweisen.
Statuswerte und Ausgabetokenbudget
Wenn generation_config.max_output_tokens in einer Interactions API-Anfrage weggelassen wird, beträgt das Standardbudget für die Gesamtausgabe 65.536 Tokens. Das entspricht dem Limit von 65.536 Tokens für ein einzelnes Segment im Vordergrund für Streaming- und Nicht-Streaming-Anfragen. Legen Sie generation_config.max_output_tokens größer als 65,536 (bis zu 1,048,576 minus Eingabetokens) für lange Decodierungen mit mehreren Segmenten im Vordergrund- und background=true-Modus fest. Der Server gibt die folgenden Statuswerte zurück:
requires_continuation: Das Ausgabelimit von 65.536 Tokens pro Segment wurde vormax_output_tokenserreicht. Übergeben Sie den zurückgegebenencontinuation_tokenbei der nächsten Anfrage,um die Decodierung fortzusetzen.incomplete: Das Gesamtbudget fürmax_output_tokenswurde aufgebraucht. Wenn Sie mitcontinuation_tokenfortfahren, ohnemax_output_tokenszu erhöhen, wird ein HTTP-Fehler400(max_output_tokens has already been exhausted) zurückgegeben. Erhöhen Siemax_output_tokensbei der nächsten Anfrage, um die Decodierung fortzusetzen.completed: Die Generierung wurde normal abgeschlossen undcontinuation_tokenwird gelöscht.
Verkettung, Moduswechsel und Segmentspeicherung
Für Fortsetzungsanfragen an die Interactions API gelten die folgenden Regeln:
- Gespeicherte Fortsetzung (
store=true, Standard): Übergeben Sieprevious_interaction_id, wobei der Wert auf das Segmentidgesetzt ist, das diecontinuation_tokenzusammen mitcontinuation_tokenausgegeben hat, und lassen Sieinputweg (das gespeicherte Segment enthält bereits die Eingabe für die Runde). Kombinieren Sie jedencontinuation_tokenimmer mit derprevious_interaction_iddes Segments, von dem er ausgegeben wurde. Wenn Sie einencontinuation_tokenfür eine bereitscompletedInteraktion übergeben, wird ein HTTP-Fehler400zurückgegeben. - Zustandslose Fortsetzung (
store=false): Lassen Sieprevious_interaction_idweg und senden Sie die ursprünglicheinputzusammen mitcontinuation_tokenfür jedes Segment noch einmal. store-Modi zwischen Segmenten wechseln: Sie können während der Decodierung von gespeichert (store=true) zu zustandslos (store=false) wechseln, indem Sieprevious_interaction_idweglassen und die ursprünglicheinputmitcontinuation_tokennoch einmal senden. Der Wechsel von zustandslos (store=false) zu gespeichert (store=true) wird nicht unterstützt, da fürprevious_interaction_idkeine gespeicherte übergeordnete Interaktion vorhanden ist.- Wechsel zwischen Vordergrund- und
background=true-Modus und Verzweigung: Gespeicherte Fortsetzungen (store=true) können zwischen der Ausführung im Vordergrund (background=false) und im Hintergrund (background=true) über Segmente hinweg wechseln. Dazu gehört auch die Wiederaufnahme einer abgebrochenenbackground=true-Interaktion von ihrem Prüfpunktcontinuation_token(dauerhaft gespeichert ab 65.536 Ausgabetokens und danach alle 5.000 Tokens) im Hintergrund- oder Vordergrundmodus. Wenn Sie dieselbenprevious_interaction_id- undcontinuation_token-Werte wiederverwenden, werden unabhängige verzweigte Fortsetzungen erstellt. - Erzwingung von Turn-Grenzen: Wenn Sie einen neuen Nutzer-Turn (
previous_interaction_idmit neueminputund ohnecontinuation_token) aus einem Segment starten, dessen Statusrequires_continuationoderincompleteist, wird ein HTTP-Fehler400zurückgegeben. Schließen Sie die Decodierung biscompletedab oder verzweigen Sie Ihren nächsten Turn von der letztencompleted-Interaktion. Sobald das letzte Segmentcompletederreicht, wird durch die Übergabe deriddes letzten Segments alsprevious_interaction_idder vollständige Unterhaltungsverlauf über alle vorherigen Segmente hinweg rekonstruiert. - Parameterkonsistenz über Segmente hinweg: Wenn Sie
model,system_instructionoder Funktionsdeklarationen (tools) in einem Fortsetzungssegment ändern, wird ein HTTP-400-Fehler zurückgegeben. Behalten Siethinking_levelund integrierte Tools auch segmentübergreifend unverändert bei (siehe Bekannte Probleme). - Verhalten von
get,listunddeletefür einzelne Segmente: Im Vordergrundmodus (background=false) wird jedes Segment als separateInteraction-Ressource gespeichert (interactions.get(id)gibt nur dieses Segment zurück,interactions.list()listet jedes Segment separat auf undinteractions.delete(id)löscht nur dieses Segment. Wenn Sie eine Kette von Segmenten löschen, löschen Sie sie in umgekehrter Reihenfolge, beginnend mit dem letzten Segment). Im Google Gen AI SDK mitautomatic_continuation=True(stream=False) führtinteractions.create()alle Segmente bei der Rückgabe zusammen und fülltinteraction.continuation_idsmit den geordneten Segment-IDs (die mitinteraction.idenden). Wenn ein späteres Segment fehlschlägt, ein numerischestimeoutpro Aufruf überschreitet oder mitten im Stream abbricht, nachdem ein fortsetzbarer Prüfpunkt erreicht wurde, löst das SDKContinuationInterruptedErrormitpartial_interaction,continuation_token,interaction_idundcontinuation_idsaus, sodass Sie abcontinuation_tokenfortfahren können.
GenerateContent-Regeln für benutzerdefinierte Schleifen
Beachten Sie in einer benutzerdefinierten GenerateContent-Fortsetzungsschleife die folgenden Regeln:
- Setzen Sie
max_output_tokensauf einen Wert größer als 65.536 (bis zu 1.048.576) und senden Sie die ursprünglichen Werte fürcontents,system_instructionundtoolsbei jeder Fortsetzungsanfrage zusammen mit dem neuestencontinuation_token(ein Feld auf oberster Ebene inGenerateContentRequestin REST oder inGenerateContentConfigim Google Gen AI SDK). - Hängen Sie keine unvollständige Modellausgabe an
contentsan und senden Sie keinen Folgeprompt, in dem Sie das Modell auffordern, fortzufahren. - Setzen Sie die Schleife fort, solange
finish_reasonden WertCONTINUATIONhat undcontinuation_tokenvorhanden ist, auch wenn ein Segment alle 65.536 Tokens für das Nachdenken (parts: [{"text": ""}]) verbraucht hat. Wennfinish_reasonden WertMAX_TOKENShat, wenncontinuation_tokenvorhanden ist, erhöhen Siemax_output_tokensin der nächsten Anfrage. - Kombiniert akkumulierte Teile erst nach
STOPzu einer einzelnenmodel-Runde für den Verlauf mit mehreren Runden.
Tokenzählung, Komprimierung und implizites Caching
Die Tokenabrechnung und das Caching über Fortsetzungssegmente hinweg funktionieren so:
- In der Interactions API werden bei nicht-streamingbasierten
interactions.create()-Aufrufen mitautomatic_continuation=Trueund vom Server verwaltetenbackground=true-Interaktionen die Token-Anzahlen über alle Segmente inusage(total_input_tokens,total_cached_tokens,total_output_tokens,total_thought_tokens,total_tokens) hinweg summiert. Die Prompt-Anzahl des ersten Segments wird inusage.initial_input_tokensbeibehalten. In benutzerdefinierten Vordergrundschleifen und gestreamteninteraction.completed-Ereignissen wird in derusagejedes Segments nur das Delta dieses Segments gemeldet. Addieren Sie daher dieusage-Felder über die Segmente hinweg, um die Gesamtzahl der abgerechneten Tokens zu erhalten. - Am
GenerateContentakkumuliert das Python Google Gen AI SDK (generate_contentundgenerate_content_stream) die Gesamtzahl der abgerechneten Tokens über Segmente hinweg im endgültigenusage_metadataund behältinitial_prompt_token_countbei. In benutzerdefinierten REST-Schleifen werden die endgültigen Werte fürprompt_token_count,cached_content_token_count,candidates_token_countundthoughts_token_countüber die Segmente hinweg summiert. - Da jedes Segment zur Fortsetzung im Vordergrund die Unterhaltung und zuvor generierte Tokens als Eingabe neu vorbefüllt, steigen
usage.total_input_tokens(in der Interactions API) undprompt_token_count(inGenerateContent) über die Segmente hinweg an. Verwenden Sie keine kumulativen Eingabezahlen, um die Kontextkomprimierung in Agenten-Frameworks auszulösen. Prüfen Sie stattdessenusage.initial_input_tokens(oderinitial_prompt_token_countbeiGenerateContent) und komprimieren Sie erst, nachdem die Runde beendet ist (status="completed"oder keincontinuation_token). - In jedem Fortsetzungssegment wird der Prompt sowie zuvor decodierte Tokens noch einmal vorab ausgefüllt. Außerdem wird automatisch das implizite Kontext-Caching (mindestens 4.096 Tokens,wobei das dauerhafte Caching standardmäßig aktiviert ist) angewendet, wenn Segmente nacheinander ausgeführt werden. Abgeschlossene Segmente werden am Ende jedes Segments abgerechnet, auch wenn ein späteres Segment fehlschlägt oder abgebrochen wird.
Von 3.8 Flash zu Hydrogen migrieren
Das folgende Verhalten unterscheidet sich von gemini-3.8-flash und früheren Gemini 3 Flash-Modellen:
- Hydrogen hat ein einheitliches Limit von 1.048.576 Tokens für Eingabe und Ausgabe (wobei die Ausgabe den Thinking-Modus, Funktionsaufrufe und die endgültige Antwort umfasst), anstatt separater Limits für Eingabe und Ausgabe. Die Vordergrundausgabe für ein einzelnes Segment ist auf 65.536 Tokens (Streaming oder Nicht-Streaming) begrenzt und kann mit langen Decodierungen in der Interactions API oder
GenerateContentauf bis zu 1.048.576 Tokens erweitert werden (wird im Google Gen AI SDK automatisch mitbackground=truein der Interactions API oder mitcontinuation_tokenin benutzerdefinierten Schleifen verarbeitet). - Der Standardwert für
thinking_levelistHIGH(geändert vonMEDIUMamgemini-3.8-flash).XHIGHwird für Deep-Reasoning-Aufgaben unterstützt. Lassen Sie bei Multi-Turn-Coding-Harnesses Kontextkomprimierungsspielraum fürHIGH- undXHIGH-Reasoning-Traces oder legen Sie bei latenzempfindlichen TurnsMEDIUMfest.thinking_budgetundthinking_level="MINIMAL"geben einen HTTP-Fehler400zurück. - Explizites Kontext-Caching (
cached_content) wird nicht unterstützt. Das implizite Caching wird automatisch ab einer Mindestanzahl von 4.096 Tokens angewendet (reduziert von 6.144 Tokens beigemini-3.8-flash). Das langlebige Caching ist standardmäßig aktiviert. - Microsoft Office-Dateien (
.docx,.dotx,.doc,.pptx,.ppt,.xlsx,.xls) und OpenDocument-Dateien (.odt,.odp,.ods) werden inline oder über einen Cloud Storage-URI (gs://) unterstützt, auch innerhalb von multimodalenFunctionResponse-Teilen. - Bei parallelen Funktionsaufrufen wird eine strikte Platzierung von
thought_signatureerzwungen (nur der erstefunctionCall-Teil in einem parallelen Aufruf enthältthought_signature. Wenn er im aktiven Aufruf weggelassen oder in nachfolgende gleichgeordnetefunctionCall-Teile dupliziert wird, wird ein HTTP-400-Fehler zurückgegeben). Außerdem schlagen Änderungen am Prompt-Präfix desselben Modells standardmäßig mit HTTP-400fehl, es sei denn,prefix_mismatch_behavior="DROP"ist inThinkingConfigfestgelegt. Behalten Sie auchthought_signature-Teile aus allen vorherigen Runden bei (sowohlfunctionCall- als auch endgültigetext-Teile), um die Qualität der Argumentation aufrechtzuerhalten undMALFORMED_FUNCTION_CALL-Beendigungsgründe zu vermeiden. - Jedes vom Modell verarbeitete Token wird in Rechnung gestellt, einschließlich interner Systemanweisungen für Tools und Funktionsdeklarationen bei der Verwendung von Fundierung.
Einen direkten Vergleich finden Sie unter Von Gemini 3-Modellen migrieren.
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
),
),
)
So migrieren Sie von gemini-3.8-flash oder früheren Gemini 3 Flash-Modellen:
- Aktualisieren Sie die Modell-ID auf
gemini-4-hydrogen. - Auf das neueste Google Gen AI SDK upgraden und das einheitliche Limit für Eingabe- und Ausgabetokens berücksichtigen: Führen Sie ein Upgrade auf
google-genai >= 2.34.0(Python),@google/genai >= 2.32.0(JavaScript/TypeScript), Go>= 1.77.0oder Java>= 1.80.0durch, um die automatische Fortsetzung der Interactions API zu nutzen (oder>= 2.30.1Python />= 2.29.1JavaScript aufGenerateContent). Eingabe- und Ausgabetokens (einschließlich Denkprozessen und Funktionsaufrufen) teilen sich das einheitliche Limit von 1.048.576 Tokens. Für Ausgaben mit mehr als 65.536 Tokens (bis zu 1.048.576 Tokens) in der Interactions API oderGenerateContentlegen Siemax_output_tokensauf einen Wert über 65.536 fest, damit das Google Gen AI SDK automatisch über Segmente hinweg fortgesetzt wird (oder verwenden Siebackground=trueoder eine benutzerdefiniertecontinuation_token-Schleife). thinking_level-Konfiguration aktualisieren: Ersetzen Siethinking_budgetundMINIMALdurchthinking_level, wobei der Wert aufLOW,MEDIUM,HIGH(Standardwert beigemini-4-hydrogen) oderXHIGHfestgelegt ist (verwenden Sie in der Interactions API die Kleinbuchstaben"low","medium","high"oder"xhigh"). Wenn Ihre ArbeitslastMEDIUMals Standard fürgemini-3.8-flashverwendet hat, legen Sie explizitthinking_level="MEDIUM"fest, um eine gleichwertige Reasoning-Latenz beizubehalten.- Entfernen Sie das explizite Caching und laden Sie statische Prompt-Inhalte (4.096 Tokens oder mehr) vorab,um das automatische implizite Caching zu ermöglichen.
- Multi-Turn- und parallele
thought_signature-Beibehaltung und Präfixkomprimierung prüfen: Behalten Siethought_signatureüber alle vorherigen Turns hinweg bei (sowohlfunctionCall- als auch finaletext-Teile), anstatt Signaturen zwischen Turns zu entfernen. Behalten Siethought_signaturenur im erstenfunctionCall-Teil eines parallelen Toolaufruf-Turns bei und legen Sieprefix_mismatch_behavior="DROP"inThinkingConfigfest, wenn Ihre Anwendung frühere Turns im Multi-Turn-Chatverlauf ändert oder komprimiert. - Parameter entfernen, die keine Auswirkungen haben oder nicht unterstützt werden: Entfernen Sie ignorierte und abgelehnte Generierungsfelder so:
- Entfernen Sie
temperature,top_pundtop_k, da sie ignoriert werden. - Entfernen Sie
frequency_penalty,presence_penaltyund allecandidate_count-Werte, die größer als1sind. - Entfernen Sie alle vorausgefüllten Modellantworten aus dem Unterhaltungsverlauf.
- Entfernen Sie
Zusammenfassende Checkliste für Entwickler
Verwenden Sie die folgende Checkliste, um Ihre Hydrogen-Integration zu überprüfen:
Bekannte Probleme
Die folgenden bekannten Probleme gelten für lange Hydrogen-Decodierungen:
- Lange Decodierungen erfordern
v1beta1: Lange Decodierungen (continuation_token) werden sowohl in der Interactions API als auch in derGenerateContentAPI (generateContentundstreamGenerateContent) nur in derv1beta1API (nichtv1) auf der Agent Platform unterstützt. Das Google Gen AI SDK verwendet standardmäßigv1beta1, es sei denn,api_version='v1'ist inhttp_options(oderapi_version="v1"aufinteractions.create) festgelegt. Verwenden Sie für direkte REST-Aufrufe den Endpunktpfad/v1beta1/. - Parameteränderungen über Fortsetzungssegmente der Interactions API hinweg: Wenn Sie
model,system_instructionoder Funktionsdeklarationen über Fortsetzungssegmente hinweg ändern, wird ein HTTP-Fehler400zurückgegeben. Änderungen angeneration_config.thinking_leveloder integrierten Tools (google_search,code_execution,url_context) während der Decodierung werden dagegen nicht von der Servervalidierung abgelehnt. Lassen Siethinking_levelund integrierte Tools in allen Segmenten einer Fortsetzungsschleife unverändert.
Zusätzliche Ressourcen
Weitere Informationen zu Hydrogen finden Sie in den folgenden Ressourcen: