Decodifica lunga

La decodifica lunga consente a Gemini 4 Argon di generare oltre il limite di output di una singola richiesta per le attività di ragionamento profondo, fino alla finestra contestuale unificata da 1 milione di token (1.048.576 token condivisi tra input, pensiero e output).

La modifica del solo ID modello non attiva la decodifica lunga. Senza una configurazione aggiuntiva, l'output si interrompe a 64.000 token per le chiamate in streaming e a 32.000 token per le chiamate non in streaming. Il modo più rapido per attivare la decodifica lunga è eseguire l'upgrade dell'SDK Google GenAI e impostare max_output_tokens su un valore superiore a 65.536. Questa guida spiega come funziona la decodifica di lunga durata, quando utilizzarla e come attivarla con generateContent.

Come funziona la decodifica lunga

Una singola richiesta di streaming o SDK genera fino a 64.000 token, mentre una richiesta REST non di streaming genera fino a 32.000 token. Quando una risposta richiede più token, il modello la genera in più hop di richiesta e risposta, ognuno dei quali continua da dove si è interrotto l'hop precedente.

• Limite di token di input e output unificato: input, ragionamento, chiamate di funzione e risposta finale condividono una finestra di 1 milione di token. L'output può utilizzare fino a 1.048.576 token meno i token di input.
• Un limite per ogni hop:un hop restituisce fino a 65.536 token di output. Le richieste REST non in streaming restituiscono fino a 32.768 token.
• Un segnale di continuazione:se il modello raggiunge il limite e ha ancora token, la risposta termina con finish_reason: CONTINUATION e continuation_token.
• L'hop successivo: il client invia nuovamente la stessa richiesta con il token. Il modello continua dal punto in cui si era interrotto.
• Un totale per tutti gli hop:max_output_tokens imposta i token di ragionamento e di output totali per tutti gli hop insieme.
• Un segnale di interruzione:quando il modello utilizza tutti i token max_output_tokens, la risposta termina con finish_reason: MAX_TOKENS.

Per i problemi difficili, un hop può utilizzare tutti i suoi token per il ragionamento interno e restituire un testo vuoto con un continuation_token. Questo è normale e la risposta finale arriva negli hop successivi.

Limiti di output predefiniti

Senza la decodifica lunga, una singola richiesta si arresta a questi limiti per richiesta:

• Richieste di streaming e non di streaming tramite l'SDK Google GenAI (generate_content): il valore predefinito è 64.000 token di output.
• Chiamate REST dirette non in streaming (generateContent): il valore predefinito è 32.000 token di output. Se imposti max_output_tokens su un valore superiore a 32.768 in una chiamata REST non in streaming senza continuation_token,viene restituito un errore 400.

Quando utilizzare la decodifica lunga

La maggior parte delle richieste viene completata entro il limite per singola richiesta (64.000 token per le chiamate SDK e di streaming o 32.000 token per le chiamate REST non di streaming). Utilizza la decodifica lunga quando una risposta richiede più token di pensiero e output combinati di quanto consenta una singola richiesta. Aumentando max_output_tokens, il modello ha un limite più alto per ragionare su problemi difficili, anziché allungare le risposte standard.

L'impostazione di un valore elevato per max_output_tokens consente al modello di riflettere più a lungo sui problemi difficili, ma il modello decide comunque quanto scrivere. Per controllare l'impegno di ragionamento utilizzato dal modello, imposta thinking_level.

Attiva la decodifica lunga

Puoi eseguire la decodifica lunga automaticamente con l'SDK Google GenAI (opzione 1, consigliata per la maggior parte delle app) o scrivere il tuo loop di continuazione (opzione 2). Entrambe le opzioni supportano la finestra contestuale da 1 milione di token.

Il continuation_token criptato trasporta lo stato del modello tra le richieste, quindi non viene memorizzato nulla sul server.

Opzione 1: utilizza l'SDK Google GenAI (consigliato)

Nell'ultimo SDK Google GenAI, automatic_continuation è abilitato per impostazione predefinita sia per le chiamate di streaming sia per quelle non di streaming, quindi non devi impostarlo. Quando imposti max_output_tokens su un valore superiore al limite per richiesta, l'SDK esegue automaticamente i passaggi di continuazione e restituisce una risposta combinata.

1. Esegui l'upgrade dell'SDK.

   Python

   pip install -U "google-genai>=2.30.1"
   

   JavaScript

   npm install "@google/genai@>=2.29.1"
   

2. Imposta max_output_tokens su un valore maggiore di 65.536.

   Python

   from google import genai
   from google.genai import types
   
   client = genai.Client()  # Reads GEMINI_API_KEY
   
   response = client.models.generate_content(
       model="gemini-4-argon",
       contents="Write a complete, rigorous proof of the prime number theorem.",
       config=types.GenerateContentConfig(
           max_output_tokens=262_144,  # Total thinking and output for all hops
           thinking_config=types.ThinkingConfig(thinking_level="high"),
           automatic_continuation=True,  # Default. Shown for clarity.
       ),
   )
   
   print(response.text)
   print("Finish reason:", response.candidates[0].finish_reason)
   print("Prompt size:", response.usage_metadata.initial_prompt_token_count)
   print("Billed tokens:", response.usage_metadata.total_token_count)
   

   JavaScript

   import { GoogleGenAI, ThinkingLevel } from "@google/genai";
   
   const ai = new GoogleGenAI({}); // Reads GEMINI_API_KEY
   
   const response = await ai.models.generateContent({
     model: "gemini-4-argon",
     contents: "Write a complete, rigorous proof of the prime number theorem.",
     config: {
       maxOutputTokens: 262144, // Total thinking and output for all hops
       thinkingConfig: { thinkingLevel: ThinkingLevel.HIGH },
       automaticContinuation: true, // Default. Shown for clarity.
     },
   });
   
   console.log(response.text);
   console.log("Finish reason:", response.candidates?.[0]?.finishReason);
   console.log("Prompt size:", response.usageMetadata?.initialPromptTokenCount);
   console.log("Billed tokens:", response.usageMetadata?.totalTokenCount);
   

Tieni presenti questi punti:

• Streaming:generate_content_stream (Python) e generateContentStream (JavaScript) continuano a funzionare. Se uno stream viene interrotto dopo un checkpoint, l'SDK riprende da quel checkpoint.
• Timeout: i timeout e i nuovi tentativi si applicano a ogni hop, non all'intera esecuzione.
• Controllo manuale:per eseguire il ciclo autonomamente, imposta automatic_continuation=False (Python) o automaticContinuation: false (JavaScript). Quindi, segui l'opzione 2.
• Utilizzo: i campi di utilizzo mostrano la somma di tutti gli hop. Per conoscere le dimensioni del prompt, leggi initial_prompt_token_count. Consulta Conta i token.

Opzione 2: scrivi il tuo loop

Scrivi il tuo loop se chiami direttamente REST, utilizzi un linguaggio senza l'SDK più recente o hai bisogno di un controllo completo. Puoi anche consultare le nostre implementazioni dell'SDK Google GenAI in Python e JavaScript/TypeScript come riferimento.

Segui queste regole:

1. Invia la stessa richiesta a ogni hop. Invia l'contents, l'system_instruction, l'tools e l'generation_config originali. Mantieni invariato max_output_tokens.
2. Non aggiungere output parziale a contents. Il continuation_token contiene lo stato del modello, incluso il suo ragionamento.
3. Invia solo l'ultimo token. Ogni token contiene tutti i progressi precedenti.
4. Continua mentre finish_reason è CONTINUATION. Interrompi per qualsiasi altro motivo di interruzione.
5. Unisci le parti dopo l'ultimo hop. Combina le parti di tutti i passaggi in un unico turno del modello per la cronologia delle conversazioni.

from google import genai
from google.genai import types

client = genai.Client()  # Reads GEMINI_API_KEY
PROMPT = "Write a complete, rigorous proof of the prime number theorem."
parts = []
token = None

while True:
    response = client.models.generate_content(
        model="gemini-4-argon",
        contents=PROMPT,  # The original contents on every request
        config=types.GenerateContentConfig(
            max_output_tokens=262_144,  # The same total on every request
            thinking_config=types.ThinkingConfig(thinking_level="high"),
            automatic_continuation=False,  # You run the loop
            continuation_token=token,
        ),
    )
    candidate = response.candidates[0]
    if candidate.content and candidate.content.parts:
        parts.extend(candidate.content.parts)
    token = candidate.continuation_token
    if candidate.finish_reason != types.FinishReason.CONTINUATION or not token:
        break

print("".join(p.text for p in parts if p.text and not p.thought))
print("Finish reason:", candidate.finish_reason)

import { GoogleGenAI, ThinkingLevel } from "@google/genai";

const ai = new GoogleGenAI({}); // Reads GEMINI_API_KEY
const PROMPT = "Write a complete, rigorous proof of the prime number theorem.";
const parts = [];
let token = undefined;
let candidate = undefined;

while (true) {
  const response = await ai.models.generateContent({
    model: "gemini-4-argon",
    contents: PROMPT, // The original contents on every request
    config: {
      maxOutputTokens: 262144, // The same total on every request
      thinkingConfig: { thinkingLevel: ThinkingLevel.HIGH },
      automaticContinuation: false, // You run the loop
      continuationToken: token,
    },
  });
  candidate = response.candidates?.[0];
  if (candidate?.content?.parts) {
    parts.push(...candidate.content.parts);
  }
  token = candidate?.continuationToken;
  if (candidate?.finishReason !== "CONTINUATION" || !token) {
    break;
  }
}

console.log(parts.filter((p) => p.text && !p.thought).map((p) => p.text).join(""));
console.log("Finish reason:", candidate?.finishReason);

# Hop 1: send the request with max_output_tokens.
curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-argon:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "Write a complete, rigorous proof of the prime number theorem."}]}],
    "generationConfig": {
      "maxOutputTokens": 262144,
      "thinkingConfig": {"thinkingLevel": "high"}
    }
  }'

# Hop 2: if finishReason is CONTINUATION, send the same request plus the token.
curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-argon:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "Write a complete, rigorous proof of the prime number theorem."}]}],
    "generationConfig": {
      "maxOutputTokens": 262144,
      "thinkingConfig": {"thinkingLevel": "high"}
    },
    "continuationToken": "TOKEN_FROM_HOP_1"
  }'

Un hop dedicato interamente al pensiero restituisce text vuoto con finishReason: "CONTINUATION". Considera questo come un normale avanzamento e richiedi l'hop successivo:

{
  "candidates": [{
    "content": {"role": "model", "parts": [{"text": ""}]},
    "finishReason": "CONTINUATION",
    "continuationToken": "CiQ4ZmQ3..."
  }],
  "usageMetadata": {
    "promptTokenCount": 142,
    "candidatesTokenCount": 0,
    "thoughtsTokenCount": 32768,
    "totalTokenCount": 32910
  }
}

I loop di streaming richiedono un'altra regola. Dopo i primi 32.768 token, lo stream invia un token di checkpoint ogni 5000 token. Mantieni i nuovi segmenti in un elenco in attesa. Quando un chunk ha un continuation_token, sposta i chunk in attesa nell'output di cui è stato eseguito il commit e salva il token. Se lo stream viene interrotto, scarta i chunk in attesa e riprendi dall'ultimo token. Se lo stream viene interrotto prima del primo checkpoint, invia di nuovo la richiesta originale.

Imposta max_output_tokens

max_output_tokens imposta il limite combinato per il ragionamento e l'output in tutti gli hop. Se lo abbassi, il modello non pensa in modo più conciso, ma interrompe la risposta prima.

Per utilizzare meno token, riduci thinking_level. Utilizza high per le attività di ragionamento più difficili. Utilizza medium (l'impostazione predefinita) per la maggior parte delle attività di programmazione e agentiche. Utilizza low per le attività meno complesse.

Gestisci le richieste a lunga esecuzione

Poiché Gemini 4 Argon ragiona più a lungo rispetto ai modelli Gemini 3.x su problemi difficili, devi aumentare i timeout del client in modo che le richieste lunghe non si disconnettano in anticipo.

• Chiamate non in streaming:il server chiude la connessione dopo 10 minuti.
• Chiamate in streaming:il server chiude lo stream dopo 20 minuti.
• Timeout client:imposta il timeout di lettura HTTP su 20 minuti. Un timeout di 3 o 5 minuti interrompe la richiesta in anticipo.

In Python, imposta il timeout sul client in millisecondi:

client = genai.Client(http_options=types.HttpOptions(timeout=1_200_000))  # 20 minutes

Per i job di cui il client esegue il polling, l'API Interactions esegue la decodifica lunga sul server. Consulta la sezione Esecuzione in background.

Riprendi quando il modello utilizza tutti i token di output

Quando una risposta termina con MAX_TOKENS, include comunque un continuation_token. Hai due opzioni:

• Continua:invia la stessa richiesta con il token e un max_output_tokens più elevato. Il valore deve essere superiore ai token utilizzati finora. In caso contrario, l'API restituisce un errore 400.
• Ricomincia:invia la richiesta originale con un valore max_output_tokens più alto e senza token. Paghi per entrambe le corse.

Contare i token

Con la continuazione automatica, usage_metadata segnala i totali di tutti gli hop. L'SDK somma tutti i campi di conteggio: prompt_token_count, cached_content_token_count, candidates_token_count, thoughts_token_count e total_token_count.

prompt_token_count somma i token di input di ogni hop. Ogni hop invia il prompt e tutto ciò che è stato generato fino a quel momento al modello come input, quindi gli stessi token vengono conteggiati di nuovo in ogni hop successivo. Ad esempio, con l'SDK Google GenAI, un prompt di 1000 token che produce 200.000 token di ragionamento e output richiede quattro hop:

prompt_token_count riporta circa 397.000 token (con gli input dei passaggi ripetuti scontati automaticamente del 95% dalla memorizzazione nella cache implicita) e total_token_count riporta circa 597.000 token, anche se la dimensione effettiva del contesto è di soli 201.000 token circa: il prompt da 1000 token più 200.000 token di ragionamento e output. Un ciclo REST non in streaming utilizza 32.000 hop, quindi sono necessari sette hop per lo stesso output e vengono segnalati 695.128 token di input.

prompt_token_count e total_token_count sono la somma di ogni hop, non le dimensioni del contesto. Non utilizzarli per decidere quando riassumere o tagliare la cronologia delle conversazioni (compattazione del contesto) o per imporre un limite al contesto. Per stimare le dimensioni del contesto, aggiungi le dimensioni del prompt dalla tabella a candidates_token_count e thoughts_token_count.

Aggiorna il framework dell'agente, lo strumento di valutazione o il proxy prima di eseguire la decodifica lunga:

• Agenti e strumenti di valutazione:se il codice comprime il contesto o interrompe un'esecuzione al raggiungimento di un limite di token, utilizza initial_prompt_token_count (o prompt_token_count del primo hop in REST) anziché prompt_token_count sommato. Le risposte che terminano in un hop riportano lo stesso valore in entrambi i campi, quindi i test brevi non mostrano il problema.
• Proxy e gateway che chiamano REST: ogni risposta REST segnala solo il proprio hop. Somma ogni campo nei vari hop per il costo e mantieni le dimensioni del prompt del primo hop promptTokenCount come dimensioni del prompt. In caso contrario, i tuoi utenti vedranno numeri diversi da quelli visualizzati dagli utenti dell'SDK per la stessa richiesta.
• Log e risposte serializzate:l'SDK calcola initial_prompt_token_count sul client. Non è presente nella risposta REST o nell'output JSON dell'SDK, ad esempio model_dump(). Salvalo come valore separato se ne hai bisogno in un secondo momento.

Se riproduci in streaming il tuo loop, usage_metadata è cumulativo all'interno di ogni stream. Mantieni solo l'ultimo valore di ogni stream, quindi somma i valori tra gli hop.

Informazioni sulla fatturazione

Paghi per ogni token in ogni hop, inclusi gli hop che contengono solo ragionamento.

• Sconto per la memorizzazione nella cache:la memorizzazione nella cache implicita sconta del 95% l'input ripetuto in ogni hop. Durante il periodo di lancio, l'input memorizzato nella cache costa 0,10 $per 1 milione di token anziché 2 $.
• Scadenza della cache:la cache scade dopo 15-20 minuti di inutilizzo. Una pausa prolungata tra i salti comporta nuovamente l'addebito della velocità di input completa.
• Hop non in streaming non riusciti:paghi solo quando una risposta viene completata. Una richiesta non riuscita o interrotta costa 0 $.
• Stream interrotti:uno stream che si interrompe prima di 32.000 token costa 0 $. Dopodiché, paghi fino all'ultimo token del checkpoint, perché puoi riprendere da lì.

Risoluzione dei problemi

Limitazioni

• Endpoint di compatibilità con OpenAI:la decodifica lunga non è disponibile. L'output si interrompe al raggiungimento del limite per richiesta.
• SDK precedenti:le versioni precedenti ai minimi indicati nella nota non vengono aggiornate automaticamente.
• Lunghezza:il modello non segue i target di lunghezza dei token o di conteggio delle parole.

Elenco di controllo

• Esegui l'upgrade dell'SDK Google GenAI alla versione minima.
• Imposta max_output_tokens su un valore maggiore di 65.536.
• Utilizza thinking_level (low, medium o high), non thinking_budget.
• Imposta i timeout di lettura HTTP su 20 minuti.
• Utilizza initial_prompt_token_count per la dimensione e la compressione del contesto.
• Esegui un prompt come test prima di una valutazione su larga scala.

Passaggi successivi

• Novità di Gemini 4 Argon
• Thinking
• Conteggio dei token