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 automaticamentecontinuation_tokentra i segmenti oppure puoi eseguire decodifiche in background asincrone gestite dal server (background=true) o gestirecontinuation_tokenin un ciclo di continuazione personalizzato. - Livelli di ragionamento: Hydrogen supporta
LOW,MEDIUM,HIGH(predefinito) eXHIGH. - 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 suGenerateContentsia sull'API Interactions, anche all'interno di parti multimodaliFunctionResponse. - 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:
- Apri Agent Studio nel tuo progetto Google Cloud e seleziona
gemini-4-hydrogennel gruppo Gemini. - In Impostazioni modello, configura le seguenti opzioni:
- Livello di ragionamento: scegli
Low,Medium,High(predefinito) oExtra high. - Regione: seleziona
Global,usoeu. - Limite di token di output: imposta un valore compreso tra
32,768e1,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.
- Livello di ragionamento: scegli
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:
Python (SDK - Consigliato)
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,576token 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_tokenscontrolla il limite di token di output per la generazione (fino a1,048,576meno i token di input); l'impostazione dimax_output_tokensmaggiore di1,048,576restituisce un errore HTTP400. - 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) eXHIGHvengono conteggiati ai fini dimax_output_tokense si accumulano nel contesto multi-turn quando conservi le firme di pensiero tra i turni. Impostamax_output_tokenssu 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 impostathinking_level="MEDIUM"sui turni degli strumenti sensibili alla latenza.
- Il limite totale di token del modello è
- 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://) utilizzandoinlineDataofileDatasuGenerateContent(anche all'interno delle partiFunctionResponse) e gli inputdocument(inclusi i risultati degli strumenti) nell'API Interactions. - Video agentico: i video caricati vengono impostati su
media_processing="static"per impostazione predefinita. Impostamedia_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 conthinking_levele il formato di output conresponse_schema. - Parametri non supportati (
frequency_penalty,presence_penaltyecandidate_countmaggiori di1): se passifrequency_penalty,presence_penaltyocandidate_countmaggiori di1(candidateCountè fissato a1), viene restituito un errore HTTP400. 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_signaturea più turni seguono queste regole:- Simmetria delle svolte: ogni
FunctionResponsedeve corrispondere aid,namee all'ordine dellaFunctionCallprecedente. - Parti
FunctionResponsemultimodali: includi documenti, fogli di lavoro, presentazioni, PDF, immagini, audio e video di Office all'interno di partiFunctionResponsemultimodali (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ù partifunctionCallparallele in un singolo turnomodel, solo la prima partefunctionCallcontienethought_signature. Se omettithought_signaturedalla prima partefunctionCallnel turno dell'utente attivo, lo duplichi nelle partifunctionCallparallele successive o alterni i turnifunctionCallefunctionResponse, viene restituito un errore HTTP400. Mantieni tutte le partifunctionCallparallele in un unico turnomodel, seguito da tutte le partifunctionResponsecorrispondenti in un unico turnouser. Per maggiori dettagli, consulta Firme di pensiero. - Conservazione dei
thought_signaturetra i turni: restituisci ognithought_signatureall'interno del suoPartoriginale in tutti i turni precedenti nella cronologia della chat a più turni (sia le partifunctionCallche quelle finalitext), non solo all'interno del turno dell'utente attivo. Sebbene la convalida della firma HTTP400si applichi solo ai passaggifunctionCallall'interno del turno utente attivo, l'eliminazione dei valorithought_signaturedai turni precedenti o la sostituzione dei valori di bypass comeskip_thought_signature_validatorrimuove il contesto di ragionamento, riduce la qualità dell'output e può causare motivi di interruzioneMALFORMED_FUNCTION_CALL. Formattazione pre-strumento: separa le istruzioni in linea con
\n\ned 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"] } }
- Simmetria delle svolte: ogni
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.
- I payload della cronologia non possono terminare con un turno del ruolo
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 inGenerateContent(generateContentestreamGenerateContent) è supportata solo nell'APIv1beta1(nonv1) su Agent Platform. L'SDK Google Gen AI utilizzav1beta1per impostazione predefinita, a meno cheapi_version='v1'non sia specificato inhttp_options(oapi_version="v1"suinteractions.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.0o Java>= 1.80.0(per .NET e Kotlin nell'API Interactions, utilizzabackground=trueo un loop di continuazione personalizzato). Per la continuazione automatica suGenerateContent, esegui l'upgrade a Python>= 2.30.1, JavaScript/TypeScript>= 2.29.1, Go>= 1.74.0, Java>= 1.77.0, .NET>= 1.26.0o 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 dimax_output_tokens; passa il valorecontinuation_tokenrestituito nella richiesta successiva per continuare la decodifica.incomplete: il budget totale dimax_output_tokensè stato esaurito; se continui concontinuation_tokensenza aumentaremax_output_tokens, viene restituito un errore HTTP400(max_output_tokens has already been exhausted). Aumentamax_output_tokensnella richiesta successiva per riprendere la decodifica.completed: la generazione è terminata naturalmente econtinuation_tokenviene 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): passaprevious_interaction_idimpostato sul segmentoidche ha emessocontinuation_tokeninsieme acontinuation_tokene omettiinput(il segmento memorizzato contiene già l'input del turno). Associa sempre ognicontinuation_tokenalprevious_interaction_iddel segmento che lo ha emesso; il passaggio di uncontinuation_tokensu un'interazione giàcompletedrestituisce un errore HTTP400. - Continuazione stateless (
store=false): omettiprevious_interaction_ide invia nuovamente l'inputoriginale insieme acontinuation_tokensu ogni segmento. - Passaggio tra le modalità
storetra i segmenti: puoi passare dalla modalità archiviata (store=true) a quella stateless (store=false) durante la decodifica omettendoprevious_interaction_ide inviando nuovamente ilinputoriginale concontinuation_token. Il passaggio da stateless (store=false) a archiviata (store=true) non è supportato perché non esiste un'interazione principale archiviata perprevious_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'interazionebackground=trueannullata dal relativo checkpointcontinuation_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 stessiprevious_interaction_idecontinuation_tokencrea continuazioni ramificate indipendenti. - Applicazione dei limiti dei turni: l'avvio di un nuovo turno utente (
previous_interaction_idcon un nuovoinpute senzacontinuation_token) da un segmento il cui stato èrequires_continuationoincompleterestituisce un errore HTTP400. Completa la decodifica fino acompletedo crea un ramo per il turno successivo dall'interazionecompletedpiù recente. Una volta che il segmento finale raggiungecompleted, il passaggio diiddi quel segmento finale comeprevious_interaction_idricostruisce la cronologia completa della conversazione in tutti i segmenti precedenti. - Coerenza dei parametri tra i segmenti: la modifica di
model,system_instructiono delle dichiarazioni di funzione (tools) in un segmento di continuazione restituisce un errore HTTP400. Mantieni invariati anchethinking_levele gli strumenti integrati nei vari segmenti (consulta Problemi noti). - Comportamento di
get,listedeleteper un singolo segmento: in modalità in primo piano (background=false), ogni segmento viene archiviato come risorsaInteractionseparata (interactions.get(id)restituisce solo quel segmento,interactions.list()elenca ogni segmento separatamente einteractions.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 conautomatic_continuation=True(stream=False),interactions.create()unisce tutti i segmenti al ritorno e compilainteraction.continuation_idscon gli ID segmento ordinati (che terminano coninteraction.id). Se un segmento successivo non va a buon fine, supera untimeoutnumerico per chiamata o si interrompe a metà flusso dopo che è stato superato un checkpoint ripristinabile, l'SDK generaContinuationInterruptedErrorconpartial_interaction,continuation_token,interaction_idecontinuation_idsin modo da poter riprendere dacontinuation_token.
Regole del loop personalizzato GenerateContent
In un loop di continuazione GenerateContent personalizzato, segui queste regole:
- Imposta
max_output_tokenssu un valore superiore a 65.536 (fino a 1.048.576) e invia nuovamente i valori originali dicontents,system_instructionetoolsin ogni richiesta di continuazione insieme all'ultimocontinuation_token(un campo di primo livello suGenerateContentRequestin REST o inGenerateContentConfignell'SDK Google Gen AI). - Non aggiungere l'output parziale del modello a
contentse non inviare un prompt aggiuntivo per chiedere al modello di continuare. - Continua il loop finché
finish_reasonèCONTINUATIONed è presentecontinuation_token, anche se un segmento ha utilizzato tutti i 65.536 token per il ragionamento (parts: [{"text": ""}]). Sefinish_reasonèMAX_TOKENSquando è presentecontinuation_token, aumentamax_output_tokensnella richiesta successiva. - Combina le parti accumulate in un unico turno
modelper la cronologia multi-turno solo dopoSTOP.
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 conautomatic_continuation=Truee le interazionibackground=truegestite dal server sommano i conteggi dei token in tutti i segmenti inusage(total_input_tokens,total_cached_tokens,total_output_tokens,total_thought_tokens,total_tokens), preservando il conteggio dei prompt del primo segmento inusage.initial_input_tokens. Nei loop in primo piano personalizzati e negli eventiinteraction.completedin streaming, il campousagedi ogni segmento riporta solo il delta di quel segmento, quindi somma i campiusagetra i segmenti per ottenere i token fatturati totali. - Su
GenerateContent, l'SDK Google Gen AI per Python (generate_contentegenerate_content_stream) accumula i token fatturati totali tra i segmenti nelusage_metadatafinale e conservainitial_prompt_token_count. Nei loop REST personalizzati, somma i valori finali diprompt_token_count,cached_content_token_count,candidates_token_countethoughts_token_counttra 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) eprompt_token_count(inGenerateContent) aumentano tra i segmenti. Non utilizzare i conteggi degli input cumulativi per attivare la compressione del contesto nelle infrastrutture agentiche; controlla inveceusage.initial_input_tokens(oinitial_prompt_token_countsuGenerateContent) e comprimi solo dopo il termine del turno (status="completed"o nessuncontinuation_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, conbackground=truenell'API Interactions o utilizzandocontinuation_tokenin loop personalizzati). - Il valore predefinito di
thinking_levelèHIGH(modificato daMEDIUMilgemini-3.8-flash) eXHIGHè supportato per le attività di deep reasoning (lascia spazio per la compressione del contesto per le tracce di ragionamento diHIGHeXHIGHnei framework di programmazione multi-turn o impostaMEDIUMnei turni sensibili alla latenza).thinking_budgetethinking_level="MINIMAL"restituiscono un errore HTTP400. - 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 sugemini-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 partiFunctionResponsemultimodali. - I turni di chiamata di funzione parallela applicano un posizionamento rigoroso di
thought_signature(solo la prima partefunctionCallin un turno parallelo contienethought_signature; ometterlo nel turno attivo o duplicarlo nelle partifunctionCalldi pari livello successive restituisce un errore HTTP400) e le modifiche al prefisso del prompt dello stesso modello non vanno a buon fine con HTTP400per impostazione predefinita, a meno cheprefix_mismatch_behavior="DROP"non sia impostato inThinkingConfig. Conserva anche le partithought_signaturedi tutti i turni precedenti (sia le partifunctionCallche quelle finalitext) per mantenere la qualità del ragionamento ed evitare i motivi di interruzioneMALFORMED_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:
- Aggiorna l'ID modello in
gemini-4-hydrogen. - 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.0o Java>= 1.80.0per la continuazione automatica dell'API Interactions (o>= 2.30.1Python/>= 2.29.1JavaScript suGenerateContent). 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 oGenerateContent, impostamax_output_tokenssu un valore superiore a 65.536 in modo che l'SDK Google Gen AI continui automaticamente tra i segmenti (o utilizzabackground=trueo un ciclocontinuation_tokenpersonalizzato). - Aggiorna la configurazione di
thinking_level: sostituiscithinking_budgeteMINIMALconthinking_levelimpostato suLOW,MEDIUM,HIGH(predefinito sugemini-4-hydrogen) oXHIGH(utilizza"low","medium","high"o"xhigh"in minuscolo nell'API Interactions). Se il tuo workload si basava suMEDIUMcome impostazione predefinita sugemini-3.8-flash, imposta esplicitamentethinking_level="MEDIUM"per mantenere una latenza di ragionamento equivalente. - 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.
- Verifica la conservazione di
thought_signaturein più turni e in parallelo e la compattazione dei prefissi: conservathought_signaturein tutti i turni precedenti (sia le partifunctionCallche quelle finalitext) anziché rimuovere le firme tra i turni, mantienithought_signaturesolo nella prima partefunctionCalldi un turno di chiamata allo strumento in parallelo e impostaprefix_mismatch_behavior="DROP"inThinkingConfigse la tua applicazione modifica o compatta i turni precedenti nella cronologia della chat a più turni. - Rimuovi i parametri che non hanno effetto o non sono supportati: rimuovi i campi di generazione ignorati e rifiutati come segue:
- Rimuovi
temperature,top_petop_k, che vengono ignorati. - Rimuovi
frequency_penalty,presence_penaltye qualsiasi valorecandidate_countmaggiore di1. - Rimuovi eventuali turni precompilati del modello dalle cronologie delle conversazioni.
- Rimuovi
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'APIGenerateContent(generateContentestreamGenerateContent) è supportata solo nell'APIv1beta1(nonv1) su Agent Platform. L'SDK Google Gen AI utilizzav1beta1per impostazione predefinita, a meno cheapi_version='v1'non sia impostato inhttp_options(oapi_version="v1"suinteractions.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_instructiono delle dichiarazioni delle funzioni nei segmenti di continuazione restituisce un errore HTTP400, mentre le modifiche a metà decodifica digeneration_config.thinking_levelo degli strumenti integrati (google_search,code_execution,url_context) non vengono rifiutate dalla convalida del server. Mantieni invariatithinking_levele gli strumenti integrati in tutti i segmenti di un loop di continuazione.
Risorse aggiuntive
Per saperne di più su Hydrogen, consulta le seguenti risorse: