Entwicklerhandbuch für Gemini 4 Hydrogen

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 verarbeitet continuation_token automatisch segmentübergreifend. Alternativ können Sie asynchrone, vom Server verwaltete Hintergrunddecodierungen (background=true) ausführen oder continuation_token in einer benutzerdefinierten Fortsetzungsschleife verwalten.
  • Denkstufen: Hydrogen unterstützt LOW, MEDIUM, HIGH (Standard) und XHIGH.
  • 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 in GenerateContent als auch in der Interactions API, einschließlich in multimodalen FunctionResponse-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:

  1. Öffnen Sie Agent Studio in Ihrem Google Cloud -Projekt und wählen Sie gemini-4-hydrogen in der Gemini-Gruppe aus.
  2. Konfigurieren Sie unter Modelleinstellungen die folgenden Optionen:
    • Denkstufe: Wählen Sie Low, Medium, High (Standard) oder Extra high aus.
    • Region: Wählen Sie Global, us oder eu aus.
    • Tokenausgabelimit: Legen Sie einen Wert zwischen 32,768 und 1,048,576 fest (Standardwert: 1,048,576). Agent Studio verarbeitet Fortsetzungstokens automatisch für Antworten, die das Limit für einzelne Anfragen überschreiten.

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:

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,576 Tokens und umfasst sowohl Eingabe- als auch Ausgabe-Tokens (wobei die Ausgabe Thinking, Funktionsaufrufe und die endgültige Antwort umfasst). max_output_tokens steuert die Obergrenze für die Ausgabe-Tokens für die Generierung (bis zu 1,048,576 minus Ihrer Eingabe-Tokens). Wenn Sie max_output_tokens größer als 1,048,576 festlegen, 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) und XHIGH generiert werden, werden auf max_output_tokens angerechnet und im Kontext mit mehreren Runden akkumuliert, wenn Sie Thought-Signaturen über mehrere Runden hinweg beibehalten. Legen Sie max_output_tokens hoch 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 Sie thinking_level="MEDIUM" für latenzempfindliche Tool-Turns fest.
  • 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://) mit inlineData oder fileData in GenerateContent (einschließlich in FunctionResponse-Teilen) und document-Eingaben (einschließlich Tool-Ergebnissen) in der Interactions API übergeben.
  • Agentisches Video: Hochgeladene Videos werden standardmäßig auf media_processing="static" gesetzt. Legen Sie media_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. Mit thinking_level können Sie den Detailgrad der Problemlösung und mit response_schema das Ausgabeformat steuern.
  • Nicht unterstützte Parameter (frequency_penalty, presence_penalty und candidate_count größer als 1): Wenn Sie frequency_penalty, presence_penalty oder candidate_count größer als 1 übergeben (candidateCount ist auf 1 festgelegt), wird ein HTTP-Fehler 400 zurü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 FunctionResponse muss mit der id, der name und der Reihenfolge der vorherigen FunctionCall übereinstimmen.
    • Multimodale FunctionResponse-Teile: Fügen Sie Office-Dokumente, Tabellen, Präsentationen, PDFs, Bilder, Audio und Video in multimodale FunctionResponse-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 parallele functionCall-Teile in einer einzelnen model-Runde ausgibt, enthält nur der erste functionCall-Teil den thought_signature. Wenn Sie thought_signature im ersten functionCall-Teil im aktiven Nutzer-Turn weglassen, es in nachfolgenden parallelen functionCall-Teilen duplizieren oder functionCall- und functionResponse-Turns verschachteln, wird ein HTTP-400-Fehler zurückgegeben. Behalten Sie alle parallelen functionCall-Teile in einem einzigen model-Turn bei, gefolgt von allen übereinstimmenden functionResponse-Teilen in einem einzigen user-Turn. Weitere Informationen finden Sie unter Thought-Signaturen.
    • thought_signature-Erhaltung über mehrere Runden: Geben Sie jede thought_signature innerhalb ihrer ursprünglichen Part über alle vorherigen Runden im Chatverlauf mit mehreren Runden (sowohl functionCall- als auch endgültige text-Teile) zurück, nicht nur innerhalb der aktiven Nutzerrunde. Die HTTP-400-Signaturvalidierung gilt zwar nur für functionCall-Schritte innerhalb des aktiven Nutzerturns, aber das Entfernen von thought_signature-Werten aus früheren Turns oder das Ersetzen durch Bypass-Werte wie skip_thought_signature_validator entfernt den Reasoning-Kontext, verschlechtert die Ausgabequalität und kann zu MALFORMED_FUNCTION_CALL-Beendigungsgründen führen.
    • Formatierung vor dem Toolaufruf: Trennen Sie Inline-Anweisungen mit \n\n und 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"]
        }
      }
      
  • Validierung der Chatsequenz: Für Multi-Turn-Unterhaltungen gelten die folgenden Einschränkungen:

    • Verlaufsnutzlasten dürfen nicht mit einem Rollenwechsel von model enden.
    • Vorausgefüllte Modellantworten werden nicht unterstützt.

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:

  • v1beta1 API-Anforderung (bekanntes Problem): Die lange Decodierung (continuation_token) sowohl für die Interactions API als auch für GenerateContent (generateContent und streamGenerateContent) wird auf der Agent Platform nur in der v1beta1 API (nicht in der v1) unterstützt. Das Google Gen AI SDK verwendet standardmäßig v1beta1, es sei denn, api_version='v1' wird in http_options (oder api_version="v1" auf interactions.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.0 oder Java >= 1.80.0 durch. Für .NET und Kotlin in der Interactions API verwenden Sie background=true oder eine benutzerdefinierte Fortsetzungsschleife. Wenn Sie GenerateContent automatisch 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.0 oder Kotlin >= 1.6.0 durch. 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 vor max_output_tokens erreicht. Übergeben Sie den zurückgegebenen continuation_token bei der nächsten Anfrage,um die Decodierung fortzusetzen.
  • incomplete: Das Gesamtbudget für max_output_tokens wurde aufgebraucht. Wenn Sie mit continuation_token fortfahren, ohne max_output_tokens zu erhöhen, wird ein HTTP-Fehler 400 (max_output_tokens has already been exhausted) zurückgegeben. Erhöhen Sie max_output_tokens bei der nächsten Anfrage, um die Decodierung fortzusetzen.
  • completed: Die Generierung wurde normal abgeschlossen und continuation_token wird gelöscht.

Verkettung, Moduswechsel und Segmentspeicherung

Für Fortsetzungsanfragen an die Interactions API gelten die folgenden Regeln:

  • Gespeicherte Fortsetzung (store=true, Standard): Übergeben Sie previous_interaction_id, wobei der Wert auf das Segment id gesetzt ist, das die continuation_token zusammen mit continuation_token ausgegeben hat, und lassen Sie input weg (das gespeicherte Segment enthält bereits die Eingabe für die Runde). Kombinieren Sie jeden continuation_token immer mit der previous_interaction_id des Segments, von dem er ausgegeben wurde. Wenn Sie einen continuation_token für eine bereits completed Interaktion übergeben, wird ein HTTP-Fehler 400 zurückgegeben.
  • Zustandslose Fortsetzung (store=false): Lassen Sie previous_interaction_id weg und senden Sie die ursprüngliche input zusammen mit continuation_token fü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 Sie previous_interaction_id weglassen und die ursprüngliche input mit continuation_token noch einmal senden. Der Wechsel von zustandslos (store=false) zu gespeichert (store=true) wird nicht unterstützt, da für previous_interaction_id keine 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 abgebrochenen background=true-Interaktion von ihrem Prüfpunkt continuation_token (dauerhaft gespeichert ab 65.536 Ausgabetokens und danach alle 5.000 Tokens) im Hintergrund- oder Vordergrundmodus. Wenn Sie dieselben previous_interaction_id- und continuation_token-Werte wiederverwenden, werden unabhängige verzweigte Fortsetzungen erstellt.
  • Erzwingung von Turn-Grenzen: Wenn Sie einen neuen Nutzer-Turn (previous_interaction_id mit neuem input und ohne continuation_token) aus einem Segment starten, dessen Status requires_continuation oder incomplete ist, wird ein HTTP-Fehler 400 zurückgegeben. Schließen Sie die Decodierung bis completed ab oder verzweigen Sie Ihren nächsten Turn von der letzten completed-Interaktion. Sobald das letzte Segment completed erreicht, wird durch die Übergabe der id des letzten Segments als previous_interaction_id der vollständige Unterhaltungsverlauf über alle vorherigen Segmente hinweg rekonstruiert.
  • Parameterkonsistenz über Segmente hinweg: Wenn Sie model, system_instruction oder Funktionsdeklarationen (tools) in einem Fortsetzungssegment ändern, wird ein HTTP-400-Fehler zurückgegeben. Behalten Sie thinking_level und integrierte Tools auch segmentübergreifend unverändert bei (siehe Bekannte Probleme).
  • Verhalten von get, list und delete für einzelne Segmente: Im Vordergrundmodus (background=false) wird jedes Segment als separate Interaction-Ressource gespeichert (interactions.get(id) gibt nur dieses Segment zurück, interactions.list() listet jedes Segment separat auf und interactions.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 mit automatic_continuation=True (stream=False) führt interactions.create() alle Segmente bei der Rückgabe zusammen und füllt interaction.continuation_ids mit den geordneten Segment-IDs (die mit interaction.id enden). Wenn ein späteres Segment fehlschlägt, ein numerisches timeout pro Aufruf überschreitet oder mitten im Stream abbricht, nachdem ein fortsetzbarer Prüfpunkt erreicht wurde, löst das SDK ContinuationInterruptedError mit partial_interaction, continuation_token, interaction_id und continuation_ids aus, sodass Sie ab continuation_token fortfahren können.

GenerateContent-Regeln für benutzerdefinierte Schleifen

Beachten Sie in einer benutzerdefinierten GenerateContent-Fortsetzungsschleife die folgenden Regeln:

  • Setzen Sie max_output_tokens auf einen Wert größer als 65.536 (bis zu 1.048.576) und senden Sie die ursprünglichen Werte für contents, system_instruction und tools bei jeder Fortsetzungsanfrage zusammen mit dem neuesten continuation_token (ein Feld auf oberster Ebene in GenerateContentRequest in REST oder in GenerateContentConfig im Google Gen AI SDK).
  • Hängen Sie keine unvollständige Modellausgabe an contents an und senden Sie keinen Folgeprompt, in dem Sie das Modell auffordern, fortzufahren.
  • Setzen Sie die Schleife fort, solange finish_reason den Wert CONTINUATION hat und continuation_token vorhanden ist, auch wenn ein Segment alle 65.536 Tokens für das Nachdenken (parts: [{"text": ""}]) verbraucht hat. Wenn finish_reason den Wert MAX_TOKENS hat, wenn continuation_token vorhanden ist, erhöhen Sie max_output_tokens in der nächsten Anfrage.
  • Kombiniert akkumulierte Teile erst nach STOP zu einer einzelnen model-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 mit automatic_continuation=True und vom Server verwalteten background=true-Interaktionen die Token-Anzahlen über alle Segmente in usage (total_input_tokens, total_cached_tokens, total_output_tokens, total_thought_tokens, total_tokens) hinweg summiert. Die Prompt-Anzahl des ersten Segments wird in usage.initial_input_tokens beibehalten. In benutzerdefinierten Vordergrundschleifen und gestreamten interaction.completed-Ereignissen wird in der usage jedes Segments nur das Delta dieses Segments gemeldet. Addieren Sie daher die usage-Felder über die Segmente hinweg, um die Gesamtzahl der abgerechneten Tokens zu erhalten.
  • Am GenerateContent akkumuliert das Python Google Gen AI SDK (generate_content und generate_content_stream) die Gesamtzahl der abgerechneten Tokens über Segmente hinweg im endgültigen usage_metadata und behält initial_prompt_token_count bei. In benutzerdefinierten REST-Schleifen werden die endgültigen Werte für prompt_token_count, cached_content_token_count, candidates_token_count und thoughts_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) und prompt_token_count (in GenerateContent) über die Segmente hinweg an. Verwenden Sie keine kumulativen Eingabezahlen, um die Kontextkomprimierung in Agenten-Frameworks auszulösen. Prüfen Sie stattdessen usage.initial_input_tokens (oder initial_prompt_token_count bei GenerateContent) und komprimieren Sie erst, nachdem die Runde beendet ist (status="completed" oder kein continuation_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 GenerateContent auf bis zu 1.048.576 Tokens erweitert werden (wird im Google Gen AI SDK automatisch mit background=true in der Interactions API oder mit continuation_token in benutzerdefinierten Schleifen verarbeitet).
  • Der Standardwert für thinking_level ist HIGH (geändert von MEDIUM am gemini-3.8-flash). XHIGH wird für Deep-Reasoning-Aufgaben unterstützt. Lassen Sie bei Multi-Turn-Coding-Harnesses Kontextkomprimierungsspielraum für HIGH- und XHIGH-Reasoning-Traces oder legen Sie bei latenzempfindlichen Turns MEDIUM fest. thinking_budget und thinking_level="MINIMAL" geben einen HTTP-Fehler 400 zurü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 bei gemini-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 multimodalen FunctionResponse-Teilen.
  • Bei parallelen Funktionsaufrufen wird eine strikte Platzierung von thought_signature erzwungen (nur der erste functionCall-Teil in einem parallelen Aufruf enthält thought_signature. Wenn er im aktiven Aufruf weggelassen oder in nachfolgende gleichgeordnete functionCall-Teile dupliziert wird, wird ein HTTP-400-Fehler zurückgegeben). Außerdem schlagen Änderungen am Prompt-Präfix desselben Modells standardmäßig mit HTTP-400 fehl, es sei denn, prefix_mismatch_behavior="DROP" ist in ThinkingConfig festgelegt. Behalten Sie auch thought_signature-Teile aus allen vorherigen Runden bei (sowohl functionCall- als auch endgültige text-Teile), um die Qualität der Argumentation aufrechtzuerhalten und MALFORMED_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:

  1. Aktualisieren Sie die Modell-ID auf gemini-4-hydrogen.
  2. 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.0 oder Java >= 1.80.0 durch, um die automatische Fortsetzung der Interactions API zu nutzen (oder >= 2.30.1 Python / >= 2.29.1 JavaScript auf GenerateContent). 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 oder GenerateContent legen Sie max_output_tokens auf einen Wert über 65.536 fest, damit das Google Gen AI SDK automatisch über Segmente hinweg fortgesetzt wird (oder verwenden Sie background=true oder eine benutzerdefinierte continuation_token-Schleife).
  3. thinking_level-Konfiguration aktualisieren: Ersetzen Sie thinking_budget und MINIMAL durch thinking_level, wobei der Wert auf LOW, MEDIUM, HIGH (Standardwert bei gemini-4-hydrogen) oder XHIGH festgelegt ist (verwenden Sie in der Interactions API die Kleinbuchstaben "low", "medium", "high" oder "xhigh"). Wenn Ihre Arbeitslast MEDIUM als Standard für gemini-3.8-flash verwendet hat, legen Sie explizit thinking_level="MEDIUM" fest, um eine gleichwertige Reasoning-Latenz beizubehalten.
  4. 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.
  5. Multi-Turn- und parallele thought_signature-Beibehaltung und Präfixkomprimierung prüfen: Behalten Sie thought_signature über alle vorherigen Turns hinweg bei (sowohl functionCall- als auch finale text-Teile), anstatt Signaturen zwischen Turns zu entfernen. Behalten Sie thought_signature nur im ersten functionCall-Teil eines parallelen Toolaufruf-Turns bei und legen Sie prefix_mismatch_behavior="DROP" in ThinkingConfig fest, wenn Ihre Anwendung frühere Turns im Multi-Turn-Chatverlauf ändert oder komprimiert.
  6. Parameter entfernen, die keine Auswirkungen haben oder nicht unterstützt werden: Entfernen Sie ignorierte und abgelehnte Generierungsfelder so:
    • Entfernen Sie temperature, top_p und top_k, da sie ignoriert werden.
    • Entfernen Sie frequency_penalty, presence_penalty und alle candidate_count-Werte, die größer als 1 sind.
    • Entfernen Sie alle vorausgefüllten Modellantworten aus dem Unterhaltungsverlauf.

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 der GenerateContent API (generateContent und streamGenerateContent) nur in der v1beta1 API (nicht v1) auf der Agent Platform unterstützt. Das Google Gen AI SDK verwendet standardmäßig v1beta1, es sei denn, api_version='v1' ist in http_options (oder api_version="v1" auf interactions.create) festgelegt. Verwenden Sie für direkte REST-Aufrufe den Endpunktpfad /v1beta1/.
  • Parameteränderungen über Fortsetzungssegmente der Interactions API hinweg: Wenn Sie model, system_instruction oder Funktionsdeklarationen über Fortsetzungssegmente hinweg ändern, wird ein HTTP-Fehler 400 zurückgegeben. Änderungen an generation_config.thinking_level oder integrierten Tools (google_search, code_execution, url_context) während der Decodierung werden dagegen nicht von der Servervalidierung abgelehnt. Lassen Sie thinking_level und integrierte Tools in allen Segmenten einer Fortsetzungsschleife unverändert.

Zusätzliche Ressourcen

Weitere Informationen zu Hydrogen finden Sie in den folgenden Ressourcen: