|

تطلق Gemini API ميزة استرداد الأدوات: أربعة نماذج تدعم التحميل عند الطلب، ولم يعد الوكيل يقرأ جميع معلمات الأدوات في كل مرة

تطلق Gemini API ميزة استرداد الأدوات: أربعة نماذج تدعم التحميل عند الطلب، ولم يعد الوكيل يقرأ جميع معلمات الأدوات في كل مرة

في 19 نوفمبر 2026، أطلقت Google ميزة Tool Retrieval (استرداد الأدوات) في Gemini Interactions API بصيغة Preview. فصار بإمكان الوكيل (Agent) أن يرى في البداية أسماء الأدوات ووصفًا موجزًا لكل منها فقط، ثم لا يُحمِّل مخطط المعاملات الكامل (Schema) في السياق إلا عند الحاجة الفعلية إلى الاستدعاء. والمشكلة الأساسية التي تعالجها هي: «كلما زاد عدد الأدوات الموصولة، امتلأ السياق بتعريفات أدوات لا تُستعمل». وهي الأنسب للوكلاء الذين يملكون أدوات كثيرة تتجمّع استدعاءاتهم في عدد قليل من الأدوات عالية التكرار مع وجود عدد كبير من أدوات «الذيل الطويل»، وليست ميزةً يُفعّلها كل تطبيق افتراضيًا على أمل خفض التكلفة.

ماذا ستكتشف بعد قراءة هذا المقال؟

  • ما الذي تغيّره Tool Retrieval فعلاً، وكيف يصحّ في الوقت نفسه أن «المطوّر ما زال مطالبًا بإرسال تعريفات الأدوات كاملة» وأن «النموذج غير مضطر لقراءة المخطط الكامل مسبقًا»
  • سلسلة التنفيذ الكاملة من تسجيل الأداة حتى function_call، وتوزيع العمل بين الاسترداد من جهة الخادم والاسترداد من جهة العميل
  • معرّفات النماذج الأربعة المدعومة صراحةً في الوقت الحالي، والسعر القياسي، ومعنى «لا توجد رسوم منفصلة لهذه الميزة، لكن الرموز تُحتسب كالمعتاد»
  • مثالي الحساب الرسميان اللذان يسيران في اتجاهين متعاكسين: متى يتحقق التوفير، ومتى يصبح الأمر أغلى مما كان
  • القيود التي يجب الانتباه إليها قبل التكامل، وكيف تحدّد ما إذا كان وكيلك يستحق تبنّي هذه الميزة

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

gemini-api-tool-retrieval-agent-on-demand-tool-schema-ar-image-0

Gemini API Tool Retrieval: المفاهيم التي يجب معرفتها أولاً (To Know)

المفهوم شرح موجز
استرجاع الأدوات (Tool Retrieval) استرجاع الأدوات المطلوبة أولاً، ثم إضافة تعريفات المعاملات الكاملة للأدوات المطابقة إلى سياق النموذج
Interactions API واجهة Gemini الموجهة للوكلاء، تدير سجل التفاعلات وخطوات تنفيذ الأدوات ومخرجات النموذج، وأصبحت متاحة رسميًا في يونيو 2026
مخطط المعاملات (Parameter Schema) بنية تصف المعاملات التي تقبلها الدالة وأنواعها وأيها مطلوب، ويُعبّر عنها عادةً باستخدام JSON Schema
استدعاء الدوال (Function Calling) يولّد النموذج اسم الدالة ومعاملاتها، ثم ينفذ التطبيق الدالة، ويعيد النتيجة إلى النموذج
tool_search نوع أداة يعلن آلية استرجاع الأدوات، ويستخدمه النموذج للبحث عن تعريفات الأدوات وتحميلها
defer_loading إعداد في وضع الخادم يؤخر تحميل تعريف المعاملات الكامل للأداة حتى تتم مطابقة الاسترجاع
short_description وصف قصير للأداة المؤجلة، يساعد النموذج على التعرف على الأداة في الفهرس الأولي
MCP عن بُعد يربط الأدوات التي توفرها خدمات طرف ثالث خارج التطبيق عبر Model Context Protocol
التخزين المؤقت الضمني تعيد المنصة استخدام نفس بادئة السياق تلقائيًا، ويُحتسب الجزء المطابق وفق سعر إدخال المخزن المؤقت

