Guide de Gemini 4 Hydrogen pour les développeurs

Gemini 4 Hydrogen apporte une intelligence de pointe, rapide et efficace, au codage quotidien et aux workflows d'entreprise agentiques.

Ce document présente les principales fonctionnalités d'Hydrogen, les conventions d'API qu'il applique, la procédure de migration depuis Gemini 3.8 Flash et les modèles Gemini 3 Flash antérieurs, ainsi qu'un guide de démarrage rapide. Pour une présentation de la famille Gemini 4, consultez Premiers pas avec Gemini 4.

Principales fonctionnalités de Gemini 4 Hydrogen

Gemini 4 Hydrogen inclut les fonctionnalités suivantes :

  • Limite unifiée de jetons d'entrée et de sortie : Hydrogen a une limite unifiée de 1 048 576 jetons qui inclut à la fois les jetons d'entrée et de sortie (où la sortie inclut le raisonnement, les appels de fonction et la réponse finale).
  • Décodages longs jusqu'à 1 048 576 jetons : Hydrogen étend la génération au-delà d'un seul segment de premier plan de 65 536 jetons (en streaming ou non) jusqu'à 1 048 576 jetons (moins vos jetons d'entrée) sur l'API Interactions et GenerateContent (v1beta1). Le SDK Google Gen AI gère automatiquement continuation_token sur les segments. Vous pouvez également exécuter des décodages asynchrones en arrière-plan gérés par le serveur (background=true) ou gérer continuation_token dans une boucle de continuation personnalisée.
  • Niveaux de réflexion : Hydrogen est compatible avec LOW, MEDIUM, HIGH (par défaut) et XHIGH.
  • Mise en cache implicite avec mise en cache durable : la mise en cache implicite s'applique automatiquement aux préfixes de requêtes partagés de 4 096 jetons ou plus, la mise en cache durable étant activée par défaut. La mise en cache explicite du contexte n'est pas prise en charge.
  • Entrées de fichiers Office et OpenDocument : en plus des fichiers PDF et en texte brut, Hydrogen accepte les fichiers Microsoft Office (.docx, .dotx, .doc, .pptx, .ppt, .xlsx, .xls) et OpenDocument (.odt, .odp, .ods) intégrés ou provenant de Cloud Storage sur GenerateContent et l'API Interactions, y compris dans les parties FunctionResponse multimodales.
  • Compréhension agentique des vidéos : la compréhension agentique des vidéos est en disponibilité générale et désactivée par défaut.
  • Cycle de vie des versions à court terme : Hydrogen est une version en disponibilité générale (DG) à court terme, soumise à une règle de préavis de retrait d'au moins 45 jours. Pour en savoir plus sur le cycle de vie, consultez Versions et cycle de vie des modèles.

Guide de démarrage rapide

Avant de commencer, vous devez vous authentifier auprès de Gemini Enterprise Agent Platform à l'aide des identifiants par défaut de l'application (ADC) ou d'une clé API. Pour en savoir plus, consultez Premiers pas avec Agent Platform.

Dans les blocs de code suivants, remplacez PROJECT_ID par l'ID de votre projet.

Essayer dans Agent Studio

Pour tester des prompts et configurer gemini-4-hydrogen dans l'interface utilisateur d'Agent Studio, procédez comme suit :

  1. Ouvrez Agent Studio dans votre projet Google Cloud et sélectionnez gemini-4-hydrogen sous le groupe Gemini.
  2. Dans Paramètres du modèle, configurez les options suivantes :
    • Niveau de réflexion : choisissez Low, Medium, High (par défaut) ou Extra high.
    • Région : sélectionnez Global, us ou eu.
    • Limite de jetons de sortie : définissez une valeur comprise entre 32,768 et 1,048,576 (1,048,576 par défaut). Agent Studio gère automatiquement les jetons de continuation pour les réponses qui dépassent la limite d'une seule requête.

Installation

Passez à la dernière version du SDK Google Gen AI. La continuation automatique sur l'API Interactions nécessite google-genai >= 2.34.0 pour Python, @google/genai >= 2.32.0 pour JavaScript/TypeScript, >= 1.77.0 pour Go ou >= 1.80.0 pour Java (sur GenerateContent, la continuation automatique nécessite >= 2.30.1 pour Python, >= 2.29.1 pour JavaScript/TypeScript, >= 1.74.0 pour Go, >= 1.77.0 pour Java, >= 1.26.0 pour .NET ou >= 1.6.0 pour Kotlin) :

pip install --upgrade "google-genai>=2.34.0"

Requête de base

Envoyez une requête à gemini-4-hydrogen à l'aide du SDK Google Gen AI ou de REST :

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 (API Interactions)

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"
    }
  }
}'

