O Veo 3 já está disponível na API Gemini. Saiba mais

Esta página foi traduzida pela API Cloud Translation.

Pensamento do Gemini

Os modelos da série Gemini 2.5 usam um "processo de pensamento" 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 as capacidades de raciocínio do Gemini usando a API Gemini.

Antes de começar

Use um modelo da série 2.5 compatível para pensar. Talvez seja útil conhecer esses modelos no AI Studio antes de usar a API:

Gerar conteúdo com reflexão

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

Python

from google import genai

client = genai.Client()
prompt = "Explain the concept of Occam's Razor and provide a simple, everyday example."
response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents=prompt
)

print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});

async function main() {
  const prompt = "Explain the concept of Occam's Razor and provide a simple, everyday example.";

  const response = await ai.models.generateContent({
    model: "gemini-2.5-pro",
    contents: prompt,
  });

  console.log(response.text);
}

main();

Go

package main

import (
  "context"
  "fmt"
  "log"
  "os"
  "google.golang.org/genai"
)

func main() {
  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  prompt := "Explain the concept of Occam's Razor and provide a simple, everyday example."
  model := "gemini-2.5-pro"

  resp, _ := client.Models.GenerateContent(ctx, model, genai.Text(prompt), nil)

  fmt.Println(resp.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-pro:generateContent" \
 -H "x-goog-api-key: $GEMINI_API_KEY" \
 -H 'Content-Type: application/json' \
 -X POST \
 -d '{
   "contents": [
     {
       "parts": [
         {
           "text": "Explain the concept of Occam\'s Razor and provide a simple, everyday example."
         }
       ]
     }
   ]
 }'
 ```

Orçamentos de pensamento

O parâmetro thinkingBudget orienta o modelo sobre o número de tokens de pensamento a serem usados ao gerar uma resposta. Um número maior de tokens geralmente permite um raciocínio mais detalhado, o que pode ser útil para lidar com tarefas mais complexas. Se a latência for mais importante, use um orçamento menor ou desative o pensamento definindo thinkingBudget como 0. Definir thinkingBudget como -1 ativa o pensamento dinâmico. Isso significa que o modelo vai ajustar o orçamento com base na complexidade da solicitação.

O thinkingBudget só é compatível com o Gemini 2.5 Flash, 2.5 Pro e 2.5 Flash-Lite. Dependendo do comando, o modelo pode exceder ou não atingir o orçamento de tokens.

Confira a seguir os detalhes da configuração thinkingBudget para cada tipo de modelo.

Modelo	Configuração padrão (o orçamento de pensamento não está definido)	Intervalo	Desativar raciocínio	Ativar o pensamento dinâmico
2.5 Pro	Pensamento dinâmico: o modelo decide quando e quanto pensar	`128` a `32768`	N/A: não é possível desativar o pensamento	`thinkingBudget = -1`
2.5 Flash	Pensamento dinâmico: o modelo decide quando e quanto pensar	`0` a `24576`	`thinkingBudget = 0`	`thinkingBudget = -1`
2.5 Flash Lite	O modelo não pensa	`512` a `24576`	`thinkingBudget = 0`	`thinkingBudget = -1`

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents="Provide a list of 3 famous physicists and their key contributions",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_budget=1024)
        # Turn off thinking:
        # thinking_config=types.ThinkingConfig(thinking_budget=0)
        # Turn on dynamic thinking:
        # thinking_config=types.ThinkingConfig(thinking_budget=-1)
    ),
)

print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-pro",
    contents: "Provide a list of 3 famous physicists and their key contributions",
    config: {
      thinkingConfig: {
        thinkingBudget: 1024,
        // Turn off thinking:
        // thinkingBudget: 0
        // Turn on dynamic thinking:
        // thinkingBudget: -1
      },
    },
  });

  console.log(response.text);
}

main();

Go

package main

import (
  "context"
  "fmt"
  "google.golang.org/genai"
  "os"
)

func main() {
  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  thinkingBudgetVal := int32(1024)

  contents := genai.Text("Provide a list of 3 famous physicists and their key contributions")
  model := "gemini-2.5-pro"
  resp, _ := client.Models.GenerateContent(ctx, model, contents, &genai.GenerateContentConfig{
    ThinkingConfig: &genai.ThinkingConfig{
      ThinkingBudget: &thinkingBudgetVal,
      // Turn off thinking:
      // ThinkingBudget: int32(0),
      // Turn on dynamic thinking:
      // ThinkingBudget: int32(-1),
    },
  })

fmt.Println(resp.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-pro:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
  "contents": [
    {
      "parts": [
        {
          "text": "Provide a list of 3 famous physicists and their key contributions"
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
          "thinkingBudget": 1024
          # Thinking off:
          # "thinkingBudget": 0
          # Turn on dynamic thinking:
          # "thinkingBudget": -1
    }
  }
}'

Resumos de ideias

Os resumos de ideias são versões sintetizadas das ideias brutas do modelo e oferecem insights sobre o processo de raciocínio interno dele. Os orçamentos de pensamento se aplicam aos pensamentos brutos do modelo, não aos resumos de pensamento.

Para ativar os resumos de ideias, defina includeThoughts como true na configuração da solicitação. Em seguida, acesse o resumo iterando o parts do parâmetro response e verificando o booleano thought.

Confira um exemplo de como ativar e recuperar resumos de ideias sem streaming, que retorna um único resumo final com a resposta:

Python

from google import genai
from google.genai import types

client = genai.Client()
prompt = "What is the sum of the first 50 prime numbers?"
response = client.models.generate_content(
  model="gemini-2.5-pro",
  contents=prompt,
  config=types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(
      include_thoughts=True
    )
  )
)

for part in response.candidates[0].content.parts:
  if not part.text:
    continue
  if part.thought:
    print("Thought summary:")
    print(part.text)
    print()
  else:
    print("Answer:")
    print(part.text)
    print()

JavaScript

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-pro",
    contents: "What is the sum of the first 50 prime numbers?",
    config: {
      thinkingConfig: {
        includeThoughts: true,
      },
    },
  });

  for (const part of response.candidates[0].content.parts) {
    if (!part.text) {
      continue;
    }
    else if (part.thought) {
      console.log("Thoughts summary:");
      console.log(part.text);
    }
    else {
      console.log("Answer:");
      console.log(part.text);
    }
  }
}

main();

Go

package main

import (
  "context"
  "fmt"
  "google.golang.org/genai"
  "os"
)

func main() {
  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  contents := genai.Text("What is the sum of the first 50 prime numbers?")
  model := "gemini-2.5-pro"
  resp, _ := client.Models.GenerateContent(ctx, model, contents, &genai.GenerateContentConfig{
    ThinkingConfig: &genai.ThinkingConfig{
      IncludeThoughts: true,
    },
  })

  for _, part := range resp.Candidates[0].Content.Parts {
    if part.Text != "" {
      if part.Thought {
        fmt.Println("Thoughts Summary:")
        fmt.Println(part.Text)
      } else {
        fmt.Println("Answer:")
        fmt.Println(part.Text)
      }
    }
  }
}

Confira um exemplo de uso do recurso de pensar com streaming, que retorna resumos incrementais e contínuos durante a geração:

Python

from google import genai
from google.genai import types

client = genai.Client()

prompt = """
Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue.
The person who lives in the red house owns a cat.
Bob does not live in the green house.
Carol owns a dog.
The green house is to the left of the red house.
Alice does not own a cat.
Who lives in each house, and what pet do they own?
"""

thoughts = ""
answer = ""

for chunk in client.models.generate_content_stream(
    model="gemini-2.5-pro",
    contents=prompt,
    config=types.GenerateContentConfig(
      thinking_config=types.ThinkingConfig(
        include_thoughts=True
      )
    )
):
  for part in chunk.candidates[0].content.parts:
    if not part.text:
      continue
    elif part.thought:
      if not thoughts:
        print("Thoughts summary:")
      print(part.text)
      thoughts += part.text
    else:
      if not answer:
        print("Answer:")
      print(part.text)
      answer += part.text

JavaScript

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

const ai = new GoogleGenAI({});

const prompt = `Alice, Bob, and Carol each live in a different house on the same
street: red, green, and blue. The person who lives in the red house owns a cat.
Bob does not live in the green house. Carol owns a dog. The green house is to
the left of the red house. Alice does not own a cat. Who lives in each house,
and what pet do they own?`;

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

async function main() {
  const response = await ai.models.generateContentStream({
    model: "gemini-2.5-pro",
    contents: prompt,
    config: {
      thinkingConfig: {
        includeThoughts: true,
      },
    },
  });

  for await (const chunk of response) {
    for (const part of chunk.candidates[0].content.parts) {
      if (!part.text) {
        continue;
      } else if (part.thought) {
        if (!thoughts) {
          console.log("Thoughts summary:");
        }
        console.log(part.text);
        thoughts = thoughts + part.text;
      } else {
        if (!answer) {
          console.log("Answer:");
        }
        console.log(part.text);
        answer = answer + part.text;
      }
    }
  }
}

await main();

Go

package main

import (
  "context"
  "fmt"
  "log"
  "os"
  "google.golang.org/genai"
)

const prompt = `
Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue.
The person who lives in the red house owns a cat.
Bob does not live in the green house.
Carol owns a dog.
The green house is to the left of the red house.
Alice does not own a cat.
Who lives in each house, and what pet do they own?
`

func main() {
  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  contents := genai.Text(prompt)
  model := "gemini-2.5-pro"

  resp := client.Models.GenerateContentStream(ctx, model, contents, &genai.GenerateContentConfig{
    ThinkingConfig: &genai.ThinkingConfig{
      IncludeThoughts: true,
    },
  })

  for chunk := range resp {
    for _, part := range chunk.Candidates[0].Content.Parts {
      if len(part.Text) == 0 {
        continue
      }

      if part.Thought {
        fmt.Printf("Thought: %s\n", part.Text)
      } else {
        fmt.Printf("Answer: %s\n", part.Text)
      }
    }
  }
}

Assinaturas de pensamento

Como as chamadas padrão de geração de texto e conteúdo da API Gemini não têm estado, ao usar o pensamento em interações multiturno (como chat), o modelo não tem acesso ao contexto de pensamento de turnos anteriores.

É possível manter o contexto do pensamento usando assinaturas de pensamento, que são representações criptografadas do processo de pensamento interno do modelo. O modelo retorna assinaturas de pensamento no objeto de resposta quando o pensamento e a chamada de função estão ativados. Para garantir que o modelo mantenha o contexto em várias rodadas de uma conversa, forneça as assinaturas de pensamento de volta ao modelo nas solicitações subsequentes.

Você vai receber assinaturas de pensamento quando:

O recurso de pensamento está ativado e as ideias são geradas.
A solicitação inclui declarações de função.

Confira um exemplo de como pensar com chamadas de função na página Chamada de função.

Outras limitações de uso a serem consideradas com a chamada de função incluem:

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 ao modelo em turnos subsequentes.
Não concatene partes com assinaturas.
Não mescle uma parte com uma assinatura com outra sem assinatura.

Preços

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

Python

# ...
print("Thoughts tokens:",response.usage_metadata.thoughts_token_count)
print("Output tokens:",response.usage_metadata.candidates_token_count)

JavaScript

// ...
console.log(`Thoughts tokens: ${response.usageMetadata.thoughtsTokenCount}`);
console.log(`Output tokens: ${response.usageMetadata.candidatesTokenCount}`);

Go

// ...
usageMetadata, err := json.MarshalIndent(response.UsageMetadata, "", "  ")
if err != nil {
  log.Fatal(err)
}
fmt.Println("Thoughts tokens:", string(usageMetadata.thoughts_token_count))
fmt.Println("Output tokens:", string(usageMetadata.candidates_token_count))

Os modelos de pensamento geram ideias completas para melhorar a qualidade da resposta final e, em seguida, produzem resumos para fornecer insights sobre o processo de pensamento. Portanto, o preço se baseia nos tokens de pensamento completos que o modelo precisa gerar para criar um resumo, mesmo que apenas o resumo seja a saída da API.

Saiba mais sobre tokens no guia Contagem de tokens.

Modelos compatíveis

Os recursos de pensamento são compatíveis com todos os modelos da série 2.5. Você pode encontrar todos os recursos do modelo na página Visão geral do modelo.

Práticas recomendadas

Esta seção inclui algumas orientações para usar modelos de pensamento de maneira eficiente. Como sempre, seguir nossas orientações e práticas recomendadas para comandos vai gerar os melhores resultados.

Depuração e direcionamento

Analise o raciocínio: quando você não recebe a resposta esperada dos modelos de pensamento, é útil analisar com cuidado os resumos de pensamento do Gemini. Você pode ver como ele dividiu a tarefa e chegou à conclusão, além de usar essas informações para corrigir e chegar aos resultados certos.
Forneça orientação no raciocínio: se você espera uma resposta particularmente longa, forneça orientação no comando para restringir a quantidade de raciocínio usada pelo modelo. Isso permite reservar mais da saída de token para sua resposta.

Complexidade da tarefa

Tarefas fáceis (o pensamento pode estar DESATIVADO): para solicitações simples em que não é necessário raciocínio complexo, como recuperação de fatos ou classificação, o pensamento não é necessário. Por exemplo:
- "Onde a DeepMind foi fundada?"
- "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 detalhado ou compreensão mais profunda. O Gemini pode usar a capacidade de raciocínio de forma flexível para tarefas como:
- Comparar a fotossíntese e o crescimento.
- Compare e contraste carros elétricos e híbridos.
Tarefas difíceis (capacidade máxima de raciocínio): para desafios realmente complexos, como resolver problemas matemáticos ou tarefas de programação, recomendamos definir um orçamento de raciocínio alto. Esses tipos de tarefas exigem que o modelo use todas as suas capacidades de raciocínio e planejamento, muitas vezes envolvendo várias etapas internas antes de fornecer uma resposta. Por exemplo:
- Resolva o problema 1 da AIME 2025: encontre a soma de todas as bases inteiras b > 9 para as quais 17_b é um divisor de 97_b.
- Escrever código Python para um aplicativo da Web que visualiza dados do mercado de ações em tempo real, incluindo autenticação de usuário. Faça com que seja o mais eficiente possível.

Pensar com ferramentas e recursos

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ódigo ou acessem informações em tempo real, incorporando os resultados ao raciocínio e à resposta final.

Com a ferramenta de pesquisa, o modelo pode consultar a Pesquisa Google para encontrar informações atualizadas ou que vão além dos dados de treinamento. Isso é útil para perguntas sobre eventos recentes ou tópicos muito específicos.
A ferramenta de execução de código permite que o modelo gere e execute código Python para fazer cálculos, manipular dados ou resolver problemas que são melhor tratados de forma algorítmica. O modelo recebe a saída do código e pode usá-la na resposta.
Com a saída estruturada, é possível restringir o Gemini para responder com JSON. Isso é muito útil para integrar a saída do modelo em aplicativos.
A chamada de função conecta o modelo de pensamento a ferramentas e APIs externas. Assim, ele pode decidir quando chamar a função certa e quais parâmetros fornecer.
O contexto de URL fornece ao modelo URLs como contexto adicional para seu comando. Em seguida, o modelo pode recuperar conteúdo dos URLs e usar essas informações para criar e formatar a resposta.

Confira exemplos de como usar ferramentas com modelos de raciocínio no Livro de receitas de raciocínio.

A seguir

Para conferir exemplos mais detalhados, como:
- Como usar ferramentas com raciocínio
- Streaming com raciocínio
- Ajustar o orçamento de pensamento para resultados diferentes
e muito mais, confira nosso livro de receitas de pensamento.
A cobertura de pensamento já está disponível no nosso guia de compatibilidade com a OpenAI.
Para mais informações sobre o Gemini 2.5 Pro, o Gemini Flash 2.5 e o Gemini 2.5 Flash-Lite, acesse a página do modelo.