لمحة سريعة عن تأثير «استرداد الأدوات» في Gemini API

  • المطورون الذين يربطون عددًا كبيرًا من أدوات الأعمال بالوكيل (Agent): لم يعد عليهم بناء مستودع استرداد أدوات خاص بهم، بل يمكنهم ترك النموذج يقرأ مخططات (Schema) عشرات أو حتى مئات الأدوات حسب الطلب. غير أنه لا يزال يتعين إرسال مصفوفة الأدوات كاملة مع كل طلب، وإعادة تقييم التخزين المؤقت والفوترة. قبل الترحيل، يُنصح بقياس الاستهلاك الفعلي لتعريفات الأدوات عبر مسار Function Calling الحالي، ويمكن الاستعانة بواجهة موحّدة متعددة النماذج مثل APIYI على apiyi.com للحصول على خط أساس للمقارنة بسرعة.
  • مسؤولو المنتج والتكلفة: لا توجد رسوم وظيفية منفصلة، لكن كل عملية بحث على جانب الخادم تحفّز استدلالًا إضافيًا للنموذج. وهل ينخفض الاستهلاك أم لا يعتمد على حجم الأدوات وطول السياق وعدد مرات البحث، ويجب التحقق منه عبر حقول الفاتورة، لا بالاكتفاء بتوجه الإعلان.
  • التطبيقات التي تمتلك أدوات قليلة واستدعاءات مستقرة: تُظهر أمثلة الحساب الرسمية أن مجموعة أدوات صغيرة مع سياق طويل تؤدي في الواقع إلى زيادة إجمالي عدد الرموز (Tokens)، لذا يبقى التحميل المباشر الخيار الأكثر أمانًا.
  • الفرق التي تستخدم أُطر عمل الوكيل (Agent): هذه قدرة جديدة على مستوى API النموذج، وقد لا تتوافق معها أُطر العمل فورًا. وفي مسألة التحميل التدريجي على مستوى الإطار، لا ينبغي افتراض أنها باتت محلولة.

حقائق موضوعية: ما الذي أطلقته ميزة Tool Retrieval في Gemini API

معلومات الإطلاق والخلفية

نشرت مدونة Google الرسمية في 19 نوفمبر 2026 مقالًا بعنوان «Introducing Tool Retrieval in the Gemini API»، وكتبته لوسيا لوهير (مديرة منتج Gemini API) ونورا كاسنر (باحثة في Google DeepMind). الميزة حاليًا في مرحلة المعاينة (Preview)، ولا يمكن استخدامها إلا عبر Interactions API وبإصدار v1beta. أما الطريقة القديمة generateContent فلا تدعمها.

وكانت التحضيرات الهندسية قد سبقت الإعلان. ففي 18 نوفمبر أصدرت Google إصدار v3.6.0 من حزمة SDK الرسمية للبايثون، وجاء في سجل التحديثات أنه أضاف مخططات (Schema) عامة مرتبطة بـ Tool Retrieval ونتائج الدوال. وفي اليوم نفسه ضمّ إصدار Go SDK v1.79.0 التحديثات المطابقة. ومن هذا التسلسل الزمني يتضح أن الأمر يتعلق باستكمال قدرات اكتشاف الأدوات وتحميلها عند الحاجة فوق Interactions API الذي بلغ مرحلة الإتاحة العامة (GA) بالفعل، وليس إطلاق منتج API جديد.

وثمّة سجل يوثّق احتياجات المطورين أيضًا. ففي 18 مارس 2026 قدّم أحد المطورين Issue رقم #2185 في مستودع SDK البايثون، طالبًا فيه دعم defer_loading وtool_search، بحجة أن ربط الوكيل (Agent) بأكثر من 30 أداة يؤدي إلى تضخّم السياق بسبب المخططات الكاملة. واستجاب القائمون على الصيانة في Google في 20 مارس بتسجيل الطلب كطلب ميزة. وهذه آراء وملاحظات احتياج، وليست اختبارات أداء.

وبعبارة واحدة، يمكن تلخيص Tool Retrieval على النحو التالي: يمكن اكتشاف الأداة أولًا، ثم تُقرأ معاملاتها التفصيلية عند الحاجة إلى استدعائها.

