Guida per gli sviluppatori a Gemini 4 Hydrogen

Gemini 4 Hydrogen offre un'intelligence all'avanguardia con velocità ed efficienza per la programmazione quotidiana e i workflow aziendali basati su agenti.

Questo documento illustra le funzionalità principali di Hydrogen, le convenzioni API che applica, come eseguire la migrazione da Gemini 3.8 Flash e dai modelli Gemini 3 Flash precedenti e una guida rapida. Per una panoramica della famiglia Gemini 4, consulta Inizia a utilizzare Gemini 4.

Funzionalità principali di Gemini 4 Hydrogen

Gemini 4 Hydrogen include le seguenti funzionalità:

  • Limite unificato di token di input e output: Hydrogen ha un limite unificato di 1.048.576 token che include sia i token di input che quelli di output (dove l'output include il ragionamento, le chiamate di funzione e la risposta finale).
  • Decodifiche lunghe fino a 1.048.576 token: Hydrogen estende la generazione oltre un singolo segmento in primo piano di 65.536 token (in streaming o non in streaming) fino a 1.048.576 token (meno i token di input) sia sull'API Interactions sia su GenerateContent (v1beta1). L'SDK Google Gen AI gestisce automaticamente continuation_token tra i segmenti oppure puoi eseguire decodifiche in background asincrone gestite dal server (background=true) o gestire continuation_token in un ciclo di continuazione personalizzato.
  • Livelli di ragionamento: Hydrogen supporta LOW, MEDIUM, HIGH (predefinito) e XHIGH.
  • Memorizzazione nella cache implicita con memorizzazione nella cache durevole: la memorizzazione nella cache implicita si applica automaticamente ai prefissi dei prompt condivisi di almeno 4096 token, con la memorizzazione nella cache durevole abilitata per impostazione predefinita. La memorizzazione nella cache del contesto esplicita non è supportata.
  • Input di file Office e OpenDocument: oltre ai PDF e al testo normale, Hydrogen accetta file Microsoft Office (.docx, .dotx, .doc, .pptx, .ppt, .xlsx, .xls) e OpenDocument (.odt, .odp, .ods) in linea o da Cloud Storage sia su GenerateContent sia sull'API Interactions, anche all'interno di parti multimodali FunctionResponse.
  • Comprensione dei video agentica: la comprensione dei video agentica è in disponibilità generale e disattivata per impostazione predefinita.
  • Ciclo di vita della release a breve termine: Hydrogen è una release in disponibilità generale (GA) a breve termine soggetta a una policy di preavviso di ritiro di almeno 45 giorni. Per i dettagli sul ciclo di vita, consulta Versioni e ciclo di vita dei modelli.

Guida rapida

Prima di iniziare, devi autenticarti su Gemini Enterprise Agent Platform utilizzando le credenziali predefinite dell'applicazione (ADC) o una chiave API. Per saperne di più, consulta Inizia a utilizzare Agent Platform.

Nei blocchi di codice seguenti, sostituisci PROJECT_ID con il tuo ID progetto.

Fai una prova in Agent Studio

Per testare i prompt e configurare gemini-4-hydrogen nell'interfaccia utente di Agent Studio, segui questi passaggi:

  1. Apri Agent Studio nel tuo progetto Google Cloud e seleziona gemini-4-hydrogen nel gruppo Gemini.
  2. In Impostazioni modello, configura le seguenti opzioni:
    • Livello di ragionamento: scegli Low, Medium, High (predefinito) o Extra high.
    • Regione: seleziona Global, us o eu.
    • Limite di token di output: imposta un valore compreso tra 32,768 e 1,048,576 (valore predefinito: 1,048,576). Agent Studio gestisce automaticamente i token di continuazione per le risposte che superano il limite di una singola richiesta.

Installazione

Esegui l'upgrade all'SDK Google Gen AI più recente. La continuazione automatica nell'API Interactions richiede google-genai >= 2.34.0 per Python, @google/genai >= 2.32.0 per JavaScript/TypeScript, >= 1.77.0 per Go o >= 1.80.0 per Java (su GenerateContent, la continuazione automatica richiede >= 2.30.1 per Python, >= 2.29.1 per JavaScript/TypeScript, >= 1.74.0 per Go, >= 1.77.0 per Java, >= 1.26.0 per .NET o >= 1.6.0 per Kotlin):

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

Richiesta di base

Invia una richiesta a gemini-4-hydrogen utilizzando l'SDK Google Gen AI o 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"
    }
  }
}'

