هل يوفر Gemini Tool Retrieval الرموز حقًا؟ 200 أداة مقابل 10 أدوات، نتيجتان للتكلفة

يمكن التوفير، لكن بشروط. استنادًا إلى مثالين حسابيين افتراضيين وردا في وثائق Google الرسمية: في سيناريو يضم 200 أداة وسياق أساسي قدره 2,000 رمز (Token)، ينخفض عدد رموز الإدخال في Gemini Tool Retrieval من 164,000 إلى 23,650، أي بنحو 85.6%. أما في سيناريو يضم 10 أدوات وسياق أساسي قدره 30,000 رمز، فيرتفع عدد رموز الإدخال من 68,000 إلى 92,830، أي بزيادة نحو 36.5%. وهل الأمر مجدٍ فعلًا؟ يتوقف ذلك على سؤال واحد: هل ما نوفره من مخططات الأدوات الكاملة (Schema) قادر على تغطية التكلفة الإضافية للسياق الناتجة عن البحث من جانب الخادم؟

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

  • أي جزء من الرموز يوفره Tool Retrieval، وأي جزء جديد يضيفه.
  • الافتراضات الكاملة للمثال الرسمي ذي 200 أداة ومثال الـ10 أدوات، مع تفكيك البنود واحدًا واحدًا.
  • صيغة نقطة التعادل المستندة إلى المعاملات الرسمية، وطريقة الحكم على “كم عدد الأدوات اللازم للوصول إلى حجم يستحق عنده التفعيل”.
  • كيف تحسب التكلفة الحقيقية لمهمة Agent واحدة باستخدام حقل interaction.usage وقواعد التخزين المؤقت.

الفهرس: نبدأ بجدول المفاهيم ونظرة سريعة على التأثير، لمساعدتك على توحيد المصطلحات ومعرفة نوع القارئ الذي تنتمي إليه. أما قسم “الحقائق الموضوعية” فيعرض الآلية التي نشرتها Google وقواعد الفوترة والنص الأصلي للمثالين الحسابيين. ويقدم قسم “التحليل والحكم” نقطة التعادل المستندة إلى المعاملات الرسمية، والفرق بين ثلاثة أنواع من “التوفير”، وصيغة فاتورة المهمة الواحدة، وجدول قرار التفعيل.

gemini-tool-retrieval-token-cost-200-vs-10-tools-ar-image-0


تحليل تكلفة استرجاع الأدوات في Gemini To Know: شرح المفاهيم

المفهوم شرح موجز
رموز الإدخال (Input Token) وحدة القياس للنصوص والسياق التاريخي وإعلانات الأدوات وغيرها من المحتوى الذي يُرسل إلى النموذج ليعالجه
مخطط الأداة (Tool Schema) تعريف المعاملات الكامل الذي يعتمد عليه النموذج عند توليد استدعاء دالة؛ في مثال الحساب يبلغ كل مخطط نحو 400 رمز
قائمة الأدوات المؤجلة (Deferred Tools List) بعد ضبط defer_loading: true، لا يرى النموذج في البداية سوى أسماء الأدوات ووصف موجز لها، وقد بلغ كل عنصر منها نحو 26 رمزًا في الاختبارات الرسمية المبكرة
السياق الأساسي B معلومات السياق والمهمة التي كان النموذج سيعالجها أصلاً في كل استدعاء ضمن مثال الحساب
الاستدلال بعد البحث استدعاء إضافي للنموذج يُنفَّذ بعد أن يسترجع الخادم الأداة، حاملًا السياق الحالي ومخطط الأداة (Schema) المضاف
total_tool_use_tokens حجم الإدخال في استدعاءات النموذج الإضافية التي تحفّزها أدوات الخادم والبحث ضمن الطلب نفسه
total_cached_tokens الجزء من استهلاك الإدخال الذي تعالجه ذاكرة التخزين المؤقت ويُحتسب وفق سعرها
نقطة التعادل الحد الذي يتساوي عنده، في ظل المجموعة نفسها من الافتراضات، حجم تكلفة الإدخال في التحميل الثابت والتحميل عند الطلب
تكلفة المهمة الناجحة الواحدة مجموع تكاليف جولات استدعاء النموذج والأدوات اللازمة لإنجاز هدف عمل واحد

