انتقل إلى المحتوى الرئيسي

الوحدة 3 — نداء الدوالّ ووصف الأدوات

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

مخطّط الأداة: العقد الرسميّ​

كلّ أداة تُقدَّم للنموذج بمخطّط JSON. عناصره الأربعة:

{
  "type": "function",
  "function": {
    "name": "recherche_web",
    "description": "يبحث في الويب ويُعيد قائمة عناوين URL مع مقتطف. للأسئلة الحاليّة أو التي تتغيّر بسرعة.",
    "parameters": {
      "type": "object",
      "properties": {
        "requete": {"type": "string", "description": "استفسار موجز بلغة إنجليزيّة أو عربيّة."},
        "n_resultats": {"type": "integer", "minimum": 1, "maximum": 10, "default": 5}
      },
      "required": ["requete"]
    }
  }
}

الاسم يُقرَأ سريعًا؛ اجعله وصفيًّا مختصرًا (recherche_web لا search). الوصف يقرأه النموذج قبل كلّ قرار: هو ما يُقنعه بأنّ هذه الأداة الأنسب. المخطّط يمنع الاستدعاء بوسائط بلا معنى ويسمح بقيم افتراضيّة معقولة.

جودة الوصف: أكبر رافعة​

فرق بين وصفين:

  • سيّئ: "description": "بحث."
  • جيّد: "description": "يبحث في الويب ويُعيد عناوين URL. يُستعمل للأسئلة الحاليّة أو التي تتغيّر بسرعة. لا يُستعمل لأسئلة نظريّة عن مفاهيم مستقرّة (استعمل base_interne بدلًا)."

الوصف الثاني يفعل ثلاثة أشياء: يشرح ما تُعيده الأداة، ويعطي معيار اختيار، ويُنبِّه إلى بديل. قاعدة عمليّة: اقرأ وصف كلّ أداة من منظور النموذج: هل يميّزها من الأدوات الأخرى؟ هل يعرف متى يستعملها ومتى لا؟

عدد الأدوات والالتباس​

كلّما زاد عدد الأدوات، صار اختيارها أصعب. تجارب عمليّة على GPT-4o-mini:

  • ثلاث أدوات جيّدة الوصف: نسبة اختيار صحيح تقارب 96 ٪.
  • ثماني أدوات: النسبة تنزل إلى 89 ٪.
  • خمس عشرة أداة: النسبة إلى 76 ٪.

قاعدة: أقلّ من عشر أدوات في وكيل واحد. إن احتجت أكثر، فتِّت الوكيل إلى وكلاء متخصّصين، أو ادمج الأدوات المتشابهة في أداة واحدة بمعلمة mode. مثال: بدل recherche_pdf وrecherche_html، استعمل recherche(source: "pdf"|"html").

تحقّق الوسائط قبل التنفيذ​

النموذج يُخطئ بانتظام: تاريخ بصيغة خاطئة، عملة كنصّ عربيّ، عدد كسلسلة. الأداة لا تُنفَّذ قبل التحقّق:

from pydantic import BaseModel, Field, ValidationError

class SchemaLirePage(BaseModel):
    url: str = Field(pattern=r"^https?://")
    max_caracteres: int = Field(default=8000, ge=500, le=20000)

def executer_lire_page(args: dict) -> dict:
    try:
        params = SchemaLirePage(**args)
    except ValidationError as e:
        return {"erreur": f"وسائط غير صالحة: {e.errors()[0]['msg']}"}
    return {"texte": telecharger(params.url)[: params.max_caracteres]}

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

التنفيذ الآمن​

بعض الأدوات خطيرة: noter_fait يكتب في تقرير، envoyer_mail يُرسل، executer_sql يُنفّذ على قاعدة. ثلاث طبقات أمان:

  1. قائمة بيضاء صارمة: executer_sql تقبل SELECT فقط، تُرفض UPDATE وDELETE بتحقّق نمطيّ.
  2. بيئة معزولة: قراءة صفحات ويب تجري في حاوية أو شبكة داخليّة محدَّدة، لا في بيئة الإنتاج.
  3. تأكيد بشريّ: للأفعال غير القابلة للتراجع، نعرض الوسائط للمستخدم ونصبر قبل التنفيذ. الوحدة 7 تُفصّل هذا النمط.

أدوات الخيط الأحمر​

وكيل البحث يمتلك أربع أدوات:

  • recherche_web(requete, n_resultats): قراءة فقط، بلا خطر. مناسبة للأسئلة الحاليّة.
  • lire_page(url, max_caracteres): قراءة فقط، لكن الحمولة قد تُلوَّث بمحتوى ضارّ (سنعالج ذلك في الوحدة 8).
  • base_interne(question, seuil): بحث دلاليّ في قاعدة داخليّة (مقالات فريقك). قراءة فقط.
  • noter_fait(fait, source, categorie): كتابة سطر في مذكّرة العمل الحاليّة. آمنة لأنّ المذكّرة لا تخرج إلا بعد مراجعة، لكنّها تُغيّر حالة بالمعنى التقنيّ.

كلّ أداة مصحوبة بمخطّط ووصف مفصَّل يوضّح متى تُستعمل ومتى لا.

الفخّ: الأداة الفائضة​

نُضيف أداة resumer_page(url) تشبه lire_page لكنّها تُختصر النصّ. النموذج يخلط بينهما، فيستدعي resumer_page لأنّ الاسم يبدو أذكى، فيفوّت التفاصيل. الحلّ: أداة واحدة بمعلمة، بدل أداتين. أو حذف resumer_page إن كان بإمكان النموذج تلخيص نصّ lire_page بنفسه.

اقرأ الوصف بعين النموذج

النموذج لا يقرأ الشيفرة، بل الوصف. أداة ذات شيفرة لامعة ووصف ضعيف عديمة الفائدة. اعتَبِر كلّ وصف تعليمة موجَّهة للنموذج: قصير، محدَّد، بمعيار اختيار واضح، وذكر البديل عند وجوده.

الخلاصة​

  • الأداة عقد رسميّ ذو أربعة حقول: نوع، اسم، وصف، ومخطّط وسائط.
  • الوصف أكبر رافعة على جودة الوكيل؛ يُشرح ما تُعيده الأداة، ومتى تُستعمل، ومتى لا.
  • أقلّ من عشر أدوات لكلّ وكيل؛ فوق ذلك، الالتباس يُضاعف الأخطاء.
  • التحقّق من الوسائط بـPydantic قبل التنفيذ؛ أخطاء التحقّق تعود إلى النموذج كنتيجة أداة، لا كاستثناءات.