استدعاء الأدوات

تعريف الأدوات

مرّر مصفوفة tools في الطلب، بنفس الشكل الذي تستخدمه واجهة استدعاء الدوال الخاصة بـ OpenAI:

{
  "model": "tai-4.1",
  "messages": [{"role": "user", "content": "Ankara'da hava nasıl?"}],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"]
        }
      }
    }
  ]
}

description أهم مما قد يبدو: فهي المعلومة الوحيدة التي يملكها النموذج عمّا تفعله الأداة ومتى يكون من المناسب اللجوء إليها. الوصف الغامض أو المفقود يؤدي إلى استدعاء أداة في اللحظات الخاطئة، أو عدم استدعائها حين ينبغي ذلك. أما parameters فهو كائن JSON Schema يصف الوسائط (arguments) التي تقبلها الأداة؛ وتُولَّد وسائط النموذج نفسها في استدعاء الأداة لتطابق ذلك المخطط.

استقبال استدعاء أداة

عندما يقرر النموذج استدعاء أداة بدلاً من الرد مباشرة، تكون finish_reason في الاستجابة هي "tool_calls" ويُملأ message.tool_calls بدلاً من (أو إلى جانب) message.content:

{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_a1b2c3",
        "type": "function",
        "function": {"name": "get_weather", "arguments": "{\"city\": \"Ankara\"}"}
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

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

في وضع البث، تصل نفس المعلومة كقطعة delta.tool_calls تليها قطعة إنهاء بـ "finish_reason": "tool_calls"؛ راجع البث لمعرفة أشكال القطع العامة التي يُبنى عليها هذا.

تشغيلها ومتابعة المحادثة

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

{
  "model": "tai-4.1",
  "messages": [
    {"role": "user", "content": "Ankara'da hava nasıl?"},
    {"role": "assistant", "content": null, "tool_calls": [{"id": "call_a1b2c3", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\": \"Ankara\"}"}}]},
    {"role": "tool", "tool_call_id": "call_a1b2c3", "content": "18°C, parçalı bulutlu"}
  ],
  "tools": [/* same tools array as before */]
}

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

رفض تشغيل استدعاء

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

لماذا هذا التصميم تحديدًا

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