O Gemini 3 já está disponível. Leia o guia para desenvolvedores e comece a usar nosso modelo mais avançado até agora.

Esta página foi traduzida pela API Cloud Translation.

Pensamento do Gemini

Os modelos da série Gemini 3 e 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.

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."
         }
       ]
     }
   ]
 }'
 ```

Resumos de pensamentos

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

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)
      }
    }
  }
}

Controle do pensamento

Os modelos do Gemini usam o pensamento dinâmico por padrão, ajustando automaticamente a quantidade de esforço de raciocínio com base na complexidade da solicitação do usuário. No entanto, se você tiver restrições de latência específicas ou precisar que o modelo faça um raciocínio mais profundo do que o normal, use parâmetros para controlar o comportamento de pensamento.

Níveis de pensamento (Gemini 3 Pro)

O parâmetro thinkingLevel, recomendado para modelos do Gemini 3 e versões mais recentes, permite controlar o comportamento de raciocínio. É possível definir o nível de pensamento como "low" ou "high". Se você não especificar um nível de raciocínio, o Gemini usará o nível dinâmico padrão do modelo, "high", para o Gemini 3 Pro Preview.

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Provide a list of 3 famous physicists and their key contributions",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="low")
    ),
)

print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: "Provide a list of 3 famous physicists and their key contributions",
    config: {
      thinkingConfig: {
        thinkingLevel: "low",
      },
    },
  });

  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)
  }

  thinkingLevelVal := "low"

  contents := genai.Text("Provide a list of 3 famous physicists and their key contributions")
  model := "gemini-3-pro-preview"
  resp, _ := client.Models.GenerateContent(ctx, model, contents, &genai.GenerateContentConfig{
    ThinkingConfig: &genai.ThinkingConfig{
      ThinkingLevel: &thinkingLevelVal,
    },
  })

fmt.Println(resp.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview: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": {
          "thinkingLevel": "low"
    }
  }
}'

Não é possível desativar o recurso de pensar do Gemini 3 Pro. Os modelos da série Gemini 2.5 não são compatíveis com thinkingLevel. Use thinkingBudget.

Orçamentos de pensamento

O parâmetro thinkingBudget, introduzido com a série Gemini 2.5, orienta o modelo sobre o número específico de tokens de pensamento a serem usados no raciocínio.

Confira a seguir os detalhes da configuração thinkingBudget para cada tipo de modelo. Para desativar o pensamento, defina thinkingBudget como 0. Definir thinkingBudget como -1 ativa o pensamento dinâmico, ou seja, o modelo ajusta o orçamento com base na complexidade da solicitação.

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`
Pré-lançamento do 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`
Prévia do 2.5 Flash Lite	O modelo não pensa	`512` a `24576`	`thinkingBudget = 0`	`thinkingBudget = -1`
Pré-lançamento do Robotics-ER 1.5	Pensamento dinâmico: o modelo decide quando e quanto pensar	`0` a `24576`	`thinkingBudget = 0`	`thinkingBudget = -1`
Pré-lançamento do áudio nativo do 2.5 Flash Live (09/2025)	Pensamento dinâmico: o modelo decide quando e quanto pensar	`0` 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
    }
  }
}'

Dependendo do comando, o modelo pode exceder ou não atingir o orçamento de tokens.

Assinaturas de pensamento

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

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

Os modelos do Gemini 2.5 retornam assinaturas de pensamento quando o recurso está ativado e a solicitação inclui chamada de função, especificamente declarações de função.
Os modelos do Gemini 3 podem retornar assinaturas de pensamento para todos os tipos de partes. Recomendamos que você sempre transmita todas as assinaturas de volta como recebidas, mas isso é obrigatório para assinaturas de chamadas de função. Leia a página Assinaturas de pensamento para saber mais.

O SDK da IA generativa do Google processa automaticamente o retorno das assinaturas de pensamento para você. Você só precisa gerenciar assinaturas de pensamento manualmente se estiver modificando o histórico de conversas ou usando a API REST.

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 completa com todas as partes de volta 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. 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 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.

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 de 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ê quiser uma resposta muito longa, oriente o 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 de matemática 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, geralmente 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 inteiras b > 9 para as quais 17_b é um divisor de 97_b.
- Escrever código Python para um aplicativo da Web que mostra 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.

Modelos, ferramentas e recursos compatíveis

Os recursos de raciocínio estão disponíveis em todos os modelos das séries 3 e 2.5. Você pode encontrar todos os recursos do modelo na página Visão geral do modelo.

Os modelos de pensamento 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.

Confira exemplos de como usar ferramentas com modelos de pensamento no livro de receitas de pensamento.

A seguir

A cobertura de pensamento está disponível no nosso guia de compatibilidade com a OpenAI.