التفكير في Gemini

تستخدم نماذج Gemini 3 و2.5 "عملية تفكير" تُحسّن بشكل كبير قدرات الاستدلال والتخطيط المتعدّد الخطوات، ما يجعلها فعّالة للغاية في المهام المعقدة، مثل الترميز والرياضيات المتقدّمة وتحليل البيانات.

عند استخدام نموذج تفكير، يستدلّ Gemini داخليًا قبل الردّ. تعرض واجهة برمجة التطبيقات Interactions API هذا الاستدلال من خلال خطوات thought، وهي خطوات مخصّصة تظهر بترتيب زمني إلى جانب استدعاءات الدوال أو إدخالات المستخدم أو نواتج النموذج في مصفوفة steps.

تحتوي كل خطوة تفكير على حقلَين:

الحقل مطلوب أو اختياري الوصف
signature ✅ نعم تمثيل مشفّر لحالة الاستدلال الداخلي للنموذج يظهر دائمًا، حتى عندما يُجري النموذج الحد الأدنى من الاستدلال
summary ❌ لا مصفوفة من المحتوى (نص و/أو صور) تلخّص الاستدلال قد تكون فارغة استنادًا إلى إعداد thinking_summaries، أو ما إذا كان النموذج قد أجرى ما يكفي من الاستدلال، أو نوع المحتوى (على سبيل المثال، قد لا تحتوي الصور الكامنة على ملخّصات نصية)

التفاعلات مع التفكير

يشبه بدء تفاعل مع نموذج تفكير أيّ طلب تفاعل آخر. حدِّد أحد النماذج التي تتوافق مع التفكير في الحقل model:

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Explain the concept of Occam's Razor and provide a simple, everyday example."
)
print(interaction.steps[-1].content[0].text)

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Explain the concept of Occam's Razor and provide a simple, everyday example."
});
console.log(interaction.steps.at(-1).content[0].text);

راحة

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Explain the concept of Occam'\''s Razor and provide a simple example."
  }'

ملخّصات الأفكار

تقدّم ملخّصات الأفكار إحصاءات عن عملية الاستدلال الداخلي للنموذج. لا يتم عرض سوى الناتج النهائي تلقائيًا. يمكنك تفعيل ملخّصات الأفكار باستخدام thinking_summaries:

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    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:")
        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()

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    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:");
        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);
            }
        }
    }
}

راحة

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "What is the sum of the first 50 prime numbers?",
    "generation_config": {
      "thinking_summaries": "auto"
    }
  }'

قد تحتوي كتلة الأفكار على توقيع فقط بدون ملخّص في الحالات التالية:

  • الطلبات البسيطة، حيث لم يستدلّ النموذج بما يكفي لإنشاء ملخّص
  • thinking_summaries: "none"، حيث يتم إيقاف الملخّصات بشكل صريح
  • قد لا تحتوي أنواع معيّنة من محتوى الأفكار، مثل الصور، على ملخّصات نصية

يجب أن يتعامل الرمز البرمجي دائمًا مع كتل الأفكار التي يكون فيها summary فارغًا أو غير متوفّر.

البث مع التفكير

استخدِم البث لتلقّي ملخّصات الأفكار المتزايدة أثناء الإنشاء. يتم تسليم كتل الأفكار باستخدام أحداث Server-Sent Events (SSE) مع نوعَين مختلفَين من التغييرات الجزئية:

نوع التغيير الجزئي يحتوي على وقت إرسال البيانات
thought_summary محتوى ملخّص نصي أو صورة تغيير جزئي واحد أو أكثر مع ملخّص متزايد
thought_signature التوقيع المشفّر التغيير الجزئي الأخير قبل step.stop

Python

# This will only work for SDK newer than 2.0.0
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-flash-preview",
    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.get('text', '') if hasattr(event.delta, 'content') else getattr(event.delta, '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

JavaScript

// This will only work for SDK newer than 2.0.0
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-flash-preview",
    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;
        }
    }
}

راحة

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  --no-buffer \
  -d '{
    "model": "gemini-3-flash-preview",
    "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
  }'

يستخدم الردّ على البث أحداث Server-Sent Events (SSE) ويتألف من خطوات وأحداث. يُرجى الاطّلاع على المثال أدناه.