Sortie structurée

Pour générer une sortie JSON conforme à un schéma, configurez response_mime_type et 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)

Exemples de décodage long

Par défaut, un seul segment d'API de premier plan génère jusqu'à 65 536 jetons de sortie (en streaming ou non), où la sortie inclut la réflexion, les appels de fonction et la réponse finale. Pour générer des complétions jusqu'à 1 048 576 jetons (moins vos jetons d'entrée), utilisez des décodages longs sur l'API Interactions ou GenerateContent. Pour en savoir plus sur les options de continuation, les transitions d'état et les règles de validation, consultez Décodages longs.

Utiliser des décodages longs avec l'API Interactions

Dans google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0 et Java >= 1.80.0, interactions.create() suit automatiquement continuation_token entre les segments chaque fois qu'un segment renvoie status="requires_continuation". Vous pouvez également désactiver l'option (automatic_continuation=False) pour exécuter une boucle personnalisée stockée (store=True) ou sans état (store=False) :

Python (SDK automatique)

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 (boucle personnalisée)

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 (stocké)

# 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 (sans état)

# 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"
    }
  }'

Pour l'exécution asynchrone gérée par le serveur (background=True avec store=True) ou la récupération à partir de points de contrôle de streaming (événements interaction.status_update émis à partir de 65 536 jetons de sortie, puis tous les 5 000 jetons), utilisez les modèles suivants :

Python (arrière-plan)

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 (arrière-plan)

# 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 (points de contrôle de streaming)

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 (points de contrôle de streaming)

# 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"
    }
  }'

Utiliser des décodages longs avec GenerateContent

Sur GenerateContent (v1beta1), définissez max_output_tokens sur une valeur supérieure à 65 536 (jusqu'à 1 048 576) pour les requêtes en streaming ou non. Le SDK Google Gen AI suit automatiquement continuation_token sur les segments lorsque finish_reason est CONTINUATION (définissez automatic_continuation=False dans GenerateContentConfig pour désactiver cette option), ou vous pouvez transmettre continuation_token dans une boucle personnalisée :

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 (boucle de continuation personnalisée)

# 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"}
    }
  }'

Règles d'API et conventions de comportement obligatoires

Hydrogen applique les conventions des sections suivantes pour les niveaux de réflexion, les limites de jetons, la mise en cache, les paramètres de génération et l'exécution d'outils multitours.

Niveaux de raisonnement

Hydrogen accepte quatre valeurs thinking_level (thinking_budget et MINIMAL renvoient une erreur de validation HTTP 400). Le tableau suivant liste chaque niveau de réflexion et les charges de travail recommandées :

Niveau de réflexion Charges de travail recommandées
XHIGH Raisonnement approfondi, preuves mathématiques, analyse scientifique et tâches d'ingénierie logicielle multifichiers les plus complexes.
HIGH (par défaut sur gemini-4-hydrogen) Boucles d'outils agentiques en plusieurs étapes, génération de code, refactorisation architecturale et analyse multimodale complexe.
MEDIUM Codage général, utilisation d'outils, questions/réponses sur des documents et compréhension de vidéos avec une latence équilibrée.
LOW Classification, routage, synthèse et extraction de métadonnées structurées à haut débit.

Limites de jetons, mise en cache et facturation

