Decodificação longa

A decodificação longa permite que o Gemini 4 Argon gere respostas que ultrapassam o limite de saída de uma única solicitação para tarefas de raciocínio profundo, até a janela de contexto unificada de 1 milhão de tokens (1.048.576 tokens compartilhados entre entrada, pensamento e saída).

Mudar apenas o ID do modelo não ativa a decodificação longa. Sem configuração adicional, a saída para em 64 mil tokens em chamadas de streaming e 32 mil em chamadas sem streaming. A maneira mais rápida de ativar a decodificação longa é fazer upgrade do SDK da IA generativa do Google e definir max_output_tokens como um valor maior que 65.536. Neste guia, explicamos como a decodificação longa funciona, quando usá-la e como ativá-la com generateContent.

Como funciona a decodificação longa

Uma única solicitação de streaming ou SDK gera até 64 mil tokens, e uma solicitação REST sem streaming gera até 32 mil tokens. Quando uma resposta precisa de mais tokens, o modelo a gera em vários saltos de solicitação e resposta, cada um continuando de onde o salto anterior parou.

• Limite unificado de tokens de entrada e saída:a entrada, o raciocínio, as chamadas de função e a resposta final compartilham uma janela de 1 milhão de tokens. A saída pode usar até 1.048.576 tokens menos os tokens de entrada.
• Um limite em cada salto:um salto retorna até 65.536 tokens de saída. As solicitações REST que não são de streaming retornam até 32.768.
• Um indicador de continuação:se o modelo atingir o limite e ainda tiver tokens, a resposta vai terminar com finish_reason: CONTINUATION e um continuation_token.
• O próximo salto: O cliente envia a mesma solicitação novamente com o token. O modelo continua de onde parou.
• Um total para todos os saltos:max_output_tokens define o total de tokens de processamento e saída para todos os saltos juntos.
• Um sinal de parada:quando o modelo usa todo o max_output_tokens, a resposta termina com finish_reason: MAX_TOKENS.

Em problemas difíceis, um salto pode gastar todos os tokens em pensamento interno e retornar um texto vazio com um continuation_token. Isso é normal, e a resposta final chega em saltos posteriores.

Limites de saída padrão

Sem a decodificação longa, uma única solicitação é interrompida nestes limites por solicitação:

• Solicitações de streaming e não streaming pelo SDK da IA generativa do Google (generate_content): o padrão é 64 mil tokens de saída.
• Chamadas REST diretas sem streaming (generateContent): o padrão é 32 mil tokens de saída. Definir max_output_tokens como um valor maior que 32.768 em uma chamada REST sem streaming e sem um continuation_token retorna um erro 400.

Quando usar a decodificação longa

A maioria das solicitações é concluída dentro do limite de solicitação única (64 mil tokens para chamadas de streaming e SDK ou 32 mil tokens para chamadas REST sem streaming). Use a decodificação longa quando uma resposta precisar de mais tokens de pensamento e saída combinados do que uma única solicitação permite. Aumentar max_output_tokens dá ao modelo um limite maior para resolver problemas difíceis, em vez de apenas aumentar as respostas padrão.

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

Ativar a decodificação longa

É possível executar a decodificação longa automaticamente com o SDK da IA generativa do Google (opção 1, recomendada para a maioria dos apps) ou escrever seu próprio loop de continuação (opção 2). As duas opções oferecem suporte à janela de contexto completa de 1 milhão de tokens.

O continuation_token criptografado carrega o estado do modelo entre as solicitações, então nada é armazenado no servidor.

Opção 1: usar o SDK da IA generativa do Google (recomendado)

No SDK mais recente da IA generativa do Google, automatic_continuation é ativado por padrão para chamadas com e sem streaming, então não é necessário defini-lo. Quando você define max_output_tokens acima do limite por solicitação, o SDK executa automaticamente os saltos de continuação e retorna uma resposta combinada.

1. Faça upgrade do SDK.

   Python

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

   JavaScript

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