نظرة سريعة على تأثير استرجاع الأدوات في Gemini

  • مطورو الوكلاء الذين يربطون مكتبات أدوات كبيرة: عندما تكون الأدوات كثيرة وتُستخدم أداة أو اثنتان فقط في المهمة الواحدة، فهناك فرصة لخفض تكلفة إعادة إدخال مخططات الأدوات (Schema) بشكل ملحوظ. هذه هي الحالة التي يمثلها المثال الرسمي الخاص بـ 200 أداة.
  • مطورو التطبيقات ذات مجموعات الأدوات الصغيرة والسياق الطويل: كل عملية بحث من جهة الخادم تتطلب تشغيل استدلال إضافي للنموذج وإعادة معالجة سياق طويل، لذا قد يصبح الاستخدام أكثر تكلفة بعد التفعيل. المثال الرسمي الخاص بـ 10 أدوات هو الحالة المعاكسة.
  • مهندسو التكاليف ومسؤولو FinOps: الاعتماد فقط على total_input_tokens في الطلب الأول سيقلل من تقدير التكلفة، ولا بد من احتساب total_tool_use_tokens وإصابات التخزين المؤقت (cache hits) ورموز الإخراج (output tokens) معًا.
  • فرق المنصات التي تدير سجلات أدوات المؤسسة: يمكن لنمط الاسترجاع من جهة العميل أن يدمج تصفية الصلاحيات الخاصة بك والأدوات الديناميكية، لكن كل عملية بحث تضيف رحلة ذهاب وإياب إضافية إلى API، ويجب تقييم أساس التكلفة بشكل منفصل.

حقائق موضوعية: إطلاق Gemini Tool Retrieval وآلية الفوترة

ما هو Tool Retrieval في Gemini ومتى تم إطلاقه؟

أعلنت Google في مدونتها الرسمية يوم 19 نوفمبر 2026 عن إتاحة ميزة Tool Retrieval (استرجاع الأدوات) كمعاينة داخل Gemini Interactions API. الميزة لا تزال في مرحلة المعاينة، وتتطلب استخدام إصدار API ‏v1beta، ولا تدعمها الطريقة القديمة generateContent. لتفعيل وضع الخادم، أضف {"type": "tool_search"} إلى tools، واضبط defer_loading: true على كل function أو mcp_server ترغب في تأجيل تحميله.

حتى 20 نوفمبر 2026، كانت وثائق المطورين تذكر صراحةً أربعة معرّفات نماذج متوافقة: gemini-4-hydrogen وgemini-4-argon وgemini-3.8-flash وgemini-3.6-flash. عبارة «Gemini 3.6 والطرازات الأحدث» الواردة في الإعلان أوسع نطاقًا، لكن الطرازات غير المذكورة في الوثائق تحتاج إلى تحقق يدوي؛ وضبط defer_loading على طراز غير مدعوم يعيد HTTP 400.

ثمة نقطة يسهل فهمها خطأً وتحتاج إلى تأكيد: في وضع الخادم، لا يزال المطورون بحاجة إلى إرسال مصفوفة tools كاملة مع كل طلب، بما في ذلك المعاملات الكاملة للأدوات المؤجلة، حتى عند استخدام previous_interaction_id. ما تغيّره Tool Retrieval هو توقيت دخول المخطط الكامل (Schema) إلى سياق النموذج، وليس معناه أن هذه التعريفات لم تعد تُرسل في جسم الطلب.

من أين تأتي تكاليف التحميل الساكن واسترجاع الأدوات في Gemini؟

في التحميل الساكن، يجب مع كل استدعاء للنموذج قراءة المخطط الكامل (Schema) لكل الأدوات، حتى لو لم تُستخدم في هذه الجولة سوى دالة استرداد واحدة. أما Tool Retrieval فيستبدل هذه التعريفات الكاملة بقائمة أدوات مختصرة؛ وعندما يحتاج النموذج إليها يرسل tool_search_call، فيعيد الخادم tool_search_result متضمّنًا المخطط الكامل، ثم يولّد النموذج بناءً عليه function_call.

