دليل المطوّرين في Gemini 3

‫Gemini 3 هي مجموعة النماذج الأكثر تطورًا لدينا حتى الآن، وهي تستند إلى أساس متقدّم من الاستدلال. تم تصميم هذه الأداة لتحويل أي فكرة إلى واقع من خلال إتقان مهام سير العمل المستندة إلى الذكاء الاصطناعي الوكيل، والترميز الذاتي، والمهام المعقّدة المتعددة الوسائط. يتناول هذا الدليل الميزات الرئيسية لعائلة نماذج Gemini 3 وكيفية الاستفادة منها إلى أقصى حدّ.

التفكير العالي/الديناميكي التفكير المنخفض

يستخدم Gemini 3 Pro التفكير الديناميكي تلقائيًا للتعامل مع الطلبات. للحصول على ردود أسرع وبزمن استجابة أقل عندما لا يكون التفكير المعقّد مطلوبًا، يمكنك حصر مستوى التفكير في النموذج على low.

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
)

print(response.text)

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
  });

  console.log(response.text);
}

run();

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": "Find the race condition in this multi-threaded C++ snippet: [code here]"}]
    }]
  }'

استكشاف

يمكنك استكشاف مجموعة تطبيقات Gemini 3 لمعرفة كيف يتعامل النموذج مع الاستدلال المتقدّم والترميز الذاتي والمهام المعقّدة المتعددة الوسائط.

تعرَّف على Gemini 3

‫Gemini 3 Pro هو النموذج الأول في السلسلة الجديدة. gemini-3-pro-preview هو الخيار الأفضل للمهام المعقّدة التي تتطلّب معرفة واسعة بالعالم واستدلالاً متقدّمًا على مستوى الوسائط.

* الأسعار لكل مليون رمز مميز. الأسعار المدرَجة هي للرسائل النصية العادية، وقد تختلف أسعار الإدخال المتعدد الوسائط.

للاطّلاع على حدود المعدّل التفصيلية وأسعار الدفعات والمزيد من المعلومات، يُرجى الانتقال إلى صفحة النماذج.

ميزات جديدة في واجهة برمجة التطبيقات في Gemini 3

يقدّم Gemini 3 مَعلمات جديدة مصمّمة لمنح المطوّرين مزيدًا من التحكّم في وقت الاستجابة والتكلفة ودقة الوسائط المتعددة.

مستوى التفكير

تتحكّم المَعلمة thinking_level في الحدّ الأقصى لعمق عملية الاستدلال الداخلية للنموذج قبل أن ينتج ردًا. يتعامل Gemini 3 مع هذه المستويات على أنّها مخصصات نسبية للتفكير بدلاً من ضمانات صارمة للرموز المميزة. إذا لم يتم تحديد thinking_level، سيتم تلقائيًا ضبط Gemini 3 Pro على high.

• ‫low: تقلّل من وقت الاستجابة والتكلفة. الأفضل للتطبيقات التي تتطلّب اتّباع تعليمات بسيطة أو المحادثة أو التطبيقات التي تعالج البيانات بسرعة كبيرة
• ‫medium: (ستتوفّر قريبًا)، غير متاحة عند الإطلاق
• high (تلقائي): يزيد عمق الاستدلال إلى أقصى حدّ. قد يستغرق النموذج وقتًا أطول بكثير للوصول إلى الرمز المميز الأول، ولكن سيكون الناتج أكثر دقة.

درجة دقة الوسائط

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

يمكنك الآن ضبط الدقة على media_resolution_low أو media_resolution_medium أو media_resolution_high لكل جزء من الوسائط على حدة أو على مستوى العالم (من خلال generation_config). وفي حال عدم تحديدها، يستخدم النموذج الإعدادات التلقائية المثالية استنادًا إلى نوع الوسائط.

الإعدادات المقترَحة

from google import genai
from google.genai import types
import base64

# The media_resolution parameter is currently only available in the v1alpha API version.
client = genai.Client(http_options={'api_version': 'v1alpha'})

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents=[
        types.Content(
            parts=[
                types.Part(text="What is in this image?"),
                types.Part(
                    inline_data=types.Blob(
                        mime_type="image/jpeg",
                        data=base64.b64decode("..."),
                    ),
                    media_resolution={"level": "media_resolution_high"}
                )
            ]
        )
    ]
)

print(response.text)

import { GoogleGenAI } from "@google/genai";

