Raciocínio do Gemini

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

Este guia mostra como trabalhar com os recursos de raciocínio do Gemini usando a API Gemini.

Gerar conteúdo com raciocínio

Iniciar uma solicitação com um modelo de raciocínio é semelhante a qualquer outra solicitação de geração de conteúdo. A principal diferença está em especificar um dos modelos com suporte de raciocínio no model campo:

Python

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

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

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Explain the concept of Occam'\''s Razor and provide a simple example."
  }'

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 os resumos de raciocínio com thinking_summaries:

Python

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:")
        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

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?",
    generationConfig: {
        thinkingSummaries: "auto"
    }
});

for (const step of interaction.steps) {
    if (step.type === "thought") {
        console.log("Thought 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

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "What is the sum of the first 50 prime numbers?",
    "generationConfig": {
      "thinkingSummaries": "auto"
    }
  }'

Streaming com raciocínio

Use o streaming para receber resumos de raciocínio incrementais durante a geração. Isso retorna resumos incrementais e contínuos à medida que são gerados:

Python

from google import genai

client = genai.Client()

prompt = """
Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue.
Alice does not live in the red house.
Bob does not live in the green house.
Carol does not live in the red or green house.
Which house does each person live in?
"""

thoughts = ""
answer = ""

stream = client.interactions.create(
    model="gemini-3-flash-preview",
    input=prompt,
    generation_config={
        "thinking_summaries": "auto"
    },
    stream=True
)

thoughts = ""
answer = ""

for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "thought":
            if not thoughts:
                print("Thinking...")
            summary_text = getattr(event.delta, 'text', '')
            print(f"[Thought] {summary_text}", end="")
            thoughts += summary_text
        elif event.delta.type == "text" and event.delta.text:
            if not answer:
                print("\nAnswer:")
            print(event.delta.text, end="")
            answer += event.delta.text

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const prompt = `Alice, Bob, and Carol each live in a different house on the same
street: red, green, and blue. Alice does not live in the red house.
Bob does not live in the green house.
Carol does not live in the red or green house.
Which house does each person live in?`;

let thoughts = "";
let answer = "";

const stream = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: prompt,
    generationConfig: {
        thinkingSummaries: "auto"
    },
    stream: true
});

for await (const event of stream) {
    if (event.type === "step.delta") {
        if (event.delta.type === "thought") {
            if (!thoughts) console.log("Thinking...");
            process.stdout.write(`[Thought] ${event.delta.text || ""}`);
            thoughts += event.delta.text || "";
        } else if (event.delta.type === "text" && event.delta.text) {
            if (!answer) console.log("\nAnswer:");
            process.stdout.write(event.delta.text);
            answer += event.delta.text;
        }
    }
}

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. No entanto, é possível controlar esse comportamento usando parâmetros de configuração.

Níveis de raciocínio (Gemini 3)

O parâmetro thinking_level, recomendado para modelos do Gemini 3 e versões mais recentes, permite controlar o comportamento de raciocínio.

Nível de raciocínio Gemini 3.1 Pro Gemini 3 Pro (obsoleto) Gemini 3 Flash Descrição
minimal indisponível indisponível Compatível Corresponde à configuração "sem raciocínio" para a maioria das consultas. O modelo pode pensar de forma muito mínima para tarefas de programação complexas. Minimiza a latência para aplicativos de chat ou de alta capacidade de processamento. Observação: minimal não garante que o raciocínio esteja desativado.
low Compatível Compatível Compatível Minimiza a latência e o custo. Melhor para seguir instruções, chat ou aplicativos de alta capacidade de processamento.
medium Compatível indisponível Compatível Raciocínio equilibrado para a maioria das tarefas.
high Compatível (padrão, dinâmico) Compatível (padrão, dinâmico) Compatível (padrão, dinâmico) Maximiza a profundidade do raciocínio. O modelo pode levar muito mais tempo para chegar a um primeiro token de saída (sem raciocínio), mas a saída será mais cuidadosamente raciocinada.

Python

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

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",
    generationConfig: {
        thinkingLevel: "low"
    }
});
console.log(interaction.steps.at(-1).content[0].text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -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"
    }
  }'