توضح Google صراحةً أن Tool Retrieval لا تفرض رسومًا وظيفية مستقلة، لكن العناصر التالية لا تزال تُحتسب وفق تسعيرة النموذج المختار:

  1. جميع عناصر القائمة المختصرة للأدوات ذات التحميل المؤجل.
  2. تعليمات البحث الثابتة التي تُضاف بعد تفعيل tool_search.
  3. الاستدلال الإضافي للنموذج الذي يُحرّكه كل استرجاع من الخادم، إذ يعيد معالجة السياق الكامل والمخططات المحمّلة حديثًا.
  4. المخططات الكاملة للأدوات المحمّلة، واستمرار احتسابها في الجولات اللاحقة (لا توفر الوثائق الحالية آلية لإلغاء التحميل).
  5. الرموز (Tokens) الاعتيادية الخاصة بالمخرجات وThinking ونتائج تنفيذ الأدوات.

gemini-tool-retrieval-token-cost-200-vs-10-tools-ar-image-1

أمثلة حسابية رسمية لـ Gemini Tool Retrieval: 200 أداة مقابل 10 أدوات

كلتا المجموعتين من الأمثلة الحسابية مأخوذة من وثائق Google Tool Retrieval، وهي حسابات افتراضية مصنّفة رسميًا، وليست اختبار أداء (Benchmark) في بيئة إنتاج، كما تتجاهل كلتاهما رموز الإخراج ومكاسب التخزين المؤقت. والمعايير الموحّدة هي: 400 رمز لكل Schema كامل، وحوالي 26 رمزًا لكل وصف مختصر لأداة مؤجلة، و150 رمزًا لتعليمات البحث، ومهمة واحدة تتضمن طلبين خارجيين، وإتمام بحث واحد من جانب الخادم في الطلب الأول، وتحميل أداتين إجمالًا.

بند الحساب 200 أداة، B=2,000 10 أدوات، B=30,000
التحميل الثابت: 2 × (B + N × 400) 164,000 68,000
الإدخال الأولي للطلب 1 (B + N × 26 + 150) 7,350 30,410
الاستدلال بعد البحث للطلب 1 (بإضافة 2 Schema) 8,150 31,210
إدخال الطلب 2 8,150 31,210
إجمالي Tool Retrieval 23,650 92,830
مقدار التغير -140,350 +24,830
نسبة التغير (حساب ثانوي بالأرقام الرسمية) نحو -85.6% نحو +36.5%

يعود وضوح التوفير في سيناريو الـ 200 أداة إلى أن الحل الثابت يتحمّل في كل مرة تعريفات أدوات بحجم 80,000 رمز، بينما السياق الأساسي لا يتجاوز 2,000 رمز، فتصبح تكلفة تشغيل استدلال إضافي واحد للبحث صغيرة جدًا. أما سيناريو الـ 10 أدوات فالعكس تمامًا: تعريفات الأدوات لا تتجاوز 4,000 رمز إجمالًا، والمساحة القابلة للتوفير محدودة، بينما يتطلب الاستدلال بعد البحث معالجة السياق الطويل البالغ 30,000 رمز مرة أخرى، فيتجاوز العبء الإضافي حجم التوفير مباشرة.

حقول Usage في Gemini Tool Retrieval والأسعار وقواعد التخزين المؤقت

توفّر Google في interaction.usage الحقول اللازمة لتحليل تكلفة Tool Retrieval:

الحقل المعنى دوره في تحليل التكلفة
total_input_tokens مدخلات أول استدعاء للنموذج داخل الطلب لا يعكس سوى «مقدار تقلّص السياق الأولي»
total_tool_use_tokens مدخلات الاستدعاءات الإضافية للنموذج الناتجة عن أدوات الخادم والبحث المصدر الرئيسي لتكلفة البحث، وهو الأكثر عرضة للتجاهل
total_cached_tokens الجزء المشمول في المدخلات والذي تعالجه ذاكرة التخزين المؤقت يُحسب بسعر التخزين المؤقت، ولا يجوز جمعه مرة أخرى
total_output_tokens المخرجات التي يولّدها النموذج تُحسب بسعر المخرجات
total_thought_tokens الـ Token الناتجة عن عملية الاستدلال تُحسب بسعر مخرجات النموذج المختار

