آموزش اتصال API هوش مصنوعی Mindbase به Cherry Studio

Cherry Studio یک کلاینت چت چندمدلی برای ویندوز، مک و لینوکس است که ده‌ها سرویس‌دهنده را در یک رابط گرد هم می‌آورد و برای هر سرویس سازگار با OpenAI هم امکان ساخت Provider اختصاصی دارد. مایندبیس با استاندارد OpenAI Compatible ارائه می‌شود؛ در نتیجه با یک Provider سفارشی، همه مدل‌های مایندبیس — از MindBase تا GLM-5.3 — داخل Cherry Studio در دسترس می‌شوند.

در ادامه، مراحل اتصال API Mindbase به Cherry Studio را قدم‌به‌قدم می‌بینیم؛ نکته اصلی این آموزش رفتار هوشمند Cherry Studio با آدرس API است که اگر رعایتش نکنید به خطای ۴۰۴ می‌رسید.

پیش‌نیازها

  • نصب Cherry Studio از cherry-ai.com برای ویندوز، مک یا لینوکس.
  • کلید API و Base URL مایندبیس (گام صفر پایین).

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

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

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

مرحله اول: ساخت Provider سفارشی

محیط واقعی Cherry Studio — آموزش تنظیم اتصال به مایندبیس
  1. Cherry Studio را باز کنید و از نوار کناری روی آیکون چرخ‌دنده Settings کلیک کنید.
  2. به بخش Model Provider بروید.
  3. پایین لیست Providerها روی + Add Provider کلیک کنید.
  4. در پنجره بازشده یک نام بدهید (مثلاً MindBase) و در تنظیمات Endpoint نوع OpenAI را انتخاب کنید (نوع‌های دیگر مثل Anthropic و Gemini برای مایندبیس کار نمی‌کنند).
  5. روی Add بزنید تا Provider ساخته شود.

مرحله دوم: پرکردن API Host و کلید

در صفحه Provider تازه‌ساخته‌شده:

  • API Key: کلید mb_... مایندبیس را وارد کنید.
  • API Host: فقط ریشه دامنه را بنویسید: https://api.mindbase.ir

نکته مهم: Cherry Studio خودش /v1/chat/completions را به انتهای Host می‌چسباند. اگر آدرس را با /v1 هم بدهید اشکالی ندارد (Cherry تشخیص می‌دهد و دوبار اضافه نمی‌کند)، اما هرگز آدرس کامل تا /chat/completions را وارد نکنید — درخواست خراب می‌شود. زیر فیلد، پیش‌نمایش مسیر نهایی درخواست را می‌بینید؛ مطمئن شوید به https://api.mindbase.ir/v1/chat/completions ختم می‌شود.

در پایان سوییچ فعال‌سازی Provider را در گوشه بالا-راست روشن کنید؛ بدون این سوییچ، Provider غیرفعال می‌ماند.

مرحله سوم: افزودن مدل‌های مایندبیس

دو راه دارید:

  • واکشی خودکار: روی Sync models کلیک کنید تا Cherry Studio فهرست مدل‌ها را از مایندبیس بگیرد؛ سپس مدل‌های موردنظر (مثلاً MindBase) را به لیست خودتان اضافه کنید. دقت کنید مدل‌های واکشی‌شده فقط بعد از افزودن به لیست، در انتخابگر چت دیده می‌شوند.
  • افزودن دستی: روی + کنار Sync models بزنید و مقادیر را پر کنید: Model ID = MindBase، یک Model Name دلخواه و Group Name (مثلاً MindBase).

برای دیدن بقیه مدل‌ها، صفحه مدل‌های مایندبیس شناسه دقیق هر مدل را نشان می‌دهد؛ مثلاً GLM-5.3-Max برای سنگین‌ترین توان یا GLM-5.3-Flash-Low برای پاسخ‌های سریع و ارزان.

مرحله چهارم: تست اتصال

  1. روی دکمه Model Check کنار فیلد API Key کلیک کنید. Cherry Studio با آخرین مدلی که به لیست اضافه کرده‌اید تست می‌گیرد؛ برای همین اول مدل MindBase را اضافه کنید بعد Check بزنید.
  2. پیام موفقیت باید ببینید. حالا در صفحه چت، مدل MindBase را انتخاب و یک پیام بفرستید.

رفع مشکلات رایج

  • Model Check شکست می‌خورد: اگر Host را تا /chat/completions کامل وارد کرده‌اید، مسیر دوبرابر می‌شود؛ فقط ریشه دامنه را بگذارید.
  • Provider در لیست انتخاب مدل نیست: سوییچ فعال‌سازی گوشه بالا-راست صفحه Provider را روشن نکرده‌اید.
  • خطای ۴۰۱: کلید اشتباه یا ناقص کپی شده؛ کلید mb_ را از پروفایل مایندبیس دوباره کپی کنید. اگر چند کلید با ویرگول می‌دهید، جداکننده باید ویرگول انگلیسی باشد.
  • مدل‌های Sync شده در چت دیده نمی‌شوند: مدل‌های واکشی‌شده باید از لیست Provider به لیست مدل‌های فعال اضافه شوند تا در انتخابگر ظاهر شوند.

جمع‌بندی

Cherry Studio با یک Provider سفارشی از نوع OpenAI به مایندبیس وصل می‌شود: ریشه دامنه https://api.mindbase.ir، کلید mb_، و مدل‌هایی مثل MindBase که با Sync models یا افزودن دستی وارد لیست می‌شوند. بعد از آن، چت چندمدلی، دستیارها (Assistants) و ترجمه داخلی Cherry Studio همگی روی مدل‌های مایندبیس اجرا می‌شوند.

سوالات متداول

در API Host باید v1 بنویسم یا نه؟

هر دو کار می‌کند؛ Cherry Studio مسیر نسخه‌دار را تشخیص می‌دهد و دوبار اضافه نمی‌کند. توصیه ما نوشتن ریشه دامنه (https://api.mindbase.ir) است تا خودش /v1/chat/completions را بسازد.

چرا بعد از Sync models مدل‌ها در چت نیستند؟

مدل‌های واکشی‌شده فقط یک کاتالوگ هستند؛ باید آن‌ها را به لیست مدل‌های Provider اضافه کنید تا در انتخابگر چت نمایش داده شوند.

آیا می‌توان چند کلید API مایندبیس را همزمان گذاشت؟

بله؛ Cherry Studio بین کلیدهای جدا‌شده با ویرگول انگلیسی چرخش (Round-robin) می‌کند — برای توزیع مصرف بین چند حساب کاربرد دارد.

نوع Provider را چه انتخاب کنم؟

همیشه OpenAI؛ مایندبیس فقط پروتکل OpenAI Chat Completions را ارائه می‌دهد و نوع‌های Anthropic یا Gemini به خطا می‌خورند.