الوكلاء - جولة إرشادية

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

بناء وكيلك #

لتهيئة عامل الحد الأدنى، تحتاج إلى هاتين الوسيمتين على الأقل:

• الطراز، نموذج توليد النص لتشغيل وكيلك - لأن الوكيل يختلف عن LLM البسيط، فهو نظام يستخدم LLM كمحرك له. يمكنك استخدام أي من هذه الخيارات:
  • المتحولوننموذج يأخذ تهيئة مسبقة لـ المحولات خط أنابيب لتشغيل الاستدلال على جهازك المحلي باستخدام المحولات.
  • نموذج HfApiModel يستفيد من huggingface_hub.InferenceClient.InferenceClient تحت الغطاء
  • موديل لايت لوميل تتيح لك الاتصال بأكثر من 100 طرازات مختلفة من خلال لايت لالم!
• الأدواتقائمة بـ الأدوات التي يمكن للوكيل استخدامها لحل المهمة. يمكن أن تكون قائمة فارغة. يمكنك أيضًا إضافة مجموعة الأدوات الافتراضية أعلى قائمة الأدوات عن طريق تحديد الوسيطة الاختيارية إضافة_أدوات_أساسية=صحيح.

بمجرد حصولك على هاتين الحجتين الأدوات و الطراز، يمكنك إنشاء وكيل وتشغيله. يمكنك استخدام أي LLM تريد، إما من خلال عناق الوجه API, المحولات, أولاماأو لايت لالم.

عناق الوجه API

نموذج المحولات المحلية

OpenAI أو OpenAI أو أنثروبيك API

أولاما

يمكن استخدام واجهة برمجة التطبيقات الخاصة بمعانقة الوجه مجاناً بدون رمز مميز، ولكن سيكون لها قيود على المعدل.

للوصول إلى النماذج المسوّرة أو رفع حدود أسعارك باستخدام حساب PRO، تحتاج إلى تعيين متغير البيئة HF_TOKEN أو تمرير الرمز المميز المتغير عند تهيئة نموذج HfApiModel.

تم النسخ

من smolagents smolagents استيراد CodeAgent, HfApiModel

model_id = "meta-llama/Llama-3.3-70B-Instruct"

النموذج = HfApiModel(model_id=model_id، الرمز المميز="")
وكيل = CodeAgent(أدوات=[]، نموذج=نموذج، إضافة_أدوات_قاعدية=صحيح)

agent.run(
    ") "هل يمكنك إعطائي الرقم 118 في متتابعة فيبوناتشي؟
)

وكيل الرموز ووكيل استدعاء الأدوات #

إن CodeAgent هو وكيلنا الافتراضي. سيكتب وينفذ مقتطفات كود بايثون في كل خطوة.

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

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

تم النسخ

النموذج = HfApiModel()
وكيل = CodeAgent(أدوات=[]، نموذج=نموذج، إضافي_مصرح به_موارد=['طلبات'، 'bs4'])
agent.run("هل يمكنك الحصول على عنوان الصفحة على عنوان url 'https://huggingface.co/blog'؟")

يمكن لـ LLM إنشاء تعليمات برمجية عشوائية سيتم تنفيذها بعد ذلك: لا تقم بإضافة أي واردات غير آمنة!

سيتوقف التنفيذ عند أي تعليمة برمجية تحاول تنفيذ عملية غير قانونية أو إذا كان هناك خطأ بايثون عادي في التعليمة البرمجية التي أنشأها الوكيل.

يمكنك أيضاً استخدام منفِّذ كود E2B بدلًا من مترجم بايثون المحلي عن طريق ضبط E2B_API_KEY متغير البيئة ثم تمرير استخدام_e2b_executor=صحيح عند تهيئة الوكيل.

معرفة المزيد عن تنفيذ التعليمات البرمجية في هذا البرنامج التعليمي.

نحن ندعم أيضًا الطريقة المستخدمة على نطاق واسع لكتابة الإجراءات على شكل نقاط تشبه JSON: هذا هو وكيل استدعاء الأدواتفإنها تعمل بنفس الطريقة التي تعمل بها CodeAgentبالطبع بدون واردات_مصرح بها_إضافية نظرًا لأنه لا ينفذ التعليمات البرمجية:

تم النسخ

من smolagents استيراد وكيل استدعاء الأدوات

وكيل = وكيل استدعاء الأدوات(الأدوات=[]، النموذج=النموذج)
agent.run("هل يمكنك الحصول على عنوان الصفحة على عنوان url 'https://huggingface.co/blog'؟")