Output strutturato

Per generare un output JSON conforme a uno schema, configura response_mime_type e 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)

Esempi di decodifica lunghi

Per impostazione predefinita, un singolo segmento API in primo piano genera fino a 65.536 token di output (in streaming o non in streaming), dove l'output include il ragionamento, le chiamate di funzione e la risposta finale. Per generare completamenti fino a 1.048.576 token (meno i token di input), utilizza le decodifiche lunghe nell'API Interactions o in GenerateContent. Per le opzioni di continuazione, le transizioni di stato e le regole di convalida, consulta Decodifiche lunghe.

Utilizza decodifiche lunghe con l'API Interactions

In google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0 e Java >= 1.80.0, interactions.create() segue automaticamente continuation_token tra i segmenti ogni volta che un segmento restituisce status="requires_continuation". Puoi anche disattivare l'opzione (automatic_continuation=False) per eseguire un loop personalizzato archiviato (store=True) o stateless (store=False):

Python (SDK automatico)

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 (loop personalizzato)

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 (Stored)

# 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 (stateless)

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

Per l'esecuzione asincrona gestita dal server (background=True con store=True) o il recupero dai checkpoint di streaming (eventi interaction.status_update emessi a partire da 65.536 token di output e ogni 5000 token successivi), utilizza i seguenti pattern:

Python (background)

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 (Background)

# 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 (checkpoint di flussi di dati)

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 (checkpoint di 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"
    }
  }'

Utilizza decodifiche lunghe con GenerateContent

Su GenerateContent (v1beta1), imposta max_output_tokens su un valore maggiore di 65.536 (fino a 1.048.576) per le richieste in streaming o non in streaming. L'SDK Google Gen AI segue automaticamente continuation_token tra i segmenti quando finish_reason è CONTINUATION (imposta automatic_continuation=False in GenerateContentConfig per disattivare) oppure puoi passare continuation_token in un loop personalizzato:

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 (loop di continuazione personalizzato)

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

Regole obbligatorie per le API e convenzioni comportamentali

Hydrogen applica le convenzioni nelle sezioni seguenti per i livelli di pensiero, i limiti dei token, la memorizzazione nella cache, i parametri di generazione e l'esecuzione di strumenti multi-turn.

Livelli di ragionamento

Hydrogen supporta quattro valori thinking_level (thinking_budget e MINIMAL restituiscono un errore di convalida HTTP 400). La tabella seguente elenca ogni livello di ragionamento e i relativi workload consigliati:

Livello di pensiero Workload consigliati
XHIGH Ragionamento approfondito, dimostrazioni matematiche, analisi scientifiche e le attività di software engineering multi-file più complesse.
HIGH (valore predefinito su gemini-4-hydrogen) Loop di strumenti agentici in più passaggi, generazione di codice, rifattorizzazione dell'architettura e analisi multimodale complessa.
MEDIUM Programmazione generale, utilizzo di strumenti, domande e risposte sui documenti e comprensione dei video con latenza bilanciata.
LOW Classificazione, routing, riepilogo ed estrazione di metadati strutturati con throughput elevato.

Limiti di token, memorizzazione nella cache e fatturazione