كيف يغيّر Tool Retrieval طريقة تحميل مخططات الأدوات

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

يكمن جوهر Tool Retrieval في التمييز بين ثلاثة مستويات:

  1. مستوى طلب API: يرسل المطوّر تعريفات الأدوات الكاملة كالمعتاد، بما في ذلك مخطط المعاملات.
  2. السياق الأولي للنموذج: تظهر الأدوات المعلَّمة بـ defer_loading: true بالاسم فقط مع short_description. وإذا لم يكن هناك وصف موجز مُهيَّأ، تؤخذ الجملة الأولى من description الكامل.
  3. مرحلة استدعاء الأداة: بعد أن تُصاب الأداة في عملية الاسترجاع، يدخل المخطط الكامل إلى السياق، ويولّد النموذج بناءً عليه استدعاءً بمعاملات.

لذا فإن المعنى الدقيق لعبارة “لم يعد يتم تحميل جميع معاملات الأدوات في كل مرة” الواردة في العنوان هو أن النموذج لم يعد يقرأ كل المعاملات الكاملة مسبقًا في كل جولة، وليس أن المطوّر لم يعد بحاجة إلى إرسال التعريفات الكاملة. وفي وضع الخادم، تشترط الجهة الرسمية إعادة إرسال مصفوفة tools الكاملة مع كل طلب، حتى عند استخدام previous_interaction_id.

gemini-api-tool-retrieval-agent-on-demand-tool-schema-ar-image-1

سلسلة تنفيذ Tool Retrieval: مثال رسمي لحالة استرداد مبلغ

استخدم إعلان Google سيناريو استرداد مبلغ لطلب: الطلب A-1042 وصلت منتجاته تالفة، ويطلب المستخدم استرداد 40 دولارًا، والأداة التي يحتاج إليها هي issue_refund. وفيما يلي العملية الكاملة للاسترجاع من جانب الخادم:

  1. يُعلن في الطلب عن {"type": "tool_search"}، وتُضبط الأدوات منخفضة الاستخدام مثل issue_refund على defer_loading: true.
  2. يحدد النموذج حسب المهمة أنه بحاجة إلى قدرة استرداد المبلغ، فيبدأ tool_search_call.
  3. تعيد الـ API النتيجة tool_search_result، وفيها الـ Schema الكامل لمعاملات issue_refund.
  4. يقرأ النموذج تعريف المعاملات، فيولّد function_call بمعاملات order_id: "A-1042" وamount: 40.
  5. ينفذ التطبيق الدالة ويعيد function_result، ويواصل النموذج إتمام المهمة بناءً عليه.

يمكن إتمام البحث والتحميل وتوليد استدعاء الدالة داخل طلب API خارجي واحد، ويمكن رؤية جميع الخطوات في interaction.steps. لكن انتبه: الطلب الواحد لا يعني أن الاستدلال الداخلي حدث مرة واحدة فقط، فكل بحث على جانب الخادم يسبب استدعاء نموذج إضافيًا يحتاج إلى حساب التكلفة. كما أن هذه حالة توضيحية ولا تمثل أي إحصاءات عن نسبة نجاح استرداد المبلغ.

فيما يلي كود توضيحي مُنظم وفق الوثائق الرسمية، يتصل مباشرة بنقطة Google، ويُستخدم فقط لعرض بنية الطلب:

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

tools = [
    {"type": "tool_search"},
    {
        "type": "function",
        "name": "issue_refund",
        "description": "Refund an order.",
        "short_description": "Refund a customer order.",
        "defer_loading": True,
        "parameters": {
            "type": "object",
            "properties": {
                "order_id": {"type": "string"},
                "amount": {"type": "number"}
            },
            "required": ["order_id", "amount"]
        }
    }
]

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Refund 40 USD for order A-1042.",
    tools=tools
)
for step in interaction.steps:
    print(step.type)  # نوع الخطوة: tool_search_call / tool_search_result / function_call

