DEV Community

Cover image for استدعاء الدوال مع Gemini 3.8 Flash: معرف الاستدعاء، حلقات الأدوات التكرارية، وكيفية اختبارها
Yusuf Khalidd
Yusuf Khalidd

Posted on Originally published at apidog.com

استدعاء الدوال مع Gemini 3.8 Flash: معرف الاستدعاء، حلقات الأدوات التكرارية، وكيفية اختبارها

بناء حلقة استدعاء أدوات موثوقة مع Gemini 3.8 Flash

تم إطلاق Gemini 3.8 Flash في 2 سبتمبر 2026، وصُمم من جوجل لـ«استدعاء الأدوات بشكل متكرر»: ففي المهام الصعبة يجري مكالمة، ويتحقق من النتيجة، ثم يجري مكالمة أخرى بدلًا من تخمين كل شيء دفعة واحدة. هذا مفيد للوكلاء، لكنه قد يسبب مشكلات إذا كانت حلقة الأدوات لديك مضبوطة على 3.7 Flash. أهم تغييرين في واجهة برمجة التطبيقات هما: ضرورة إرسال call_id وname مع كل نتيجة دالة، واعتماد Interactions API كطريقة أساسية لتشغيل الحلقة بدلًا من generateContent.

جرّب Apidog اليوم

يشرح هذا الدليل تدفقًا كاملًا من دورتين باستخدام Interactions API، ثم يوضح الصيغة القديمة في generateContent، وسبب زيادة دورات الأدوات والتوكنات في Gemini 3.8 Flash، وكيفية وضع سقف للحلقة واختبارها يوميًا. إذا كنت تحتاج إلى مقدمة عن النموذج، فابدأ بدليل ما هو Gemini 3.8 Flash.

كل الطلبات التالية HTTP عادية مع JSON، ولذلك يمكنك بناؤها وتصحيحها في Apidog قبل دمجها في تطبيقك.

Gemini 3.8 Flash باختصار

العنصر القيمة
معرّف النموذج gemini-3.8-flash، إصدار مستقر بلا لاحقة معاينة
واجهة API الأساسية Interactions API عبر POST /v1beta/interactions؛ وgenerateContent قديم لكنه مدعوم بالكامل
إعلان الأداة tools: [{"type": "function", "name", "description", "parameters"}]
استدعاء النموذج خطوة function_call تحتوي على id وname وarguments
رد التطبيق function_result يحتوي على call_id وname، مع previous_interaction_id
التفكير low أو medium (الافتراضي) أو high؛ أما minimal فيؤدي إلى خطأ تحقق
استخدام الأدوات Tau3-Banking بنسبة 45%، بزيادة 12 نقطة عن 3.7 Flash، وفق تحليل اصطناعي مستقل
استهلاك التوكنات نحو 48 ألف توكن إخراج لكل مهمة في مؤشر AA، بزيادة 30% عن 3.7 Flash
السعر 0.75 دولار للتوكن الداخل و3.75 دولار للتوكن الخارج لكل مليون توكن حتى 31 ديسمبر 2026؛ ويُحاسب التفكير كإخراج

1. أعلن عن الأداة

في Interactions API، يكون إعلان الأداة كائنًا مسطحًا يحتوي على type وname وdescription ومخطط JSON في parameters.

اجعل الوصف محددًا. الوصف التالي قابل للتنفيذ:

البحث عن حالة الشحن الحالية لطلب معين باستخدام معرّف الطلب

أما وصف مثل «مساعد الطلبات» فقد يدفع النموذج إلى استدعاء الأداة عشوائيًا.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-[REDACTED CREDENTIAL] \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Where is order A1029 right now?",
    "generation_config": {"thinking_level": "low"},
    "tools": [{
      "type": "function",
      "name": "get_order_status",
      "description": "Look up the current shipping status of an order by its ID.",
      "parameters": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"]
      }
    }]
  }'
Enter fullscreen mode Exit fullscreen mode

هناك خياران مهمان في الطلب:

  • استخدمنا thinking_level: "low" لأن البحث الواحد لا يحتاج إلى المستوى الافتراضي medium. راجع دليل مستويات التفكير لمعرفة متى ترفع المستوى.
  • لم نرسل temperature. توصي إرشادات Gemini 3 من جوجل بتركه على القيمة الافتراضية 1.0، لأن خفضه قد يزيد احتمال حدوث حلقات غير مرغوبة.

2. اقرأ خطوة function_call