Hydrogen applica le seguenti regole relative a token, memorizzazione nella cache, contenuti multimediali e fatturazione:

  • Limite unificato dei token di input e output e limiti di output per singola richiesta: i budget dei token e i limiti per richiesta funzionano nel seguente modo:
    • Il limite totale di token del modello è 1,048,576 token e include sia i token di input che quelli di output (dove l'output include il ragionamento, le chiamate di funzione e la risposta finale). max_output_tokens controlla il limite di token di output per la generazione (fino a 1,048,576 meno i token di input); l'impostazione di max_output_tokens maggiore di 1,048,576 restituisce un errore HTTP 400.
    • Per evitare completamenti lunghi non intenzionali, il budget di output predefinito e il limite di foreground per un singolo segmento (ragionamento, chiamate di funzione e risposta del modello) sono di 65.536 token per le richieste in streaming e non in streaming.
    • I token di ragionamento generati con HIGH (predefinito) e XHIGH vengono conteggiati ai fini di max_output_tokens e si accumulano nel contesto multi-turn quando conservi le firme di pensiero tra i turni. Imposta max_output_tokens su un valore sufficientemente alto sia per il ragionamento che per l'output finale, evita soglie di compressione del contesto eccessivamente basse nei framework di programmazione multi-turno o imposta thinking_level="MEDIUM" sui turni degli strumenti sensibili alla latenza.
  • Decodifiche lunghe: le risposte in primo piano a segmento singolo generano fino a 65.536 token di output (in streaming o non in streaming). Per estendere l'output a turno singolo fino a 1.048.576 token (meno i token di input) sull'API Interactions o su GenerateContent (v1beta1), consulta Decodifiche lunghe.
  • Memorizzazione nella cache del contesto: la memorizzazione nella cache del contesto esplicita non è supportata. La memorizzazione nella cache implicita (con la memorizzazione nella cache durevole abilitata per impostazione predefinita) si applica automaticamente ai prefissi dei prompt condivisi di almeno 4096 token, quindi inserisci i contenuti statici all'inizio del prompt.
  • Input di Office e OpenDocument: passa i file 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) ed Excel o fogli di lavoro OpenDocument (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel, application/vnd.oasis.opendocument.spreadsheet) in linea o tramite URI Cloud Storage (gs://) utilizzando inlineData o fileData su GenerateContent (anche all'interno delle parti FunctionResponse) e gli input document (inclusi i risultati degli strumenti) nell'API Interactions.
  • Video agentico: i video caricati vengono impostati su media_processing="static" per impostazione predefinita. Imposta media_processing="agentic" per attivare l'elaborazione video agentica.
  • Conteggio e fatturazione dei token: ogni token elaborato dal modello viene conteggiato e fatturato, inclusi i token di ragionamento, le istruzioni di sistema degli strumenti interni e le dichiarazioni di funzione quando si utilizza il grounding. Anche il grounding con la Ricerca Google viene fatturato per query.

Parametri, chiamata di funzione e convalida della chat

Hydrogen applica le seguenti regole per i parametri di generazione, le chiamate agli strumenti, le firme dei pensieri e la cronologia chat:

  • Parametri di campionamento ignorati (temperature, top_k, top_p): il backend ignora i valori personalizzati. Controlla la profondità del ragionamento con thinking_level e il formato di output con response_schema.
  • Parametri non supportati (frequency_penalty, presence_penalty e candidate_count maggiori di 1): se passi frequency_penalty, presence_penalty o candidate_count maggiori di 1 (candidateCount è fissato a 1), viene restituito un errore HTTP 400. Rimuovi questi parametri dalle tue richieste.
  • Chiamata di funzione e firme di pensiero: le dichiarazioni degli strumenti, le chiamate parallele agli strumenti e la riproduzione di thought_signature a più turni seguono queste regole:

    • Simmetria delle svolte: ogni FunctionResponse deve corrispondere a id, name e all'ordine della FunctionCall precedente.
    • Parti FunctionResponse multimodali: includi documenti, fogli di lavoro, presentazioni, PDF, immagini, audio e video di Office all'interno di parti FunctionResponse multimodali (o risultati degli strumenti nell'API Interactions) anziché aggiungerli come parti separate del turno dell'utente.
    • Posizionamento della chiamata di funzione parallela thought_signature: quando il modello emette più parti functionCall parallele in un singolo turno model, solo la prima parte functionCall contiene thought_signature. Se ometti thought_signature dalla prima parte functionCall nel turno dell'utente attivo, lo duplichi nelle parti functionCall parallele successive o alterni i turni functionCall e functionResponse, viene restituito un errore HTTP 400. Mantieni tutte le parti functionCall parallele in un unico turno model, seguito da tutte le parti functionResponse corrispondenti in un unico turno user. Per maggiori dettagli, consulta Firme di pensiero.
    • Conservazione dei thought_signature tra i turni: restituisci ogni thought_signature all'interno del suo Part originale in tutti i turni precedenti nella cronologia della chat a più turni (sia le parti functionCall che quelle finali text), non solo all'interno del turno dell'utente attivo. Sebbene la convalida della firma HTTP 400 si applichi solo ai passaggi functionCall all'interno del turno utente attivo, l'eliminazione dei valori thought_signature dai turni precedenti o la sostituzione dei valori di bypass come skip_thought_signature_validator rimuove il contesto di ragionamento, riduce la qualità dell'output e può causare motivi di interruzione MALFORMED_FUNCTION_CALL.
    • Formattazione pre-strumento: separa le istruzioni in linea con \n\n ed evita il testo non strutturato prima delle chiamate allo strumento. Per registrare lo stato intermedio prima di una chiamata allo strumento, utilizza una dichiarazione di funzione dedicata:

      {
        "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"]
        }
      }
      
  • Convalida della sequenza di chat: i payload della chat a più turni applicano i seguenti vincoli:

    • I payload della cronologia non possono terminare con un turno del ruolo model.
    • I turni precompilati del modello non sono supportati.