لم يتغير تقسيم المسؤوليات الأصلي في Function Calling. بالنسبة للدوال المخصصة، تعيد الـ API فقط function_call، ويبقى تنفيذ استرداد المبلغ والوصول إلى قاعدة البيانات ومعالجة الصلاحيات من عمل التطبيق. فقط عند الاتصال بخادم MCP بعيد تتولى الـ API نيابةً عنك إجراء الاستدعاء البعيد، وتعيد mcp_server_tool_call وmcp_server_tool_result.

استرجاع الأدوات (Tool Retrieval): التحميل المختلط، وMCP عن بُعد، ونمطا الاسترجاع

توصي Google بالاستخدام المختلط: تحميل الأدوات كثيرة الاستخدام مباشرةً، وتأجيل تحميل الأدوات المتخصصة قليلة الاستخدام وطويلة الذيل. بهذه الطريقة لا تحتاج المهام البسيطة إلى إجراء بحث أولي، كما لا تشغل القدرات طويلة الذيل السياق لفترة طويلة. ويمكن أيضًا ضبط خوادم MCP البعيدة بالكامل على التحميل المؤجل، مثل إضافة defer_loading: true إلى إعداد type: "mcp_server"؛ عندها تُحمّل الأدوات التي يعرضها ذلك الخادم عند الحاجة، دون الحاجة إلى إعلانها واحدة تلو الأخرى.

إلى جانب النمط الخادمي الذي تتولى فيه Gemini الاسترجاع، توفر الجهة الرسمية أيضًا نمطًا من جهة العميل: يعلن المطوّر عن tool_search بالإعداد execution: "client"، ويقوم تطبيقه بالاستعلام من سجل الأدوات، ثم يضع إعلانات الأدوات الكاملة المطابقة في function_result.result ويعيدها إلى النموذج. والفرق بين النمطين كما يلي:

بُعد المقارنة الاسترجاع من جهة الخادم الاسترجاع من جهة العميل
موضع التنفيذ خادم Gemini API (الافتراضي server) تطبيق المطوّر (client)
هل يلزم بناء مسترجع خاص؟ لا نعم
هل يلزم إعلان مكتبة الأدوات مسبقًا؟ نعم لا، يمكن إدخال أدوات جديدة أثناء الجلسة
defer_loading ينطبق لا ينطبق
رحلات الشبكة الإضافية لا حاجة إلى رحلات إضافية من العميل رحلة إضافية واحدة لكل بحث
التحكم في الصلاحيات تحدده مجموعة الأدوات المعلنة في الطلب يمكن دمجه مع تصفية صلاحيات مبنية على مستوى المستخدم
السيناريو النموذجي مجموعات أدوات كبيرة وثابتة نسبيًا مكتبة أدوات ديناميكية، وأوضاع متعددة المستأجرين، وسجلات خاصة بالمؤسسات

يجب أن تكون إعلانات الدوال التي يعيدها النمط من جهة العميل كائنات منظمة، ولا يمكن تحويلها إلى سلاسل JSON. ولا يمكن مزج النمطين في الطلب نفسه، ويمكن الإعلان عن tool_search واحد فقط كحد أقصى.

النماذج المدعومة في Gemini API Tool Retrieval وأسعارها

صياغة إعلان Google واسعة نسبيًا؛ إذ يقول إن نماذج Gemini 3.6 والأحدث مدعومة جميعها، بما في ذلك كل نماذج Gemini 4. غير أن وثائق المطورين لم تذكر صراحةً، حتى 20 نوفمبر، سوى أربعة معرفات نماذج. عند التطبيق، ينبغي الاعتماد على وثائق المطورين؛ فتعيين defer_loading لنموذج غير مدعوم سيؤدي إلى إرجاع HTTP 400.

معرف النموذج سعر الإدخال القياسي (بالدولار/مليون Tokens) سعر الإخراج القياسي (بما في ذلك التفكير) ملاحظات
gemini-4-hydrogen $1.50 $7.50 موسوم بأنه ضمن Free Tier
gemini-4-argon $2.00 (اعتبارًا من 1 ديسمبر $4.00) $10.00 (اعتبارًا من 1 ديسمبر $20.00) لا يتوفر في Free Tier
gemini-3.8-flash $0.75 (اعتبارًا من 1 يناير 2027 $1.50) $3.75 (اعتبارًا من 1 يناير 2027 $7.50) موسوم بأنه ضمن Free Tier
gemini-3.6-flash $0.75 (اعتبارًا من 1 يناير 2027 $1.50) $3.75 (اعتبارًا من 1 يناير 2027 $7.50) موسوم بأنه ضمن Free Tier