2. Defina max_output_tokens como um valor maior que 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);
   

Lembre-se destes pontos:

• Streaming:generate_content_stream (Python) e generateContentStream (JavaScript) também continuam para você. Se um fluxo for interrompido após um checkpoint, o SDK vai retomar a partir desse ponto.
• Tempos limite:os tempos limite e as novas tentativas se aplicam a cada salto, não à execução completa.
• Controle manual:para executar o loop por conta própria, defina automatic_continuation=False (Python) ou automaticContinuation: false (JavaScript). Em seguida, siga a opção 2.
• Uso:os campos de uso mostram a soma de todos os saltos. Para saber o tamanho do seu comando, leia initial_prompt_token_count. Consulte Contar tokens.

Opção 2: escrever seu próprio loop

Escreva seu próprio loop se você chamar a REST diretamente, usar uma linguagem sem o SDK mais recente ou precisar de controle total. Você também pode consultar nossas implementações do SDK da IA generativa do Google em Python e JavaScript/TypeScript como referência.

Siga estas regras:

1. Envie a mesma solicitação em cada salto. Envie os documentos originais: contents, system_instruction, tools e generation_config. Mantenha max_output_tokens igual.
2. Não adicione saída parcial a contents. O continuation_token carrega o estado do modelo, incluindo o raciocínio.
3. Envie apenas o token mais recente. Cada token contém todo o progresso anterior.
4. Continue enquanto finish_reason estiver CONTINUATION. Interromper por qualquer outro motivo de finalização.
5. Junte as partes depois da última parada. Combine as partes de todos os hops em uma única ação do modelo para o histórico da conversa.

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"
  }'

Um salto gasto inteiramente em pensamento retorna text vazio com finishReason: "CONTINUATION". Trate isso como um progresso normal e peça o próximo salto:

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

Os loops de streaming precisam de mais uma regra. Após os primeiros 32.768 tokens, o stream envia um token de checkpoint a cada 5.000 tokens. Manter novos blocos em uma lista pendente. Quando um trecho tiver um continuation_token, mova os trechos pendentes para a saída confirmada e salve o token. Se o stream cair, descarte os blocos pendentes e retome do último token. Se o fluxo cair antes do primeiro ponto de verificação, envie a solicitação original novamente.

Definir max_output_tokens

max_output_tokens define o limite combinado para o raciocínio e a saída em todos os saltos. Diminuir esse valor não faz com que o modelo pense de forma mais concisa, mas sim que a resposta seja interrompida antes.

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 agentes. Use o low para tarefas menos complexas.

Processar solicitações de longa duração

Como o Gemini 4 Argon pensa mais do que os modelos do Gemini 3.x em problemas difíceis, aumente os tempos limite do cliente para que as solicitações longas não sejam desconectadas antes do tempo.

• Chamadas não transmitidas:o servidor fecha a conexão após 10 minutos.
• Chamadas de streaming:o servidor fecha o stream após 20 minutos.
• Tempos limite do cliente:defina o tempo limite de leitura HTTP como 20 minutos. Um tempo limite de 3 ou 5 minutos interrompe a solicitação antecipadamente.

Em Python, defina o tempo limite no cliente em milissegundos:

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

Para jobs que o cliente pesquisa, a API Interactions executa a decodificação longa no servidor. Consulte execução em segundo plano.

Retomar quando o modelo usar todos os tokens de saída

Quando uma resposta termina com MAX_TOKENS, ela ainda inclui um continuation_token. Você tem duas opções:

• Continuar:envie a mesma solicitação com o token e um max_output_tokens maior. O valor precisa ser maior que o número de tokens usados até o momento. Caso contrário, a API retorna um erro 400.
• Comece de novo:envie a solicitação original com um max_output_tokens maior e sem token. Você paga pelas duas execuções.

Contar tokens

Com a continuação automática, o usage_metadata informa os totais de todos os saltos. O SDK soma todos os campos de contagem: prompt_token_count, cached_content_token_count, candidates_token_count, thoughts_token_count e total_token_count.