// The media_resolution parameter is currently only available in the v1alpha API version.
const ai = new GoogleGenAI({ apiVersion: "v1alpha" });

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: [
      {
        parts: [
          { text: "What is in this image?" },
          {
            inlineData: {
              mimeType: "image/jpeg",
              data: "...",
            },
            mediaResolution: {
              level: "media_resolution_high"
            }
          }
        ]
      }
    ]
  });

  console.log(response.text);
}

run();

curl "https://generativelanguage.googleapis.com/v1alpha/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": "What is in this image?" },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "..."
          },
          "mediaResolution": {
            "level": "media_resolution_high"
          }
        }
      ]
    }]
  }'

درجة الحرارة

بالنسبة إلى Gemini 3، ننصحك بشدة بإبقاء مَعلمة درجة الحرارة على قيمتها التلقائية البالغة 1.0.

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

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

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

• استدعاء الدوال (وضع صارم): تفرض واجهة برمجة التطبيقات التحقّق الصارم من صحة "الجولة الحالية". سيؤدي عدم توفّر التواقيع إلى حدوث خطأ 400.
• النص/المحادثة: لا يتم فرض التحقّق من الصحة بشكل صارم، ولكن سيؤدي حذف التوقيعات إلى خفض جودة التفكير والإجابات في النموذج.

استدعاء الدالة (التحقّق الدقيق)

عندما ينشئ Gemini functionCall، يعتمد على thoughtSignature لمعالجة نتيجة الأداة بشكل صحيح في الجولة التالية. يتضمّن "الدور الحالي" جميع خطوات "النموذج" (functionCall) و"المستخدم" (functionResponse) التي حدثت منذ آخر رسالة مستخدم text عادية.

• استدعاء دالة واحدة: يحتوي الجزء functionCall على توقيع. يجب إرجاعها.
• عمليات استدعاء الدوال المتوازية: سيحتوي الجزء الأول فقط من functionCall في القائمة على التوقيع. يجب إرجاع الأجزاء بالترتيب نفسه الذي تم استلامها به.
• متعددة الخطوات (متسلسلة): إذا استدعى النموذج أداة، وتلقّى نتيجة، واستدعى أداة أخرى (في نفس الجولة)، سيكون لكلتا استدعاءَي الدالتَين توقيعات. يجب عرض جميع التواقيع المتراكمة في السجلّ.

النص والبث

بالنسبة إلى المحادثات العادية أو إنشاء النصوص، لا يمكن ضمان ظهور توقيع.

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

أمثلة على الرموز

// Model Response (Turn 1, Step 1)
  {
    "role": "model",
    "parts": [
      {
        "functionCall": { "name": "check_flight", "args": {...} },
        "thoughtSignature": "<Sig_A>" // SAVE THIS
      }
    ]
  }

// User Request (Turn 1, Step 2)
[
  { "role": "user", "parts": [{ "text": "Check flight AA100..." }] },
  { 
    "role": "model", 
    "parts": [
      { 
        "functionCall": { "name": "check_flight", "args": {...} }, 
        "thoughtSignature": "<Sig_A>" // REQUIRED
      } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": { "name": "check_flight", "response": {...} } }] }
]

// Model Response (Turn 1, Step 3)
{
  "role": "model",
  "parts": [
    {
      "functionCall": { "name": "book_taxi", "args": {...} },
      "thoughtSignature": "<Sig_B>" // SAVE THIS
    }
  ]
}

// User Request (Turn 1, Step 4)
[
  // ... previous history ...
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "check_flight", ... }, "thoughtSignature": "<Sig_A>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] },
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "book_taxi", ... }, "thoughtSignature": "<Sig_B>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] }
]

// User Request (Sending Parallel Results)
[
  {
    "role": "user",
    "parts": [
      { "text": "Check the weather in Paris and London." }
    ]
  },
  {
    "role": "model",
    "parts": [
      // 1. First Function Call has the signature
      {
        "functionCall": { "name": "check_weather", "args": { "city": "Paris" } },
        "thoughtSignature": "<Signature_A>" 
      },
      // 2. Subsequent parallel calls DO NOT have signatures
      {
        "functionCall": { "name": "check_weather", "args": { "city": "London" } }
      } 
    ]
  },
  {
    "role": "user",
    "parts": [
      // 3. Function Responses are grouped together in the next block
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "15C" } }
      },
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "12C" } }
      }
    ]
  }
]

// User Request (Follow-up question)
[
  { 
    "role": "user", 
    "parts": [{ "text": "What are the risks of this investment?" }] 
  },
  { 
    "role": "model", 
    "parts": [
      {
        "text": "I need to calculate the risk step-by-step. First, I'll look at volatility...",
        "thoughtSignature": "<Signature_C>" // Recommended to include
      }
    ]
  },
  { 
    "role": "user", 
    "parts": [{ "text": "Summarize that in one sentence." }] 
  }
]