أما من ناحية الأسعار، ففي فئة الأسعار القياسية Standard على صفحة أسعار Google، يكون سعر مدخلات Gemini 4 Hydrogen هو 1.50 دولار لكل مليون Token، وسعر المخرجات (بما فيها Thinking) هو 7.50 دولار، وسعر المدخلات المخزّنة مؤقتًا هو 0.075 دولار. وإذا اكتفينا بضرب سعر المدخلات هذا في أعداد الـ Token المفترضة في المثال الرسمي، فإن سيناريو الـ 200 أداة يعطي نحو 0.246 دولار مقابل 0.0355 دولار، وسيناريو الـ 10 أدوات يعطي نحو 0.102 دولار مقابل 0.139 دولار. وهذا مجرد ضرب لأعداد Token افتراضية في الأسعار الرسمية، وليس أي فاتورة حقيقية.

لقواعد التخزين المؤقت عتبتان ينبغي فهم كل منهما على حدة. أولاً، لا تدعم Interactions API سوى التخزين المؤقت الضمني، واعتبارًا من 20 نوفمبر 2026، فإن الحد الأدنى لحجم المدخلات في التخزين المؤقت الضمني لكل من سلسلة Gemini 4 وGemini 3.8 Flash وGemini 3.6 Flash هو 4,096 Token. ثانيًا، في المحادثات متعددة الأدوار وفي Agent Loop ضمن Gemini 4، يجب أن يضيف الطلب الجديد 2,050 Token على الأقل حتى يخزّن النظام الطلب السابق بالكامل؛ وإذا قلّ عن ذلك، فإن آخر 2,050 Token من الطلب السابق تُحتسب من جديد بسعر المدخلات القياسي، وتدخل مخرجات النموذج وThinking ونتائج الدوال جميعها في هذا الحجم الإضافي.

وحتى تاريخ التحقق من المواد، لم تنشر Google نسبة توفير الـ Token على مجموعات مهام حقيقية، ولا مقدار التحسّن في زمن الاستجابة، ولا نسبة التحسّن في دقة اختيار الأدوات، كما لم نرَ أي قياس إنتاجي مستقل من مطوّرين يمكن التحقق منه على نحو كافٍ.

تحليل وتقييم: متى يوفر Gemini Tool Retrieval الرموز فعلاً؟

نقطة التعادل في استرداد الأدوات من Gemini: عند أي عدد من الأدوات يصبح التفعيل مجديًا؟

ما يلي مثال موسّع مشتق باستخدام معاملات المثال الرسمي، وليس حدًا عامًا نشرته Google. لنفترض أن N هو إجمالي عدد الأدوات، وأن B هو السياق الأساسي، مع الإبقاء على S=400 وD=26 وH=150 وK=2 وعلى منطق «طلبين وعملية بحث واحدة»:

  • التحميل الثابت: T_static = 2 × (B + 400N)
  • التحميل عند الطلب: T_retrieval = 3 × (B + 26N + 150) + 2 × 2 × 400

يمكن لهذه المعادلة أن تعيد إنتاج نتيجتي Google الرسميتين بالكامل. وبجعل T_retrieval < T_static، ثم بالتبسيط نحصل على 722N > B + 2050، أي N > (B + 2050) / 722. الرقم 2050 هنا ناتج عن 3 × 150 + 1600، وهو مجرد نتيجة جبرية، ولا علاقة له على الإطلاق بشرط زيادة 2,050 توكنًا في التخزين المؤقت متعدد الجولات في Gemini 4 ضمن وثائق التخزين المؤقت، فلا تخلط بينهما.

السياق الأساسي B عدد الأدوات N التحميل الثابت استرداد الأدوات التغيّر النسبة مصدر البيانات
2,000 200 164,000 23,650 -140,350 -85.6% المثال الرسمي
30,000 10 68,000 92,830 +24,830 +36.5% المثال الرسمي
30,000 44 95,200 95,482 +282 +0.3% اشتقاق موسّع
30,000 45 96,000 95,560 -440 -0.5% اشتقاق موسّع
30,000 50 100,000 95,950 -4,050 -4.1% اشتقاق موسّع
30,000 100 140,000 99,850 -40,150 -28.7% اشتقاق موسّع