الأسعار مأخوذة من فئة Standard في صفحة تسعير Google Gemini Developer API. أما الحصة الفعلية وحدود معدل الطلبات في Free Tier، فيجب تأكيدهما على مستوى المشروع.

من حيث الفوترة، توضح Google صراحةً أن Tool Retrieval لا تفرض رسومًا مستقلة على الميزة، لكن ذلك لا يعني أن البحث مجاني. فالقائمة المختصرة للأدوات المؤجلة، وتعليمات البحث الثابتة الإضافية بعد تفعيل tool_search، والاستدلال الإضافي في كل عملية بحث على الخادم، والمخطط الكامل (Schema) الذي يتم تحميله والاحتفاظ به في الجولات اللاحقة، كلها تُحتسب كـ Tokens وفق تسعير النموذج المختار. وعند مراقبة التكلفة، ينبغي إيلاء اهتمام خاص للحقل total_tool_use_tokens، فهو يسجل مدخلات استدعاءات النموذج الإضافية الناتجة عن البحث على الخادم. إن مجرد النظر إلى انخفاض Tokens الإدخال في الطلب الأول قد يؤدي بسهولة إلى المبالغة في تقدير حجم الوفر.

أمثلة حسابية رسمية توضيحية لاستهلاك Token في Tool Retrieval

أظهرت الاختبارات الرسمية المبكرة أن كل أداة مؤجلة تشغل في الدليل الأولي نحو 26 Token في المتوسط. هذه قيمة تقريبية وليست تكلفة ثابتة. وتقدم الوثائق أيضًا مثالين حسابيين افتراضيين بنتيجتين متعاكستين:

السيناريو (الافتراض الرسمي) التحميل الثابت لجميع الأدوات Tool Retrieval التغير
200 أداة، كل منها 400 Token، سياق أساسي 2,000، استخدام أداتين، وإجمالًا طلبان 164,000 نحو 23,650 انخفاض بنحو 85.6% (وفق حساب المثال)
10 أدوات، كل منها 400 Token، سياق أساسي 30,000، استخدام أداتين، وإجمالًا طلبان 68,000 92,830 زيادة بنحو 36.5% (وفق حساب المثال)

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

gemini-api-tool-retrieval-agent-on-demand-tool-schema-ar-image-2

أما من ناحية التخزين المؤقت، فتقول Google إن Tool Retrieval يدعم التخزين المؤقت الضمني: لا يظهر Schema الكامل في البادئة الأولية، وتصبح البادئات مثل تعليمات النظام ودليل الأدوات أسهل في الحفاظ على استقرارها. لكن الوثائق تحذر أيضًا من أن التحميل المتأخر يجعل الموجه الأولي أقصر، وقد تنخفض الطلبات التي كانت تعتمد على كمية كبيرة من Schema للوصول إلى الحد الأدنى لتفعيل التخزين المؤقت إلى ما دون هذا الحد.

القيود الحالية لاستخدام Tool Retrieval

النقاط التالية مستمدة من الوثائق الرسمية، وهي الأكثر عرضة للمشاكل أثناء التطوير:

  • لا يمكن إلغاء تحميل الأدوات المحملة: بمجرد استرداد Schema، يبقى محفوظًا في الجلسة الحالية. وفي الجلسات الطويلة التي تُسترد فيها أدوات جديدة باستمرار، تستمر نافذة السياق في النمو.
  • إعادة إرسال مصفوفة الأدوات الكاملة مع كل طلب: بما في ذلك tool_search، وجميع الأدوات المؤجلة وغير المؤجلة، وإعدادات MCP ذات الصلة. لا يمكن إرسال name وshort_description فقط دون parameters.
  • الأدوات المذكورة صراحةً في تعليمات النظام يجب عدم تأجيلها: قد يتجاوز النموذج البحث ويستدعيها مباشرةً، ما يؤدي إلى خطأ بسبب غياب سياق التحميل.
  • الجلسات عديمة الحالة يجب أن تحتفظ بخطوات الاسترداد كاملةً: عند إدارة السجل بنفسك باستخدام store=false، لا يمكن حذف أو تعديل tool_search_call وtool_search_result وsignature الخاص بها، وإلا فقد يعيد HTTP 400.
  • عند التصحيح راقب steps: حتى إذا لم يكن interaction.status مساويًا لـ requires_action، فقد تحتوي النتيجة على function_call بانتظار التنفيذ.
  • قد يعيد نصًا عند عدم وجود تطابق: عندما لا يجد بحث الخادم أداة مطابقة، فإنه لا يعيد بالضرورة خطأً منظمًا.

