Gemini 2.5 系列模型采用内部“思考过程”,可显著提升其推理和多步规划能力,使其在处理编码、高级数学和数据分析等复杂任务时非常高效。
本指南介绍了如何使用 Gemini API 处理 Gemini 的思考功能。
准备工作
确保您使用的是受支持的 2.5 系列模型进行思考。 在深入了解 API 之前,不妨先在 AI Studio 中探索以下模型:
通过思考生成内容
使用思考模型发起请求与任何其他内容生成请求类似。主要区别在于,您需要在 model
字段中指定某个支持思考的模型,如以下文本生成示例所示:
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."
}
]
}
]
}'
```
思考摘要(实验性)
思考摘要可让您深入了解模型的内部推理过程。此功能对于验证模型方法以及在执行较长任务期间让用户了解最新进展非常有用,尤其是与流式传输结合使用时。
您可以在请求配置中将 includeThoughts
设置为 true
,以启用思考摘要。然后,您可以通过迭代 response
参数的 parts
并检查 thought
布尔值来访问摘要。
以下示例演示了如何在不流式传输的情况下启用和检索思考摘要,这会在响应中返回单个最终思考摘要:
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)
}
}
}
}
下面是一个使用“以流式传输的方式思考”方法的示例,该方法会在生成期间返回滚动增量摘要:
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();
思考预算
借助 thinkingBudget
参数,您可以为模型提供指导,帮助其了解在生成回答时可使用的思考 token 数量。令牌数量越多,推理过程通常越详细,这对处理更复杂的任务很有帮助。如果您未设置 thinkingBudget
,模型将根据请求的复杂性动态调整预算。
thinkingBudget
必须是0
到24576
之间的整数。- 将思考预算设置为
0
会停用思考功能。 - 根据问题,模型可能会超出或低于令牌预算。
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
}
}
}'
价格
开启思考功能后,回答价格为输出令牌和思考令牌的总和。您可以从 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))
思考模型会生成完整的想法,以提高最终回答的质量,然后输出摘要,以便深入了解思考过程。因此,价格是根据模型生成摘要所需生成的完整思维令牌计算得出的,尽管 API 只输出摘要。
如需详细了解令牌,请参阅令牌统计指南。
支持的模型
您可以在模型概览页面上找到所有模型功能。
型号 | 思考摘要 | 思考预算 |
---|---|---|
Gemini 2.5 Flash | ✔️ | ✔️ |
Gemini 2.5 Pro | ✔️ | X |
最佳做法
本部分包含一些关于高效使用思维模型的指导。 一如既往,遵循我们的提示指南和最佳实践,您将取得理想的成效。
调试和转向
查看推理过程:如果您未从思考模型获得预期的回答,不妨仔细分析 Gemini 的推理过程。您可以查看它如何拆解任务并得出结论,并使用这些信息来修正结果,以获得正确的结果。
在推理中提供指导:如果您希望获得特别长的输出,则可以在问题中提供指导,以限制模型使用的思考量。这样,您就可以为响应预留更多令牌输出。
任务复杂性
- 简单任务(可以关闭思考):对于不需要复杂推理且直截了当的请求(例如事实检索或分类),无需思考。例如:
- “DeepMind 的创始地在哪里?”
- “这封电子邮件是想安排会议,还是只是提供信息?”
- 中等任务(默认/需要一些思考):许多常见请求都需要进行一定程度的分步处理或更深入的理解。Gemini 可以灵活地使用思考功能来执行以下任务:
- 将光合作用与成长进行类比。
- 比较和对比电动汽车与混合动力汽车。
- 难题(最大思考能力):对于真正复杂的挑战,模型需要调用其全部推理和规划能力,通常需要完成许多内部步骤才能提供答案。例如:
- 解 AIME 2025 题目 1:求所有大于 9 且 17b 是 97b 的因子的整数底数 b 的总和。
- 为可直观呈现实时股市数据(包括用户身份验证)的 Web 应用编写 Python 代码。尽可能提高效率。
利用工具和功能进行思考
思考模型可与 Gemini 的所有工具和功能搭配使用。这样一来,模型就可以与外部系统交互、执行代码或访问实时信息,并将结果纳入其推理和最终回答中。
借助搜索工具,模型可以查询 Google 搜索,以查找最新信息或超出其训练数据范围的信息。这对于有关近期事件或极其具体的主题的问题非常有用。
借助代码执行工具,模型可以生成和运行 Python 代码,以执行计算、处理数据或解决最好通过算法处理的问题。模型会接收代码的输出,并可以在其回答中使用该输出。
借助结构化输出,您可以限制 Gemini 使用 JSON 进行响应。这对于将模型的输出集成到应用中特别有用。
函数调用可将思考模型连接到外部工具和 API,以便推理何时调用正确的函数以及要提供哪些参数。
您可以在思考手册中尝试使用工具与思考模型的示例。
后续操作
如需深入了解示例,请参阅以下内容:
- 在使用工具时思考
- 边思考边直播
- 调整思考预算以获得不同的结果
等内容,请参阅我们的思考手册。
我们的 OpenAI 兼容性指南现已提供思考覆盖率。
如需详细了解 Gemini 2.5 Pro 预览版和 Gemini Flash 2.5 Thinking,请访问模型页面。