آموزش اتصال API هوش مصنوعی Mindbase به LiteLLM (گت‌وی مدل)

LiteLLM محبوب‌ترین گت‌وی متن‌باز LLM است: یک پایانه OpenAI-compatible محلی جلویتان می‌گذارد و ترافیک را به هر اپ‌استریمی — از جمله مایندبیس — سوییچ می‌کند. مزیت برای تیم: لاگ، بودجه، لودبالانس و تبدیل پروتکل بین چند ابزار. مایندبیس با پیشوند openai/ به‌عنوان سازگار-OpenAI ثبت می‌شود.

پیش‌نیازها

  • Python 3.9+ یا Docker برای اجرای پروکسی.
  • کلید API مایندبیس (گام صفر پایین).

گام صفر: دریافت API Key و Base URL از مایندبیس

قبل از هر چیز به دو مقدار نیاز دارید: کلید API و Base URL. هر دو از سایت مایندبیس قابل دریافت هستند:

  1. وارد حساب کاربری خود در mindbase.ir شوید (ثبت‌نام رایگان است).
  2. از منوی پروفایل، بخش «کلیدهای API» را باز کنید.
  3. روی «+ کلید جدید» بزنید و یک نام دلخواه بدهید؛ مثلاً LiteLLM تا بعداً بدانید این کلید مال کدام ابزار است.
  4. مقدار کلید را کپی کنید — این کلید با پیشوند mb_ شروع می‌شود.
  5. Base URL نیز در همین صفحه نمایش داده می‌شود: https://api.mindbase.ir/v1
دریافت کلید API و Base URL از پنل کاربری مایندبیس

در ادامه همین دو مقدار را در تنظیمات LiteLLM جای‌گذاری می‌کنیم. اگر خواستید مدل دیگری هم امتحان کنید، لیست کامل مدل‌ها (GLM-5.3 در سه سطح توان، مدل سبک سریع و Qwen3.8) در صفحه مدل‌های مایندبیس قابل مشاهده است.

مرحله اول: نوشتن config.yaml

محیط واقعی LiteLLM — آموزش تنظیم اتصال به مایندبیس

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 است.