Décodage long

Le décodage long permet à Gemini 4 Argon de générer plus de 64 000 jetons pour les tâches de raisonnement approfondi, jusqu'à la fenêtre de contexte unifiée d'un million de jetons (1 048 576 jetons partagés entre l'entrée, le raisonnement et la sortie). Dans l'API Interactions, vous activez le décodage long avec l'exécution en arrière-plan afin que nos serveurs génèrent et combinent automatiquement chaque saut de 64 000 jetons en une seule interaction.

Fonctionnement du décodage long

Un seul appel de modèle génère jusqu'à 64 000 jetons. Lorsqu'une réponse nécessite plus de 64 000 jetons, le serveur la génère par sauts de 64 000 jetons qui reprennent là où le saut précédent s'est arrêté. Chaque saut ajoute une étape model_output à interaction.steps sous le même ID d'interaction. Vous devez donc joindre ces étapes pour lire la réponse complète :

1. Vous créez une interaction avec background: true et max_output_tokens supérieur à 65 536, jusqu'à 1 million.
2. Le serveur génère le premier saut, jusqu'à 64 000 jetons.
3. Le serveur démarre le saut suivant là où le précédent s'est arrêté et répète l'opération jusqu'à ce que le modèle se termine ou utilise tous les max_output_tokens.
4. Vous interrogez l'interaction ou la diffusez en flux continu pour obtenir le résultat.

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

Limites de sortie

Les interactions en flux continu et hors flux continu sont limitées par défaut à 64 000 jetons de sortie. Les réponses contenant jusqu'à 64 000 jetons ne nécessitent donc aucune modification du code. Pour générer plus de 64 000 jetons, activez l'exécution en arrière-plan et augmentez max_output_tokens.

Quand utiliser le décodage long

La plupart des requêtes se terminent avec moins de 64 000 jetons. N'utilisez le décodage long que lorsqu'une réponse nécessite plus de réflexion et de sortie.

Définir un max_output_tokens élevé permet au modèle de réfléchir plus longtemps aux problèmes difficiles, mais il décide toujours de la quantité à écrire. Pour contrôler l'effort de raisonnement utilisé par le modèle, définissez thinking_level.

Choisir comment exécuter le décodage long

L'exécution en arrière-plan est le moyen le plus simple d'exécuter le décodage long sur l'API Interactions. La continuation côté client, où votre code démarre chaque saut, est disponible avec l'API GenerateContent. Elle sera bientôt disponible dans l'API Interactions en tant qu'option plus avancée pour gérer votre propre résilience.

Pour utiliser la continuation côté client, consultez la section Décodage long avec l'API GenerateContent.

Diffuser le décodage long en flux continu

Pour diffuser les sorties et les résumés de réflexion à mesure qu'ils arrivent, ajoutez stream: true et thinking_summaries: "auto". Les flux longs peuvent être interrompus. Votre client doit donc se reconnecter. Suivez le modèle de reconnexion dans le guide d'exécution en arrière-plan. Le décodage long ajoute les règles suivantes :

• Enregistrez l'ID d'interaction : lisez-le à partir de l'événement interaction.created.
• Enregistrez chaque event_id : un event_id peut arriver sur les événements interaction.status_update, et pas seulement sur les deltas de texte.
• Reconnectez-vous avec last_event_id: appelez interactions.get avec stream: true et le dernier event_id. Le flux se poursuit après cet événement.
• Lisez jusqu'à la fin : une fois que vous êtes reconnecté, lisez le flux jusqu'à la fin avant de vérifier l'état. Le serveur relit les événements manqués, même une fois l'interaction terminée.
• Définissez des délais d'expiration longs : définissez des délais d'expiration de lecture HTTP de 15 à 20 minutes par flux.
• Attendez-vous à une sortie par blocs de 5 000 jetons : après les 64 000 premiers jetons (environ les 10 premières minutes), le flux envoie la sortie par blocs d'environ 5 000 jetons. Les pauses entre les blocs sont normales. L'interaction n'est pas bloquée. Laissez donc la connexion ouverte.

État en arrière-plan

Une interaction en arrière-plan peut s'exécuter pendant 24 heures maximum. Une fois que l'état n'est plus in_progress ou queued, gérez l'état final à l'aide de ce tableau :

Pour arrêter une interaction en cours d'exécution, appelez client.interactions.cancel(id=interaction.id) en Python, client.interactions.cancel(interaction.id) en JavaScript ou POST /v1beta/interactions/{id}/cancel dans REST.

Définir max_output_tokens

max_output_tokens définit la limite combinée pour la réflexion et la sortie de l'interaction. La réduire ne rend pas la réflexion du modèle plus concise, mais coupe la réponse plus tôt.

Pour utiliser moins de jetons, réduisez thinking_level. Utilisez high pour les tâches de raisonnement les plus difficiles. Utilisez medium (valeur par défaut) pour la plupart des tâches de codage et agentiques.

Compter les jetons

interaction.usage indique les totaux pour tous les sauts. Lisez les champs suivants : total_input_tokens, total_cached_tokens, total_output_tokens, total_thought_tokens et total_tokens.

total_input_tokens additionne les jetons d'entrée de chaque saut. Chaque saut renvoie votre prompt et tout ce qui a été généré jusqu'à présent au modèle en tant qu'entrée. Les mêmes jetons sont donc comptés à nouveau dans chaque saut ultérieur. Par exemple, un prompt de 1 000 jetons qui produit 200 000 jetons de réflexion et de sortie nécessite quatre sauts :

total_input_tokens indique environ 397 000 jetons (avec les entrées de saut répétées automatiquement réduites de 95% par la mise en cache implicite), même si la taille réelle du contexte n'est que d'environ 201 000 jetons : le prompt de 1 000 jetons plus 200 000 jetons de réflexion et de sortie.

Lors d'un flux continu, les événements step.stop et interaction.status_update incluent usage (cumulatif pour l'interaction). Lisez la dernière valeur usage au lieu de les additionner.

Comprendre la facturation

Vous payez pour chaque jeton de chaque saut, y compris les sauts qui ne contiennent que de la réflexion.

• Remise sur le cache : la mise en cache implicite réduit l'entrée répétée de chaque saut de 95%. L'entrée mise en cache coûte 0,10 $ par million de jetons au lieu de 2,00 $ pendant la période d'introduction.
• Interactions annulées et ayant échoué : vous payez pour tout le travail effectué avant la fin de l'interaction.

Dépannage

Limites

• Pas de décodage long sans exécution en arrière-plan : les interactions avec background: false s'arrêtent à 65 536 jetons. La compatibilité sera bientôt disponible.
• Pas d'objectifs de longueur : le modèle ne respecte pas les objectifs de longueur de jeton ni de nombre de mots.

Étapes suivantes

• Nouveautés de Gemini 4 Argon
• Exécution en arrière-plan
• Raisonnement
• Décodage long avec l'API GenerateContent