مدلهای سری Gemini 3 و 2.5 از یک «فرآیند تفکر» استفاده میکنند که به طور قابل توجهی تواناییهای استدلال و برنامهریزی چند مرحلهای آنها را بهبود میبخشد و آنها را برای کارهای پیچیدهای مانند کدنویسی، ریاضیات پیشرفته و تجزیه و تحلیل دادهها بسیار مؤثر میکند.
وقتی از یک مدل تفکر استفاده میکنید، Gemini قبل از پاسخ دادن، استدلال درونی میکند. API تعاملات این استدلال را از طریق مراحل thought ، مراحل اختصاصی که به ترتیب زمانی در کنار فراخوانیهای تابع، ورودیهای کاربر یا خروجیهای مدل در آرایه steps ظاهر میشوند، آشکار میکند.
هر گام فکری شامل دو فیلد است:
| میدان | مورد نیاز | توضیحات |
|---|---|---|
signature | ✅ بله | یک نمایش رمزگذاریشده از وضعیت استدلال داخلی مدل. همیشه وجود دارد، حتی زمانی که مدل کمترین استدلال را انجام میدهد. |
summary | ❌ خیر | آرایهای از محتوا (متن و/یا تصاویر) که خلاصهای از استدلال را ارائه میدهد. بسته به پیکربندی thinking_summaries ، اینکه آیا مدل به اندازه کافی استدلال انجام داده است یا خیر، یا نوع محتوا (برای مثال، تصاویر نهفته ممکن است خلاصه متنی نداشته باشند)، ممکن است خالی باشد. |
شروع تعامل با یک مدل متفکر مشابه هر درخواست تعامل دیگری است. یکی از مدلهای دارای پشتیبانی تفکر را در فیلد model مشخص کنید:
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.5-flash",
input="Explain the concept of Occam's Razor and provide a simple, everyday example."
)
print(interaction.output_text)
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: "gemini-3.5-flash",
input: "Explain the concept of Occam's Razor and provide a simple, everyday example."
});
console.log(interaction.output_text);
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.5-flash",
"input": "Explain the concept of Occam'\''s Razor and provide a simple example."
}'
خلاصههای تفکر، بینشهایی در مورد فرآیند استدلال داخلی مدل ارائه میدهند. به طور پیشفرض، فقط خروجی نهایی بازگردانده میشود. میتوانید خلاصههای تفکر را با thinking_summaries فعال کنید:
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.5-flash",
input="What is the sum of the first 50 prime numbers?",
generation_config={
"thinking_summaries": "auto"
}
)
for step in interaction.steps:
if step.type == "thought":
print("Thought summary:")
if step.summary:
for content_block in step.summary:
if content_block.type == "text":
print(content_block.text)
print()
elif step.type == "model_output":
for content_block in step.content:
if content_block.type == "text":
print("Answer:")
print(content_block.text)
print()
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: "gemini-3.5-flash",
input: "What is the sum of the first 50 prime numbers?",
generation_config: {
thinking_summaries: "auto"
}
});
for (const step of interaction.steps) {
if (step.type === "thought") {
console.log("Thought summary:");
if (step.summary) {
for (const contentBlock of step.summary) {
if (contentBlock.type === "text") console.log(contentBlock.text);
}
}
} else if (step.type === "model_output") {
for (const contentBlock of step.content) {
if (contentBlock.type === "text") {
console.log("Answer:");
console.log(contentBlock.text);
}
}
}
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.5-flash",
"input": "What is the sum of the first 50 prime numbers?",
"generation_config": {
"thinking_summaries": "auto"
}
}'
یک انسداد فکری ممکن است در این موارد فقط شامل یک امضا باشد و خلاصهای نداشته باشد :
- درخواستهای ساده، که در آنها مدل دلیل کافی برای تولید خلاصه نداشت
-
thinking_summaries: "none"، که در آن خلاصهها به صراحت غیرفعال هستند - برخی از انواع محتوای فکری، مانند تصاویر، ممکن است خلاصه متنی نداشته باشند.
کد شما باید همیشه بلوکهای فکری را که در آنها summary خالی است یا وجود ندارد، مدیریت کند.
از جریانسازی برای دریافت خلاصههای تدریجی افکار در طول تولید استفاده کنید. بلوکهای فکری با استفاده از رویدادهای ارسالی از سرور (SSE) با دو نوع دلتای متمایز ارائه میشوند:
| نوع دلتا | شامل | هنگام ارسال |
|---|---|---|
thought_summary | محتوای خلاصه متن یا تصویر | یک یا چند دلتا با خلاصه افزایشی |
thought_signature | امضای رمزنگاری شده | آخرین دلتا قبل از step.stop |
from google import genai
client = genai.Client()
prompt = """
Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue.
Alice does not live in the red house.
Bob does not live in the green house.
Carol does not live in the red or green house.
Which house does each person live in?
"""
thoughts = ""
answer = ""
stream = client.interactions.create(
model="gemini-3.5-flash",
input=prompt,
generation_config={
"thinking_summaries": "auto"
},
stream=True
)
for event in stream:
if event.event_type == "step.delta":
if event.delta.type == "thought_summary":
if not thoughts:
print("Thinking...")
summary_text = event.delta.content.text
print(f"[Thought] {summary_text}", end="")
thoughts += summary_text
elif event.delta.type == "text" and event.delta.text:
if not answer:
print("\nAnswer:")
print(event.delta.text, end="")
answer += event.delta.text
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const prompt = `Alice, Bob, and Carol each live in a different house on the same
street: red, green, and blue. Alice does not live in the red house.
Bob does not live in the green house.
Carol does not live in the red or green house.
Which house does each person live in?`;
let thoughts = "";
let answer = "";
const stream = await client.interactions.create({
model: "gemini-3.5-flash",
input: prompt,
generation_config: {
thinking_summaries: "auto"
},
stream: true
});
for await (const event of stream) {
if (event.event_type === "step.delta") {
if (event.delta.type === "thought_summary") {
if (!thoughts) console.log("Thinking...");
const text = event.delta.content?.text || "";
process.stdout.write(`[Thought] ${text}`);
thoughts += text;
} else if (event.delta.type === "text" && event.delta.text) {
if (!answer) console.log("\nAnswer:");
process.stdout.write(event.delta.text);
answer += event.delta.text;
}
}
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
--no-buffer \
-d '{
"model": "gemini-3.5-flash",
"input": "Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue. Alice does not live in the red house. Bob does not live in the green house. Carol does not live in the red or green house. Which house does each person live in?",
"generation_config": {
"thinking_summaries": "auto"
},
"stream": true
}'
پاسخ استریمینگ از رویدادهای ارسالی از سرور (SSE) استفاده میکند و از مراحل و رویدادهایی تشکیل شده است، به عنوان مثال:
event: interaction.created
data: {"interaction":{"id":"v1_xxx","status":"in_progress","object":"interaction","model":"gemini-3.5-flash"},"event_type":"interaction.created"}
event: step.start
data: {"index":0,"step":{"signature":"","summary":[{"text":"**Evaluating the clues**\n\nI'm considering...","type":"text"}],"type":"thought"},"event_type":"step.start"}
event: step.delta
data: {"index":0,"delta":{"signature":"EpoGCpcGAXLI2nx/...","type":"thought_signature"},"event_type":"step.delta"}
event: step.stop
data: {"index":0,"event_type":"step.stop"}
event: step.start
data: {"index":1,"step":{"content":[{"text":"Based on the clues provided, here","type":"text"}],"type":"model_output"},"event_type":"step.start"}
event: step.delta
data: {"index":1,"delta":{"text":" is the answer to your question...","type":"text"},"event_type":"step.delta"}
event: step.stop
data: {"index":1,"event_type":"step.stop"}
event: interaction.completed
data: {"interaction":{"id":"v1_xxx","status":"completed","usage":{"total_tokens":530,"total_input_tokens":62,"total_output_tokens":171,"total_thought_tokens":297}},"event_type":"interaction.completed"}
event: done
data: [DONE]
مدلهای Gemini به طور پیشفرض در تفکر پویا درگیر هستند و به طور خودکار میزان تلاش استدلال را بر اساس پیچیدگی درخواست تنظیم میکنند. شما میتوانید این رفتار را با استفاده از پارامتر thinking_level کنترل کنید.
| مدل | تفکر پیشفرض | سطوح پشتیبانی شده |
|---|---|---|
| پیشنمایش gemini 3.1 pro | روشن (زیاد) | کم، متوسط، زیاد |
| تصاویر-فلش-لایت-gemini-3.1 | روشن (حداقل) | حداقل، زیاد |
| پیشنمایش gemini-3-flash | روشن (زیاد) | حداقل، کم، متوسط، زیاد |
| پیشنمایش gemini-3-pro | روشن (زیاد) | کم، زیاد |
| فلش جمینی ۳.۵ | روشن (متوسط) | حداقل، کم، متوسط، زیاد |
| جمینی ۲.۵ پرو | روشن | کم، متوسط، زیاد |
| فلش جمینی ۲.۵ | روشن | کم، متوسط، زیاد |
| جمینی ۲.۵-فلش لایت | خاموش | کم، متوسط، زیاد |
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.5-flash",
input="Provide a list of 3 famous physicists and their key contributions",
generation_config={
"thinking_level": "low"
}
)
print(interaction.output_text)
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: "gemini-3.5-flash",
input: "Provide a list of 3 famous physicists and their key contributions",
generation_config: {
thinking_level: "low"
}
});
console.log(interaction.output_text);
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.5-flash",
"input": "Provide a list of 3 famous physicists and their key contributions",
"generation_config": {
"thinking_level": "low"
}
}'
امضاهای فکری، بازنماییهای رمزگذاریشده از استدلال درونی مدل هستند. آنها برای حفظ پیوستگی استدلال در تعاملات چند نوبتی مورد نیاز هستند.
رابط برنامهنویسی کاربردی (API) تعاملات، مدیریت امضاهای فکری را بسیار سادهتر از رابط برنامهنویسی کاربردی generateContent API) میکند.
به طور پیشفرض، وقتی از API تعاملات در حالت stateful استفاده میکنید (با تنظیم store: true و ارسال previous_interaction_id در نوبتهای بعدی)، سرور به طور خودکار وضعیت مکالمه، شامل تمام بلوکهای فکری و امضاها را مدیریت میکند. در این حالت، لازم نیست کاری در مورد امضاها انجام دهید. آنها کاملاً در سمت سرور مدیریت میشوند.
اگر خودتان وضعیت مکالمه را مدیریت میکنید (حالت بدون وضعیت) و تاریخچه کامل ورودیها و خروجیها را در هر درخواست ارسال میکنید:
- شما همیشه باید تمام بلوکهای
thoughtرا دقیقاً همانطور که از مدل دریافت شدهاند، دوباره ارسال کنید. - شما نباید بلوکهای فکری را از تاریخچه حذف یا اصلاح کنید، زیرا آنها حاوی امضاهای مورد نیاز مدل برای ادامه استدلال خود هستند.
- هنگام تغییر مدلها در یک جلسه، شما همچنان باید بلوکهای فکری مدل قبلی را دوباره ارسال کنید. backend سازگاری را مدیریت میکند.
وقتی تفکر فعال باشد، قیمتگذاری پاسخ، مجموع توکنهای خروجی و توکنهای تفکر است. میتوانید تعداد کل توکنهای تفکر تولید شده را از فیلد total_thought_tokens دریافت کنید.
print("Thoughts tokens:", interaction.usage.total_thought_tokens)
print("Output tokens:", interaction.usage.total_output_tokens)
console.log(`Thoughts tokens: ${interaction.usage.total_thought_tokens}`);
console.log(`Output tokens: ${interaction.usage.total_output_tokens}`);
مدلهای تفکر، افکار کاملی را برای بهبود کیفیت پاسخ نهایی تولید میکنند و سپس خلاصههایی را برای ارائه بینش در مورد فرآیند تفکر، ارائه میدهند. قیمتگذاری بر اساس توکنهای فکری کاملی است که مدل باید تولید کند، با وجود اینکه فقط خلاصه از API خروجی گرفته میشود.
میتوانید در راهنمای شمارش توکنها، اطلاعات بیشتری در مورد توکنها کسب کنید.
با پیروی از این دستورالعملها، از مدلهای تفکر به طور مؤثر استفاده کنید.
- مرور استدلال : خلاصه افکار را تجزیه و تحلیل کنید تا شکستها را بفهمید و نکات را بهبود بخشید.
- کنترل بودجه تفکر : مدل را وادار کنید تا برای صرفهجویی در توکنها، کمتر به خروجیهای طولانی فکر کند.
- وظایف ساده : از تفکر حداقلی یا سطح پایین برای بازیابی یا طبقهبندی حقایق استفاده کنید (مثلاً «دیپمایند کجا تأسیس شد؟»).
- وظایف متوسط : از تفکر پیشفرض برای مقایسه مفاهیم یا استدلال خلاقانه استفاده کنید (مثلاً مقایسه خودروهای برقی و هیبریدی).
- وظایف پیچیده : از حداکثر تفکر برای کدنویسی پیشرفته، ریاضی یا برنامهریزی چند مرحلهای استفاده کنید (مثلاً حل مسائل ریاضی AIME).
- تولید متن : پاسخهای متنی پایه
- فراخوانی تابع : اتصال به ابزارها
- راهنمای Gemini 3 : ویژگیهای خاص هر مدل