النقل من طُرز أخرى

إذا كنت تنقل سجلّ محادثة من نموذج آخر (مثل ‫Gemini 2.5) أو إدخال طلب مخصّص لاستدعاء دالة لم يتم إنشاؤه بواسطة Gemini 3، لن يكون لديك توقيع صالح.

لتجاوز عملية التحقّق الصارمة في هذه السيناريوهات المحدّدة، املأ الحقل بالسلسلة الوهمية المحدّدة التالية: "thoughtSignature": "context_engineering_is_the_way_to_go"

المُخرجات المنظَّمة مع الأدوات

يتيح لك Gemini 3 الجمع بين النتائج المنظَّمة والأدوات المضمَّنة، بما في ذلك الاستناد إلى معلومات من "بحث Google" وسياق عنوان URL وتنفيذ الرمز البرمجي.

from google import genai
from google.genai import types
from pydantic import BaseModel, Field
from typing import List

class MatchResult(BaseModel):
    winner: str = Field(description="The name of the winner.")
    final_match_score: str = Field(description="The final match score.")
    scorers: List[str] = Field(description="The name of the scorer.")

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Search for all details for the latest Euro.",
    config={
        "tools": [
            {"google_search": {}},
            {"url_context": {}}
        ],
        "response_mime_type": "application/json",
        "response_json_schema": MatchResult.model_json_schema(),
    },  
)

result = MatchResult.model_validate_json(response.text)
print(result)

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ai = new GoogleGenAI({});

const matchSchema = z.object({
  winner: z.string().describe("The name of the winner."),
  final_match_score: z.string().describe("The final score."),
  scorers: z.array(z.string()).describe("The name of the scorer.")
});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: "Search for all details for the latest Euro.",
    config: {
      tools: [
        { googleSearch: {} },
        { urlContext: {} }
      ],
      responseMimeType: "application/json",
      responseJsonSchema: zodToJsonSchema(matchSchema),
    },
  });

  const match = matchSchema.parse(JSON.parse(response.text));
  console.log(match);
}

run();

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": "Search for all details for the latest Euro."}]
    }],
    "tools": [
      {"googleSearch": {}},
      {"urlContext": {}}
    ],
    "generationConfig": {
        "responseMimeType": "application/json",
        "responseJsonSchema": {
            "type": "object",
            "properties": {
                "winner": {"type": "string", "description": "The name of the winner."},
                "final_match_score": {"type": "string", "description": "The final score."},
                "scorers": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "The name of the scorer."
                }
            },
            "required": ["winner", "final_match_score", "scorers"]
        }
    }
  }'

الترحيل من Gemini 2.5

‫Gemini 3 هي مجموعة النماذج الأكثر تطورًا لدينا حتى الآن، وهي تقدّم تحسّنًا تدريجيًا مقارنةً بـ Gemini 2.5 Pro. عند نقل البيانات، يجب مراعاة ما يلي:

• التفكير: إذا كنت تستخدم سابقًا هندسة الطلبات المعقّدة (مثل "سلسلة الأفكار") لإجبار Gemini 2.5 على التفكير، جرِّب Gemini 3 مع thinking_level: "high" وطلبات مبسطة.
• إعدادات درجة الحرارة: إذا كان الرمز الحالي يضبط درجة الحرارة بشكل صريح (خاصةً على قيم منخفضة للحصول على نتائج حتمية)، ننصحك بإزالة هذه المَعلمة واستخدام القيمة التلقائية 1.0 في Gemini 3 لتجنُّب المشاكل المحتملة في التكرار أو انخفاض الأداء في المهام المعقّدة.
• فهم مستندات PDF: تم تغيير درجة الدقة التلقائية لتكنولوجيا التعرّف البصري على الأحرف في ملفات PDF. إذا كنت تعتمد على سلوك معيّن لتحليل المستندات الكثيفة، اختبِر الإعداد الجديد media_resolution_high لضمان استمرار الدقة.
• استهلاك الرموز المميزة: قد يؤدي الانتقال إلى الإعدادات التلقائية في Gemini 3 Pro إلى زيادة استخدام الرموز المميزة لملفات PDF، ولكنّه سيؤدي إلى تقليل استخدام الرموز المميزة للفيديوهات. إذا تجاوزت الطلبات الآن قدرة الاستيعاب بسبب زيادة دقة العرض التلقائية، ننصحك بتقليل دقة الوسائط بشكلٍ صريح.
• تقسيم الصور: لا تتوفّر إمكانات تقسيم الصور (عرض أقنعة على مستوى البكسل للكائنات) في Gemini 3 Pro. بالنسبة إلى أحمال العمل التي تتطلّب تقسيم الصور الأصلي، ننصحك بمواصلة استخدام Gemini 2.5 Flash مع إيقاف ميزة "التفكير" أو Gemini Robotics-ER 1.5.