Decodifiche lunghe

La decodifica lunga suddivide una generazione fino a 1.048.576 token (meno i token di input) in più segmenti nell'API Interactions o GenerateContent (v1beta1). Nell'API Interactions, ogni segmento in primo piano (stream=true o stream=false) genera fino a 65.536 token di output e restituisce status="requires_continuation" con un continuation_token crittografato oppure puoi impostare background=true (store=true) in modo che il server esegua il ciclo di continuazione in modo asincrono e memorizzi l'output unito in un Interaction. Su GenerateContent, ogni segmento di streaming o non streaming genera fino a 65.536 token di output prima di emettere finish_reason=CONTINUATION con continuation_token, continuando fino a finish_reason=STOP. In Agent Studio, l'impostazione del limite di token di output su un valore superiore a 65.536 fino a 1.048.576 gestisce automaticamente i token di continuazione. Per esempi di codice eseguibile, consulta gli esempi di guida rapida alla decodifica lunga.

Quando utilizzare la decodifica lunga

La maggior parte delle richieste viene completata entro il limite di output di 65.536 token per segmento. Utilizza la decodifica lunga solo quando una risposta richiede un output maggiore. La decodifica lunga offre al modello più spazio per ragionare; non rende le risposte più lunghe (utilizza thinking_level per controllare la profondità del ragionamento).

Workload Utilizzare la decodifica lunga? Perché
Matematica, scienze, ricerca e dimostrazioni formali complesse Sì Il modello può utilizzare più di 65.536 token per esplorare e verificare il suo ragionamento.
Le attività di programmazione e agentiche più difficili Sì Alcune attività richiedono più di 65.536 token di ragionamento e codice in un'unica risposta. La maggior parte delle attività di programmazione e agentiche viene completata con meno di 65.536 token.
Framework di valutazione che si interrompono al limite di output Sì La decodifica lunga impedisce risposte incomplete quando il modello impiega un intero segmento di 65.536 token per il ragionamento.
Chat, domande e risposte, riepilogo, classificazione ed estrazione No Queste attività terminano ben al di sotto dei 65.536 token.
Richieste di una lunghezza fissa, ad esempio "scrivi un libro di 700.000 parole" No Il modello non segue i target di lunghezza.
Agenti che chiamano strumenti in molti turni brevi No Ogni turno è breve. Output di grandi dimensioni in ogni turno riempiono rapidamente il limite unificato di input e output di 1.048.576 token.
Prompt vicini al limite di input di 1.048.576 token No L'output può utilizzare solo 1.048.576 token meno l'input.
Richieste sensibili alla latenza No La decodifica lunga può richiedere diversi minuti.

Scegli un'opzione di continuazione

Seleziona un pattern di continuazione in base alla superficie dell'API, alla postura di archiviazione e all'ambiente di runtime. Tutte le opzioni nella tabella seguente raggiungono lo stesso limite di 1.048.576 token (meno i token di input) su gemini-4-hydrogen.