تحليل وتقييم: ماذا يعني Tool Retrieval في Gemini API لتطوير الوكلاء؟

تقييم الحالات المناسبة لاستخدام Tool Retrieval

القيمة العملية لهذا التحديث هي فصل أمرين عن بعضهما: «الاحتفاظ بقائمة كاملة من الأدوات» و«قراءة هذه القائمة بالكامل في كل جولة استدلال». يمكن لمكتبة الأدوات أن تستمر في التوسع، بينما لا يبقى في سياق النموذج سوى فهرس خفيف جدًا. وبالنسبة للفرق التي تربط أنظمة أعمال جديدة باستمرار، فإن هذا يقلل من عبء تقليص مجموعة الأدوات مسبقًا، ويحد أيضا من اضطرار التطبيق إلى تصفية الأدوات ديناميكيًا في كل جولة للتحكم في الرموز (Tokens)، وما ينتج عن ذلك من إفساد بادئة التخزين المؤقت.

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

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

خلاصتنا هي: كلما كان توزيع استدعاءات الأدوات أكثر «ذيلًا طويلًا»، كان Tool Retrieval أوفر بالاستخدام. وعلى العكس، إذا كانت معظم الأدوات تُستخدم في كل جولة، فإن التحميل المؤجل لن يضيف إلا جولة استدلال بحث إضافية.

قبل الانتقال إلى Tool Retrieval، قِس أولاً الاستهلاك الفعلي لمخطط الأدوات

أكثر ما يمكن الاعتماد عليه في قرار الانتقال هو بيانات عملك أنت. وقبل الانتقال، يمكنك استخدام مسار Function Calling المتوافق مع OpenAI الذي تعمل به الآن، وقياس الفرق في رموز الإدخال (prompt tokens) بين طلبين: طلب يحمل كل الأدوات، وطلب يحمل فقط الأدوات المستخدمة فعليًا. بهذه الطريقة تحصل على الاستهلاك الحقيقي لمخطط الأدوات. السكربت التالي يقوم بهذا القياس الأساسي، وهو ليس Tool Retrieval نفسه:

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # واجهة APIYI المتوافقة مع OpenAI، تُستخدم لقياس خط الأساس للتحميل الثابت
)

def make_tool(name, desc):
    return {"type": "function", "function": {
        "name": name, "description": desc,
        "parameters": {"type": "object",
                       "properties": {"order_id": {"type": "string"}},
                       "required": ["order_id"]}}}

all_tools = [make_tool(f"crm_tool_{i}", f"CRM operation {i}") for i in range(50)]
messages = [{"role": "user", "content": "查询订单 A-1042 的状态"}]

for label, tools in [("全量 50 个工具", all_tools), ("仅 1 个工具", all_tools[:1])]:
    resp = client.chat.completions.create(
        model="your-model-id", messages=messages, tools=tools)
    print(label, "prompt_tokens =", resp.usage.prompt_tokens)
عرض سكربت القياس الأساسي الكامل (مقارنة دفعية حسب عدد الأدوات)
import json
import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # قياس تكلفة مخطط الأدوات عبر نماذج مختلفة من خلال واجهة APIYI الموحّدة
)

def load_tools(path: str) -> list:
    """قراءة تعريفات الأدوات بصيغة OpenAI من سجل أدوات الأعمال (ملف JSON)"""
    with open(path, "r", encoding="utf-8") as f:
        return json.load(f)

def measure(model: str, tools: list, prompt: str) -> int:
    resp = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": prompt}],
        tools=tools if tools else None,
        max_tokens=16,
    )
    return resp.usage.prompt_tokens