Hydrogen applique les règles suivantes concernant les jetons, la mise en cache, les contenus multimédias et la facturation :

  • Limite unifiée de jetons d'entrée et de sortie, et limites de sortie pour une seule requête : Les budgets de jetons et les limites par requête fonctionnent comme suit :
    • La limite globale de jetons du modèle est de 1,048,576 jetons et inclut à la fois les jetons d'entrée et de sortie (où la sortie inclut le raisonnement, les appels de fonction et la réponse finale). max_output_tokens contrôle la limite de jetons de sortie pour la génération (jusqu'à 1,048,576 moins vos jetons d'entrée). Définir max_output_tokens sur une valeur supérieure à 1,048,576 renvoie une erreur HTTP 400.
    • Pour éviter les complétions involontairement longues, le budget de sortie par défaut et la limite de premier plan pour un seul segment (réflexion, appels de fonction et réponse du modèle) sont de 65 536 jetons pour les requêtes en streaming et non en streaming.
    • Les jetons de raisonnement générés à HIGH (par défaut) et XHIGH sont comptabilisés dans max_output_tokens et s'accumulent dans le contexte multitour lorsque vous conservez les signatures de pensée d'un tour à l'autre. Définissez max_output_tokens sur une valeur suffisamment élevée pour la réflexion et la sortie finale, évitez les seuils de compactage de contexte trop bas dans les environnements de codage multitours, ou définissez thinking_level="MEDIUM" sur les tours d'outils sensibles à la latence.
  • Décodages longs : les réponses de premier plan à segment unique génèrent jusqu'à 65 536 jetons de sortie (en streaming ou non). Pour étendre la sortie à un seul tour jusqu'à 1 048 576 jetons (moins les jetons d'entrée) sur l'API Interactions ou GenerateContent (v1beta1), consultez Décodages longs.
  • Cache de contexte : le cache de contexte explicite n'est pas pris en charge. La mise en cache implicite (avec la mise en cache durable activée par défaut) s'applique automatiquement aux préfixes de requêtes partagés de 4 096 jetons ou plus. Placez donc le contenu statique au début de votre requête.
  • Entrées Office et OpenDocument : transmettez des fichiers 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) et Excel ou des feuilles de calcul OpenDocument (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel, application/vnd.oasis.opendocument.spreadsheet) de manière intégrée ou par URI Cloud Storage (gs://) à l'aide de inlineData ou fileData sur les entrées GenerateContent (y compris dans les parties FunctionResponse) et document (y compris les résultats des outils) sur l'API Interactions.
  • Vidéo agentive : les vidéos importées sont définies par défaut sur media_processing="static". Définissez media_processing="agentic" pour activer le traitement agentique des vidéos.
  • Comptage et facturation des jetons : chaque jeton traité par le modèle est comptabilisé et facturé, y compris les jetons de raisonnement, les instructions système des outils internes et les déclarations de fonction lors de l'utilisation de l'ancrage. L'ancrage avec la recherche Google reste également facturé par requête.

Paramètres, appel de fonction et validation du chat

Hydrogen applique les règles suivantes pour les paramètres de génération, les appels d'outils, les signatures de pensée et l'historique des discussions :

  • Paramètres d'échantillonnage ignorés (temperature, top_k, top_p) : le backend ignore les valeurs personnalisées. Contrôlez la profondeur du raisonnement avec thinking_level et le format de sortie avec response_schema.
  • Paramètres non compatibles (frequency_penalty, presence_penalty et candidate_count supérieur à 1) : la transmission de frequency_penalty, presence_penalty ou candidate_count supérieur à 1 (candidateCount est fixé à 1) renvoie une erreur HTTP 400. Supprimez ces paramètres de vos requêtes.
  • Appel de fonction et signatures de pensée : les déclarations d'outils, les appels d'outils parallèles et la relecture thought_signature multitour suivent ces règles :

    • Symétrie des tours : chaque FunctionResponse doit correspondre à id, name et à l'ordre du FunctionCall précédent.
    • Parties FunctionResponse multimodales : incluez des documents Office, des feuilles de calcul, des présentations, des PDF, des images, de l'audio et de la vidéo dans des parties FunctionResponse multimodales (ou des résultats d'outils sur l'API Interactions) plutôt que de les ajouter en tant que parties distinctes du tour de l'utilisateur.
    • Emplacement de l'thought_signature de l'appel de fonction parallèle : lorsque le modèle émet plusieurs parties functionCall parallèles en un seul tour model, seule la première partie functionCall contient l'thought_signature. Si vous omettez thought_signature de la première partie functionCall du tour d'utilisateur actif, si vous le dupliquez sur les parties functionCall parallèles suivantes ou si vous entrelacez les tours functionCall et functionResponse, une erreur HTTP 400 est renvoyée. Conservez toutes les parties functionCall parallèles dans un seul tour model, suivies de toutes les parties functionResponse correspondantes dans un seul tour user. Pour en savoir plus, consultez Signatures de pensée.
    • Conservation de thought_signature entre les tours : transmettez chaque thought_signature dans son Part d'origine pour tous les tours précédents de l'historique de chat multitour (parties functionCall et text finales), et pas seulement dans le tour de l'utilisateur actif. Bien que la validation de la signature HTTP 400 ne s'applique qu'aux étapes functionCall du tour d'utilisateur actif, la suppression des valeurs thought_signature des tours précédents ou le remplacement par des valeurs de contournement telles que skip_thought_signature_validator supprime le contexte de raisonnement, dégrade la qualité de la sortie et peut entraîner des motifs de fin MALFORMED_FUNCTION_CALL.
    • Mise en forme avant l'outil : séparez les instructions intégrées par \n\n et évitez le texte non structuré avant les appels d'outils. Pour consigner l'état intermédiaire avant un appel d'outil, utilisez une déclaration de fonction dédiée :

      {
        "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"]
        }
      }
      
  • Validation de la séquence de chat : les charges utiles de chat multitour appliquent les contraintes suivantes :

    • Les charges utiles de l'historique ne peuvent pas se terminer par un tour de rôle model.
    • Les tours de modèle préremplis ne sont pas acceptés.

