كيفية نشر سير عمل متعدد الوكلاء باستخدام CrewAI على TrueFoundry

في هذا الدليل، سنوضح لك كيفية نشر CrewAI وكيل على TrueFoundry، وهي منصة مصممة لتبسيط نشر الذكاء الاصطناعي بأقل قدر من الخبرة في DevOps أو MLOps. تقوم TrueFoundry بأتمتة إدارة البنية التحتية، والتوسع، والمراقبة، مما يتيح لك التركيز على استخلاص الرؤى بدلاً من التعامل مع تعقيدات النشر. بنقرات قليلة فقط، يمكنك تحويل طلبات اللغة الطبيعية إلى استعلامات SQL ومخططات ديناميكية، مما يجعل استكشاف البيانات سلساً وذكياً. لا حاجة للاستعلام اليدوي!

إذا كنت ترغب في تجربة هذا مباشرة، يرجى زيارة منصة TrueFoundry والانتقال إلى العروض التوضيحية المباشرة (Live Demos) و CrewAI-Streamlit: عرض توضيحي مباشر لسير عمل الوكيل الخاص بنا

نظرة عامة على البنية

يتكون هذا المشروع من عدة مكونات رئيسية تعمل معًا:

وكيل الاستعلام

• يستخدم GPT-4o لفهم اللغة الطبيعية
• ينشئ استعلامات SQL مناسبة لـ ClickHouse
• ينفذ استعلام SQL مقابل قاعدة بيانات مهيأة مسبقًا
• يعيد البيانات بتنسيق جدولي كمدخل لوكيل التصور

وكيل التصور: وكيل ذكاء اصطناعي ثانٍ يقوم بـ

• يحدد نوع التصور الأكثر ملاءمة بناءً على البيانات
• ينشئ رسومًا بيانية باستخدام matplotlib/seaborn
• يتعامل مع تنسيق وتصميم التصورات

الواجهة الخلفية لـ FastAPI: واجهة برمجة تطبيقات RESTful تقوم بـ

• ينسق بين الوكلاء باستخدام CrewAI
• يدير معالجة المهام غير المتزامنة
• يعرض صور الرسوم البيانية والنتائج

الواجهة الأمامية لـ Streamlit: واجهة مستخدم تقوم بـ

• توفر واجهة استعلام بديهية
• تعرض حالة المعالجة في الوقت الفعلي
• تعرض تصورات تفاعلية

تدفق البيانات

يرسل المستخدم استعلامًا باللغة الطبيعية عبر Streamlit.

• يستخدم وكيل الاستعلام CrewAI مع GPT-4o لإنشاء استعلامات SQL لقاعدة بيانات ClickHouse
• ينفذ استعلام SQL مقابل قاعدة بيانات ClickHouse
• تُرجع النتائج بتنسيق جدولي كمدخل لوكيل التصور
• ينشئ وكيل التصور تصورات ويعيد صورًا للعرض

البدء

استنساخ المستودع

أولاً، انتقل إلى TrueFoundry Getting Started Examples المستودع واستنسخه:

git clone <https://github.com/truefoundry/getting-started-examples.git>

انتقل إلى دليل وكيل الرسم البياني لـ CrewAI:

cd getting-started-examples/plot_agent/crewai_plot_agent

إعداد البيئة

أنشئ بيئة افتراضية وقم بتنشيطها:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

ثبّت التبعيات:

pip install uv
uv pip install -r requirements.txt

تهيئة متغيرات البيئة

أنشئ .env ملف:

# Truefoundry LLMGateway Configuration if using Truefoundry LLM Gateway for calling models
LLM_GATEWAY_BASE_URL=your_llm_gateway_base_url_here
LLM_GATEWAY_API_KEY=your_llm_gateway_api_key_here

# OPENAI API Configuration if not using Truefoundry LLM Gateway
OPENAI_API_KEY=<your_openai_api_key_here>
CLICKHOUSE_HOST=your_clickhouse_host
CLICKHOUSE_PORT=443
CLICKHOUSE_USER=your_user
CLICKHOUSE_PASSWORD=your_password
CLICKHOUSE_DATABASE=default
CREWAI_VERBOSE=true

ملاحظة: عند استخدام بوابة TrueFoundry LLM، يجب أن يكون تنسيق معرف النموذج هو provider-name/model-name (على سبيل المثال، openai-main/gpt-4o). تأكد من أن ملف .env الخاص بك يحتوي على بيانات اعتماد بوابة LLM الصحيحة كما هو موضح في قسم تهيئة البيئة.

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

تنفيذ وكيل CrewAI

@CrewBase
class CrewaiPlotAgent():
	"""CrewaiPlotAgent crew"""

	# Learn more about YAML configuration files here:
	# Agents: https://docs.crewai.com/concepts/agents#yaml-configuration-recommended
	# Tasks: https://docs.crewai.com/concepts/tasks#yaml-configuration-recommended
	agents_config = 'config/agents.yaml'
	tasks_config = 'config/tasks.yaml'

	# def process_output(self, output):
	# 	# Modify output after the crew finishes
	# 	output.raw += "\nProcessed after kickoff."
	# 	print("Output", output ,"sdfsdfsdfsd")
	# 	return output

	# If you would like to add tools to your agents, you can learn more about it here:
	# https://docs.crewai.com/concepts/agents#agent-tools
	@agent
	def sql_writer(self) -> Agent:
		return Agent(
			config=self.agents_config['sql_writer'],
			verbose=True,
			tools=[ClickHouseTool()]
		)

	@agent
	def plot_writer(self) -> Agent:
		return Agent(
			config=self.agents_config['plot_writer'],
			verbose=True,
			tools=[PlotTools()],
			pydantic_output=PlotResult,
		)

	# To learn more about structured task outputs, 
	# task dependencies, and task callbacks, check out the documentation:
	# https://docs.crewai.com/concepts/tasks#overview-of-a-task
	@task
	def sql_task(self) -> Task:
		return Task(
			config=self.tasks_config['sql_task'],
		)

	@task
	def plot_task(self) -> Task:
		return Task(
			config=self.tasks_config['plot_task'],
			# callback=self.process_output,
			allow_code_execution=True,
			output_pydantic=PlotResult,
			# output_file='plot.png'
		)

	@crew
	def crew(self) -> Crew:
		"""Creates the CrewaiPlotAgent crew"""
		# To learn how to add knowledge sources to your crew, check out the documentation:
		# https://docs.crewai.com/concepts/knowledge#what-is-knowledge

		return Crew(
			agents=self.agents, # Automatically created by the @agent decorator
			tasks=self.tasks, # Automatically created by the @task decorator
			process=Process.sequential,
			verbose=True,
			# output_pydantic=True,
			# process=Process.hierarchical, # In case you wanna use that instead https://docs.crewai.com/how-to/Hierarchical/
		)
	