def baseline_report(model: str, tools: list, prompt: str, steps=(0, 10, 20, 50, 100)):
    base = measure(model, [], prompt)
    print(f"无工具基础输入: {base} tokens")
    for n in steps:
        if n == 0 or n > len(tools):
            continue
        used = measure(model, tools[:n], prompt)
        print(f"{n:>4} 个工具: {used} tokens, Schema 约占 {used - base} tokens")

if __name__ == "__main__":
    tools = load_tools("tool_registry.json")
    baseline_report("your-model-id", tools, "查询订单 A-1042 的状态")

🎯 توصية تقنية: قبل تقييم Tool Retrieval، يمكنك أولاً تشغيل قياس خط الأساس للتحميل الثابت عبر APIYI على apiyi.com بمفتاح API واحد وعلى عدة نماذج رائدة، لترى بوضوح كم من الرموز يستهلكه مخطط الأدوات فعليًا داخل طلبك. وبعد الحصول على خط الأساس، انتقل إلى Gemini Interactions API وفعّل tool_search للمقارنة، عبر مقارنة مجموع total_input_tokens وtotal_tool_use_tokens.

تجدر الإشارة إلى أن Tool Retrieval يعتمد على واجهة v1beta في Interactions API وعلى حقول مخصّصة، وأن الاستدعاءات المتوافقة مع OpenAI المذكورة أعلاه تُستخدم فقط لقياس كلفة التحميل الساكن. وعند إجراء اختبار مقارن، يُنصح بالإبقاء على النموذج ومكتبة الأدوات ومجموعة المهام وطول السياق وظروف التخزين المؤقت ثابتة، ثم مقارنة إجمالي تكلفة الفاتورة والزمن الكلي من الطرف إلى الطرف ونسبة اختيار الأدوات الصحيحة ومتوسط عدد عمليات البحث؛ وبهذه الطريقة فقط يمكن إسناد الفروق إلى استراتيجية الاسترجاع. وإذا أردت أن تنظر أفقيًا في فروق خط الأساس بين نماذج مختلفة ضمن المجموعة نفسها من السكربتات، فإن الواجهة الموحّدة لدى APIYI apiyi.com تغنيك عن عناء الربط بكل مزوّد على حدة.

تطورات لاحقة تستحق المتابعة (تقييمات تنبؤية)

ما يلي تقييمات وليست حقائق مؤكدة.

أولًا، هناك اختلاف بين الإعلان ووثائق المطوّرين في نطاق النماذج المدعومة؛ لذا ينبغي متابعة تحديثات الوثائق لمعرفة ما إذا كانت طرازات مثل Gemini 4 Carbon وGemini 4 Neon ستدخل قائمة التوافق. ثانيًا، عدم إمكانية إلغاء تحميل Schema المحمّلة يُعدّ نقطة ضعف واضحة لدى وكلاء الجلسات الطويلة، وما إذا كانت النسخة الرسمية ستوفّر آلية لإلغاء التحميل أو التخلّص منها سيؤثر مباشرة في أدائه في المهام الطويلة. ثالثًا، أبلغ مستخدمو Google ADK سابقًا في Issue #7241 عن مشكلات في التحميل التدريجي وإبطال التخزين المؤقت؛ ودعم واجهة النموذج لقدرات جديدة لا يعني أن الإطار سيتبنّاها تلقائيًا، لذا تستحق وتيرة التكيّف على مستوى الإطار المتابعة.

فكرة تحميل تعريفات الأدوات عند الطلب لها سوابق في القطاع، وما فعلته Google هذه المرة هو إضافتها إلى واجهة Agent في Gemini. ونظرًا لأن الواجهة قد تتغيّر في مرحلة Preview، يُنصح عند ربط أنظمة الإنتاج بالإبقاء على مفتاح للرجوع إلى التحميل الساكن.

حول بعض الأسئلة الشائعة بشأن Tool Retrieval في Gemini API

س1: عند تفعيل Tool Retrieval، هل يصبح جسم الطلب أصغر؟

لا. في وضع الخادم، لا يزال كل طلب يرسل مصفوفة الأدوات كاملة، وما يصغر فعلاً هو الحجم الذي تشغله الأدوات داخل سياق النموذج الأولي. وإذا أردت أن تحسب أولاً حجم تعريفات الأدوات في طلبك الحالي، يمكنك استخدام السكربت المذكور سابقاً عبر APIYI apiyi.com لقياس خط الأساس.