prompt_token_count soma os tokens de entrada de cada salto. Cada salto envia seu 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, com o SDK de IA generativa do Google, um comando de 1.000 tokens que produz 200.000 tokens de pensamento e saída leva quatro saltos:

O prompt_token_count informa cerca de 397.000 tokens (com entradas de salto repetidas descontadas automaticamente em 95% pelo armazenamento em cache implícito), e o total_token_count informa cerca de 597.000 tokens, mesmo que o tamanho real do contexto seja de apenas cerca de 201.000 tokens: o comando de 1.000 tokens mais 200.000 tokens de pensamento e saída. Um loop REST não de streaming usa 32 mil hops. Portanto, são necessários sete hops para a mesma saída e 695.128 tokens de entrada.

prompt_token_count e total_token_count são a soma de cada salto, não o tamanho do contexto. Não as use para decidir quando resumir ou cortar o histórico de conversas (compactação de contexto) ou para aplicar um limite de contexto. Para estimar o tamanho do contexto, adicione o tamanho do comando da tabela a candidates_token_count e thoughts_token_count.

Atualize o framework do agente, a ferramenta de avaliação ou o proxy antes de executar o decodificador longo:

• Agentes e ferramentas de avaliação:se o código compactar o contexto ou interromper uma execução em um limite de tokens, use initial_prompt_token_count (ou o prompt_token_count do primeiro salto na REST) em vez do prompt_token_count somado. As respostas que terminam em um salto informam o mesmo valor nos dois campos, de modo que os testes curtos não mostram o problema.
• Proxies e gateways que chamam REST:cada resposta REST informa apenas o próprio salto. Adicione cada campo em todos os saltos para o custo e mantenha o promptTokenCount do primeiro salto como o tamanho do comando. Caso contrário, os usuários vão ver números diferentes dos que os usuários do SDK veem para a mesma solicitação.
• Registros e respostas serializadas:o SDK calcula o initial_prompt_token_count no cliente. Ele não está na resposta REST nem na saída JSON do SDK, como model_dump(). Salve-o como um valor separado se precisar dele mais tarde.

Se você fizer streaming no seu próprio loop, usage_metadata será cumulativo em cada stream. Manter apenas o último valor de cada stream e, em seguida, adicionar os valores entre os saltos.

Noções básicas sobre o faturamento

Você paga por cada token em cada salto, incluindo os que contêm apenas pensamento.

• Desconto de cache:o armazenamento em cache implícito desconta em 95% a entrada repetida em cada salto. A entrada em cache custa US $0,10 por 1 milhão de tokens em vez de US $2,00 durante o período inicial.
• Expiração do cache:o cache expira após 15 a 20 minutos sem uso. Uma pausa longa entre as baldeações cobra a taxa de entrada completa novamente.
• Saltos sem streaming com falha:você só paga quando uma resposta é concluída. Uma solicitação com falha ou descartada não tem custo.
• Streams descartados:um stream descartado antes de 32 mil tokens custa US $0. Depois disso, você paga até o último token de ponto de controle, porque pode retomar a partir dele.

Solução de problemas

Limitações

• Endpoint de compatibilidade com a OpenAI:a decodificação longa não está disponível. A saída é interrompida no limite por solicitação.
• SDKs mais antigos:as versões abaixo dos mínimos na observação não continuam automaticamente.
• Comprimento:o modelo não segue as metas de comprimento de token ou contagem de palavras.

Lista de verificação

• Faça upgrade do SDK da IA generativa do Google para a versão mínima.
• Defina max_output_tokens como um valor maior que 65.536.
• Use thinking_level (low, medium ou high), não thinking_budget.
• Defina os tempos limite de leitura HTTP como 20 minutos.
• Use initial_prompt_token_count para o tamanho e a compactação do contexto.
• Execute um comando como teste antes de uma avaliação grande.

Próximas etapas

• Novidades do Gemini 4 Argon
• Raciocínio
• Contagem de tokens