Opzione di continuazione Piattaforma API Chi avvia ogni segmento Token per segmento Limite di tempo per richiesta Spazio di archiviazione del server Ideale per
(Consigliato) Continuazione automatica dell'SDK Google Gen AI API Interactions (v1beta1) SDK Google Gen AI: Python (google-genai >= 2.34.0), JavaScript/TypeScript (@google/genai >= 2.32.0), Go (>= 1.77.0) e Java (>= 1.80.0) Fino a 65.536 (stream=true o stream=false) 20 minuti per segmento Archiviazione sul server per 7 giorni per impostazione predefinita (store=true) o nessuna (store=false) La maggior parte delle applicazioni API Interactions stateful o stateless
Loop in background gestito dal server (background=true) API Interactions (v1beta1) Loop del server Agent Platform; il tuo codice esegue il polling di get Gestito lato server fino a max_output_tokens Asincrona (non è richiesto uno stream client aperto) Spazio di archiviazione del server per 7 giorni (store=true richiesto) Job asincroni, chiamanti .NET/Kotlin e persistenza di un singolo record
Loop archiviato in primo piano personalizzato (store=true) API Interactions (v1beta1) Il tuo codice (previous_interaction_id + continuation_token, senza input) Fino a 65.536 (stream=true o stream=false; checkpoint a partire da 65.536 e ogni 5000 token successivi) 20 minuti per segmento Spazio di archiviazione sul server per 7 giorni (store=true) Chiamanti REST e recupero di checkpoint personalizzati
Loop stateless in primo piano personalizzato (store=false) API Interactions (v1beta1) Il tuo codice (input originale + continuation_token, senza previous_interaction_id) Fino a 65.536 (stream=true o stream=false; checkpoint a partire da 65.536 e ogni 5000 token successivi) 20 minuti per segmento Nessuna archiviazione sul server (workflow di conservazione zero dei dati) Harness REST personalizzati che richiedono l'esecuzione stateless
(Consigliato) Continuazione automatica dell'SDK Google Gen AI 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) e Kotlin (>= 1.6.0) Fino a 65.536 (generate_content_stream o generate_content) 20 minuti per segmento Nessuna archiviazione sul server (workflow di conservazione zero dei dati) Applicazioni GenerateContent esistenti
Loop di continuazione personalizzato GenerateContent (v1beta1) Il tuo codice (contents originale + continuation_token) Fino a 65.536 (streamGenerateContent o generateContent; checkpoint a partire da 65.536 e ogni 5000 token successivi) 20 minuti per segmento Nessuna archiviazione sul server (workflow di conservazione zero dei dati) Chiamanti REST GenerateContent diretti e strumenti di valutazione

Requisiti relativi alla versione dell'API e all'SDK

Le decodifiche lunghe richiedono la seguente versione dell'API e le seguenti versioni minime dell'SDK:

  • Requisito dell'API v1beta1 (problema noto): la decodifica lunga (continuation_token) sia nell'API Interactions sia in GenerateContent (generateContent e streamGenerateContent) è supportata solo nell'API v1beta1 (non v1) su Agent Platform. L'SDK Google Gen AI utilizza v1beta1 per impostazione predefinita, a meno che api_version='v1' non sia specificato in http_options (o api_version="v1" su interactions.create); per le chiamate REST dirette, utilizza il percorso dell'endpoint /v1beta1/.
  • Versioni dell'SDK e compatibilità con OpenAI: per la continuazione automatica nell'API Interactions, esegui l'upgrade a Python google-genai >= 2.34.0, JavaScript/TypeScript @google/genai >= 2.32.0, Go >= 1.77.0 o Java >= 1.80.0 (per .NET e Kotlin nell'API Interactions, utilizza background=true o un loop di continuazione personalizzato). Per la continuazione automatica su GenerateContent, esegui l'upgrade a Python >= 2.30.1, JavaScript/TypeScript >= 2.29.1, Go >= 1.74.0, Java >= 1.77.0, .NET >= 1.26.0 o Kotlin >= 1.6.0. Le versioni precedenti dell'SDK e il livello di compatibilità con OpenAI non possono recuperare i completamenti lunghi utilizzando i token di continuazione.

Regole di continuazione dell'API Interactions

Le seguenti transizioni di stato, regole di concatenamento e comportamenti di archiviazione si applicano alle decodifiche lunghe nell'API Interactions.

Valori di stato e budget dei token di output

Se generation_config.max_output_tokens viene omesso in una richiesta API Interactions, il budget di output totale viene impostato per impostazione predefinita su 65.536 token (corrispondente al limite di foreground di un singolo segmento di 65.536 token per le richieste in streaming e non in streaming). Imposta generation_config.max_output_tokens su un valore maggiore di 65,536 (fino a 1,048,576 meno i token di input) per le decodifiche lunghe di più segmenti sia in modalità in primo piano che background=true. Il server restituisce i seguenti valori di stato:

  • requires_continuation: il limite di output di 65.536 token per segmento è stato raggiunto prima di max_output_tokens; passa il valore continuation_token restituito nella richiesta successiva per continuare la decodifica.
  • incomplete: il budget totale di max_output_tokens è stato esaurito; se continui con continuation_token senza aumentare max_output_tokens, viene restituito un errore HTTP 400 (max_output_tokens has already been exhausted). Aumenta max_output_tokens nella richiesta successiva per riprendere la decodifica.
  • completed: la generazione è terminata naturalmente e continuation_token viene cancellato.