س2: هل تقول Google رسمياً إن التوفير يصل إلى 85%؟

لا يوجد أي نتيجة قياس فعلية بهذا المعنى. نسبة 85.6% مستنتجة من مثال افتراضي يفترض وجود 200 أداة، والوثيقة نفسها تقدم مثالاً معاكساً تزيد فيه الـ Tokens بنحو 36.5% عند استخدام مجموعة أدوات صغيرة.

س3: هل Tool Retrieval خدمة مدفوعة؟

لا توجد رسوم وظيفية منفصلة، لكن تعليمات البحث والاستدلال الإضافي والمخططات (Schema) التي يتم تحميلها تُحتسب جميعها كـ Tokens بأسعار النموذج. وللفرق الحساسة للميزانية، يمكنها أولاً اختبار تكلفة Function Calling لنماذج مختلفة على نطاق صغير بالدفع حسب الاستخدام عبر APIYI apiyi.com، ثم تحديد النموذج المناسب للوكيل (Agent).

س4: بعد استخدام Tool Retrieval، هل لم أعد بحاجة إلى تنفيذ الدوال بنفسي؟

لا. فالدوال المخصصة لا يزال تطبيقك هو من ينفذها ويعيد نتائجها، وTool Retrieval مسؤول فقط عن العثور على تعريفات الأدوات وتحميلها. الاستثناء الوحيد هو أدوات MCP البعيدة، فهي التي يستدعيها الـ API نيابة عنك.


ستكبر مكتبة الأدوات مع الوقت، لكن ما تحتاجه فعلاً في كل جولة هو عدد قليل منها فقط. Tool Retrieval يفصل بين «تجهيز كل الأدوات» و«استخدامها عند الحاجة»، فإن أحسنت استخدامه صار وكيلك الكبير أخف وزناً، وإن أسأت استخدامه فقد تدفع ثمن جولة استدلال إضافية. وكما جاء في «المحادثات» (لون يو، فصل وي لينغ غونغ): «من أراد إتقان عمله، فليشحذ أدواته أولاً.» فقِس أولاً وزن كل «أداة» بين يديك، ثم قرر كيف ترتبها.


📚 المراجع

  1. إعلان Google الرسمي: Introducing Tool Retrieval in the Gemini API (2026-11-19)

    • الرابط: blog.google/innovation-and-ai/technology/developers-tools/gemini-api-tool-retrieval
    • الوصف: معلومات الإصدار، وأهداف التصميم، ونمطا الاسترداد، ومبادئ التسعير
  2. وثائق مطوّري Google Tool Retrieval: الإعداد والقيود والتسعير وأمثلة حسابية توضيحية

    • الرابط: aistudio.google.com/docs/tool-retrieval
    • الوصف: قائمة النماذج المدعومة، وحقل Usage، وأفضل الممارسات والأخطاء الشائعة
  3. تسعير Gemini Developer API: الأسعار القياسية للنماذج وأسعار التخزين المؤقت

    • الرابط: aistudio.google.com/docs/pricing
    • الوصف: سعر الإدخال والإخراج لكل نموذج وتاريخ السريان
  4. وثائق Interactions API: دور الواجهة وخطوات التنفيذ

    • الرابط: aistudio.google.com/docs/interactions-overview
    • الوصف: المحادثات ذات الحالة، وبنية steps، والفرق عن generateContent
  5. Google Python SDK v3.6.0 و Issue #2185: أدلة هندسية وسجل احتياجات المطورين

    • الرابط: github.com/googleapis/python-genai/releases/tag/v3.6.0
    • الرابط: github.com/googleapis/python-genai/issues/2185
    • الوصف: تحديث Schema العام في SDK والاحتياجات المبكرة للمجتمع

المؤلف: فريق APIYI التقني
للتواصل التقني: نرحب بتواصلكم معنا عبر الصفحة الرئيسية لـ APIYI على apiyi.com، ولمزيد من مواد التكامل يمكنكم زيارة مركز الوثائق docs.apiyi.com

مقالات ذات صلة

موضوعات ذات صلة