event: interaction.created
data: {"interaction":{"id":"v1_xxx","status":"in_progress","object":"interaction","model":"gemini-3-flash-preview"},"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-preview مفعّل (مرتفع) منخفض، متوسط، مرتفع
gemini-3-flash-preview مفعّل (مرتفع) الحد الأدنى، منخفض، متوسط، مرتفع
gemini-3-pro-preview مفعّل (مرتفع) منخفض، مرتفع
gemini-2.5-pro مفعّل منخفض، متوسط، مرتفع
gemini-2.5-flash مفعّل منخفض، متوسط، مرتفع
gemini-2.5-flash-lite إيقاف منخفض، متوسط، مرتفع

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Provide a list of 3 famous physicists and their key contributions",
    generation_config={
        "thinking_level": "low"
    }
)
print(interaction.steps[-1].content[0].text)

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Provide a list of 3 famous physicists and their key contributions",
    generation_config: {
        thinking_level: "low"
    }
});
console.log(interaction.steps.at(-1).content[0].text);

راحة

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Provide a list of 3 famous physicists and their key contributions",
    "generation_config": {
      "thinking_level": "low"
    }
  }'

توقيعات الأفكار

توقيعات الأفكار هي تمثيلات مشفّرة للاستدلال الداخلي للنموذج. وهي مطلوبة للحفاظ على استمرارية الاستدلال في التفاعلات المتعدّدة الأدوار.

تسهّل واجهة برمجة التطبيقات Interactions API التعامل مع توقيعات الأفكار بشكل كبير مقارنةً بواجهة برمجة التطبيقات generateContent.

تلقائيًا، عند استخدام واجهة برمجة التطبيقات Interactions API في الوضع الذي يحفظ الحالة (من خلال ضبط store: true وتمرير previous_interaction_id في الأدوار اللاحقة)، يدير الخادم تلقائيًا حالة المحادثة، بما في ذلك جميع كتل الأفكار والتوقيعات. في هذا الوضع، ليس عليك إجراء أيّ شيء بشأن التوقيعات. تتم معالجتها بالكامل على جانب الخادم.

الوضع الذي لا يحفظ الحالة

إذا كنت تدير حالة المحادثة بنفسك (الوضع الذي لا يحفظ الحالة) وتمرِّر السجلّ الكامل للإدخالات والنواتج في كل طلب:

  • يجب دائمًا إعادة إرسال جميع كتل thought تمامًا كما تم تلقّيها من النموذج.
  • لا يجب إزالة كتل الأفكار أو تعديلها من السجلّ، لأنّها تحتوي على التوقيعات المطلوبة ليواصل النموذج استدلاله.
  • عند التبديل بين النماذج ضمن جلسة، يجب أن تظل تعيد إرسال كتل الأفكار الخاصة بالنموذج السابق. يدير النظام الخلفي التوافق.

الأسعار

عند تفعيل التفكير، يكون سعر الردّ هو مجموع رموز الإخراج ورموز التفكير. يمكنك الحصول على إجمالي عدد رموز التفكير التي تم إنشاؤها من حقل total_thought_tokens.

Python

# This will only work for SDK newer than 2.0.0
# ...
print("Thoughts tokens:", interaction.usage.total_thought_tokens)
print("Output tokens:", interaction.usage.total_output_tokens)

JavaScript

// This will only work for SDK newer than 2.0.0
// ...
console.log(`Thoughts tokens: ${interaction.usage.total_thought_tokens}`);
console.log(`Output tokens: ${interaction.usage.total_output_tokens}`);

تُنشئ نماذج التفكير أفكارًا كاملة لتحسين جودة الردّ النهائي ، ثم تعرض ملخّصات لتقديم إحصاءات عن عملية التفكير. تستند الأسعار إلى رموز التفكير الكاملة التي يحتاج النموذج إلى إنشائها، على الرغم من أنّ واجهة برمجة التطبيقات لا تعرض سوى الملخّص.

يمكنك الاطّلاع على مزيد من المعلومات عن الرموز في دليل احتساب الرموز.

أفضل الممارسات

استخدِم نماذج التفكير بكفاءة من خلال اتّباع هذه الإرشادات.

  • مراجعة الاستدلال: حلِّل ملخّصات الأفكار لفهم حالات الفشل وتحسين الطلبات.
  • التحكّم في ميزانية التفكير: اطلب من النموذج التفكير بشكل أقل في النواتج الطويلة لتوفير الرموز.
  • المهام البسيطة: استخدِم الحد الأدنى من التفكير لاسترداد الحقائق أو التصنيف (مثل "أين تم تأسيس DeepMind؟").
  • المهام المتوسّطة: استخدِم التفكير التلقائي لمقارنة المفاهيم أو الاستدلال الإبداعي (مثل مقارنة السيارات الكهربائية والسيارات الهجينة).
  • المهام المعقدة: استخدِم الحد الأقصى من التفكير للترميز المتقدّم أو الرياضيات أو التخطيط المتعدّد الخطوات (مثل حلّ مسائل الرياضيات في مسابقة AIME).

الخطوات التالية