Apresentamos atualizações para a família de modelos de pensamento 2.5. 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 em 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 pensamento do Gemini usando a API Gemini.

Antes de começar

Use um modelo da série 2.5 com suporte para pensar. Talvez seja útil conferir estes modelos no AI Studio antes de mergulhar na API:

Como gerar conteúdo com pensamento

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 ao pensamento 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. Uma contagem de tokens mais alta geralmente permite um raciocínio mais detalhado, o que pode ser benéfico para resolver 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, o que significa que o modelo vai ajustar o orçamento com base na complexidade da solicitação.

O thinkingBudget tem suporte apenas no Gemini 2.5 Flash, 2.5 Pro e 2.5 Flash-Lite. Dependendo da solicitação, o modelo pode exceder ou ficar abaixo do orçamento de tokens.

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

Modelo	Configuração padrão (o orçamento de pensamento não está definido)	Intervalo	Desativar o 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 pensamentos

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

É possível ativar os resumos de pensamentos definindo includeThoughts como true na configuração da solicitação. Em seguida, acesse o resumo iterando pelo parts do parâmetro response e verificando o booleano thought.

Confira um exemplo que demonstra como ativar e recuperar resumos de pensamentos sem streaming, que retorna um único resumo de pensamento 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 como 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("Thoughts summary:")
      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)
      }
    }
  }
}

Preços

Quando o pensamento é ativado, o preço da resposta é a soma dos tokens de saída e de pensamento. Você pode 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 pensamentos completos para melhorar a qualidade da resposta final e, em seguida, geram resumos para fornecer insights sobre o processo de pensamento. Portanto, o preço é baseado 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. Todos os recursos do modelo estão disponíveis 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, siga nossas orientações e práticas recomendadas para ter os melhores resultados.

Depuração e direção

Analise o raciocínio: quando você não recebe a resposta esperada dos modelos de pensamento, isso pode ajudar a analisar cuidadosamente os resumos de pensamento do Gemini. Você pode ver como ele dividiu a tarefa e chegou à conclusão e usar essas informações para corrigir os resultados corretos.
Fornecer orientação no raciocínio: se você espera uma saída particularmente longa, forneça orientação na instrução para restringir a quantidade de pensamento que o modelo usa. Isso permite que você reserve mais da saída do token para sua resposta.

Complexidade da tarefa

Tarefas fáceis (o pensamento pode estar DESLIGADO): 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á solicitando uma reunião ou apenas fornecendo informações?"
Tarefas médias (padrão/algum pensamento): muitas solicitações comuns se beneficiam de um processamento detalhado ou de uma compreensão mais profunda. O Gemini pode usar flexivelmente a capacidade de pensar para tarefas como:
- Faça uma analogia entre a fotossíntese e o crescimento.
- Compare e contraste carros elétricos e híbridos.
Tarefas difíceis (capacidade de pensar ao máximo): para desafios realmente complexos, como resolver problemas matemáticos ou tarefas de programação, recomendamos definir um orçamento de pensamento alto. Esses tipos de tarefas exigem que o modelo use todos os recursos de raciocínio e planejamento, muitas vezes envolvendo muitas etapas internas antes de fornecer uma resposta. Por exemplo:
- Resolva o problema 1 da AIME 2025: encontre a soma de todas as bases de números inteiros b > 9 para as quais 17_b é um divisor de 97_b.
- Escrever um código Python para um aplicativo da Web que visualize dados de mercado de ações em tempo real, incluindo a autenticação do usuário. Torne o processo 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ódigos ou acessem informações em tempo real, incorporando os resultados ao raciocínio e à resposta final.

A ferramenta de pesquisa permite que o modelo consulte 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 o código Python para realizar cálculos, manipular dados ou resolver problemas que são melhor processados algoritmicamente. O modelo recebe a saída do código e pode usá-la na resposta.
Com a saída estruturada, é possível limitar o Gemini para responder com JSON. Isso é útil principalmente para integrar a saída do modelo aos aplicativos.
A chamada de função conecta o modelo de pensamento a ferramentas e APIs externas para que ele possa raciocinar sobre quando chamar a função certa e quais parâmetros fornecer.
O Contexto de URL fornece ao modelo URLs como contexto adicional para sua instrução. O modelo pode recuperar conteúdo dos URLs e usar esse conteúdo para informar e moldar a resposta.

Você pode conferir exemplos de uso de ferramentas com modelos de pensamento no Livro de receitas de pensamento.

A seguir

Para conferir exemplos mais detalhados, como:
- Usar ferramentas com pensamento
- Streaming com pensamento
- Como 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.