لا تُرجع Interactions API رسالة واحدة، بل تعيد معرّف التفاعل وقائمة بخطوات التنفيذ، مثل أفكار النموذج واستدعاءات الأدوات ثم model_output.

عندما يحتاج النموذج إلى أداة، ستجد خطوة function_call بدلًا من model_output:

{
  "type": "function_call",
  "id": "call_8f2d...",
  "name": "get_order_status",
  "arguments": {
    "order_id": "A1029"
  }
}
Enter fullscreen mode Exit fullscreen mode

تحتاج إلى الحقول الثلاثة:

  • id: أرسله لاحقًا كـcall_id.
  • name: يحدد الدالة التي يجب تشغيلها، ويجب إعادته أيضًا.
  • arguments: كائن JSON محلل مسبقًا.

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

احفظ أيضًا id الموجود أعلى استجابة التفاعل؛ ستستخدمه بوصفه previous_interaction_id في الدورة التالية.

3. أعد النتيجة باستخدام call_id وname

شغّل الدالة ثم أرسل طلبًا ثانيًا يحتوي على function_result. يتطلب Gemini 3.8 Flash كلاً من call_id وname:

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-[REDACTED CREDENTIAL] \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "previous_interaction_id": "<interaction id from step 2>",
    "input": [{
      "type": "function_result",
      "name": "get_order_status",
      "call_id": "call_8f2d...",
      "result": [{"type": "text", "text": "{\"status\":\"in_transit\",\"eta\":\"2026-09-05\"}"}]
    }]
  }'
Enter fullscreen mode Exit fullscreen mode

إسقاط أحد الحقلين يؤدي إلى فشل الطلب، وهو أكثر الأخطاء شيوعًا عند نقل حلقات كُتبت لنماذج أقدم.

result قائمة من أجزاء المحتوى، ويُرسل JSON الخاص بك كسلسلة نصية. وبما أن previous_interaction_id يشير إلى الدورة السابقة، يحتفظ الخادم بالمطالبة الأصلية وإعلان الأداة وسياق النموذج؛ لذلك لا تحتاج إلى إعادة إرسالها.

بعد ذلك:

  1. إذا انتهت الاستجابة بخطوة model_output، انتهت الحلقة، ويمكنك قراءة النص من interaction.output_text.
  2. إذا احتوت على function_call أخرى، شغّل الأداة وأعد النتيجة بالطريقة نفسها.
  3. استمر حتى الوصول إلى نتيجة نهائية أو إلى سقف الدورات الذي تحدده أنت.

في بايثون، يكون النمط المكافئ:

client.interactions.create(
    model="gemini-3.8-flash",
    input=...,
    ...
)
Enter fullscreen mode Exit fullscreen mode

ثم تستدعي create مرة ثانية باستخدام previous_interaction_id وقائمة function_result في input. يغطي دليل كيفية استخدام Gemini 3.8 Flash API المفاتيح والبث وقراءة استخدام التوكنات.

الصيغة القديمة مع generateContent

لا يزال كثير من كود Gemini يستخدم:

models/gemini-3.8-flash:generateContent
Enter fullscreen mode Exit fullscreen mode

وتصف جوجل هذه الواجهة بأنها قديمة لكنها «مدعومة بالكامل» دون تاريخ إيقاف.

المفردات مختلفة، لكن العقد نفسه:

  • إعلان الأدوات يكون تحت functionDeclarations.
  • يرد النموذج بجزء functionCall.
  • ترد أنت بجزء functionResponse.
  • يجب أن يعكس id في functionResponse قيمة id في functionCall.
  • يجب إرسال id وname معًا.

تكون الواجهة بلا حالة، لذلك عليك حمل سجل المحادثة كاملًا في كل دورة، بما فيه جزء functionCall وتوقيعات التفكير.

كما يختلف إعداد التفكير:

