Gemini 2.5 系列模型採用內部「思考過程」,大幅提升推理和多步驟規劃能力,因此在編碼、進階數學和資料分析等複雜工作上,能發揮極高的效能。
本指南將說明如何使用 Gemini API 運用 Gemini 的思考功能。
事前準備
請務必使用支援的 2.5 系列模型進行思考。在深入瞭解 API 之前,建議您先在 AI Studio 中探索這些模型:
- 在 AI 工作室中試用 Gemini 2.5 Flash
- 在 AI Studio 中試用 Gemini 2.5 Pro
- 在 AI Studio 中試用 Gemini 2.5 Flash-Lite 預覽版
思考後產生內容
使用思考模型發出要求的做法,與任何其他內容產生要求類似。主要差異在於您必須在 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", 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", 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") 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: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." } ] } ] }' ```
思考預算
thinkingBudget
參數可引導模型在產生回覆時,使用思考符號的數量。詞元數量越高,推理過程通常會越詳細,有助於處理更複雜的工作。將 thinkingBudget
設為 -1 會啟用動態思考功能,也就是說模型會根據要求的複雜度調整預算。
thinkingBudget
僅支援 Gemini 2.5 Flash、2.5 Pro 和 2.5 Flash-Lite。視提示而定,模型可能會溢出或不足符號預算。
以下是各模型類型的 thinkingBudget
設定詳細資料。
模型 | 預設設定 (未設定思考預算) | 範圍 | 停用思考功能 | 啟用動態思考 |
---|---|---|---|---|
2.5 Pro | 動態思考:模型決定思考的時機和程度 | 128 至 32768 | 不適用:無法停用思考 | thinkingBudget = -1 |
2.5 Flash | 動態思考:模型決定思考的時機和程度 | 0 至 24576 | thinkingBudget = 0 | thinkingBudget = -1 |
2.5 Flash Lite | 模型不會思考 | 512 至 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) ), ) 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", 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" 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: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 } } }'
思想摘要 (實驗功能)
想法摘要是模型原始想法的合成版本,可提供模型內部推理過程的洞察資料。請注意,思考預算會套用至模型的原始想法,而非想法摘要。
您可以在要求設定中將 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", 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", 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" 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", 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", 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();
定價
啟用思考功能後,回應定價就是輸出符記和思考符記的總和。您可以從 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 2.5 Flash Lite | ✔️ | ✔️ |
最佳做法
本節提供一些指引,說明如何有效運用思考模式。一如往常,只要遵循我們的提示指南和最佳做法,就能獲得最佳成果。
偵錯和轉向
查看推論:如果思考模型未提供預期的回應,建議仔細分析 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 和 Gemini 2.5 Flash-Lite,請參閱模型頁面。