مدلهای سری Gemini 3 و 2.5 از یک «فرآیند تفکر» داخلی استفاده میکنند که به طور قابل توجهی تواناییهای استدلال و برنامهریزی چند مرحلهای آنها را بهبود میبخشد و آنها را برای کارهای پیچیدهای مانند کدنویسی، ریاضیات پیشرفته و تجزیه و تحلیل دادهها بسیار مؤثر میکند.
این راهنما به شما نشان میدهد که چگونه با استفاده از رابط برنامهنویسی نرمافزار Gemini، با قابلیتهای تفکر Gemini کار کنید.
تولید محتوا با تفکر
شروع یک درخواست با یک مدل تفکر مشابه هر درخواست تولید محتوای دیگری است. تفاوت کلیدی در مشخص کردن یکی از مدلهای دارای پشتیبانی تفکر در فیلد model است، همانطور که در مثال تولید متن زیر نشان داده شده است:
پایتون
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)
جاوا اسکریپت
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();
برو
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())
}
استراحت
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."
}
]
}
]
}'
```
خلاصههای فکری
خلاصههای فکری، نسخههای ترکیبی از افکار خام مدل هستند و بینشهایی در مورد فرآیند استدلال درونی مدل ارائه میدهند. توجه داشته باشید که سطوح و بودجههای فکری در مورد افکار خام مدل اعمال میشوند و نه در مورد خلاصههای فکری.
شما میتوانید با تنظیم includeThoughts روی true در پیکربندی درخواست خود، خلاصههای تفکر را فعال کنید. سپس میتوانید با پیمایش parts پارامتر response و بررسی مقدار بولی thought ، به خلاصه دسترسی پیدا کنید.
در اینجا مثالی آورده شده است که نحوه فعالسازی و بازیابی خلاصه افکار بدون جریانسازی را نشان میدهد، که یک خلاصه فکر نهایی و واحد را به همراه پاسخ برمیگرداند:
پایتون
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()
جاوا اسکریپت
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();
برو
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)
}
}
}
}
و در اینجا مثالی با استفاده از تفکر با جریانسازی آورده شده است که خلاصههای افزایشی و غلتان را در طول تولید برمیگرداند:
پایتون
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
جاوا اسکریپت
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();
برو
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)
}
}
}
}
کنترل تفکر
مدلهای Gemini به طور پیشفرض در تفکر پویا مشارکت میکنند و به طور خودکار میزان تلاش استدلال را بر اساس پیچیدگی درخواست کاربر تنظیم میکنند. با این حال، اگر محدودیتهای تأخیر خاصی دارید یا نیاز دارید که مدل در استدلال عمیقتر از حد معمول مشارکت کند، میتوانید به صورت اختیاری از پارامترهایی برای کنترل رفتار تفکر استفاده کنید.
سطوح تفکر (Gemini 3 Pro)
پارامتر thinkingLevel که برای مدلهای Gemini 3 و بالاتر توصیه میشود، به شما امکان کنترل رفتار استدلالی را میدهد. میتوانید سطح تفکر را روی "low" یا "high" تنظیم کنید. اگر سطح تفکری را مشخص نکنید، Gemini از سطح تفکر پویای پیشفرض مدل، یعنی "high" ، برای پیشنمایش Gemini 3 Pro استفاده خواهد کرد.
پایتون
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)
جاوا اسکریپت
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();
برو
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())
}
استراحت
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"
}
}
}'
شما نمیتوانید thinking را برای Gemini 3 Pro غیرفعال کنید. مدلهای سری Gemini 2.5 از thinkingLevel پشتیبانی نمیکنند؛ به جای آن thinkingBudget استفاده کنید.
بودجههای در نظر گرفته شده
پارامتر thinkingBudget که با سری Gemini 2.5 معرفی شد، مدل را در مورد تعداد مشخصی از توکنهای تفکر برای استفاده در استدلال راهنمایی میکند.
جزئیات پیکربندی thinkingBudget برای هر نوع مدل در زیر آمده است. میتوانید با تنظیم thinkingBudget روی ۰، thinking را غیرفعال کنید. تنظیم thinkingBudget روی -۱، تفکر پویا را فعال میکند، به این معنی که مدل، بودجه را بر اساس پیچیدگی درخواست تنظیم میکند.
| مدل | تنظیم پیشفرض (فکر کنم بودجه تعیین نشده) | محدوده | غیرفعال کردن تفکر | تفکر پویا را فعال کنید |
|---|---|---|---|---|
| ۲.۵ پرو | تفکر پویا: مدل تصمیم میگیرد چه زمانی و چقدر فکر کند | 128 تا 32768 | ناموجود: نمیتوان تفکر را غیرفعال کرد | thinkingBudget = -1 |
| ۲.۵ فلش | تفکر پویا: مدل تصمیم میگیرد چه زمانی و چقدر فکر کند | 0 تا 24576 | thinkingBudget = 0 | thinkingBudget = -1 |
| پیشنمایش فلش ۲.۵ | تفکر پویا: مدل تصمیم میگیرد چه زمانی و چقدر فکر کند | 0 تا 24576 | thinkingBudget = 0 | thinkingBudget = -1 |
| ۲.۵ فلش لایت | مدل فکر نمیکند | 512 تا 24576 | thinkingBudget = 0 | thinkingBudget = -1 |
| پیشنمایش فلش لایت ۲.۵ | مدل فکر نمیکند | 512 تا 24576 | thinkingBudget = 0 | thinkingBudget = -1 |
| پیشنمایش Robotics-ER 1.5 | تفکر پویا: مدل تصمیم میگیرد چه زمانی و چقدر فکر کند | 0 تا 24576 | thinkingBudget = 0 | thinkingBudget = -1 |
| پیشنمایش صوتی بومی Flash Live 2.5 (09-2025) | تفکر پویا: مدل تصمیم میگیرد چه زمانی و چقدر فکر کند | 0 تا 24576 | thinkingBudget = 0 | thinkingBudget = -1 |
پایتون
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)
جاوا اسکریپت
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();
برو
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())
}
استراحت
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
}
}
}'
بسته به اعلان، مدل ممکن است از بودجه توکن سرریز یا کمتر از حد مجاز داشته باشد.
امضاهای فکری
رابط برنامهنویسی Gemini بدون وضعیت (stateless) است، بنابراین مدل با هر درخواست API به طور مستقل رفتار میکند و در تعاملات چند نوبتی به محتوای فکری نوبتهای قبلی دسترسی ندارد.
به منظور فعال کردن حفظ زمینه فکری در تعاملات چند نوبتی، Gemini امضاهای فکری را برمیگرداند که بازنماییهای رمزگذاریشدهای از فرآیند فکری داخلی مدل هستند.
- مدلهای Gemini 2.5 وقتی قابلیت تفکر فعال باشد و درخواست شامل فراخوانی تابع ، به ویژه اعلانهای تابع باشد ، امضاهای فکری را برمیگردانند.
- مدلهای Gemini 3 ممکن است امضاهای فکری را برای انواع قطعات برگردانند. توصیه میکنیم همیشه همه امضاها را به همان صورت که دریافت شدهاند، برگردانید، اما برای امضاهای فراخوانی تابع لازم است. برای کسب اطلاعات بیشتر، صفحه امضاهای فکری را مطالعه کنید.
کیت توسعه نرمافزاری Google GenAI به طور خودکار بازگشت امضاهای فکری را برای شما مدیریت میکند. فقط در صورتی که سابقه مکالمه را تغییر میدهید یا از REST API استفاده میکنید، باید امضاهای فکری را به صورت دستی مدیریت کنید .
سایر محدودیتهای کاربردی که باید در فراخوانی تابع در نظر گرفته شوند عبارتند از:
- امضاها از مدل در بخشهای دیگر پاسخ، مثلاً فراخوانی تابع یا بخشهای متنی، بازگردانده میشوند. کل پاسخ را به همراه تمام بخشها در نوبتهای بعدی به مدل برگردانید .
- بخشهایی که امضا دارند را به هم وصل نکنید.
- یک قسمت دارای امضا را با قسمت بدون امضا ادغام نکنید.
قیمتگذاری
وقتی تفکر فعال باشد، قیمتگذاری پاسخ، مجموع توکنهای خروجی و توکنهای تفکر است. میتوانید تعداد کل توکنهای تفکر تولید شده را از فیلد 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 میتواند مفید باشد. میتوانید ببینید که چگونه کار را تجزیه کرده و به نتیجه رسیده است و از آن اطلاعات برای اصلاح به سمت نتایج درست استفاده کنید.
ارائه راهنمایی در استدلال : اگر انتظار خروجی طولانی دارید، میتوانید در اعلان خود راهنمایی ارائه دهید تا میزان تفکر مورد استفاده مدل را محدود کنید. این به شما امکان میدهد خروجی توکن بیشتری را برای پاسخ خود رزرو کنید.
پیچیدگی وظیفه
- وظایف آسان (تفکر میتواند غیرفعال باشد): برای درخواستهای سادهای که در آنها استدلال پیچیدهای لازم نیست، مانند بازیابی یا طبقهبندی حقایق، تفکر لازم نیست. مثالها عبارتند از:
- «دیپمایند کجا تأسیس شد؟»
- «آیا این ایمیل درخواست جلسه است یا فقط ارائه اطلاعات؟»
- وظایف متوسط (پیشفرض/کمی تفکر): بسیاری از درخواستهای رایج از درجهای از پردازش گام به گام یا درک عمیقتر بهرهمند میشوند. Gemini میتواند به طور انعطافپذیری از قابلیت تفکر برای وظایفی مانند موارد زیر استفاده کند:
- فتوسنتز و بزرگ شدن را با هم مقایسه کنید.
- مقایسه و بررسی خودروهای برقی و هیبریدی.
- وظایف سخت (حداکثر توانایی تفکر): برای چالشهای واقعاً پیچیده، مانند حل مسائل پیچیده ریاضی یا وظایف کدنویسی، توصیه میکنیم بودجهای با تفکر بالا تعیین کنید. این نوع وظایف مستلزم آن است که مدل از تمام قابلیتهای استدلال و برنامهریزی خود استفاده کند، که اغلب شامل مراحل داخلی زیادی قبل از ارائه پاسخ است. مثالها عبارتند از:
- مسئله ۱ را در AIME 2025 حل کنید: مجموع تمام پایههای صحیح b > 9 را بیابید که در آنها ۱۷b مقسومعلیه ۹۷b باشد.
- کد پایتون را برای یک برنامه وب بنویسید که دادههای بازار سهام را به صورت بلادرنگ، از جمله احراز هویت کاربر، نمایش میدهد. آن را تا حد امکان کارآمد کنید.
مدلها، ابزارها و قابلیتهای پشتیبانیشده
ویژگیهای Thinking در تمام مدلهای سری ۳ و ۲.۵ پشتیبانی میشوند. میتوانید تمام قابلیتهای مدل را در صفحه نمای کلی مدل پیدا کنید.
مدلهای تفکر با تمام ابزارها و قابلیتهای Gemini کار میکنند. این به مدلها اجازه میدهد تا با سیستمهای خارجی تعامل داشته باشند، کد را اجرا کنند یا به اطلاعات بلادرنگ دسترسی داشته باشند و نتایج را در استدلال و پاسخ نهایی خود بگنجانند.
میتوانید مثالهایی از استفاده از ابزارها با مدلهای تفکر را در کتاب آشپزی تفکر امتحان کنید.
بعدش چی؟
- پوشش Thinking در راهنمای سازگاری OpenAI ما موجود است.