تفكير Gemini

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

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

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

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

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

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

Python

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)

JavaScript

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:

Python

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()

JavaScript

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 فارغًا أو غير متوفّر.

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

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

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

Python

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

JavaScript

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
  }'

يستخدم الردّ على البث أحداث Server-Sent Events (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-preview مفعّل (عالي) منخفض، متوسط، عالي
gemini-3-flash-preview مفعّل (عالي) منخفض، متوسط، عالي
gemini-3-pro-preview مفعّل (عالي) منخفض، عالي
gemini-3.5-flash مفعّل (متوسط) منخفض، متوسط، عالي
gemini-2.5-pro مفعّل منخفض، متوسط، عالي
gemini-2.5-flash مفعّل منخفض، متوسط، عالي
gemini-2.5-flash-lite إيقاف منخفض، متوسط، عالي

Python

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)

JavaScript

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"
    }
  }'

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

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

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

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

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

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

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

الأسعار

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

Python

print("Thoughts tokens:", interaction.usage.total_thought_tokens)
print("Output tokens:", interaction.usage.total_output_tokens)

JavaScript

console.log(`Thoughts tokens: ${interaction.usage.total_thought_tokens}`);
console.log(`Output tokens: ${interaction.usage.total_output_tokens}`);

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

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

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

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

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

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