بني وكلاء LLM كيتعاملو مع الأدوات وكيتطوّرو بوحدهم باستعمال miniEvoAgent

شنو هو miniEvoAgent؟

miniEvoAgent هو إطار عمل صغير بـ Python كيساعدك تتعلّم كيفاش كيتبناو وكيتمّ تحسين الوكلاء اللي مبنيين على LLM. مستوحى من EvoAgentX، وكيحتافظ بالمفاهيم الأساسية ديال تنفيذ الوكيل، واستدعاء الأدوات، والتقييم، وإعادة كتابة التعليمات، والتطوّر الذاتي، مع إزالة التعقيد ديال إطار عمل كبير للوكلاء.

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

كيفاش كيخدم إطار العمل

تطبيق miniEvoAgent كيتجمع من شوية ديال المكوّنات المركّزة:

• PromptTemplate: كيدخل مدخلات المهمة فالقالب ديال التعليمات.
• Action: كيتاصل بـ LLM، ويقدر اختياريا ينفّذ الأدوات على جولات متعددة، وكيحلّل الجواب النهائي.
• Agent: كيلفّ إجراء وكيُرجع رسالة منظّمة.
• Evaluator functions: كيقيسو توقّعات QA باستعمال التطابق التام، وF1 على مستوى الرموز، والدقة.
• PromptRewriter: كيستعمل LLM مُحسِّن باش يقترح تعليمات منقّحة انطلاقا من أمثلة ملموسة على الملاحظات.
• PromptSelector: كيقارن بين تعليمات أصلية والمرشّح ديالها على نفس مجموعة التطوير، وكيحتافظ بالأفضل أداء.
• evolve: كيعيد تنفيذ التدريب، وتوليد الملاحظات، وإعادة الكتابة، والتقييم، والاختيار.

المميزات الأساسية

• تجريد بسيط وقابل للفحص لوكيل بإجراء واحد.
• محوّل LLM متوافق مع OpenAI، كيتضبط عبر متغيّرات البيئة أو ملف محلي .env.
• أدوات للدوال على طريقة OpenAI، مع تنفيذ الأدوات على جولات متعددة.
• إعادة كتابة التعليمات اعتمادا على الملاحظات باستعمال LLM مُحسِّن.
• اختيار على مجموعة التطوير، بحيث ما كيتقبل المرشّح إلا إلا حسّن النتيجة.
• آثار التطوّر، وكتتضمن عمليات التنفيذ ديال التدريب، ومدخلات إعادة الكتابة، ونتائج التطوير، وقرارات الاختيار.
• LLMs وهمية وحتمية للاختبار، باش تختبر سلوك إطار العمل بلا استدعاءات لـ API عن بُعد.

تثبيت miniEvoAgent

المتطلبات

استعمل Python 3.10 أو أحدث. أوامر PowerShell التالية كاتدخل للمستودع، وكتنشئ بيئة افتراضية، وكتفعّلها، وكتحدّث pip، وكتثبّت الحزمة فالوضع القابل للتعديل:

cd D:\Projects\RSIProject\student-project\Evo-repro
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e .

التثبيت فالوضع القابل للتعديل مفيد أثناء دراسة المصدر أو تعديلو، حيث إن التغييرات المحلية فالحزمة كاتولي متاحة مباشرة لبيئة Python ديالك.

إعداد LLM متوافق مع OpenAI

المحوّل الافتراضي OpenAILLM كيقرا الإعدادات ديالو من متغيّرات البيئة أو من ملف محلي .env. فـ PowerShell، عيّن مفتاح API والموديل بهاد الشكل:

$env:OPENAI_API_KEY="your_api_key"
$env:OPENAI_MODEL="gpt-4o-mini"

إلا كنت كتستعمل خدمة أخرى متوافقة مع OpenAI، عيّن نقطة النهاية ديالها:

$env:OPENAI_BASE_URL="https://your-compatible-endpoint/v1"

ويمكن كذلك تنسخ .env.example لـ .env وتزيد تما نفس قيم الإعداد.