تُستخدم المزينّات @Crewbase و@agent و@task وما إلى ذلك لتمكين التتبع في TrueFoundry، وسيتم ذكرها بالتفصيل لاحقًا.

تشغيل الخدمات

ابدأ سير عمل CrewAI

crewai run

ابدأ الواجهة الخلفية لـ FastAPI:

python api.py

ابدأ واجهة مستخدم Streamlit (طرفية جديدة):

streamlit run app.py

النشر على TrueFoundry

المتطلبات الأساسية

ثبّت TrueFoundry CLI:

pip install -U "truefoundry"

سجّل الدخول إلى TrueFoundry:

tfy login --host "<https://app.truefoundry.com>"

خطوات النشر

1. انتقل إلى قسم عمليات النشر في TrueFoundry.

2. انقر على "خدمة" في الأسفل.
3. حدد مساحة عمل مجموعتك.
4. يمكنك النشر من جهاز الكمبيوتر المحمول الخاص بك، أو GitHub، أو Docker. إذا كنت تنشر من جهاز الكمبيوتر المحمول الخاص بك، فتأكد من إكمال المتطلبات الأساسية المذكورة أعلاه.
5. ستقوم منصة TrueFoundry بإنشاء ملف deploy.py وإضافته إلى مشروعك. ستحتاج إلى تعديل هذا الملف لإضافة متغيرات البيئة الخاصة بك. ابحث عن قسم env في الملف الذي تم إنشاؤه وأضف بيانات الاعتماد الخاصة بك:
6. استخدم الملف الذي تم إنشاؤه deploy.py وقم بتعديل env القسم:

env={
    "OPENAI_API_KEY": "your_openai_api_key",
    "CLICKHOUSE_HOST": "your_clickhouse_host",
    "CLICKHOUSE_PORT": "443",
    "CLICKHOUSE_USER": "your_user",
    "CLICKHOUSE_PASSWORD": "your_password",
    "CLICKHOUSE_DATABASE": "default",
    "CREWAI_VERBOSE": "true"
},

استبدل العناصر النائبة ببيانات الاعتماد وتكوينات البيئة الخاصة بك.

اختبار النشر

أرسل استعلامًا تجريبيًا:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"query": "Show me the cost trends by model over the last week"}' \
  <https://crewai-plot-agent-demo-8000.aws.demo.truefoundry.cloud/query>

مثال على استجابة ناجحة:

{
  "job_id": "1234-abcd-5678-efgh"
}

نقاط نهاية API

• إرسال استعلام:

curl -X POST <http://localhost:8000/query> -H "Content-Type: application/json" -d '{"query": "Your query here."}'

• التحقق من حالة الاستعلام:

curl -X GET <http://localhost:8000/status/{job_id}>

• استرداد صورة الرسم البياني:

curl -X GET <http://localhost:8000/plot/{job_id}> > plot.png

الواجهة الأمامية و CORS

تهيئة CORS في FastAPI:

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

تحديد متغير البيئة في Streamlit:

import os

FASTAPI_ENDPOINT = os.getenv("FASTAPI_ENDPOINT", "<http://localhost:8000>")

ملاحظات ما بعد النشر

• اختبر اتصال API من Streamlit إلى FastAPI.
• حدّث ملف Streamlit’s .env ببيانات نقطة نهاية FastAPI.
• تأكد من أن إعدادات CORS تسمح بطلبات Streamlit.

راقب وأدر نشرك عبر TrueFoundry من خلال:

• عرض السجلات
• مراقبة استخدام الموارد
• إعداد قواعد التحجيم التلقائي
• التحقق من سلامة الواجهة الخلفية (/health), وثائق واجهة برمجة التطبيقات (/docs), والمقاييس على /metrics

أضف التتبعات إلى وكيلك

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

تحتاج إلى تثبيت ما يلي

 pip install traceloop-sdk

ثم أضف متغيرات البيئة الضرورية لتمكين التتبع

"TRACELOOP_BASE_URL": "<your_host_name>/api/otel" # "https://internal.devtest.truefoundry.tech/api/otel"
"TRACELOOP_HEADERS"="Authorization=Bearer%20<your_tfy_api_key>"

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

from traceloop.sdk import Traceloop
from traceloop.sdk.decorators import workflow, agent, task
Traceloop.init(app_name="crew-ai")

ثم أضف المزين إلى الوكيل وسير العمل على النحو التالي

@agent(name="sql_and_plot_workflow")
@workflow(name="plotting workflow")
@task(name="execute sql query")

بهذه الخطوات، تم نشر سير عمل وكيل CrewAI الخاص بك بنجاح الآن على TrueFoundry!

‍