ساخت تیم چندایجنتی CrewAI با کلاس LLM و base_url پیکو هوش؛ تعریف Agent، Task و Crew، انتخاب مدل برای هر ایجنت و کنترل هزینه.
پیکو هوش·انتشار: ·۵ دقیقه مطالعه
خلاصه: CrewAI برای LLM از کلاس crewai.LLM استفاده می‌کند. طبق مستندات فعلی، برای OpenAI و چند ارائهدهندهی دیگر از SDKهای بومی استفاده میشود و فقط بقیه‌ی ارائه‌دهندگان از طریق LiteLLM (بسته‌ی اختیاری crewai[litellm]) کار می‌کنند. برای مدل‌های سازگار با OpenAI، قالب provider/model-id را با پیشوند openai/ به‌کار می‌برید و base_url را به https://api.picoai.ir/v1 می‌دهید. سپس همان LLM را به ایجنت‌ها می‌دهید.
(ابزارهای اضافه در بسته‌ی جداگانه crewai-tools هستند. مستندات CrewAI نصب با uv را توصیه می‌کند؛ pip install crewai هم معمولاً کار می‌کند.)
تعریف LLM
import os
from crewai import LLM
fast = LLM(
model="openai/claude-haiku-5-5",
base_url="https://api.picoai.ir/v1",
api_key=os.environ["PICO_API_KEY"],
temperature=0.2,
)
strong = LLM(
model="openai/gpt-6-sol",
base_url="https://api.picoai.ir/v1",
api_key=os.environ["PICO_API_KEY"],
temperature=0.4,
)
طبق مستندات CrewAI، قالب provider/model-id الزامی است و حذف پیشوند خطا میدهد؛ در نمونه‌های رسمی برای اندپوینت‌های سازگار با OpenAI (مثل سرورهای خودمیزبان) از openai/ به‌همراه base_url سفارشی استفاده شده است. نام واقعی مدل که به پیکو هوش میرسد همان بخش بعد از اسلش است. بنابراین بعد از آن باید شناسهی دقیق کاتالوگ باشد.
Claude Code را با متغیرهای ANTHROPIC_BASE_URL و کلید پیکو هوش روی اندپوینت سازگار با Anthropic (/v1/messages) اجرا کنید؛ مرحلهبهمرحله و با عیب‌یابی.
·
خبرنامه
آموزش‌ها و تغییرات جدید را به‌موقع بگیرید
فقط مطالب مفید درباره‌ی API هوش مصنوعی؛ بدون هرزنامه.
from crewai import Agent, Task, Crew, Process
researcher = Agent(
role="پژوهشگر فنی",
goal="جمع‌آوری نکات کلیدی درباره‌ی موضوع دادهشده",
backstory="تو تحلیلگر دقیقی هستی که فقط به نکات قابل دفاع اشاره میکنی.",
llm=fast,
allow_delegation=False,
verbose=True,
)
writer = Agent(
role="نویسندهی فنی",
goal="نوشتن یک مقالهی کوتاه فارسی بر اساس یادداشتهای پژوهشگر",
backstory="تو نویسندهای هستی که ساده و روشن مینویسی.",
llm=strong,
verbose=True,
)
t1 = Task(
description="درباره‌ی «کش HTTP» پنج نکتهی کلیدی بنویس.",
expected_output="فهرست پنجموردی",
agent=researcher,
)
t2 = Task(
description="با استفاده از نکات قبلی یک مقالهی ۲۰۰ کلمهای بنویس.",
expected_output="متن مقاله",
agent=writer,
context=[t1],
)
crew = Crew(agents=[researcher, writer], tasks=[t1, t2], process=Process.sequential)
result = crew.kickoff()
print(result)
الگوی خوب: ایجنت‌های جمع‌آوری و دسته‌بندی با مدل اقتصادی و ایجنت نویسنده با مدل قوی‌تر. هر کدام llm خودش را دارد.
مصرف توکن و هزینه
CrewAI برای هر ایجنت چندین درخواست می‌فرستد (فکر کردن، استفاده از ابزار، جمع‌بندی) و تاریخچه‌ی وظایف قبلی را در context می‌گذارد. بنابراین:
verbose=True را در تولید خاموش کنید.
max_iter ایجنت را محدود کنید تا حلقه‌ی طولانی نشود (این پارامتر در صفحهی مفاهیم LLM تأیید نشد؛ در مرجع Agent نسخه‌ی خود ببینید).
خروجی مورد انتظار را مختصر تعریف کنید.
پس از اجرا، crew.usage_metrics را (در صورت وجود در نسخه‌ی شما) بررسی کنید.
برای تخمین هزینه‌ی هر اجرا، فرمول در این مقاله و قیمت مدل‌ها در صفحهی قیمت آمده است.
نکته درباره‌ی embeddings و حافظه
قابلیت‌های حافظه‌ی CrewAI (memory=True) از امبدینگ استفاده می‌کند و در حالت پیش‌فرض طبق مستندات به text-embedding-3-large اوپن‌ای‌آی و OPENAI_API_KEY متکی است. برای embedder دیگر آرگومان embedder در Crew (یا Memory(embedder={"provider": ..., "config": {...}})) را به‌کار ببرید؛ مستندات از جمله ollama، cohere، voyageai، google و huggingface را فهرست کرده است. چون پیکو هوش اندپوینت embeddings ندارد، یا حافظه را خاموش بگذارید یا یک embedder محلی/سرویس دیگر را طبق مستندات CrewAI پیکربندی کنید. فعال‌کردن حافظه با تنظیمات پیش‌فرض روی پیکو هوش با خطا مواجه میشود.
در این حالت تعداد درخواست‌ها بیشتر میشود چون مدیر هر مرحله را هماهنگ می‌کند. برای شروع، حالت ترتیبی را امتحان کنید.
۳. خروجی ساخت‌یافته. با output_pydantic در Task می‌توانید خروجی را به مدل Pydantic ببندید؛ این ویژگی به توانایی مدل در پیروی از قالب وابسته است و باید روی مدل انتخابی آزمایش شود.
ابزارها
ایجنت‌ها می‌توانند ابزار بگیرند (جستجو، خواندن فایل و غیره). ابزارها بر پایه‌ی function calling کار می‌کنند و باید مدلی انتخاب کنید که ابزار را خوب پشتیبانی می‌کند. اگر ایجنت ابزار را صدا نمی‌زند، توضیح goal و backstory را دقیق‌تر کنید یا مدل قوی‌تر بگذارید. اصول پروتکل ابزار در راهنمای Function Calling توضیح داده شده است. ابزارهای خارجی مثل جستجوی وب سرویس‌های جداگانه‌اند و با پیکو هوش ارائه نمیشوند.
اجرای مطمئن در تولید
کلید را فقط از متغیر محیطی بخوانید.
برای هر اجرا یک سقف بودجه تعریف کنید: ابتدا اجرای آزمایشی با ورودی کوچک بزنید و مصرف را در داشبورد بسنجید.
خطاهای 402 و 429 را بگیرید و اجرا را به‌جای کرش، متوقف یا با تأخیر دوباره امتحان کنید؛ جزئیات در کدهای خطا و Retry.
از چند کلید جدا برای محیط توسعه و تولید استفاده کنید تا مصرف قابل تفکیک باشد.
سوالات متداول
چرا باید پیشوند openai/ بگذارم؟
چون CrewAI از روی پیشوند provider/ ارائهدهنده را تشخیص میدهد و بدون آن خطا میدهد. با base_url سفارشی، درخواست به پیکو هوش میرسد و نام مدل بدون پیشوند ارسال میشود. (مستندات یک گزینهی custom_openai=True هم برای ارسال مدلهایی با نام ارائهدهندهی دیگر به اندپوینت OpenAI-سازگار نشان میدهد؛ برای پیکو هوش لازم نیست.)
آیا میتوان از Claude هم استفاده کرد؟
بله، با شناسهی claude-sonnet-5-5 از همان مسیر OpenAI-سازگار. اتصال بومی Anthropic هم در آموزش Claude Code توضیح داده شده است.