آموزش اتصال API هوش مصنوعی Mindbase به LiteLLM (گتوی مدل)
LiteLLM محبوبترین گتوی متنباز LLM است: یک پایانه OpenAI-compatible محلی جلویتان میگذارد و ترافیک را به هر اپاستریمی — از جمله مایندبیس — سوییچ میکند. مزیت برای تیم: لاگ، بودجه، لودبالانس و تبدیل پروتکل بین چند ابزار. مایندبیس با پیشوند openai/ بهعنوان سازگار-OpenAI ثبت میشود.
پیشنیازها
- Python 3.9+ یا Docker برای اجرای پروکسی.
- کلید API مایندبیس (گام صفر پایین).
گام صفر: دریافت API Key و Base URL از مایندبیس
قبل از هر چیز به دو مقدار نیاز دارید: کلید API و Base URL. هر دو از سایت مایندبیس قابل دریافت هستند:
- وارد حساب کاربری خود در mindbase.ir شوید (ثبتنام رایگان است).
- از منوی پروفایل، بخش «کلیدهای API» را باز کنید.
- روی «+ کلید جدید» بزنید و یک نام دلخواه بدهید؛ مثلاً
LiteLLMتا بعداً بدانید این کلید مال کدام ابزار است. - مقدار کلید را کپی کنید — این کلید با پیشوند
mb_شروع میشود. - Base URL نیز در همین صفحه نمایش داده میشود:
https://api.mindbase.ir/v1
در ادامه همین دو مقدار را در تنظیمات LiteLLM جایگذاری میکنیم. اگر خواستید مدل دیگری هم امتحان کنید، لیست کامل مدلها (GLM-5.3 در سه سطح توان، مدل سبک سریع و Qwen3.8) در صفحه مدلهای مایندبیس قابل مشاهده است.
مرحله اول: نوشتن config.yaml
LiteLLM با فایل کانفیگ کار میکند نه پنل. یک config.yaml بسازید و مایندبیس را بهعنوان اپاستریم OpenAI-compatible تعریف کنید:
model_list:
- model_name: MindBase
litellm_params:
model: openai/MindBase
api_base: https://api.mindbase.ir/v1
api_key: os.environ/MINDBASE_API_KEY
litellm_settings:
drop_params: True
مرحله دوم: اجرای پروکسی
پروکسی را بالا بیاورید — پایانه استاندارد روی پورت ۴۰۰ باز میشود:
مرحله سوم: استفاده از مدل در کلاینتها
هر ابزاری که Base URL سفارشی میپذیرد حالا به http://localhost:4000/v1 اشاره کند و بهجای مدل، همان model_name (یعنی MindBase) را بفرستد. کلید هم کلید مجازی LiteLLM است (یا بیکلید اگر auth روشن نیست). کلاینتهای OpenAI SDK با یک تغییر base_url وصل میشوند.
نکات مهم
- پسوندد /v1: خودِ api_base باید به
/v1ختم شود و نباید /chat/completions اضافه کنید — کلاینت OpenAI مسیر را خودش میچسباند. - کلید خالی نه: provider openai به کلید غیرخالی نیاز دارد؛ اگر سرویسی کلید نخواست، مقدار placeholder بدهید.
- پیام سیستم: اپاستریمی که system نمیپذیرد با
supports_system_message: Falseدر پارامترها علامت میخورد. - پارامترهای ناشناخته:
drop_params: Trueجای خطا، پارامترهای غیرپشتیبانی را حذف میکند.
رفع مشکلات رایج
- Not Found خطا داد: api_base بدون /v1 است — دقیقاً https://api.mindbase.ir/v1 (بدون /chat/completions).
- No api key passed in: api_key خالی است؛ کلید mb_ یا متغیر محیطی MINDBASE_API_KEY را تنظیم کنید.
- خطای پارامتر: drop_params: True را در litellm_settings بگذارید.
جمعبندی
LiteLLM با ده خط config، مایندبیس را به اپاستریم رسمی کل تیم تبدیل میکند: یک پایانه محلی، لاگ و بودجه مرکزی، و همه ابزارهای OpenAI-compatible شما با یک Base URL.
سوالات متداول
چرا پیشوند openai/؟
پیشوند، روت LiteLLM را روی پروتکل OpenAI میگذارد تا MindBase بهعنوان سازگار-OpenAI صدا زده شود؛ بدون پیشوند، LiteLLM دنبال فرمتهای دیگر میگردد.
مدلهای دیگر مایندبیس؟
به ازای هر مدل (GLM-5.3 و…) یک model_name جدید با همان api_base اضافه کنید؛ مدل wildcard (*) هم برای عبور هر نامی هست.
پنل گرافیکی دارد؟
از نسخه ۱.۱۰۳ با store_model_in_db میتوان مدلها را در UI ادمین هم نگه داشت، اما مسیر رسمی همان config.yaml است.