Décodages longs

Le décodage long divise une génération de 1 048 576 jetons (moins vos jetons d'entrée) en plusieurs segments sur l'API Interactions ou GenerateContent (v1beta1). Sur l'API Interactions, chaque segment de premier plan (stream=true ou stream=false) génère jusqu'à 65 536 jetons de sortie et renvoie status="requires_continuation" avec un continuation_token chiffré. Vous pouvez également définir background=true (store=true) pour que le serveur exécute la boucle de continuation de manière asynchrone et stocke la sortie fusionnée dans un Interaction. Sur GenerateContent, chaque segment en streaming ou non génère jusqu'à 65 536 jetons de sortie avant d'émettre finish_reason=CONTINUATION avec continuation_token, et continue jusqu'à finish_reason=STOP. Dans Agent Studio, si vous définissez la limite de jetons de sortie sur une valeur supérieure à 65 536 et inférieure ou égale à 1 048 576, les jetons de continuation sont gérés automatiquement. Pour obtenir des exemples de code exécutables, consultez les exemples du guide de démarrage rapide sur le décodage long.

Quand utiliser le décodage long

La plupart des requêtes se terminent dans la limite de sortie de 65 536 jetons par segment. N'utilisez le décodage long que lorsqu'une réponse nécessite plus de sortie que cela. Le décodage long donne au modèle plus de marge de manœuvre pour raisonner. Il ne rallonge pas les réponses (utilisez thinking_level pour contrôler la profondeur du raisonnement).

Charge de travail Utiliser le décodage long ? Pourquoi
Mathématiques, sciences, recherche et preuves formelles complexes Oui Le modèle peut utiliser plus de 65 536 jetons pour explorer et vérifier son raisonnement.
Les tâches de codage et agentiques les plus difficiles Oui Certaines tâches nécessitent plus de 65 536 jetons de réflexion et de code dans une seule réponse. La plupart des tâches de codage et d'agent se terminent en moins de 65 536 jetons.
Outils d'évaluation qui s'arrêtent à la limite de sortie Oui Le décodage long évite les réponses tronquées lorsque le modèle consacre un segment entier de 65 536 jetons à la réflexion.
Chat, questions/réponses, synthèse, classification et extraction Non Ces tâches se terminent bien avant d'atteindre 65 536 jetons.
Les requêtes demandant une longueur fixe, comme "rédiger un livre de 700 000 mots" Non Le modèle ne respecte pas les objectifs de longueur.
Agents qui appellent des outils en de nombreux tours courts Non Chaque tour est court. Les sorties volumineuses à chaque tour remplissent rapidement la limite unifiée de 1 048 576 jetons d'entrée et de sortie.
Requêtes proches de la limite d'entrée de 1 048 576 jetons Non La sortie ne peut utiliser que 1 048 576 jetons moins votre entrée.
Requêtes sensibles à la latence Non Le décodage long peut prendre plusieurs minutes.

Choisir une option de continuation

Sélectionnez un modèle de continuation en fonction de la surface de votre API, de votre stratégie de stockage et de votre environnement d'exécution. Toutes les options du tableau suivant atteignent la même limite de 1 048 576 jetons (moins les jetons d'entrée) sur gemini-4-hydrogen.