التوافق مع OpenAI

بالنسبة إلى المستخدمين الذين يستفيدون من طبقة التوافق مع OpenAI، يتم تلقائيًا ربط المَعلمات العادية بمثيلاتها في Gemini:

• يتم ربط reasoning_effort (OAI) بـ thinking_level (Gemini). يُرجى العِلم أنّ مستوى الدقة reasoning_effort المتوسط يتوافق مع مستوى الدقة thinking_level العالي.

أفضل الممارسات المتعلّقة بإدخال الطلبات

‫Gemini 3 هو نموذج للاستدلال، ما يغيّر طريقة إدخال الطلبات.

• تعليمات دقيقة: يجب أن تكون طلبات الإدخال موجزة. يقدّم Gemini 3 أفضل ردّ عند تلقّي تعليمات مباشرة وواضحة. قد يبالغ في تحليل الأساليب المطوّلة أو المعقّدة بشكل مفرط في هندسة الطلبات المستخدَمة مع النماذج القديمة.
• مستوى التفصيل في الإجابات: يكون مستوى التفصيل في الإجابات التي يقدّمها Gemini 3 أقل بشكل تلقائي، وهو يفضّل تقديم إجابات مباشرة وفعّالة. إذا كانت حالة الاستخدام تتطلّب شخصية أكثر حوارية أو "ودية"، عليك توجيه النموذج بشكل واضح في الطلب (على سبيل المثال، "اشرح هذا الموضوع بأسلوب ودود ومفصّل").
• إدارة السياق: عند العمل مع مجموعات بيانات كبيرة (مثل الكتب الكاملة أو قواعد التعليمات البرمجية أو الفيديوهات الطويلة)، ضَع تعليماتك أو أسئلتك المحدّدة في نهاية الطلب، بعد سياق البيانات. استند في استنتاج النموذج إلى البيانات المقدَّمة من خلال بدء سؤالك بعبارة مثل "استنادًا إلى المعلومات الواردة أعلاه...".

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

الأسئلة الشائعة

1. ما هو تاريخ آخر تحديث للبيانات في Gemini 3 Pro؟ يبلغ تاريخ انتهاء بيانات Gemini 3 يناير 2025. للحصول على معلومات أحدث، استخدِم أداة تحديد المصدر.

2. ما هي حدود قدرة الاستيعاب؟ يتيح Gemini 3 Pro إدخال ما يصل إلى مليون رمز مميّز، كما يتيح إخراج ما يصل إلى 64 ألف رمز مميّز.

3. هل تتوفّر فئة مجانية من Gemini 3 Pro؟ يمكنك تجربة النموذج مجانًا في Google AI Studio، ولكن لا تتوفّر حاليًا أي طبقة مجانية لنموذج gemini-3-pro-preview في Gemini API.

4. هل سيظلّ رمز thinking_budget القديم صالحًا؟ نعم، لا يزال thinking_budget متاحًا لضمان التوافق مع الأنظمة القديمة، ولكنّنا ننصح بالانتقال إلى thinking_level لتحقيق أداء أكثر قابلية للتوقّع. لا تستخدِم كليهما في الطلب نفسه.

5. هل يتوافق Gemini 3 مع Batch API؟ نعم، يتوافق Gemini 3 مع Batch API.

6. هل تتوفّر ميزة "التخزين المؤقت حسب السياق"؟ نعم، تتوافق ميزة "التخزين المؤقت للسياق" مع Gemini 3. الحدّ الأدنى لعدد الرموز المميزة المطلوبة لبدء التخزين المؤقت هو 2,048 رمزًا مميزًا.

7. ما هي الأدوات المتوافقة مع Gemini 3؟ يتوافق Gemini 3 مع بحث Google والبحث عن الملفات وتنفيذ الرموز البرمجية وسياق عنوان URL. يتيح هذا النموذج أيضًا استخدام ميزة استدعاء الدوال العادية لأدواتك المخصّصة. يُرجى العِلم أنّ خرائط Google واستخدام الكمبيوتر غير متاحَين حاليًا.

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

• بدء استخدام كتاب الطبخ Gemini 3
• راجِع دليل Cookbook المخصّص حول مستويات التفكير وكيفية نقل البيانات من ميزانية التفكير إلى مستويات التفكير.