Decodificación larga

La decodificación larga permite que Gemini 4 Argon genere más de 64, 000 tokens para tareas de razonamiento profundo,hasta la ventana de contexto unificada de 1 millón de tokens (1,048, 576 tokens compartidos entre la entrada, el pensamiento y la salida). En la API de Interactions, habilitas la decodificación larga con la ejecución en segundo plano para que nuestros servidores generen y combinen automáticamente cada salto de 64,000 tokens en una sola interacción.

Cómo funciona la decodificación larga

Una sola llamada al modelo genera hasta 64,000 tokens. Cuando una respuesta necesita más de 64,000 tokens, el servidor la genera en saltos de 64,000 tokens que continúan desde donde se detuvo el salto anterior. Cada salto agrega un paso model_output a interaction.steps con el mismo ID de interacción, por lo que debes unir esos pasos para leer la respuesta completa:

1. Crea una interacción con background: true y max_output_tokens superior a 65,536, hasta 1 millón.
2. El servidor genera el primer salto, hasta 64,000 tokens.
3. El servidor inicia el próximo salto desde donde se detuvo el último y se repite hasta que el modelo finaliza o usa todos los max_output_tokens.
4. Sondea la interacción o transmítela para obtener el resultado.

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

Límites de salida

Las interacciones de transmisión y sin transmisión tienen un límite predeterminado de tokens de salida de 64,000, por lo que las respuestas de hasta 64,000 tokens no necesitan cambios de código. Para generar más de 64,000 tokens, activa la ejecución en segundo plano y aumenta max_output_tokens.

Cuándo usar la decodificación larga

La mayoría de las solicitudes finalizan en 64,000 tokens. Usa la decodificación larga solo cuando una respuesta necesite más pensamiento y salida que eso.

Establecer un max_output_tokens alto le da al modelo espacio para pensar más tiempo en problemas difíciles, pero el modelo aún decide cuánto escribir. Para controlar cuánto esfuerzo de razonamiento usa el modelo, establece thinking_level.

Elige cómo ejecutar la decodificación larga

La ejecución en segundo plano es la forma más sencilla de ejecutar la decodificación larga en la API de Interactions. La continuación del cliente, en la que tu código inicia cada salto, está disponible con la API de GenerateContent. Próximamente estará disponible en la API de Interactions como una opción más avanzada para administrar tu propia resiliencia.

Para usar la continuación del cliente, consulta la decodificación larga con la API de GenerateContent.

Transmite la decodificación larga

Para transmitir los resultados y los resúmenes de pensamiento a medida que llegan, agrega stream: true y thinking_summaries: "auto". Las transmisiones largas pueden descartarse, por lo que tu cliente debe volver a conectarse. Sigue el patrón de reconexión en la guía de ejecución en segundo plano. La decodificación larga agrega estas reglas:

• Guarda el ID de interacción: Léelo desde el evento interaction.created.
• Guarda cada event_id: Un event_id puede llegar a los eventos interaction.status_update, no solo a los deltas de texto.
• Vuelve a conectarte con last_event_id: Llama a interactions.get con stream: true y el último event_id. La transmisión continúa después de ese evento.
• Lee hasta el final: Después de volver a conectarte, lee la transmisión hasta el final antes de verificar el estado. El servidor reproduce los eventos perdidos, incluso después de que se completa la interacción.
• Establece tiempos de espera largos: Establece tiempos de espera de lectura de HTTP de 15 a 20 minutos por transmisión.
• Espera resultados en fragmentos de 5,000 tokens: Después de los primeros 64,000 tokens (aproximadamente los primeros 10 minutos), la transmisión envía resultados en fragmentos de aproximadamente 5,000 tokens. Las pausas entre fragmentos son normales. La interacción no está atascada, por lo que debes mantener la conexión abierta.

Estado en segundo plano

Una interacción en segundo plano puede ejecutarse hasta por 24 horas. Una vez que el estado ya no sea in_progress o queued, controla el estado de la terminal con esta tabla:

Para detener una interacción en ejecución, llama a client.interactions.cancel(id=interaction.id) en Python, client.interactions.cancel(interaction.id) en JavaScript o POST /v1beta/interactions/{id}/cancel en REST.

Establece max_output_tokens

max_output_tokens establece el límite combinado para el pensamiento y la salida en toda la interacción. Si lo reduces, el modelo no pensará de forma más concisa, sino que cortará la respuesta antes.

Para usar menos tokens, disminuye thinking_level. Usa high para las tareas de razonamiento más difíciles. Usa medium (el valor predeterminado) para la mayoría de las tareas de programación y con agentes.

Cuenta tokens

interaction.usage informa los totales en todos los saltos. Lee estos campos: total_input_tokens, total_cached_tokens, total_output_tokens, total_thought_tokens y total_tokens.

total_input_tokens suma los tokens de entrada de cada salto. Cada salto envía tu instrucción más todo lo generado hasta el momento al modelo como entrada, por lo que los mismos tokens se vuelven a contar en cada salto posterior. Por ejemplo, una instrucción de 1,000 tokens que produce 200,000 tokens de pensamiento y salida requiere cuatro saltos:

total_input_tokens informa aproximadamente 397,000 tokens (con entradas de salto repetidas con un descuento automatizado del 95% por el almacenamiento en caché implícito), aunque el tamaño real del contexto es de solo 201,000 tokens: la instrucción de 1,000 tokens más 200,000 tokens de razonamiento y resultado.

Durante una transmisión, los eventos step.stop y interaction.status_update incluyen usage (acumulativo para la interacción). Lee el valor usage más reciente en lugar de sumarlos.

Comprender la facturación

Pagas por cada token en cada salto, incluidos los saltos que solo contienen pensamiento.

• Descuento de caché: El almacenamiento en caché implícito descuenta la entrada repetida en cada salto en un 95%. La entrada almacenada en caché cuesta USD 0.10 por cada millón de tokens en lugar de USD 2.00 durante el período introductorio.
• Interacciones canceladas y fallidas: Pagas por todo el trabajo completado antes de que finalice la interacción.

Solución de problemas

Limitaciones

• No hay decodificación larga sin ejecución en segundo plano: Las interacciones con background: false se detienen en 65,536 tokens. La asistencia estará disponible próximamente.
• No hay objetivos de longitud: El modelo no sigue los objetivos de longitud de tokens ni de recuento de palabras.

Próximos pasos

• Novedades de Gemini 4 Argon
• Ejecución en segundo plano
• Pensamiento
• Decodificación larga con la API de GenerateContent