Option de continuation Surface d'API Qui démarre chaque segment Jetons par segment Limite de temps par requête Stockage du serveur Application idéale
Continuation automatique du SDK Google Gen AI (recommandé) API Interactions (v1beta1) SDK Google Gen AI : Python (google-genai >= 2.34.0), JavaScript/TypeScript (@google/genai >= 2.32.0), Go (>= 1.77.0) et Java (>= 1.80.0) Jusqu'à 65 536 (stream=true ou stream=false) 20 minutes par segment Stockage sur serveur pendant 7 jours par défaut (store=true) ou aucun (store=false) La plupart des applications d'API Interactions avec ou sans état
Boucle gérée par le serveur en arrière-plan (background=true) API Interactions (v1beta1) Boucle du serveur Agent Platform ; votre code interroge get Géré côté serveur jusqu'à max_output_tokens Asynchrone (aucun flux client ouvert requis) Stockage sur serveur pendant 7 jours (store=true requis) Jobs asynchrones, appelants .NET/Kotlin et persistance d'un seul enregistrement
Boucle stockée personnalisée au premier plan (store=true) API Interactions (v1beta1) Votre code (previous_interaction_id + continuation_token, sans input) Jusqu'à 65 536 (stream=true ou stream=false ; points de contrôle à partir de 65 536 et tous les 5 000 jetons par la suite) 20 minutes par segment Stockage sur serveur pendant 7 jours (store=true) Appels REST et récupération de points de contrôle personnalisés
Boucle sans état personnalisée au premier plan (store=false) API Interactions (v1beta1) Votre code (input d'origine + continuation_token, pas de previous_interaction_id) Jusqu'à 65 536 (stream=true ou stream=false ; points de contrôle à partir de 65 536 et tous les 5 000 jetons par la suite) 20 minutes par segment Aucun stockage sur serveur (workflows de conservation zéro donnée) Harnais REST personnalisés nécessitant une exécution sans état
Continuation automatique du SDK Google Gen AI (recommandé) GenerateContent (v1beta1) SDK Google Gen AI : Python (>= 2.30.1), JavaScript/TypeScript (>= 2.29.1), Go (>= 1.74.0), Java (>= 1.77.0), .NET (>= 1.26.0) et Kotlin (>= 1.6.0) Jusqu'à 65 536 (generate_content_stream ou generate_content) 20 minutes par segment Aucun stockage sur serveur (workflows de conservation zéro donnée) Applications GenerateContent existantes
Boucle de continuation personnalisée GenerateContent (v1beta1) Votre code (contents d'origine + continuation_token) Jusqu'à 65 536 (streamGenerateContent ou generateContent ; points de contrôle à partir de 65 536 et tous les 5 000 jetons par la suite) 20 minutes par segment Aucun stockage sur serveur (workflows de conservation zéro donnée) Appels REST GenerateContent directs et outils d'évaluation

Exigences concernant la version de l'API et le SDK

Les décodages longs nécessitent la version d'API et les versions minimales du SDK suivantes :

  • Exigence de l'API v1beta1 (problème connu) : le décodage long (continuation_token) sur l'API Interactions et GenerateContent (generateContent et streamGenerateContent) n'est compatible qu'avec l'API v1beta1 (et non v1) sur Agent Platform. Le SDK Google Gen AI utilise v1beta1 par défaut, sauf si api_version='v1' est spécifié dans http_options (ou api_version="v1" sur interactions.create). Pour les appels REST directs, utilisez le chemin d'accès au point de terminaison /v1beta1/.
  • Versions du SDK et compatibilité avec OpenAI : pour la continuation automatique sur l'API Interactions, passez à Python google-genai >= 2.34.0, JavaScript/TypeScript @google/genai >= 2.32.0, Go >= 1.77.0 ou Java >= 1.80.0 (pour .NET et Kotlin sur l'API Interactions, utilisez background=true ou une boucle de continuation personnalisée). Pour continuer automatiquement sur GenerateContent, passez à Python >= 2.30.1, JavaScript/TypeScript >= 2.29.1, Go >= 1.74.0, Java >= 1.77.0, .NET >= 1.26.0 ou Kotlin >= 1.6.0. Les versions antérieures du SDK et la couche de compatibilité OpenAI ne peuvent pas récupérer les complétions longues à l'aide de jetons de continuation.

Règles de continuation de l'API Interactions

Les transitions d'état, les règles de chaînage et les comportements de stockage suivants s'appliquent aux décodages longs sur l'API Interactions.

Valeurs d'état et budget de jetons de sortie

Lorsque generation_config.max_output_tokens est omis dans une requête API Interactions, le budget de sortie total est défini par défaut sur 65 536 jetons (ce qui correspond à la limite de 65 536 jetons pour un seul segment au premier plan pour les requêtes en streaming et sans streaming). Définissez generation_config.max_output_tokens sur une valeur supérieure à 65,536 (jusqu'à 1,048,576 moins les jetons d'entrée) pour les décodages longs multisegments dans les modes de premier plan et background=true. Le serveur renvoie les valeurs d'état suivantes :

  • requires_continuation : la limite de sortie de 65 536 jetons par segment a été atteinte avant max_output_tokens. Transmettez le continuation_token renvoyé lors de la requête suivante pour continuer le décodage.
  • incomplete : le budget max_output_tokens total a été épuisé. Continuer avec continuation_token sans augmenter max_output_tokens renvoie une erreur HTTP 400 (max_output_tokens has already been exhausted). Augmentez max_output_tokens lors de la prochaine requête pour reprendre le décodage.
  • completed : la génération s'est terminée naturellement et continuation_token est effacé.

Chaînage, changement de mode et stockage des segments

Les requêtes de continuation sur l'API Interactions appliquent les règles suivantes :

  • Suite stockée (store=true, par défaut) : transmettez previous_interaction_id défini sur le segment id qui a émis le continuation_token avec continuation_token, et omettez input (le segment stocké contient déjà l'entrée du tour). Associez toujours chaque continuation_token au previous_interaction_id du segment qui l'a émis. Transmettre un continuation_token sur une interaction déjà completed renvoie une erreur HTTP 400.
  • Continuation sans état (store=false) : omettez previous_interaction_id et renvoyez le input d'origine avec continuation_token sur chaque segment.
  • Changer de mode store entre les segments : vous pouvez passer du mode stocké (store=true) au mode sans état (store=false) en cours de décodage en omettant previous_interaction_id et en renvoyant le input d'origine avec continuation_token. Le passage de l'état sans état (store=false) à l'état stocké (store=true) n'est pas possible, car il n'existe aucune interaction parente stockée pour previous_interaction_id.
  • Changement de mode et branchement entre premier plan et background=true : les continuations stockées (store=true) peuvent basculer entre l'exécution au premier plan (background=false) et en arrière-plan (background=true) entre les segments, y compris en reprenant une interaction background=true annulée à partir de son point de contrôle continuation_token (conservé à partir de 65 536 jetons de sortie, puis tous les 5 000 jetons) en mode arrière-plan ou premier plan. La réutilisation des mêmes valeurs previous_interaction_id et continuation_token crée des continuations ramifiées indépendantes.
  • Application des limites de tour : démarrer un nouveau tour d'utilisateur (previous_interaction_id avec un nouveau input et sans continuation_token) à partir d'un segment dont l'état est requires_continuation ou incomplete renvoie une erreur HTTP 400. Terminez le décodage jusqu'à completed ou branchez votre prochain tour à partir de l'interaction completed la plus récente. Une fois que le dernier segment atteint completed, la transmission de l'élément id de ce dernier segment en tant que previous_interaction_id reconstruit l'historique complet de la conversation sur tous les segments précédents.
  • Cohérence des paramètres entre les segments : la modification de model, system_instruction ou des déclarations de fonction (tools) sur un segment de continuation renvoie une erreur HTTP 400. Conservez également thinking_level et les outils intégrés inchangés d'un segment à l'autre (voir Problèmes connus).
  • Comportement des segments uniques get, list et delete : en mode premier plan (background=false), chaque segment est stocké en tant que ressource Interaction distincte (interactions.get(id) ne renvoie que ce segment, interactions.list() liste chaque segment séparément et interactions.delete(id) ne supprime que ce segment ; lors de la suppression d'une chaîne de segments, supprimez-les dans l'ordre inverse, en commençant par le dernier segment). Dans le SDK Google Gen AI avec automatic_continuation=True (stream=False), interactions.create() fusionne tous les segments au retour et remplit interaction.continuation_ids avec les ID de segment ordonnés (se terminant par interaction.id). Si un segment ultérieur échoue, dépasse un timeout numérique par appel ou est supprimé en cours de flux après avoir dépassé un point de contrôle réactivable, le SDK génère ContinuationInterruptedError contenant partial_interaction, continuation_token, interaction_id et continuation_ids afin que vous puissiez reprendre à partir de continuation_token.

Règles de boucle personnalisées GenerateContent

Dans une boucle de continuation GenerateContent personnalisée, suivez ces règles :

  • Définissez max_output_tokens sur une valeur supérieure à 65 536 (jusqu'à 1 048 576) et renvoyez les valeurs contents, system_instruction et tools d'origine à chaque requête de continuation, ainsi que la dernière valeur continuation_token (un champ de premier niveau sur GenerateContentRequest dans REST ou dans GenerateContentConfig dans le SDK Google Gen AI).
  • N'ajoutez pas de sortie de modèle partielle dans contents et n'envoyez pas de requête de suivi demandant au modèle de continuer.
  • Continuez à boucler tant que finish_reason est CONTINUATION et que continuation_token est présent, même si un segment a utilisé l'intégralité des 65 536 jetons pour la réflexion (parts: [{"text": ""}]). Si finish_reason est MAX_TOKENS lorsque continuation_token est présent, augmentez max_output_tokens dans la requête suivante.
  • Combinez les parties accumulées en un seul tour model pour l'historique multitour uniquement après STOP.

Comptage, compactage et mise en cache implicite des jetons

La comptabilisation et la mise en cache des jetons sur les segments de continuation fonctionnent comme suit :

  • Sur l'API Interactions, les appels interactions.create() sans streaming avec automatic_continuation=True et les interactions background=true gérées par le serveur additionnent le nombre de jetons de tous les segments dans usage (total_input_tokens, total_cached_tokens, total_output_tokens, total_thought_tokens, total_tokens), en conservant le nombre de requêtes du premier segment dans usage.initial_input_tokens. Dans les boucles de premier plan personnalisées et les événements interaction.completed diffusés en streaming, le champ usage de chaque segment ne signale que le delta de ce segment. Par conséquent, additionnez les champs usage de tous les segments pour obtenir le nombre total de jetons facturés.
  • Sur GenerateContent, le SDK Google Gen AI pour Python (generate_content et generate_content_stream) cumule le nombre total de jetons facturés sur les segments dans le usage_metadata final et conserve initial_prompt_token_count. Dans les boucles REST personnalisées, additionnez les valeurs finales de prompt_token_count, cached_content_token_count, candidates_token_count et thoughts_token_count pour tous les segments.
  • Étant donné que chaque segment de continuation au premier plan remplit à nouveau la conversation et les jetons précédemment générés en tant qu'entrée, usage.total_input_tokens (sur l'API Interactions) et prompt_token_count (sur GenerateContent) augmentent d'un segment à l'autre. N'utilisez pas le nombre d'entrées cumulées pour déclencher la compression du contexte dans les harnais d'agent. Vérifiez plutôt usage.initial_input_tokens (ou initial_prompt_token_count sur GenerateContent) et ne compressez qu'une fois le tour terminé (status="completed" ou pas de continuation_token).
  • Chaque segment de continuation préremplit à nouveau le prompt ainsi que les jetons précédemment décodés et est automatiquement éligible à la cache de contexte implicite (minimum de 4 096 jetons, avec mise en cache durable activée par défaut) lorsque les segments s'exécutent l'un après l'autre. Les segments terminés sont facturés à la fin de chaque segment, même si un segment ultérieur échoue ou est annulé.

Migrer vers Hydrogen depuis 3.8 Flash

Le comportement suivant est différent de celui de gemini-3.8-flash et des modèles Gemini 3 Flash antérieurs :

  • Hydrogen dispose d'une limite unifiée de 1 048 576 jetons pour l'entrée et la sortie (où la sortie inclut le raisonnement, les appels de fonction et la réponse finale), au lieu de limites d'entrée et de sortie distinctes. La sortie de premier plan à segment unique est limitée à 65 536 jetons (en streaming ou non), et peut être étendue jusqu'à 1 048 576 jetons à l'aide de décodages longs sur l'API Interactions ou GenerateContent (gérés automatiquement dans le SDK Google Gen AI, avec background=true sur l'API Interactions ou à l'aide de continuation_token dans des boucles personnalisées).
  • La valeur par défaut de thinking_level est HIGH (modifiée de MEDIUM le gemini-3.8-flash), et XHIGH est compatible avec les tâches de raisonnement approfondi (laissez de la marge pour la compression du contexte pour les traces de raisonnement HIGH et XHIGH dans les harnais de codage multitours, ou définissez MEDIUM sur les tours sensibles à la latence). thinking_budget et thinking_level="MINIMAL" renvoient une erreur HTTP 400.
  • La mise en cache explicite du contexte (cached_content) n'est pas disponible. La mise en cache implicite s'applique automatiquement à partir d'un minimum de 4 096 jetons (contre 6 144 jetons sur gemini-3.8-flash), avec la mise en cache durable activée par défaut.
  • Les fichiers Microsoft Office (.docx, .dotx, .doc, .pptx, .ppt, .xlsx, .xls) et OpenDocument (.odt, .odp, .ods) sont acceptés de manière intégrée ou par URI Cloud Storage (gs://), y compris dans les parties FunctionResponse multimodales.
  • Les tours d'appel de fonction en parallèle appliquent un placement strict de thought_signature (seule la première partie functionCall d'un tour parallèle comporte thought_signature ; l'omettre dans le tour actif ou le dupliquer sur les parties functionCall sœurs suivantes renvoie une erreur HTTP 400), et les modifications de préfixe de requête du même modèle échouent avec HTTP 400 par défaut, sauf si prefix_mismatch_behavior="DROP" est défini dans ThinkingConfig. Conservez également les parties thought_signature de toutes les requêtes précédentes (les parties functionCall et text finales) pour maintenir la qualité du raisonnement et éviter les motifs d'arrêt MALFORMED_FUNCTION_CALL.
  • Chaque jeton traité par le modèle est facturé, y compris les instructions système des outils internes et les déclarations de fonction lors de l'utilisation de l'ancrage.

Pour une comparaison côte à côte, consultez Migrer depuis les modèles Gemini 3.

 client = genai.Client(
     enterprise=True,
     project="PROJECT_ID",
     location="global", # Supports "global", "us", and "eu"
 )

 response = client.models.generate_content(
-    model="gemini-3.8-flash",
+    model="gemini-4-hydrogen",
     contents=prompt,
     config=types.GenerateContentConfig(
-        temperature=0.0,
-        cached_content="projects/.../cachedContents/...", # Explicit caching unsupported
         thinking_config=types.ThinkingConfig(
-            thinking_budget=16384, # Returns HTTP 400 instead of mapping silently
-            thinking_level="MINIMAL", # MINIMAL unsupported on Gemini 4 Hydrogen
+            thinking_level="HIGH", # Valid: "LOW", "MEDIUM", "HIGH" (default), "XHIGH"
+            # prefix_mismatch_behavior="DROP", # Optional: set if compacting or editing prior history
         ),
     ),
 )

Pour migrer depuis gemini-3.8-flash ou des modèles Gemini 3 Flash antérieurs, procédez comme suit :

  1. Remplacez l'ID du modèle par gemini-4-hydrogen.
  2. Passez à la dernière version du SDK Google Gen AI et tenez compte de la limite unifiée de jetons d'entrée et de sortie : passez à google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0 ou Java >= 1.80.0 pour la continuation automatique de l'API Interactions (ou >= 2.30.1 Python / >= 2.29.1 JavaScript sur GenerateContent). Les jetons d'entrée et de sortie (y compris le raisonnement et les appels de fonction) partagent la limite unifiée de 1 048 576 jetons. Pour les sorties dépassant 65 536 jetons (jusqu'à 1 048 576 jetons) sur l'API Interactions ou GenerateContent, définissez max_output_tokens sur une valeur supérieure à 65 536 afin que le SDK Google Gen AI continue automatiquement sur les segments (ou utilisez background=true ou une boucle continuation_token personnalisée).
  3. Mettre à jour la configuration de thinking_level : remplacez thinking_budget et MINIMAL par thinking_level défini sur LOW, MEDIUM, HIGH (par défaut sur gemini-4-hydrogen) ou XHIGH (utilisez "low", "medium", "high" ou "xhigh" en minuscules sur l'API Interactions). Si votre charge de travail s'appuyait sur MEDIUM par défaut sur gemini-3.8-flash, définissez explicitement thinking_level="MEDIUM" pour conserver une latence de raisonnement équivalente.
  4. Supprimez la mise en cache explicite et chargez à l'avance le contenu statique de la requête (4 096 jetons ou plus) pour la mise en cache implicite automatique.
  5. Vérifiez la conservation de thought_signature et la compression des préfixes pour les appels multitours et parallèles : conservez thought_signature pour tous les tours précédents (parties functionCall et text finales) au lieu de supprimer les signatures entre les tours, ne conservez thought_signature que sur la première partie functionCall d'un tour d'appel d'outil parallèle, et définissez prefix_mismatch_behavior="DROP" dans ThinkingConfig si votre application modifie ou compresse les tours précédents dans l'historique des discussions multitours.
  6. Supprimez les paramètres qui n'ont aucun effet ou qui ne sont pas compatibles : supprimez les champs de génération ignorés et refusés comme suit :
    • Supprimez temperature, top_p et top_k, qui sont ignorés.
    • Supprimez frequency_penalty, presence_penalty et toute valeur candidate_count supérieure à 1.
    • Supprimez tous les tours de modèle préremplis des historiques de conversation.

Checklist récapitulative pour les développeurs

Utilisez la checklist suivante pour vérifier votre intégration Hydrogen :

Problèmes connus

Les problèmes connus suivants s'appliquent aux décodages longs Hydrogen :

  • Les décodages longs nécessitent v1beta1 : le décodage long (continuation_token) sur l'API Interactions et l'API GenerateContent (generateContent et streamGenerateContent) n'est compatible qu'avec l'API v1beta1 (et non v1) sur Agent Platform. Le SDK Google Gen AI utilise v1beta1 par défaut, sauf si api_version='v1' est défini dans http_options (ou api_version="v1" sur interactions.create). Pour les appels REST directs, utilisez le chemin du point de terminaison /v1beta1/.
  • Modifications des paramètres entre les segments de continuation de l'API Interactions : la modification de model, system_instruction ou des déclarations de fonction entre les segments de continuation renvoie une erreur HTTP 400, tandis que les modifications en cours de décodage de generation_config.thinking_level ou des outils intégrés (google_search, code_execution, url_context) ne sont pas rejetées par la validation du serveur. Conservez les thinking_level et les outils intégrés inchangés dans tous les segments d'une boucle de continuation.

Autres ressources

Pour en savoir plus sur Hydrogen, consultez les ressources suivantes :