Concatenamento, cambio di modalità e archiviazione dei segmenti

Le richieste di continuazione nell'API Interactions applicano le seguenti regole:

  • Continuazione memorizzata (store=true, predefinita): passa previous_interaction_id impostato sul segmento id che ha emesso continuation_token insieme a continuation_token e ometti input (il segmento memorizzato contiene già l'input del turno). Associa sempre ogni continuation_token al previous_interaction_id del segmento che lo ha emesso; il passaggio di un continuation_token su un'interazione già completed restituisce un errore HTTP 400.
  • Continuazione stateless (store=false): ometti previous_interaction_id e invia nuovamente l'input originale insieme a continuation_token su ogni segmento.
  • Passaggio tra le modalità store tra i segmenti: puoi passare dalla modalità archiviata (store=true) a quella stateless (store=false) durante la decodifica omettendo previous_interaction_id e inviando nuovamente il input originale con continuation_token. Il passaggio da stateless (store=false) a archiviata (store=true) non è supportato perché non esiste un'interazione principale archiviata per previous_interaction_id.
  • Cambio di modalità e branching in primo piano e background=true: le continuazioni archiviate (store=true) possono passare dall'esecuzione in primo piano (background=false) a quella in background (background=true) tra i segmenti, incluso il ripristino di un'interazione background=true annullata dal relativo checkpoint continuation_token (persistente a partire da 65.536 token di output e ogni 5000 token successivi) in modalità in background o in primo piano. Il riutilizzo degli stessi previous_interaction_id e continuation_token crea continuazioni ramificate indipendenti.
  • Applicazione dei limiti dei turni: l'avvio di un nuovo turno utente (previous_interaction_id con un nuovo input e senza continuation_token) da un segmento il cui stato è requires_continuation o incomplete restituisce un errore HTTP 400. Completa la decodifica fino a completed o crea un ramo per il turno successivo dall'interazione completed più recente. Una volta che il segmento finale raggiunge completed, il passaggio di id di quel segmento finale come previous_interaction_id ricostruisce la cronologia completa della conversazione in tutti i segmenti precedenti.
  • Coerenza dei parametri tra i segmenti: la modifica di model, system_instruction o delle dichiarazioni di funzione (tools) in un segmento di continuazione restituisce un errore HTTP 400. Mantieni invariati anche thinking_level e gli strumenti integrati nei vari segmenti (consulta Problemi noti).
  • Comportamento di get, list e delete per un singolo segmento: in modalità in primo piano (background=false), ogni segmento viene archiviato come risorsa Interaction separata (interactions.get(id) restituisce solo quel segmento, interactions.list() elenca ogni segmento separatamente e interactions.delete(id) elimina solo quel segmento; quando elimini una catena di segmenti, eliminali in ordine inverso, dall'ultimo segmento indietro). Nell'SDK Google Gen AI con automatic_continuation=True (stream=False), interactions.create() unisce tutti i segmenti al ritorno e compila interaction.continuation_ids con gli ID segmento ordinati (che terminano con interaction.id). Se un segmento successivo non va a buon fine, supera un timeout numerico per chiamata o si interrompe a metà flusso dopo che è stato superato un checkpoint ripristinabile, l'SDK genera ContinuationInterruptedError con partial_interaction, continuation_token, interaction_id e continuation_ids in modo da poter riprendere da continuation_token.

Regole del loop personalizzato GenerateContent

In un loop di continuazione GenerateContent personalizzato, segui queste regole:

  • Imposta max_output_tokens su un valore superiore a 65.536 (fino a 1.048.576) e invia nuovamente i valori originali di contents, system_instruction e tools in ogni richiesta di continuazione insieme all'ultimo continuation_token (un campo di primo livello su GenerateContentRequest in REST o in GenerateContentConfig nell'SDK Google Gen AI).
  • Non aggiungere l'output parziale del modello a contents e non inviare un prompt aggiuntivo per chiedere al modello di continuare.
  • Continua il loop finché finish_reason è CONTINUATION ed è presente continuation_token, anche se un segmento ha utilizzato tutti i 65.536 token per il ragionamento (parts: [{"text": ""}]). Se finish_reason è MAX_TOKENS quando è presente continuation_token, aumenta max_output_tokens nella richiesta successiva.
  • Combina le parti accumulate in un unico turno model per la cronologia multi-turno solo dopo STOP.

Conteggio dei token, compattazione e memorizzazione nella cache implicita

Il conteggio e la memorizzazione nella cache dei token nei segmenti di continuazione funzionano come segue:

  • Nell'API Interactions, le chiamate interactions.create() non in streaming con automatic_continuation=True e le interazioni background=true gestite dal server sommano i conteggi dei token in tutti i segmenti in usage (total_input_tokens, total_cached_tokens, total_output_tokens, total_thought_tokens, total_tokens), preservando il conteggio dei prompt del primo segmento in usage.initial_input_tokens. Nei loop in primo piano personalizzati e negli eventi interaction.completed in streaming, il campo usage di ogni segmento riporta solo il delta di quel segmento, quindi somma i campi usage tra i segmenti per ottenere i token fatturati totali.
  • Su GenerateContent, l'SDK Google Gen AI per Python (generate_content e generate_content_stream) accumula i token fatturati totali tra i segmenti nel usage_metadata finale e conserva initial_prompt_token_count. Nei loop REST personalizzati, somma i valori finali di prompt_token_count, cached_content_token_count, candidates_token_count e thoughts_token_count tra i segmenti.
  • Poiché ogni segmento di prosecuzione in primo piano precompila nuovamente la conversazione e i token generati in precedenza come input, usage.total_input_tokens (nell'API Interactions) e prompt_token_count (in GenerateContent) aumentano tra i segmenti. Non utilizzare i conteggi degli input cumulativi per attivare la compressione del contesto nelle infrastrutture agentiche; controlla invece usage.initial_input_tokens (o initial_prompt_token_count su GenerateContent) e comprimi solo dopo il termine del turno (status="completed" o nessun continuation_token).
  • Ogni segmento di continuazione precompila nuovamente il prompt e i token decodificati in precedenza e si qualifica automaticamente per la memorizzazione nella cache del contesto implicita (minimo 4096 token, con memorizzazione nella cache durevole abilitata per impostazione predefinita) quando i segmenti vengono eseguiti uno dopo l'altro. I segmenti completati vengono fatturati alla fine di ogni segmento, anche se un segmento successivo non va a buon fine o viene annullato.

Esegui la migrazione a Hydrogen da 3.8 Flash

Il seguente comportamento è diverso da gemini-3.8-flash e dai modelli Gemini 3 Flash precedenti:

  • Hydrogen ha un limite unificato di 1.048.576 token per input e output (dove l'output include ragionamento, chiamate di funzione e risposta finale), anziché limiti di input e output separati. L'output in primo piano a segmento singolo è limitato a 65.536 token (in streaming o non in streaming) e può essere esteso fino a 1.048.576 token utilizzando le decodifiche lunghe nell'API Interactions o GenerateContent (gestite automaticamente nell'SDK Google Gen AI, con background=true nell'API Interactions o utilizzando continuation_token in loop personalizzati).
  • Il valore predefinito di thinking_level è HIGH (modificato da MEDIUM il gemini-3.8-flash) e XHIGH è supportato per le attività di deep reasoning (lascia spazio per la compressione del contesto per le tracce di ragionamento di HIGH e XHIGH nei framework di programmazione multi-turn o imposta MEDIUM nei turni sensibili alla latenza). thinking_budget e thinking_level="MINIMAL" restituiscono un errore HTTP 400.
  • La memorizzazione nella cache del contesto esplicita (cached_content) non è supportata. La memorizzazione nella cache implicita viene applicata automaticamente con un minimo di 4096 token (ridotto da 6144 token su gemini-3.8-flash), con la memorizzazione nella cache durevole abilitata per impostazione predefinita.
  • I file di Microsoft Office (.docx, .dotx, .doc, .pptx, .ppt, .xlsx, .xls) e OpenDocument (.odt, .odp, .ods) sono supportati in linea o tramite URI Cloud Storage (gs://), anche all'interno di parti FunctionResponse multimodali.
  • I turni di chiamata di funzione parallela applicano un posizionamento rigoroso di thought_signature (solo la prima parte functionCall in un turno parallelo contiene thought_signature; ometterlo nel turno attivo o duplicarlo nelle parti functionCall di pari livello successive restituisce un errore HTTP 400) e le modifiche al prefisso del prompt dello stesso modello non vanno a buon fine con HTTP 400 per impostazione predefinita, a meno che prefix_mismatch_behavior="DROP" non sia impostato in ThinkingConfig. Conserva anche le parti thought_signature di tutti i turni precedenti (sia le parti functionCall che quelle finali text) per mantenere la qualità del ragionamento ed evitare i motivi di interruzione MALFORMED_FUNCTION_CALL.
  • Ogni token elaborato dal modello viene fatturato, incluse le istruzioni di sistema dello strumento interno e le dichiarazioni delle funzioni quando si utilizza il grounding.

Per un confronto fianco a fianco, consulta Esegui la migrazione dai modelli 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
         ),
     ),
 )

Per eseguire la migrazione dai modelli Gemini 3 Flash gemini-3.8-flash o precedenti, procedi nel seguente modo:

  1. Aggiorna l'ID modello in gemini-4-hydrogen.
  2. Esegui l'upgrade all'SDK Google Gen AI più recente e tieni conto del limite unificato di token di input e output: esegui l'upgrade a google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0 o Java >= 1.80.0 per la continuazione automatica dell'API Interactions (o >= 2.30.1 Python/>= 2.29.1 JavaScript su GenerateContent). I token di input e output (incluse le chiamate di funzione e di ragionamento) condividono il limite unificato di 1.048.576 token. Per output superiori a 65.536 token (fino a 1.048.576 token) nell'API Interactions o GenerateContent, imposta max_output_tokens su un valore superiore a 65.536 in modo che l'SDK Google Gen AI continui automaticamente tra i segmenti (o utilizza background=true o un ciclo continuation_token personalizzato).
  3. Aggiorna la configurazione di thinking_level: sostituisci thinking_budget e MINIMAL con thinking_level impostato su LOW, MEDIUM, HIGH (predefinito su gemini-4-hydrogen) o XHIGH (utilizza "low", "medium", "high" o "xhigh" in minuscolo nell'API Interactions). Se il tuo workload si basava su MEDIUM come impostazione predefinita su gemini-3.8-flash, imposta esplicitamente thinking_level="MEDIUM" per mantenere una latenza di ragionamento equivalente.
  4. Rimuovi la memorizzazione nella cache esplicita e carica in anticipo i contenuti dei prompt statici (4096 token o più) per la memorizzazione nella cache implicita automatica.
  5. Verifica la conservazione di thought_signature in più turni e in parallelo e la compattazione dei prefissi: conserva thought_signature in tutti i turni precedenti (sia le parti functionCall che quelle finali text) anziché rimuovere le firme tra i turni, mantieni thought_signature solo nella prima parte functionCall di un turno di chiamata allo strumento in parallelo e imposta prefix_mismatch_behavior="DROP" in ThinkingConfig se la tua applicazione modifica o compatta i turni precedenti nella cronologia della chat a più turni.
  6. Rimuovi i parametri che non hanno effetto o non sono supportati: rimuovi i campi di generazione ignorati e rifiutati come segue:
    • Rimuovi temperature, top_p e top_k, che vengono ignorati.
    • Rimuovi frequency_penalty, presence_penalty e qualsiasi valore candidate_count maggiore di 1.
    • Rimuovi eventuali turni precompilati del modello dalle cronologie delle conversazioni.

Elenco di controllo di riepilogo per gli sviluppatori

Utilizza il seguente elenco di controllo per verificare l'integrazione di Hydrogen:

Problemi noti

I seguenti problemi noti si applicano alle decodifiche lunghe di Hydrogen:

  • Le decodifiche lunghe richiedono v1beta1: la decodifica lunga (continuation_token) sia sull'API Interactions sia sull'API GenerateContent (generateContent e streamGenerateContent) è supportata solo nell'API v1beta1 (non v1) su Agent Platform. L'SDK Google Gen AI utilizza v1beta1 per impostazione predefinita, a meno che api_version='v1' non sia impostato in http_options (o api_version="v1" su interactions.create); per le chiamate REST dirette, utilizza il percorso dell'endpoint /v1beta1/.
  • Modifiche ai parametri nei segmenti di continuazione dell'API Interactions: la modifica di model, system_instruction o delle dichiarazioni delle funzioni nei segmenti di continuazione restituisce un errore HTTP 400, mentre le modifiche a metà decodifica di generation_config.thinking_level o degli strumenti integrati (google_search, code_execution, url_context) non vengono rifiutate dalla convalida del server. Mantieni invariati thinking_level e gli strumenti integrati in tutti i segmenti di un loop di continuazione.

Risorse aggiuntive

Per saperne di più su Hydrogen, consulta le seguenti risorse: