Decodifica lunga

La decodifica lunga consente a Gemini 4 Argon di generare più di 64.000 token per le attività di ragionamento approfondito, fino alla finestra contestuale unificata di 1 milione di token (1.048.576 token condivisi tra input, ragionamento e output). Nell'API Interactions, puoi attivare la decodifica lunga con l'esecuzione in background in modo che i nostri server generino e combinino automaticamente ogni hop di 64.000 token in una singola interazione.

Come funziona la decodifica lunga

Una singola chiamata del modello genera fino a 64.000 token. Quando una risposta richiede più di 64.000 token, il server la genera in hop di 64.000 token che continuano dal punto in cui si è interrotto l'hop precedente. Ogni hop aggiunge un passaggio model_output a interaction.steps con lo stesso ID interazione, quindi unisci questi passaggi per leggere la risposta completa:

1. Crea un'interazione con background: true e max_output_tokens maggiore di 65.536, fino a 1 milione.
2. Il server genera il primo hop, fino a 64.000 token.
3. Il server avvia l'hop successivo dal punto in cui si è interrotto l'ultimo e ripete l'operazione finché il modello non termina o non utilizza tutti i max_output_tokens.
4. Esegui il polling dell'interazione o trasmettila in streaming per ottenere il risultato.

import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-argon",
    input="Write a complete, rigorous proof of the prime number theorem.",
    background=True,
    generation_config={
        "max_output_tokens": 262144,
        "thinking_level": "high",
    },
)

while interaction.status in ("in_progress", "queued"):
    time.sleep(5)
    interaction = client.interactions.get(id=interaction.id)

# Each hop adds a model_output step, so join the text of all of them.
text = "".join(
    content.text
    for step in interaction.steps
    if step.type == "model_output"
    for content in step.content
    if content.type == "text"
)
print(text)
print("Status:", interaction.status)
print("Usage:", interaction.usage)

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

const client = new GoogleGenAI({});

let interaction = await client.interactions.create({
  model: "gemini-4-argon",
  input: "Write a complete, rigorous proof of the prime number theorem.",
  background: true,
  generation_config: {
    max_output_tokens: 262144,
    thinking_level: "high",
  },
});

while (interaction.status === "in_progress" || interaction.status === "queued") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await client.interactions.get(interaction.id);
}

// Each hop adds a model_output step, so join the text of all of them.
const text = interaction.steps
  .filter((step) => step.type === "model_output")
  .flatMap((step) => step.content ?? [])
  .filter((content) => content.type === "text")
  .map((content) => content.text)
  .join("");
console.log(text);
console.log("Status:", interaction.status);
console.log("Usage:", interaction.usage);

# 1. Create the background interaction. It returns an ID right away.
ID=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-argon",
    "input": "Write a complete, rigorous proof of the prime number theorem.",
    "background": true,
    "generation_config": {"max_output_tokens": 262144, "thinking_level": "high"}
  }' | jq -r '.id')

# 2. Poll until the status is no longer in_progress or queued.
#    The REST response has no output_text field, so join the text of every model_output step.
while true; do
  RESP=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$ID" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
  STATUS=$(echo "$RESP" | jq -r '.status')
  if [[ "$STATUS" != "in_progress" && "$STATUS" != "queued" ]]; then
    echo "$RESP" | jq -r '[.steps[]? | select(.type == "model_output") | .content[]? | select(.type == "text") | .text] | join("")'
    echo "$RESP" | jq '{status, usage}'
    break
  fi
  sleep 5
done

Limiti di output

Le interazioni di streaming e non di streaming hanno un limite di token di output predefinito di 64.000, quindi le risposte fino a 64.000 token non richiedono modifiche al codice. Per generare più di 64.000 token, attiva l'esecuzione in background e aumenta max_output_tokens.

Quando utilizzare la decodifica lunga

La maggior parte delle richieste termina entro 64.000 token. Utilizza la decodifica lunga solo quando una risposta richiede più ragionamento e output.

L'impostazione di un valore elevato di max_output_tokens consente al modello di ragionare più a lungo su problemi difficili, ma il modello decide comunque quanto scrivere. Per controllare la quantità di ragionamento utilizzata dal modello, imposta thinking_level.

Scegliere come eseguire la decodifica lunga

L'esecuzione in background è il modo più semplice per eseguire la decodifica lunga nell'API Interactions. La continuazione lato client, in cui il codice avvia ogni hop, è disponibile con l'API GenerateContent. Sarà disponibile a breve nell'API Interactions come opzione più avanzata per gestire la resilienza.

Per utilizzare la continuazione lato client, consulta la sezione Decodifica lunga con l'API GenerateContent.

Trasmettere in streaming la decodifica lunga

Per trasmettere in streaming gli output e i riepiloghi del ragionamento man mano che arrivano, aggiungi stream: true e thinking_summaries: "auto". Gli stream lunghi possono essere interrotti, quindi il client deve riconnettersi. Segui il pattern di riconnessione nella guida all'esecuzione in background. La decodifica lunga aggiunge queste regole:

• Salva l'ID interazione: leggilo dall'evento interaction.created.
• Salva ogni event_id: un event_id può arrivare negli eventi interaction.status_update, non solo nei delta di testo.
• Riconnettiti con last_event_id: chiama interactions.get con stream: true e l'ultimo event_id. Lo stream continua dopo questo evento.
• Leggi fino alla fine: dopo la riconnessione, leggi lo stream fino alla fine prima di controllare lo stato. Il server riproduce gli eventi mancanti, anche dopo il completamento dell'interazione.
• Imposta timeout lunghi: imposta i timeout di lettura HTTP su 15-20 minuti per stream.
• Prevedi l'output in blocchi di 5000 token: dopo i primi 64.000 token (circa i primi 10 minuti), lo stream invia l'output in blocchi di circa 5000 token. Le pause tra i blocchi sono normali. L'interazione non è bloccata, quindi mantieni aperta la connessione.

Stato in background

Un'interazione in background può essere eseguita per un massimo di 24 ore. Quando lo stato non è più in_progress o queued, gestisci lo stato terminale utilizzando questa tabella:

Per interrompere un'interazione in esecuzione, chiama client.interactions.cancel(id=interaction.id) in Python, client.interactions.cancel(interaction.id) in JavaScript o POST /v1beta/interactions/{id}/cancel in REST.

Impostare max_output_tokens

max_output_tokens imposta il limite combinato per il ragionamento e l'output nell'interazione. La riduzione non rende il modello più conciso, ma tronca la risposta prima.

Per utilizzare meno token, riduci thinking_level. Utilizza high per le attività di ragionamento più difficili. Utilizza medium (valore predefinito) per la maggior parte del lavoro di programmazione e agentico.

Contare i token

interaction.usage riporta i totali di tutti gli hop. Leggi questi campi: total_input_tokens, total_cached_tokens, total_output_tokens, total_thought_tokens e total_tokens.

total_input_tokens somma i token di input di ogni hop. Ogni hop invia il prompt e tutto ciò che è stato generato finora al modello come input, quindi gli stessi token vengono conteggiati di nuovo in ogni hop successivo. Ad esempio, un prompt di 1000 token che produce 200.000 token di ragionamento e output richiede quattro hop:

total_input_tokens riporta circa 397.000 token (con gli input hop ripetuti scontati automaticamente del 95% dalla memorizzazione nella cache implicita), anche se la dimensione effettiva del contesto è di circa 201.000 token: il prompt di 1000 token più 200.000 token di ragionamento e output.

Durante uno stream, gli eventi step.stop e interaction.status_update includono usage (cumulativo per l'interazione). Leggi l'ultimo valore di usage anziché sommarli.

Informazioni sulla fatturazione

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

• Sconto cache: la memorizzazione nella cache implicita sconta l'input ripetuto in ogni hop del 95%. L'input memorizzato nella cache costa 0,10 $per 1 milione di token anziché 2,00 $durante il periodo introduttivo.
• Interazioni annullate e non riuscite: paghi per tutto il lavoro completato prima della fine dell'interazione.

Risoluzione dei problemi

Limitazioni

• Nessuna decodifica lunga senza esecuzione in background: le interazioni con background: false si interrompono a 65.536 token. Il supporto sarà disponibile a breve.
• Nessun target di lunghezza: il modello non segue i target di lunghezza dei token o di conteggio delle parole.

Passaggi successivi

• Novità di Gemini 4 Argon
• Esecuzione in background
• Ragionamento
• Decodifica lunga con l'API GenerateContent