فحص تشغيل الوكيل #

فيما يلي بعض السمات المفيدة لفحص ما حدث بعد الجري:

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

الأدوات #

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

• الاسم
• وصف
• أنواع المدخلات وأوصافها
• نوع الإخراج

يمكنك على سبيل المثال التحقق من أداة PythonInterpreterTool:: لها اسم، ووصف، وأوصاف المدخلات، ونوع المخرجات، و إلى الأمام لتنفيذ الإجراء.

عندما تتم تهيئة الوكيل، يتم استخدام سمات الأداة لإنشاء وصف للأداة يتم تضمينه في موجه نظام الوكيل. يتيح ذلك للوكيل معرفة الأدوات التي يمكنه استخدامها ولماذا.

صندوق الأدوات الافتراضي #

تأتي المحولات مع مجموعة أدوات افتراضية لتمكين الوكلاء، والتي يمكنك إضافتها إلى وكيلك عند التهيئة باستخدام الوسيطة إضافة_أدوات_أساسية = صحيح:

• بحث DuckDuckGo على الويب*:: إجراء بحث على الويب باستخدام متصفح DuckDuckGo.
• مترجم كود بايثون:: تشغيل كود Python الذي تم إنشاؤه بواسطة LLM في بيئة آمنة. ستتم إضافة هذه الأداة فقط إلى وكيل استدعاء الأدوات إذا قمت بتهيئته باستخدام إضافة_أدوات_أساسية=صحيححيث يمكن للوكيل المستند إلى التعليمات البرمجية تنفيذ كود بايثون أصلاً
• الناسخ:: خط أنابيب لتحويل الكلام إلى نص مبني على Whisper-Turbo يقوم بتحويل الصوت إلى نص.

يمكنك استخدام الأداة يدويًا عن طريق استدعائها بالوسائط الخاصة بها.

تم النسخ

من smolagents استيراد DuckDuckGoSearchTool

أداة_البحث_أداة البحث = أداة البحث DuckDuckGoSearchTool()
طباعة(search_tool("من هو الرئيس الحالي لروسيا؟")))

إنشاء أداة جديدة #

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

ستبدأ بالرمز أدناه.

تم النسخ

من huggingface_hub استيراد قائمة_النماذج

المهمة = "تصنيف النص"

