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:
- Testar a visualização do Gemini 2.5 Flash no AI Studio
- Teste a prévia do Gemini 2.5 Pro no AI Studio
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:
from google import genai
client = genai.Client(api_key="GOOGLE_API_KEY")
prompt = "Explain the concept of Occam's Razor and provide a simple, everyday example."
response = client.models.generate_content(
model="gemini-2.5-flash-preview-05-20",
contents=prompt
)
print(response.text)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
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-flash-preview-05-20",
contents: prompt,
});
console.log(response.text);
}
main();
// import packages here
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GOOGLE_API_KEY")))
if err != nil {
log.Fatal(err)
}
defer client.Close()
model := client.GenerativeModel("gemini-2.5-flash-preview-05-20")
resp, err := model.GenerateContent(ctx, genai.Text("Explain the concept of Occam's Razor and provide a simple, everyday example."))
if err != nil {
log.Fatal(err)
}
fmt.Println(resp.Text())
}
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-preview-05-20:generateContent?key=$GOOGLE_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 (experimental)
Os resumos de pensamento oferecem insights sobre o processo de raciocínio interno do modelo. Esse recurso pode ser útil para verificar a abordagem do modelo e manter os usuários informados durante tarefas mais longas, especialmente quando combinado com o streaming.
É possível ativar os resumos de pensamentos definindo 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 que demonstra como ativar e recuperar resumos de pensamentos sem streaming, que retorna um único resumo de pensamento final com a resposta:
from google import genai
from google.genai import types
client = genai.Client(api_key="GOOGLE_API_KEY")
prompt = "What is the sum of the first 50 prime numbers?"
response = client.models.generate_content(
model="gemini-2.5-flash-preview-05-20",
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()
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
async function main() {
const response = await ai.models.generateContent({
model: "gemini-2.5-flash-preview-05-20",
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();
package main
import (
"context"
"fmt"
"google.golang.org/genai"
"os"
)
func main() {
ctx := context.Background()
client, _ := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: os.Getenv("GOOGLE_API_KEY"),
Backend: genai.BackendGeminiAPI,
})
contents := genai.Text("What is the sum of the first 50 prime numbers?")
model := "gemini-2.5-flash-preview-05-20"
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:
from google import genai
from google.genai import types
client = genai.Client(api_key="GOOGLE_API_KEY")
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-flash-preview-05-20",
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
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
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-flash-preview-05-20",
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();
Orçamentos de pensamento
O parâmetro thinkingBudget
permite orientar o modelo
sobre o número de tokens de pensamento que ele pode usar ao gerar uma resposta. Uma
contagem de tokens maior geralmente permite um raciocínio mais detalhado,
o que pode ser benéfico para lidar com tarefas mais complexas.
Se você não definir o thinkingBudget
, o modelo vai ajustar dinamicamente
o orçamento com base na complexidade da solicitação.
- O
thinkingBudget
precisa ser um número inteiro no intervalo de0
a24576
. - Definir o orçamento de pensamento como
0
desativa o pensamento. - Dependendo da solicitação, o modelo pode ter um orçamento de token insuficiente ou em excesso.
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-2.5-flash-preview-05-20",
contents="Provide a list of 3 famous physicists and their key contributions",
config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(thinking_budget=1024)
),
)
print(response.text)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
async function main() {
const response = await ai.models.generateContent({
model: "gemini-2.5-flash-preview-05-20",
contents: "Provide a list of 3 famous physicists and their key contributions",
config: {
thinkingConfig: {
thinkingBudget: 1024,
},
},
});
console.log(response.text);
}
main();
package main
import (
"context"
"fmt"
"google.golang.org/genai"
"os"
)
func main() {
ctx := context.Background()
client, _ := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: os.Getenv("GOOGLE_API_KEY"),
Backend: genai.BackendGeminiAPI,
})
thinkingBudgetVal := int32(1024)
contents := genai.Text("Provide a list of 3 famous physicists and their key contributions")
model := "gemini-2.5-flash-preview-05-20"
resp, _ := client.Models.GenerateContent(ctx, model, contents, &genai.GenerateContentConfig{
ThinkingConfig: &genai.ThinkingConfig{
ThinkingBudget: &thinkingBudgetVal,
},
})
fmt.Println(resp.Text())
}
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-preview-05-20:generateContent?key=$GOOGLE_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
}
}
}'
Preços
Quando o pensamento é 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
.
# ...
print("Thoughts tokens:",response.usage_metadata.thoughts_token_count)
print("Output tokens:",response.usage_metadata.candidates_token_count)
// ...
console.log(`Thoughts tokens: ${response.usageMetadata.thoughtsTokenCount}`);
console.log(`Output tokens: ${response.usageMetadata.candidatesTokenCount}`);
// ...
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
Todos os recursos do modelo estão disponíveis na página Visão geral do modelo.
Modelo | Resumos de pensamentos | Orçamento de pensamento |
---|---|---|
Gemini 2.5 Flash | ✔️ | ✔️ |
Gemini 2.5 Pro | ✔️ | X |
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
Analisar o raciocínio: quando você não recebe a resposta esperada dos modelos de pensamento, isso pode ajudar a analisar cuidadosamente o processo de raciocínio 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 limitar 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á pedindo 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 máxima de pensamento): para desafios realmente complexos,
o modelo precisa envolver 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 17b é um divisor de 97b.
- 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 por algoritmos. 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.
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 a prévia do Gemini 2.5 Pro e o Gemini Flash 2.5 Thinking, acesse a página do modelo.