Decodificação longa

A decodificação longa permite que o Gemini 4 Argon gere mais de 64 mil tokens para tarefas de raciocínio complexas, até a janela de contexto unificada de 1 milhão de tokens (1.048.576 tokens compartilhados entre entrada, raciocínio e saída). Na API Interactions, você ativa a decodificação longa com execução em segundo plano para que nossos servidores gerem e combinem automaticamente cada salto de 64 mil tokens em uma única interação.

Como a decodificação longa funciona

Uma única chamada de modelo gera até 64 mil tokens. Quando uma resposta precisa de mais de 64 mil tokens, o servidor a gera em saltos de 64 mil tokens que continuam de onde o salto anterior parou. Cada salto adiciona uma etapa model_output a interaction.steps no mesmo ID de interação. Assim, você une essas etapas para ler a resposta completa:

1. Crie uma interação com background: true e max_output_tokens acima de 65.536, até 1 milhão.
2. O servidor gera o primeiro salto, até 64 mil tokens.
3. O servidor inicia o próximo salto de onde o último parou e repete até que o modelo termine ou use todos os max_output_tokens.
4. Você pesquisa a interação ou faz streaming dela para receber o 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

Limites de saída

As interações de streaming e não streaming têm um limite padrão de 64 mil tokens de saída. Portanto, as respostas de até 64 mil tokens não precisam de mudanças no código. Para gerar mais de 64 mil tokens, ative a execução em segundo plano e aumente max_output_tokens.

Quando usar a decodificação longa

A maioria das solicitações termina em até 64 mil tokens. Use a decodificação longa apenas quando uma resposta precisar de mais raciocínio e saída do que isso.

Definir um max_output_tokens alto dá ao modelo espaço para pensar mais em problemas difíceis, mas o modelo ainda decide quanto escrever. Para controlar o esforço de raciocínio usado pelo modelo, defina thinking_level.

Escolher como executar a decodificação longa

A execução em segundo plano é a maneira mais fácil de executar a decodificação longa na API Interactions. A continuação do lado do cliente, em que o código inicia cada salto, está disponível na API GenerateContent. Ela será lançada em breve na API Interactions como uma opção mais avançada para gerenciar sua própria resiliência.

Para usar a continuação do lado do cliente, consulte Decodificação longa com a API GenerateContent.

Fazer streaming de decodificação longa

Para fazer streaming de saídas e resumos de pensamento à medida que chegam, adicione stream: true e thinking_summaries: "auto". Streams longos podem cair, então o cliente precisa se reconectar. Siga o padrão de reconexão no guia de execução em segundo plano. A decodificação longa adiciona estas regras:

• Salve o ID da interação:leia-o no evento interaction.created.
• Salve cada event_id: Um event_id pode chegar em eventos interaction.status_update, não apenas em deltas de texto.
• Reconecte-se com last_event_id: chame interactions.get com stream: true e o último event_id. O stream continua após esse evento.
• Leia até o final:depois de se reconectar, leia o stream até o final antes de verificar o status. O servidor reproduz eventos perdidos, mesmo após a conclusão da interação.
• Defina tempos limite longos:defina tempos limite de leitura HTTP de 15 a 20 minutos por stream.
• Espere a saída em blocos de 5 mil tokens:após os primeiros 64 mil tokens (cerca de 10 minutos), o stream envia a saída em blocos de cerca de 5 mil tokens. As pausas entre os blocos são normais. A interação não está travada, então mantenha a conexão aberta.

Status em segundo plano

Uma interação em segundo plano pode ser executada por até 24 horas. Quando o status não for mais in_progress ou queued, processe o estado terminal usando esta tabela:

Para interromper uma interação em execução, chame client.interactions.cancel(id=interaction.id) em Python, client.interactions.cancel(interaction.id) em JavaScript ou POST /v1beta/interactions/{id}/cancel em REST.

Definir max_output_tokens

max_output_tokens define o limite combinado para raciocínio e saída em toda a interação. Diminuir esse valor não faz com que o modelo pense de forma mais concisa, mas corta a resposta mais cedo.

Para usar menos tokens, diminua thinking_level. Use high para as tarefas de raciocínio mais difíceis. Use medium (o padrão) para a maioria dos trabalhos de programação e agênticos.

Contar tokens

interaction.usage informa os totais de todos os saltos. Leia estes campos: total_input_tokens, total_cached_tokens, total_output_tokens, total_thought_tokens e total_tokens.

total_input_tokens soma os tokens de entrada de cada salto. Cada salto envia o comando e tudo o que foi gerado até o momento de volta ao modelo como entrada. Assim, os mesmos tokens são contados novamente em cada salto posterior. Por exemplo, um comando de 1.000 tokens que produz 200 mil tokens de raciocínio e saída leva quatro saltos:

total_input_tokens informa cerca de 397 mil tokens (com entradas de salto repetidas automaticamente descontadas em 95% pelo armazenamento em cache implícito), embora o tamanho real do contexto seja de apenas cerca de 201 mil tokens: o comando de 1.000 tokens mais 200 mil tokens de raciocínio e saída.

Durante um stream, os eventos step.stop e interaction.status_update incluem usage (cumulativo para a interação). Leia o valor usage mais recente em vez de adicioná-los.

Noções básicas sobre o faturamento

Você paga por cada token em cada salto, incluindo aqueles que contêm apenas raciocínio.

• Desconto de cache:o armazenamento em cache implícito desconta a entrada repetida em cada salto em 95%. A entrada armazenada em cache custa US $0,10 por 1 milhão de tokens em vez de US $2,00 durante o período introdutório.
• Interações canceladas e com falha:você paga por todo o trabalho concluído antes do término da interação.

Solução de problemas

Limitações

• Não há decodificação longa sem execução em segundo plano:as interações com background: false param em 65.536 tokens. O suporte será lançado em breve.
• Sem metas de comprimento:o modelo não segue metas de comprimento de token ou contagem de palavras.

Próximas etapas

• Novidades no Gemini 4 Argon
• Execução em segundo plano
• Raciocínio
• Decodificação longa com a API GenerateContent