بناء وكيل أساسي للأسئلة والأجوبة

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

from evo_repro import Action, Agent, OpenAILLM, PromptTemplate, TextOutputParser

llm = OpenAILLM()

action = Action(
    name="answer_question",
    prompt_template=PromptTemplate(
        template="جاوب على السؤال التالي:\n\n{question}"
    ),
    llm=llm,
    output_parser=TextOutputParser(),
)

agent = Agent(
    name="qa_agent",
    description="كيجاوب على سؤال واحد ديال المستخدم.",
    action=action,
)

message = agent.execute({
    "question": "شنو هو التوليد المعزّز بالاسترجاع؟"
})
print(message.content)

المفتاح question اللي كتقدّمو لـ agent.execute كيقابل العنصر النائب {question} فالقالب. الإجراء كيركّب التعليمات، وكيرسلها لـ LLM المكوّن، وكيحلّل النص المُرجع، وكيغلّف النتيجة فـ رسالة منظّمة.

وتقدر حتى تشغّل المثال المرفق:

python examples\simple_agent.py

إضافة أداة Python قابلة للاستدعاء

أدوات miniEvoAgent هي أغلفة خفيفة حول دوال Python. كل أداة كتوفّر مخطط JSON يقدر الموديل يستعملو لاستدعاء الدوال، وكتُرجع ToolResult منظّما.

الحزمة فيها get_word_length_tool، اللي تقدر تربطو بإجراء عبر الوسيط tools:

from evo_repro import Action, Agent, OpenAILLM, PromptTemplate, TextOutputParser
from evo_repro import get_word_length_tool

agent = Agent(
    name="tool_agent",
    description="كيجاوب على سؤال ويقدر يستعمل الأدوات.",
    action=Action(
        name="answer_with_tools",
        prompt_template=PromptTemplate(
            template=(
                "جاوب على السؤال التالي. "
                "استعمل الأدوات إلا كانت مفيدة:\n\n{question}"
            )
        ),
        llm=OpenAILLM(),
        output_parser=TextOutputParser(),
        tools=[get_word_length_tool],
    ),
)

message = agent.execute({
    "question": 'شحال من حرف كاين فـ "retrieval"؟'
})

print(message.content)
print(message.metadata["tool_results"])

ملي كيطلب الـLLM شي function مدعومة، كينفّذها الـaction وكيْرجّع نتيجة الأداة للمحادثة. الـaction كيدعم جولات متعددة من هاد العملية قبل ما يفسّر الخرج النهائي ديال الموديل. سجلات تنفيذ الأدوات متاحة عبر message.metadata["tool_results"].

شغّل مثال الأداة المرفق بهاد الأمر:

python examples\tool_agent.py

فهم التطور الذاتي ديال الـprompt

نظام التطور الذاتي كيحسّن الـprompt من خلال دورة مضبوطة ديال الملاحظات والتقييم:

1. شغّل الـprompt الحالي على أمثلة التدريب.
2. حوّل التوقعات، والتسميات المتوقعة، ومقاييس التقييم لأمثلة ديال الملاحظات.
3. طلب من PromptRewriter المدعوم بـLLM ديال التحسين يولّد prompt مرشّح واحد.
4. قيّم الـprompt الأصلي والـprompt المرشّح على نفس مجموعة التطوير.
5. استعمل PromptSelector باش تحتافظ بالـprompt الأحسن.
6. عاود العملية لعدد الأجيال المكوَّن.

استعمل evolve_once(...) ملي بغيتي تدير جيل واحد. كيرجّع EvolutionRoundTrace. واستعمل evolve(...) باش تدير أجيال متعددة وتتوصّل بالـprompt النهائي وبالتاريخ الكامل.

تدقيق التطور بلا موديل remote

المستودع فيه مثال تدقيق حتمي كيستعمل سلوك مزيّف ديال LLM:

python examples\evolution_audit.py

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

تقييم توقعات QA