النموذج_الأكثر_تحميلاً = التالي (التالي(تالي(list_models(filter=task, sort="downloads", direction=-1)))
طباعة(most_downloaded_model.id)

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

دعنا نرى كيف يعمل كلا الخيارين:

تزيين الدالة باستخدام @أداة

أداة الفئة الفرعية

تم النسخ

من أداة الاستيراد smolagents

@أداة
def model_download_tool (المهمة: str) -> str:
    """
    هذه أداة تقوم بإرجاع النموذج الأكثر تنزيلًا لمهمة معينة على مركز تعانق الوجه.
    تقوم بإرجاع اسم نقطة التفتيش.

    الأداة
        المهمة: المهمة المراد الحصول على عدد التنزيلات لها.
    """
    most_downloaded_model = التالي (التالي(iter(list_models(filter=task, sort="downloads", direction=-1)))
    إرجاع most_downloaded_model.id.

احتياجات الوظيفة:

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

تنسيق التعريف هذا هو نفس تنسيق مخططات الأدوات المستخدمة في تطبيق_قالب_المحادثة، والفرق الوحيد هو الإضافة الأداة مصمم الديكور: اقرأ المزيد عن استخدام الأداة API هنا.

ثم يمكنك تهيئة وكيلك مباشرةً:

تم النسخ

من smolagents استيراد CodeAgent, HfApiModel
الوكيل = CodeAgent(الأدوات=[أداة_تحميل_النموذج]، النموذج=HfApiModel())
agent.run(
    "هل يمكنك أن تعطيني اسم النموذج الذي يحتوي على أكبر عدد من التنزيلات في مهمة "تحويل النص إلى فيديو" على مركز تعانق الوجه؟
)

تحصل على السجلات التالية:

تم النسخ

╭──────────────────────────────────────── تشغيل جديد ─────────────────────────────────────────╭────────────────────────────────────────
│ │
│هل يمكنك أن تعطيني اسم النموذج الذي حصل على أكبر عدد من التنزيلات في "تحويل النص إلى فيديو
مهمة على مركز عناق الوجه؟                                                            │
│ │
╰ ─ نموذج HfApiModel - Qwen/Qwen2.5-Coder-32B-Instruct ───────────────────────────────────────────╯
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ الخطوة 0 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
╭ ╭ تنفيذ هذا الرمز: ───────────────────────────────────────────────────────────────────╮
│ 1 model_name = model_download_tool(task="text-to-video") │
2 │ طباعة (اسم الموديل) │
╰──────────────────────────────────────────────────────────────────────────────────────────╯
سجلات التنفيذ:
بايت دانس/تحريك ديف-لايتنينج

خرج لا يوجد
[الخطوة 0: المدة 0.27 ثانية | رموز الإدخال: 2,069 | رموز الإخراج: 60]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ الخطوة 1 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
╭ تنفيذ هذا الرمز ───────────────────────────────────────────────────────────────────╮
│1 الجواب النهائي("ByteDance/AnimateDiff-Lightning") │
╰──────────────────────────────────────────────────────────────────────────────────────────╯
خارج - الإجابة النهائية: بايت دانس/بايت دف-لايتنينج
[الخطوة 1: المدة 0.10 ثانية | رموز الإدخال: 4,288 | رموز الإخراج: 148]
مخرجات [20]: 'ByteDance/AnimateDiff-Lightning'

اقرأ المزيد عن الأدوات في برنامج تعليمي مخصص.

تعدد الوكلاء #

تم تقديم أنظمة متعددة الوكلاء مع إطار عمل مايكروسوفت أوتoجين.

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

يمكنك بسهولة بناء أنظمة هرمية متعددة العوامل مع smolagents.

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

فيما يلي مثال على إنشاء وكيل يدير وكيل بحث محدد على الويب باستخدام داك دوكkأداة البحث عن GoSearchTool:

تم النسخ

من smolagents استيراد CodeAgent، HfApiModel، DuckDuckGoSearchTool، ManagedAgent

نموذج = HfApiModel()

عميل الويب = CodeAgent (الأدوات=[DuckDuckDuckGoSearchTool()]، النموذج=النموذج)

عميل_ويب_مدار = عميل مُدار(
    الوكيل=web_agent,
    الاسم="web_search",
    الوصف="يدير عمليات بحث الويب نيابةً عنك. أعطه استفسارك كوسيطة."
)

Manager_Aagent = CodeAgent(
    الأدوات=[]، النموذج=النموذج، الوكلاء المُدارون=[وكيل الويب المُدار]
)

manager_Aagent.run("من هو الرئيس التنفيذي لـ Hugging Face؟")

للاطلاع على مثال متعمق لتطبيق فعال متعدد العوامل، راجع كيف دفعنا نظامنا متعدد العوامل إلى قمة قائمة المتصدرين في GAIA.

تحدث مع وكيلك وتصور أفكاره في واجهة Gradio الرائعة #

يمكنك استخدام غراديو يوي لإرسال المهام بشكل تفاعلي إلى وكيلك ومراقبة عملية التفكير والتنفيذ، إليك مثالاً على ذلك:

تم النسخ

من smolagents استيراد (
    أداة_التحميل,
    CodeAgent,
    HfApiModel,
    GradioUI
)

# أداة الاستيراد من المحور
أداة_توليد_الصور_في_الصورة = تحميل_أداة("m-ric/النص_إلى_صورة")

النموذج = نموذج HfApiModel(model_id)

# تهيئة الوكيل باستخدام أداة توليد الصور
الوكيل = CodeAgent(الأدوات=[أداة_توليد_الصور]، النموذج=النموذج)

GradioUI(وكيل).launch()

تحت الغطاء، عندما يكتب المستخدم إجابة جديدة، يتم تشغيل الوكيل مع agent.run(user_request, reset=False). إن إعادة تعيين=خطأ تعني العلامة عدم مسح ذاكرة الوكيل قبل بدء تشغيل هذه المهمة الجديدة، مما يتيح استمرار المحادثة.

يمكنك أيضاً استخدام هذا إعادة تعيين=خطأ حجة للحفاظ على استمرار المحادثة في أي تطبيق وكيل آخر.

الخطوات التالية #

للمزيد من الاستخدام المتعمق، ستحتاج بعد ذلك إلى الاطلاع على دروسنا التعليمية:

• شرح كيفية عمل وكلاء الشفرات لدينا
• هذا الدليل حول كيفية بناء عملاء جيدين.
• الدليل المتعمق لاستخدام الأدوات.