Gemini 2.5 系列模型採用內部「思考過程」，大幅提升推理和多步驟規劃能力，因此在編碼、進階數學和資料分析等複雜工作上，能發揮極高的效能。
本指南將說明如何使用 Gemini API 運用 Gemini 的思考功能。
事前準備
請務必使用支援的 2.5 系列模型進行思考。在深入研究 API 之前，建議您先在 AI Studio 中探索這些模型：
思考後產生內容
使用思考模型發出要求的做法，與任何其他內容產生要求類似。主要差異在於您必須在 model 欄位中指定一個具備思考支援功能的模型，如以下文字產生範例所示：
Python
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-pro-preview-06-05",
contents=prompt
)
print(response.text)
JavaScript
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-pro-preview-06-05",
contents: prompt,
});
console.log(response.text);
}
main();
Go
// 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-pro-preview-06-05")
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())
}
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-pro-preview-06-05: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 布林值，存取摘要。
以下範例說明如何在不串流的情況下啟用及擷取思想摘要，這會透過回應傳回單一最終思想摘要：
Python
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-pro-preview-06-05",
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({ apiKey: "GOOGLE_API_KEY" });
async function main() {
const response = await ai.models.generateContent({
model: "gemini-2.5-pro-preview-06-05",
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, _ := 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-pro-preview-06-05"
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)
}
}
}
}
以下是使用串流思考方式的範例，可在產生期間傳回滾動式增量摘要：
Python
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-pro-preview-06-05",
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({ 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-pro-preview-06-05",
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 參數，限制模型在生成回覆時，可使用的思考詞元數量。詞元數量越多，一般來說推理就越詳細，有助於處理更複雜的工作。如果您未設定 thinkingBudget，模型會根據要求的複雜度動態調整預算。
thinkingBudget 僅支援 Gemini 2.5 Flash 和 2.5 Pro。視提示內容而定，模型可能會溢出或不足符代碼預算。
以下是各模型類型的設定需求。
Gemini 2.5 Pro
thinkingBudget必須是介於128至32768之間的整數。- 使用 Gemini 2.5 Pro 時，無法關閉思考功能，最低預算為
128。 - 如果未設定
thinkingBudget，模型會自動決定思考預算的使用量。
Gemini 2.5 Flash
thinkingBudget必須是介於0至24576之間的整數。將思考預算設為
0會停用思考功能。
Python
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-2.5-pro-preview-06-05",
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)
JavaScript
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-pro-preview-06-05",
contents: "Provide a list of 3 famous physicists and their key contributions",
config: {
thinkingConfig: {
thinkingBudget: 1024,
},
},
});
console.log(response.text);
}
main();
Go
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-pro-preview-06-05"
resp, _ := client.Models.GenerateContent(ctx, model, contents, &genai.GenerateContentConfig{
ThinkingConfig: &genai.ThinkingConfig{
ThinkingBudget: &thinkingBudgetVal,
},
})
fmt.Println(resp.Text())
}
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-pro-preview-06-05: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 欄位取得產生的思考符記總數。
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))
思考模型會產生完整的思考內容，以提升最終回覆的品質，然後輸出摘要，提供思考過程的洞察資料。因此，定價會以模型建立摘要時需要產生的完整思想符記為依據，即使 API 只輸出摘要也一樣。
如要進一步瞭解權杖，請參閱「權杖計數」指南。
支援的型號
您可以在模型總覽頁面上找到所有模型功能。
| 模型 | 思考摘要 | 思考預算 |
|---|---|---|
| Gemini 2.5 Flash | ✔️ | ✔️ |
| Gemini 2.5 Pro | ✔️ | ✔️ |
最佳做法
本節提供一些指引，說明如何有效運用思考模式。一如往常，只要遵循我們的提示指南和最佳做法，就能獲得最佳成果。
偵錯和轉向
檢查推理過程：如果您沒有從思考模型獲得預期的回應，不妨仔細分析 Gemini 的推理過程。您可以查看系統如何分解工作並得出結論，並利用這些資訊修正正確的結果。
提供推理指引：如果您希望輸出內容特別長，建議您在提示中提供指引，以限制模型使用的思考量。這樣一來，您就能為回應保留更多符號輸出內容。
工作複雜度
- 簡單工作 (思考可能關閉)：如果是不需要複雜推理，例如擷取事實或分類的簡單要求，則不需要思考。例如：
- 「DeepMind 的創辦地點在哪裡？」
- 「這封電子郵件是要求開會，還是只是提供資訊？」
- 中等工作 (預設/部分思考)：許多常見要求都需要逐步處理或深入瞭解。Gemini 可靈活運用思考功能，執行以下任務：
- 將光合作用和生長過程做類比。
- 比較電動汽車和油電混合車。
- 困難任務 (最大思考能力)：對於確實複雜的挑戰，例如解決複雜的數學問題或程式碼編寫工作，建議設定較高的思考預算。這類工作需要模型充分發揮推理和規劃能力，通常在提供答案前會涉及許多內部步驟。例如：
- 解答 AIME 2025 問題 1：找出所有大於 9 的整數基底 b，其中 17b 是 97b 的除數。
- 為網頁應用程式編寫 Python 程式碼，以便將即時股票市場資料 (包括使用者驗證) 以圖形呈現。盡可能提高效率。
運用工具和功能思考
思考模型可搭配 Gemini 的所有工具和功能使用。這可讓模型與外部系統互動、執行程式碼或存取即時資訊，並將結果納入推理和最終回應。
搜尋工具可讓模型查詢 Google 搜尋，找出最新資訊或訓練資料以外的資訊。這類問題適用於近期事件或非常具體的主題。
程式碼執行工具可讓模型生成及執行 Python 程式碼，以便執行運算、操控資料，或解決以演算法最佳處理的問題。模型會接收程式碼的輸出內容，並可在回應中使用該輸出內容。
您可以使用結構化輸出，限制 Gemini 以 JSON 回應。這對於將模型輸出內容整合至應用程式特別實用。
函式呼叫可將思考模型連結至外部工具和 API，進而推斷何時呼叫正確的函式，以及要提供哪些參數。
您可以參考思考教戰手冊中的範例，瞭解如何使用工具搭配思考模式。
後續步驟
如要進一步瞭解其他範例，請參考以下內容：
- 使用工具思考
- 思考串流
- 根據不同結果調整思考預算
等內容，歡迎試試我們的思考食譜。
思考涵蓋範圍現已納入 OpenAI 相容性指南。
如要進一步瞭解 Gemini 2.5 Pro 預先發布版和 Gemini Flash 2.5 思考，請參閱模型頁面。