عند B=30,000 تكون القيمة الحرجة N > 44.39، أي أن التحميل عند الطلب يبدأ في التفوق بشكل طفيف بدءًا من الأداة 45، وعند نقطة التعادل تقريبًا يكون التوفير ضئيلًا جدًا. وباستخدام المعادلة نفسها، إذا كانت B=2,000 فإن القيمة الحرجة تساوي نحو 5.6، أي أن 6 أدوات تكفي لقلب النتيجة. من هنا يتبين أن كلما طال السياق الأساسي، زادت الحاجة إلى مكتبة أدوات أكبر لتوزيع تكلفة إعادة معالجة السياق أثناء البحث.

gemini-tool-retrieval-token-cost-200-vs-10-tools-ar-image-2

تعليق الشكل: الصفان الأولان من البيانات هما مثال Google الرسمي، والباقي مشتق بالمنهجية نفسها. ستغيّر عدد عمليات البحث وعدد عمليات التحميل في المهام الحقيقية المنحنى، لذا يُنصح بإعادة القياس باستخدام طلبات عملك الفعلية. ويمكنك عبر واجهة APIYI الموحدة على apiyi.com تشغيل خطوط أساس التحميل الثابت لعدة نماذج بسرعة للمقارنة.

المهام الواقعية نادرًا ما تتوافق تمامًا مع هذه المجموعة من الافتراضات، فالمتغيّرات التالية تُزيح نقطة التحوّل:

  1. عدد عمليات البحث: كل عملية بحث إضافية على الخادم تعني إدخالًا إضافيًا للنموذج يقترب من حجم «B + قائمة الأدوات + المخططات المحمّلة»، وفي سيناريوهات السياق الطويل يعني ذلك دفع تكلفة B مرة أخرى مع كل بحث.
  2. عدد الأدوات المحمّلة فعليًا K: كلما زاد عدد الأدوات المحمّلة قلّ التوفير؛ فالمخططات المحمّلة لا يمكن إلغاء تحميلها، وتتراكم باستمرار في الجلسات الطويلة.
  3. حجم المخطط الواحد S: الأدوات ذات المعاملات المعقّدة والأوصاف المطوّلة تحقّق فائدة أكبر من التحميل عند الطلب؛ أما المخططات القصيرة جدًا فتلتهم فائدتها بنود القائمة وتعليمات البحث.
  4. عدد جولات الجلسة: في الحلول الثابتة تتكرّر كل المخططات في كل جولة؛ وكلما زاد عدد الجولات دون تفعيل بحث جديد، ازدادت ميزة التحميل عند الطلب وضوحًا.

تقليل رموز الإدخال، وانخفاض الفاتورة الإجمالية، واستجابة أسرع: ثلاثة أوجه «للتوفير» في Gemini Tool Retrieval

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

انخفاض الفاتورة الإجمالية يعتمد أيضًا على التخزين المؤقت وسعر الوحدة. فالتحميل عند الطلب يقصّر الموجه الأولي، وإذا كان عبور عتبة التخزين المؤقت الضمني عند 4,096 رمزًا قد تحقّق أصلًا بفضل كثرة المخططات، فإن تفعيله قد يفقدك التخزين المؤقت بدلًا من أن يكسبك إياه. كذلك الحلقة القصيرة لاستدعاء الدوال وإعادة النتائج: إن كانت المحتويات الجديدة أقل من 2,050 رمزًا، فلن يتمكّن Gemini 4 من الحصول على التخزين المؤقت الكامل للطلب السابق. أي أن الرموز قد تقل، لكن بنية سعر الوحدة قد تسوء.

استجابة أسرع: لا تدعمها حاليًا أي بيانات رسمية أو مستقلة. فالبحث على الخادم لا يضيف جولة ذهاب وإياب من جانب العميل، لكن الطلب نفسه ينفّذ داخليًا استدلالًا إضافيًا للنموذج؛ أما البحث من جانب العميل فيضيف جولة API واحدة مع كل عملية بحث. والسؤال: هل يتحسّن زمن الاستجابة أم يسوء؟ لا جواب إلا عبر اختبارك الشامل من طرف إلى طرف.

كيف تحسب الفاتورة الفعلية لمهمة واحدة من Gemini Tool Retrieval Agent