المقيّمات المدمجة كتوفر ثلاثة مقاييس بسيطة عمداً لـQA:

• التطابق الكامل: كيتحقق واش التوقع مطابق بالضبط للجواب المتوقع حسب طريقة المقارنة ديال المقيّم.
• F1 على مستوى الرموز: كيقيس التداخل بين الرموز فالتوقع والجواب المتوقع.
• الدقة: كيعرض النسبة ديال التوقعات الصحيحة.

هاد المقاييس مصمّمة باش تتحقق وتبيّن دورة التطور. المشروع كيوضح أنه من بعد يمكن تبديلها بمقيّمات مناسبة لاختبار معيّن أو لمهمة محددة.

تشغيل مجموعة الاختبارات

نفّذ جميع الاختبارات من جذر المستودع:

python -m pytest

مجموعة الاختبارات المركّزة كتغطي الوكلاء، والأدوات، وسلوك التطور. فين ما كان ممكن، كيتم استعمال تطبيقات مزيّفة ديال LLM، وبهذا يمكن التحقق من أغلب منطق الإطار بلا مفتاح API ولا استدعاء لموديل remote.

نصائح متقدمة

استعمل اختبارات حتمية قبل التجارب الحية

بدا بأمثلة واختبارات LLM المزيّف ملي كتبدّل اختيار الـprompt، أو التعامل مع الأدوات، أو منطق التطور. الخرج الحتمي كيخلي الأخطاء قابلة لإعادة الإنتاج وكيعاون تفرّق بين أخطاء الإطار والتغيّر فاستجابات الموديل الحي.

فحص الـtraces فكل جيل

ما تقيّمش تشغيل التطور غير من خلال الـprompt النهائي. راجع عمليات التدريب المسجّلة، والملاحظات اللي توصّل بها الـrewriter، والـprompt المرشّح، ونتائج مجموعة التطوير، وقرار الاختيار. هاد السجلات كتكشف علاش تقبل الـprompt المرشّح أو تترفض.

خلّي أدوار التدريب والتطوير منفصلة

عملية التطور كتنشئ ملاحظات إعادة الكتابة من أمثلة التدريب، ولكن كتقارن بين الـprompt الأصلي والمرشّح على نفس مجموعة التطوير. حافظ على هاد التقسيم ملي كتوجد التجارب باش يبقى الاختيار تابع للعملية المقصودة ديال الإطار.

فحص نتائج الأدوات المهيكلة

بالنسبة للوكلاء اللي كيستعملو الأدوات، فحص message.metadata["tool_results"] وكذلك النص النهائي. هاد الشي كيساعدك تتحقق واش الموديل اختار أداة، واش التنفيذ نجح، وشنو هي النتيجة المهيكلة اللي ترجعَت.

استعمل endpoint مخصّص ومتوافق ملي تحتاج

الإعداد OPENAI_BASE_URL كيخلي OpenAILLM يوجّه الطلبات لـendpoint متوافق مع OpenAI. خلّي مفتاح API والموديل المختار متوافقين مع المتطلبات ديال الـendpoint.

فهم النطاق الحالي ديال المشروع

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

تحقق من الترخيص قبل إعادة التوزيع

ما كاينش حالياً ملف ديال الترخيص فالمشروع. زِد ترخيص مناسب قبل نشر الكود أو إعادة توزيعه.

الخلاصة

miniEvoAgent كيوفّر طريق صغير وقابل للاختبار لفهم هندسة وكلاء LLM. باستعمال حزمة evo_repro، تقدر تبني وكيلاً موجّهاً بالـprompt، وتزيد أدوات functions بأسلوب OpenAI، وتقيس أداء QA، وتعاود تكتب الـprompts انطلاقاً من الإخفاقات، وتحتافظ بالتحسينات من خلال التقييم على مجموعة التطوير. البنية المختصرة ديالو والأمثلة الحتمية كيجعلوه مفيد خصوصاً لدراسة كيفاش كيخدم تنفيذ الوكلاء وتطور الـprompts من الداخل.