Raciocínio do Gemini

Os modelos das séries Gemini 3 e 2.5 usam um "processo de raciocínio" que melhora significativamente as habilidades de raciocínio e planejamento em várias etapas, tornando-os altamente eficazes para tarefas complexas, como programação, matemática avançada e análise de dados.

Quando você usa um modelo de raciocínio, o Gemini raciocina internamente antes de responder. A API Interactions mostra esse raciocínio por meio de etapas thought, etapas dedicadas que aparecem cronologicamente ao lado de chamadas de função, entradas do usuário ou saídas do modelo na matriz steps.

Cada etapa de raciocínio contém dois campos:

Campo Obrigatório Descrição
signature ✅ Sim Uma representação criptografada do estado de raciocínio interno do modelo. Sempre presente, mesmo quando o modelo realiza um raciocínio mínimo.
summary ❌ Não Uma matriz de conteúdo (texto e/ou imagens) que resume o raciocínio. Pode estar vazia dependendo da configuração thinking_summaries, se o modelo realizou raciocínio suficiente ou do tipo de conteúdo (por exemplo, latentes de imagem podem não ter resumos de texto).

Interações com raciocínio

Iniciar uma interação com um modelo de raciocínio é semelhante a qualquer outra solicitação de interação. Especifique um dos modelos com suporte de raciocínio no campo model:

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Explain the concept of Occam's Razor and provide a simple, everyday example."
)
print(interaction.steps[-1].content[0].text)

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Explain the concept of Occam's Razor and provide a simple, everyday example."
});
console.log(interaction.steps.at(-1).content[0].text);

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Explain the concept of Occam'\''s Razor and provide a simple example."
  }'

É possível transmitir interações de raciocínio para receber resumos e assinaturas de raciocínio incrementais durante a geração. Para um guia abrangente que abrange tipos de eventos, tipos de delta e exemplos de código, consulte o guia Interações de streaming.

Resumos de raciocínio

Os resumos de raciocínio fornecem insights sobre o processo de raciocínio interno do modelo. Por padrão, apenas a saída final é retornada. É possível ativar resumos de raciocínio com thinking_summaries:

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="What is the sum of the first 50 prime numbers?",
    generation_config={
        "thinking_summaries": "auto"
    }
)

for step in interaction.steps:
    if step.type == "thought":
        print("Thought summary:")
        if step.summary:
            for content_block in step.summary:
                if content_block.type == "text":
                    print(content_block.text)
        print()
    elif step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print("Answer:")
                print(content_block.text)
                print()

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "What is the sum of the first 50 prime numbers?",
    generation_config: {
        thinking_summaries: "auto"
    }
});

for (const step of interaction.steps) {
    if (step.type === "thought") {
        console.log("Thought summary:");
        if (step.summary) {
            for (const contentBlock of step.summary) {
                if (contentBlock.type === "text") console.log(contentBlock.text);
            }
        }
    } else if (step.type === "model_output") {
        for (const contentBlock of step.content) {
            if (contentBlock.type === "text") {
                console.log("Answer:");
                console.log(contentBlock.text);
            }
        }
    }
}

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "What is the sum of the first 50 prime numbers?",
    "generation_config": {
      "thinking_summaries": "auto"
    }
  }'

Um bloco de raciocínio pode conter apenas uma assinatura sem resumo nestes casos:

  • Solicitações simples, em que o modelo não raciocinou o suficiente para gerar um resumo
  • thinking_summaries: "none", em que os resumos são explicitamente desativados
  • Alguns tipos de conteúdo de raciocínio, como imagens, podem não ter resumos de texto

O código sempre precisa processar blocos de raciocínio em que summary está vazio ou ausente.

Como controlar o raciocínio

Os modelos do Gemini se envolvem no raciocínio dinâmico por padrão, ajustando automaticamente a quantidade de esforço de raciocínio com base na complexidade da solicitação. É possível controlar esse comportamento usando o parâmetro thinking_level.