بناءً على دلالات الاستخدام (Usage) الرسمية، وفي ظل التسعير القياسي، واحتساب رموز التخزين المؤقت ضمن رموز الإدخال، وعدم وجود أدوات أخرى تُحتسب لكل استدعاء، يمكن تقدير الطلب الواحد كما يلي:

USD ≈ [ (I + U − C) × P_in + C × P_cache + (O + T) × P_out ] / 1,000,000

حيث تقابل I و U و C و O و T بالترتيب الحقول الخمسة في الجدول أعلاه. غالبًا ما تمتد مهمة Agent واحدة عبر عدة طلبات، لذا يلزم تجميع Usage الخاص بكل طلب ثم إجراء الحساب، وأخيرًا الحصول على تكلفة المهمة الناجحة الواحدة عبر «التكلفة الإجمالية ÷ عدد المهام المكتملة بنجاح».

قبل تفعيل Tool Retrieval، فإن قياس خط الأساس للتحميل الثابت هو الطريقة الأكثر أمانًا. وفي ما يلي نشغّل مرة واحدة عملية Function Calling ثابتة عبر واجهة متوافقة مع OpenAI، ونسجّل Usage الأساسي:

import openai

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

resp = client.chat.completions.create(
    model="gemini-3.8-flash",  # اسم النموذج يتبع قائمة نماذج المنصة
    messages=[{"role": "user", "content": "Refund 40 USD for order A-1042."}],
    tools=[{"type": "function", "function": {"name": "issue_refund",
            "parameters": {"type": "object", "properties": {
                "order_id": {"type": "string"}, "amount": {"type": "number"}},
                "required": ["order_id", "amount"]}}}]
)
print(resp.usage)  # تسجيل رموز الإدخال والإخراج عند التحميل الثابت الكامل

تجدر الإشارة إلى أن Tool Retrieval نفسه يعتمد على الإصدار v1beta من Google Interactions API. المثال أعلاه يُستخدم فقط للحصول على بيانات المقارنة الخاصة بالتحميل الثابت، أما الجانب المتعلق بالتحميل عند الطلب فيجب استخدام طريقة استدعاء تدعم Interactions API، ثم وضع Usage من الجانبين في صيغة التكلفة نفسها للمقارنة.

عرض كود التنفيذ الكامل: حساب نقطة التعادل + تقدير فاتورة Usage
import openai

# ---------- 1. حساب نظري وفق منهجية المثال الرسمي (مثال موسّع، وليس عتبة رسمية) ----------
def static_tokens(B: int, N: int, S: int = 400) -> int:
    return 2 * (B + N * S)

def retrieval_tokens(B: int, N: int, D: int = 26, H: int = 150,
                     K: int = 2, S: int = 400) -> int:
    return 3 * (B + N * D + H) + 2 * K * S

def breakeven_tools(B: int) -> float:
    return (B + 2050) / 722  # صالح فقط عندما S=400 وD=26 وH=150 وK=2

for B, N in [(2000, 200), (30000, 10), (30000, 45), (30000, 100)]:
    s, r = static_tokens(B, N), retrieval_tokens(B, N)
    print(f"B={B:>6} N={N:>3} static={s:>7} retrieval={r:>7} "
          f"change={(r - s) / s:+.1%}")
print("B=30000 临界工具数:", round(breakeven_tools(30000), 2))

# ---------- 2. تقدير تكلفة الطلب الواحد (بالدولار) وفق حقول Usage ----------
def request_cost(I, U, C, O, T, p_in, p_cache, p_out) -> float:
    """I/U/C/O/T تقابل total_input / tool_use / cached / output / thought tokens"""
    return ((I + U - C) * p_in + C * p_cache + (O + T) * p_out) / 1_000_000

# مثال: السعر القياسي لـ Gemini 4 Hydrogen هو 1.50 / 0.075 / 7.50 (لكل مليون Token)
print(request_cost(I=7350, U=8150, C=0, O=200, T=0,
                   p_in=1.50, p_cache=0.075, p_out=7.50))

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

def run_static_baseline(prompt: str, tools: list, model: str = "gemini-3.8-flash"):
    resp = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": prompt}],
        tools=tools
    )
    return resp.usage  # عند تجميع مهام متعددة الجولات، اجمعها طلبًا بعد طلب

