تخطَّ إلى المحتوى
توثيق CrewAI

استخدام التعليقات التوضيحية في crew.py

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

مقدمة

Section titled “مقدمة”

تُستخدم التعليقات التوضيحية في إطار عمل CrewAI لتزيين الفئات والطرق، مما يوفر بيانات وصفية ووظائف للمكونات المختلفة في طاقمك. في مشاريع Python/YAML الكلاسيكية، تنظم الكود الذي يحمّل config/agents.yaml و config/tasks.yaml ويعيد كائن Crew.

التعليقات التوضيحية المتاحة

Section titled “التعليقات التوضيحية المتاحة”

يوفر إطار عمل CrewAI التعليقات التوضيحية التالية:

  • @CrewBase: تُستخدم لتزيين فئة الطاقم الرئيسية.
  • @agent: تزين الطرق التي تعرّف وتُرجع كائنات Agent.
  • @task: تزين الطرق التي تعرّف وتُرجع كائنات Task.
  • @crew: تزين الطريقة التي تنشئ وتُرجع كائن Crew.
  • @llm: تزين الطرق التي تهيئ وتُرجع كائنات نماذج اللغة.
  • @tool: تزين الطرق التي تهيئ وتُرجع كائنات الأدوات.
  • @callback: تُستخدم لتعريف طرق الاستدعاء الراجع.
  • @output_json: تُستخدم للطرق التي تُخرج بيانات JSON.
  • @output_pydantic: تُستخدم للطرق التي تُخرج نماذج Pydantic.
  • @cache_handler: تُستخدم لتعريف طرق معالجة التخزين المؤقت.

أمثلة الاستخدام

Section titled “أمثلة الاستخدام”

لنمر عبر أمثلة لكيفية استخدام هذه التعليقات التوضيحية:

1. فئة الطاقم الأساسية

Section titled “1. فئة الطاقم الأساسية”
@CrewBase
class LinkedinProfileCrew():
    """LinkedinProfile crew"""
    agents_config = 'config/agents.yaml'
    tasks_config = 'config/tasks.yaml'

تُستخدم التعليقة التوضيحية @CrewBase لتزيين فئة الطاقم الرئيسية. تحتوي هذه الفئة عادةً على الإعدادات والطرق لإنشاء الوكلاء والمهام والطاقم نفسه.

2. تعريف الأداة

Section titled “2. تعريف الأداة”
@tool
def myLinkedInProfileTool(self):
    return LinkedInProfileTool()

تُستخدم التعليقة التوضيحية @tool لتزيين الطرق التي تُرجع كائنات أدوات. يمكن للوكلاء استخدام هذه الأدوات لأداء مهام محددة.

3. تعريف LLM

Section titled “3. تعريف LLM”
@llm
def groq_llm(self):
    api_key = os.getenv('api_key')
    return ChatGroq(api_key=api_key, temperature=0, model_name="mixtral-8x7b-32768")

تُستخدم التعليقة التوضيحية @llm لتزيين الطرق التي تهيئ وتُرجع كائنات نماذج اللغة. تستخدم هذه النماذج من قبل الوكلاء لمهام معالجة اللغة الطبيعية.

4. تعريف الوكيل

Section titled “4. تعريف الوكيل”
@agent
def researcher(self) -> Agent:
    return Agent(
        config=self.agents_config['researcher']
    )

تُستخدم التعليقة التوضيحية @agent لتزيين الطرق التي تعرّف وتُرجع كائنات Agent.

5. تعريف المهمة

Section titled “5. تعريف المهمة”
@task
def research_task(self) -> Task:
    return Task(
        config=self.tasks_config['research_linkedin_task'],
        agent=self.researcher()
    )

تُستخدم التعليقة التوضيحية @task لتزيين الطرق التي تعرّف وتُرجع كائنات Task. تحدد هذه الطرق إعداد المهمة والوكيل المسؤول عنها.

6. إنشاء الطاقم

Section titled “6. إنشاء الطاقم”
@crew
def crew(self) -> Crew:
    """Creates the LinkedinProfile crew"""
    return Crew(
        agents=self.agents,
        tasks=self.tasks,
        process=Process.sequential,
        verbose=True
    )

تُستخدم التعليقة التوضيحية @crew لتزيين الطريقة التي تنشئ وتُرجع كائن Crew. تجمع هذه الطريقة جميع المكونات (الوكلاء والمهام) في طاقم وظيفي.

إعداد YAML الكلاسيكي

Section titled “إعداد YAML الكلاسيكي”

في المشاريع الكلاسيكية، تُخزن إعدادات الوكلاء عادةً في ملف YAML. إليك مثالاً على كيفية ظهور ملف agents.yaml لوكيل الباحث:

researcher:
    role: >
        LinkedIn Profile Senior Data Researcher
    goal: >
        Uncover detailed LinkedIn profiles based on provided name {name} and domain {domain}
        Generate a Dall-E image based on domain {domain}
    backstory: >
        You're a seasoned researcher with a knack for uncovering the most relevant LinkedIn profiles.
        Known for your ability to navigate LinkedIn efficiently, you excel at gathering and presenting
        professional information clearly and concisely.
    allow_delegation: False
    verbose: True
    llm: groq_llm
    tools:
        - myLinkedInProfileTool
        - mySerperDevTool
        - myDallETool

يتوافق إعداد YAML هذا مع وكيل الباحث المُعرّف في فئة LinkedinProfileCrew. يحدد الإعداد دور الوكيل وهدفه وخلفيته وخصائص أخرى مثل LLM والأدوات التي يستخدمها.

لاحظ كيف يتوافق llm و tools في ملف YAML مع الطرق المزينة بـ @llm و @tool في فئة Python.

أفضل الممارسات

Section titled “أفضل الممارسات”
  • تسمية متسقة: استخدم اصطلاحات تسمية واضحة ومتسقة لطرقك. على سبيل المثال، يمكن تسمية طرق الوكلاء بأسماء أدوارهم (مثل researcher، reporting_analyst).
  • متغيرات البيئة: استخدم متغيرات البيئة للمعلومات الحساسة مثل مفاتيح API.
  • المرونة: صمم طاقمك ليكون مرناً بالسماح بإضافة أو إزالة الوكلاء والمهام بسهولة.
  • توافق YAML-الكود: في المشاريع الكلاسيكية، تأكد من أن الأسماء والهياكل في ملفات YAML تتوافق بشكل صحيح مع الطرق المزينة في كود Python الخاص بك.

باتباع هذه الإرشادات واستخدام التعليقات التوضيحية بشكل صحيح، يمكنك الحفاظ على أطقم كلاسيكية منظمة وسهلة الصيانة. للـ crews الجديدة، استخدم بنية JSON-first في Crews.