Não é possível desativar o raciocínio do Gemini 3 Pro. O Gemini 3 Flash também não oferece suporte ao raciocínio completo, mas a configuração minimal significa que o modelo provavelmente não vai pensar (embora ainda possa).

Assinaturas de raciocínio

A API Gemini não tem estado, então o modelo trata cada solicitação de API de forma independente e não tem acesso ao contexto de raciocínio de turnos anteriores em interações multiturno.

Para manter o contexto de raciocínio em interações multiturno, o Gemini retorna assinaturas de raciocínio, que são representações criptografadas do processo de raciocínio interno do modelo.

  • Os modelos Gemini 2.5 retornam assinaturas de raciocínio quando o raciocínio está ativado e a solicitação inclui chamadas de função, especificamente declarações de função.
  • Os modelos Gemini 3 podem retornar assinaturas de raciocínio para todos os tipos de partes. Recomendamos que você sempre transmita todas as assinaturas de volta conforme recebidas, mas isso é necessário para assinaturas de chamadas de função. Leia a página Assinaturas de raciocínio para saber mais.
  • As assinaturas são retornadas do modelo em outras partes da resposta, por exemplo, chamadas de função ou partes de texto. Retorne a resposta inteira com todas as partes para o modelo em turnos subsequentes.
  • Não concatene partes com assinaturas.
  • Não mescle uma parte com uma assinatura com outra parte sem uma assinatura.

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

# ...
print("Thoughts tokens:", interaction.usage.total_thought_tokens)
print("Output tokens:", interaction.usage.total_output_tokens)

JavaScript

// ...
console.log(`Thoughts tokens: ${interaction.usage.totalThoughtTokens}`);
console.log(`Output tokens: ${interaction.usage.totalOutputTokens}`);

Os modelos de raciocínio geram pensamentos 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 pensamento 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

Esta seção inclui orientações para usar modelos de raciocínio de forma eficiente.

Depurar e orientar

  • Analisar o raciocínio: quando você não recebe a resposta esperada dos modelos de raciocínio, pode ser útil analisar cuidadosamente os resumos de raciocínio do Gemini. É possível conferir como ele dividiu a tarefa e chegou à conclusão, e usar essas informações para corrigir os resultados.

  • Fornecer orientação no raciocínio: se você espera uma saída muito longa, talvez seja necessário fornecer orientação no comando para restringir a quantidade de raciocínio que o modelo usa. Isso permite reservar mais da saída de token para sua resposta.

Complexidade da tarefa

  • Tarefas fáceis (o raciocínio pode estar DESATIVADO) : para solicitações simples em que o raciocínio complexo não é necessário, o raciocínio não é necessário. Exemplos:
    • "Onde o DeepMind foi fundado?"
    • "Este e-mail está pedindo uma reunião ou apenas fornecendo informações?"
  • Tarefas médias (padrão/algum raciocínio) : muitas solicitações comuns se beneficiam de um grau de processamento passo a passo ou de uma compreensão mais profunda. Exemplos:
    • Analogia da fotossíntese e do crescimento.
    • Comparar e contrastar carros elétricos e carros híbridos.
  • Tarefas difíceis (capacidade máxima de raciocínio) : para desafios realmente complexos, recomendamos definir um orçamento de raciocínio alto. Esses tipos de tarefas exigem que o modelo use todos os recursos de raciocínio e planejamento. Exemplos:
    • Resolver o problema 1 no AIME 2025: encontrar a soma de todas as bases inteiras b > 9...
    • Escrever código Python para um aplicativo da Web que visualize dados do mercado de ações em tempo real, incluindo a autenticação do usuário. Deixe-o o mais eficiente possível.

Modelos compatíveis

Modelo Raciocínio padrão Níveis compatíveis
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 Orçamento: 128-32768
gemini-2.5-flash Ativado Orçamento: 0-24576
gemini-2.5-flash-lite Desativado Orçamento: 0-24576

Os modelos de raciocínio funcionam com todas as ferramentas e recursos do Gemini. Isso permite que os modelos interajam com sistemas externos, executem códigos ou acessem informações em tempo real, incorporando os resultados ao raciocínio.

A seguir