🚀 بداية سريعة: يُستحسن أولاً تشغيل خط أساس التحميل الثابت على APIYI apiyi.com بمفتاح واحد، وتسجيل عدد الـ Tokens ومعدل الإنجاز لمجموعة مهام عملك الحقيقية، ثم تحديد ما إذا كان ينبغي ترحيل الـ Agent إلى التحميل عند الطلب، بدلًا من تغيير البنية مباشرةً اعتمادًا على الأرقام التوضيحية الرسمية.

قرار تفعيل Gemini Tool Retrieval: هل مكتبة أدواتك مؤهلة؟

بالجمع بين التوصيات الهندسية الرسمية والاستنتاجات السابقة، يمكن استخدام الجدول التالي للحكم المبدئي، على أن يبقى الفصل النهائي لتكلفة المهمة الواحدة الناجحة ومعدل الإنجاز في المهام الحقيقية:

خصائص عبء العمل الاستراتيجية المقترحة السبب
أقل من نحو 20 أداة مستقرة، ومعظمها يُستخدم في كل جولة الاستمرار في التحميل الساكن توصية رسمية؛ عدد الـ Schema الذي يمكن توفيره صغير، وتبلغ نسبة تكلفة البحث حصة مرتفعة
أدوات قليلة لكن السياق الأساسي طويل جدًا التحميل الساكن، أو تأجيل عدد قليل من الأدوات ذات الـ Schema الكبيرة فقط كل عملية بحث تعيد معالجة السياق الطويل؛ ومثال الـ 10 أدوات هو حالة مضادة
من عشرات إلى مئات الأدوات، ولا يُستخدم سوى عدد قليل منها في الاستدعاء الواحد إعطاء الأولوية لتقييم الاسترجاع من جهة الخادم مكتبات الأدوات الكبيرة ذات الذيل الطويل هي الحالة المقابلة للمثال الرسمي بـ 200 أداة
مزيج من أدوات عالية التكرار وأدوات تخصصية منخفضة التكرار تحميل الأدوات عالية التكرار مباشرة، وتأجيل منخفضة التكرار عبر defer_loading الاستخدام المختلط الموصى به رسميًا، لتجنب البحث أولًا حتى في المهام البسيطة
بيئة متعددة المستأجرين، وأدوات ديناميكية، وضرورة التصفية حسب صلاحيات المستخدم تقييم الاسترجاع من جهة العميل يمكن ربط سجل أدوات مبنى ذاتيًا، لكن كل بحث يضيف رحلة ذهاب وعودة
أدوات تُذكر بالاسم كثيرًا في تعليمات النظام الإبقاء على التحميل المباشر تحذير رسمي: الأدوات المؤجلة المذكورة بالاسم قد تُستدعى مباشرة متجاوزةً البحث، فتقع في أخطاء

💡 توصية الاختيار: شغّل المجموعة نفسها من المهام مرتين، مرة بالتحميل الساكن ومرة بالتحميل عند الطلب، مع إبقاء النموذج ومكتبة الأدوات وطول السياق وظروف التخزين المؤقت ثابتة. ومن خلال APIYI apiyi.com يمكنك التبديل بين Gemini وغيره من النماذج السائدة ضمن واجهة موحدة لبناء خط أساس للمقارنة، مما يسهّل نسب فرق التكلفة إلى استراتيجية تحميل الأدوات نفسها.

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

في جوهره، 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
  3. وثائق Google Context caching: عتبات التخزين المؤقت الضمني، وقواعد التخزين المؤقت متعدد الجولات في Gemini 4
    • الرابط: aistudio.google.com/docs/caching
  4. تسعير Google Gemini Developer API: أسعار الإدخال والإخراج والتخزين المؤقت للنماذج
    • الرابط: aistudio.google.com/docs/pricing

المؤلف: فريق APIYI التقني
التواصل التقني: إذا كنت تريد مقارنة تكاليف الرموز (Token) بين عدة نماذج مثل Gemini في سيناريوهات Agent، فمرحبًا بك في زيارة APIYI على apiyi.com للحصول على حصة اختبار. ولمزيد من تفاصيل التكامل، راجع مركز الوثائق docs.apiyi.com

أضف تعليق