Modelo Raciocínio padrão Níveis aceitos
gemini-3.1-pro-preview Ativado (alto) baixo, médio, alto
gemini-3-flash-preview Ativado (alto) mínimo, baixo, médio, alto
gemini-3-pro-preview Ativado (alto) baixo, alto
gemini-2.5-pro Ativado baixo, médio, alto
gemini-2.5-flash Ativado baixo, médio, alto
gemini-2.5-flash-lite Desativado baixo, médio, alto

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Provide a list of 3 famous physicists and their key contributions",
    generation_config={
        "thinking_level": "low"
    }
)
print(interaction.steps[-1].content[0].text)

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Provide a list of 3 famous physicists and their key contributions",
    generation_config: {
        thinking_level: "low"
    }
});
console.log(interaction.steps.at(-1).content[0].text);

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Provide a list of 3 famous physicists and their key contributions",
    "generation_config": {
      "thinking_level": "low"
    }
  }'

Assinaturas de raciocínio

As assinaturas de raciocínio são representações criptografadas do raciocínio interno do modelo. Elas são necessárias para manter a continuidade do raciocínio em interações de várias etapas.

A API Interactions simplifica muito o processamento de assinaturas de raciocínio em comparação com a API generateContent.

Por padrão, quando você usa a API Interactions no modo com estado (definindo store: true e transmitindo o previous_interaction_id em turnos subsequentes), o servidor gerencia automaticamente o estado da conversa, incluindo todos os blocos e assinaturas de raciocínio. Nesse modo, você não precisa fazer nada em relação às assinaturas. Elas são processadas totalmente no lado do servidor.

Modo sem estado

Se você estiver gerenciando o estado da conversa (modo sem estado) e transmitindo o histórico completo de entradas e saídas em cada solicitação:

  • Você SEMPRE precisa reenviar todos os blocos thought exatamente como foram recebidos do modelo.
  • NÃO remova ou modifique blocos de raciocínio do histórico, porque eles contêm as assinaturas necessárias para que o modelo continue raciocinando.
  • Ao mudar de modelo em uma sessão, ainda é necessário reenviar os blocos de raciocínio do modelo anterior. O back-end gerencia a compatibilidade.

Preços

Quando o raciocínio está ativado, o preço da resposta é a soma dos tokens de saída e dos tokens de raciocínio. É possível acessar o número total de tokens de raciocínio gerados no campo total_thought_tokens.

Python

# This will only work for SDK newer than 2.0.0
# ...
print("Thoughts tokens:", interaction.usage.total_thought_tokens)
print("Output tokens:", interaction.usage.total_output_tokens)

JavaScript

// This will only work for SDK newer than 2.0.0
// ...
console.log(`Thoughts tokens: ${interaction.usage.total_thought_tokens}`);
console.log(`Output tokens: ${interaction.usage.total_output_tokens}`);

Os modelos de raciocínio geram raciocínios completos para melhorar a qualidade da resposta final e, em seguida, resumos de saída para fornecer insights sobre o processo de raciocínio. O preço é baseado nos tokens de raciocínio completos que o modelo precisa gerar, embora apenas o resumo seja gerado pela API.

Saiba mais sobre tokens no guia Contagem de tokens.

Práticas recomendadas

Use modelos de raciocínio de maneira eficiente seguindo estas diretrizes.

  • Analisar o raciocínio: analise os resumos de raciocínio para entender falhas e melhorar os comandos.
  • Controlar o orçamento de raciocínio: peça ao modelo para pensar menos em saídas longas para economizar tokens.
  • Tarefas simples: use o raciocínio mínimo para recuperação de fatos ou classificação (por exemplo, "Onde a DeepMind foi fundada?").
  • Tarefas moderadas: use o raciocínio padrão para comparar conceitos ou raciocínio criativo (por exemplo, compare carros elétricos e híbridos).
  • Tarefas complexas: use o raciocínio máximo para programação avançada, matemática ou planejamento em várias etapas (por exemplo, resolva problemas de matemática da AIME).

A seguir