{
  "generationConfig": {
    "thinkingConfig": {
      "thinkingLevel": "low"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

تظهر توكنات التفكير في:

usageMetadata.thoughtsTokenCount
Enter fullscreen mode Exit fullscreen mode

وتتم فوترتها كتوكنات إخراج. إذا كنت تبدأ مشروعًا جديدًا، فاختر Interactions API لتقليل أخطاء إدارة الحالة، مثل فقدان توقيع أو call_id.

لماذا تتكرر استدعاءات الأدوات؟

تقول جوجل في منشور الإطلاق إن النموذج «يعمل بجهد أكبر» عبر تنفيذ خطوات استدلال إضافية، واستدعاء الأدوات بشكل متكرر، والتحقق من عمله باستخدام خطوات أصغر.

كما يمكنه استخدام توكنات أكثر في المهام الطويلة والمعقدة حسب التصميم. ووفق Artificial Analysis:

  • بلغ متوسط الإخراج نحو 48 ألف توكن لكل مهمة، بزيادة 30% عن 3.7 Flash.
  • بلغت تكلفة المهمة نحو 0.58 دولار عند high مقابل 0.40 دولار في 3.7 Flash.
  • بلغت التكلفة 0.41 دولار عند medium و0.24 دولار عند low.
  • ارتفعت نتيجة Tau3-Banking لاستخدام الأدوات 12 نقطة إلى 45%.

النتيجة العملية: استدعاءات أدوات أكثر، ووقت أطول، وتكلفة أعلى محتملة. لذلك ضع الضوابط التالية:

  1. حد أقصى للدورات: ابدأ بـ6 إلى 10 دورات لعمليات البحث، واستخدم سقفًا أعلى للبرمجة الذاتية. عند بلوغ السقف، أرسل دورة أخيرة بلا أدوات أو أعد خطأ واضحًا للمستخدم.
  2. مستوى تفكير لكل مسار: استخدم low للبحث ذي الخطوة الواحدة، وmedium للمهام متعددة الخطوات، وhigh عندما يستحق التحقق الإضافي تكلفته. لا تستخدم minimal؛ فهو يؤدي إلى خطأ تحقق.
  3. مهلات زمنية: ضع مهلة لكل طلب إلى Gemini، ومؤقتًا شاملًا لكل مهمة. بلغ متوسط التشغيل عالي التفكير لدى AA نحو 2.5 دقيقة للمهمة، مقابل 0.8 دقيقة عند المستوى المنخفض.
  4. أدوات idempotent: قد يعيد النموذج المحاولة. اجعل get_order_status آمنًا للتكرار، واطلب تأكيدًا صريحًا قبل العمليات ذات الآثار الجانبية مثل الاسترداد أو الإرسال.

إذا كانت ميزانيتك لا تتحمل الدورات الإضافية، فاستخدم دليل الترحيل من 3.7 إلى 3.8 Flash للاحتفاظ بـ3.7 خلف علامة إعداد.

توقيعات التفكير والمكالمات المتوازية والمخرجات المنظمة

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

ترفق نماذج Gemini 3 توقيعات بمنطقها. في التدفق المخزن افتراضيًا، يتعامل previous_interaction_id مع ذلك نيابةً عنك.

أما عند استخدام store: false أو generateContent، فأعد إرسال كتل التفكير وتوقيعاتها كما استلمتها، مع كل نوع جزء. لا تقطعها أو تعيد ترتيبها أو تعيد تسلسلها؛ فهي قيم غير شفافة وأي تعديل قد يبطلها. راجع وثائق Interactions API لمعرفة الفرق بين الحالة المخزنة وعديمة الحالة.

المكالمات المتوازية

الاستجابة قائمة، ولذلك قد تحتوي على عدة خطوات function_call لعمليات بحث مستقلة. لكل استدعاء معرّف فريد، ويمكن أن تعود النتائج بأي ترتيب.

أعد function_result واحدًا لكل استدعاء داخل مصفوفة input نفسها، مع مطابقته عبر call_id. لا تعتمد على name فقط؛ فقد يستدعي النموذج الدالة نفسها مرتين بمعرّفين مختلفين.

المخرجات المنظمة

يدعم Gemini 3.8 Flash المخرجات المنظمة واستدعاء الدوال في النموذج نفسه. النمط العملي هو:

  • استخدم الأدوات أثناء الحلقة.
  • استخدم مخطط JSON للإجابة النهائية.
  • اجعل model_output النهائي قابلًا للمعالجة آليًا.

لا تعلن عن أداة وهمية لاستخراج arguments؛ سيتعطل هذا النمط عندما يقرر النموذج أنه لا يحتاج إلى استدعاء أداة.

توضح وثائق استدعاء الدالة ووثائق المخرجات المنظمة إعدادات هذه المزايا. كما توفر جوجل استخدام الكمبيوتر، حاليًا في المعاينة، لـ3.8 Flash. راجع استخدام الكمبيوتر مقابل واجهات API المنظمة لاختيار الأسلوب المناسب للوكيل.

اختبار حلقة الأدوات في Apidog

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

1. حاكِ الواجهة الخلفية للأداة

أنشئ نقطة النهاية:

GET /orders/{order_id}
Enter fullscreen mode Exit fullscreen mode

وشغّل خادم المحاكاة باستخدام استجابة ثابتة:

{
  "status": "in_transit",
  "eta": "2026-09-05"
}
Enter fullscreen mode Exit fullscreen mode

استخدم عنوان المحاكاة في بيئة الاختبار، والعنوان الحقيقي في الإنتاج.

2. اربط الدورتين في سيناريو اختبار

خزّن GEMINI_API_KEY كمتغير بيئة، ثم استخدمه في رأس الطلب:

{{GEMINI_API_KEY}}
Enter fullscreen mode Exit fullscreen mode

ابنِ السيناريو من ثلاث خطوات:

  • الخطوة أ: أرسل POST إلى /v1beta/interactions مع المطالبة وإعلان get_order_status. استخرج id التفاعل وid استدعاء الدالة وname وarguments.order_id إلى متغيرات.
  • الخطوة ب: أرسل GET إلى نقطة المحاكاة باستخدام {{order_id}}. هذه هي عملية تشغيل الدالة.
  • الخطوة ج: أرسل POST آخر يحتوي على function_result، مع الإعدادات التالية:
    • call_id: {{call_id}}
    • name: {{tool_name}}
    • previous_interaction_id: {{interaction_id}}
    • النص الناتج من الخطوة ب داخل جزء نصي.

يوفر دليل اختبار واجهة API لوكلاء الذكاء الاصطناعي أمثلة إضافية على السيناريوهات متعددة الخطوات.

3. تحقق من النتائج

تحقق من الآتي:

  • الخطوة أ تعيد 200 وتحتوي على function_call باسم get_order_status.
  • قيمة arguments.order_id تساوي A1029.
  • الخطوة ج تعيد 200 وتنتهي بـmodel_output دون استدعاء دالة ثانٍ.
  • يحتوي النص النهائي على in_transit.
  • عند اختبار generateContent، ضع سقفًا على usageMetadata.thoughtsTokenCount لكل مستوى تفكير لاكتشاف زيادة التكلفة مبكرًا.

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

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

هل call_id مطلوب في Gemini 3.8 Flash؟

نعم. في Interactions API، يحتاج كل function_result إلى call_id وname. وفي generateContent، يحتاج كل functionResponse إلى id وname الخاصين بالاستدعاء. الكود الذي يرسل الاسم فقط يفشل مع نماذج Gemini 3.

لماذا تستغرق الحلقة دورات أكثر مقارنة بـ3.7 Flash؟

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

هل ما زال generateContent مدعومًا؟

نعم، لكنه قديم ومدعوم بالكامل دون تاريخ إيقاف معلن. عليك إدارة سجل المحادثة وتوقيعات التفكير بنفسك، مع إرسال id وname في استجابة الدالة.

هل يعمل thinking_level: "minimal" مع الأدوات؟

لا. يعيد Gemini 3.8 Flash خطأ تحقق. استخدم low.

كم تبلغ تكلفة المهمة كثيفة استخدام الأدوات؟

السعر هو 0.75 دولار للتوكن الداخل و3.75 دولار للتوكن الخارج لكل مليون توكن حتى 31 ديسمبر 2026، مع احتساب التفكير كإخراج. قاست Artificial Analysis نحو 0.58 دولار للمهمة عند high، و0.41 دولار عند medium، و0.24 دولار عند low. قد تختلف نتائجك، لذا راقب عدد التوكنات وقِس الاستخدام الفعلي.

الخلاصة: انشر الحلقة بسقف واضح

العقد الأساسي بسيط:

  1. أعلن عن الأداة.
  2. اقرأ function_call.
  3. شغّل الدالة.
  4. أرسل function_result مع call_id وname تحت previous_interaction_id.
  5. كرر حتى model_output أو حتى بلوغ سقف الدورات.

ما تغير في Gemini 3.8 Flash هو ميل النموذج إلى التكرار، لذلك يحتاج نظامك إلى حد أقصى للدورات، ومستوى تفكير لكل مسار، ومهلات زمنية. حاكِ الواجهة الخلفية، اربط الدورتين، تحقق من عودة المعرّف ذهابًا وإيابًا، وشغّل السيناريو يوميًا. راجع ما الجديد في Gemini 3.8 Flash لملاحظات الترحيل، ثم اختبر التنفيذ قبل نقله إلى الإنتاج.

المراجع

Top comments (0)