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

Dify پلتفرم ساخت اپلیکیشن‌های LLM است — چت‌بات دانش‌محور، ایجنت و ورک‌فلو — که مدل‌ها را از «Model Provider»ها می‌گیرد. برای سرویس‌های سازگار با OpenAI، پلاگین رسمی OpenAI-API-compatible را ارائه می‌دهد؛ مایندبیس با همین پلاگین به Dify وصل می‌شود و در چت‌بات‌ها، ایجنت‌ها و ورک‌فلوهای شما اجرا می‌شود.

تفاوت Dify با خیلی از ابزارها این است که لیست مدل‌ها را از سرور واکشی نمی‌کند؛ هر مدل را باید دستی با نام دقیق تعریف کنید. در این آموزش قدم‌به‌قدم همین کار را انجام می‌دهیم.

پیش‌نیازها

  • یک نصب فعال Dify (کلود یا سلف‌هاست) با دسترسی مدیر فضای کاری.
  • کلید API و Base URL مایندبیس (گام صفر پایین).

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

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

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

مرحله اول: نصب پلاگین OpenAI-API-compatible

محیط واقعی Dify — آموزش تنظیم اتصال به مایندبیس
  1. در Dify به بخش Integrations ← Model Provider بروید (در نسخه‌های قدیمی‌تر: Settings ← Model Provider).
  2. روی Install model providers کلیک و در Marketplace عبارت OpenAI-API-compatible را جستجو کنید.
  3. پلاگین رسمی langgenius را نصب کنید؛ کارت آن در صفحه Model Provider ظاهر می‌شود.

مرحله دوم: تعریف مدل MindBase

  1. روی کارت پلاگین، دکمه Add Model را بزنید.
  2. فیلدها را این‌طور پر کنید:
    • Model Name: MindBase — دقیقاً با همین نگارش (شناسه مدل در مایندبیس).
    • Model Type: LLM
    • Model display name: دلخواه (مثلاً «مایندبیس»)
    • API Key: کلید mb_... مایندبیس
    • API Base URL: https://api.mindbase.ir/v1 — با v1؛ Dify خودش /chat/completions را می‌چسباند.
    • Completion mode: Chat
    • Model context size: 110000 (پنجره بافتار مدل MindBase)
    • Upper bound for max tokens: مثلاً 8192
    • API Type: Chat Completions API (گزینه Responses API برای مایندبیس کار نمی‌کند)
  3. Save کنید.

اگر مدل دیگری هم می‌خواهید، همین مراحل را برای GLM-5.3-Max (بافتار یک میلیون توکن)، GLM-5.3-Flash-Low (سریع و اقتصادی) یا Qwen3.8-27b تکرار کنید؛ فهرست کامل با اندازه بافتار هر مدل در صفحه مدل‌های مایندبیس هست.

مرحله سوم: مدل پیش‌فرض سیستم

  1. در بالای صفحه Model Provider روی Default Models کلیک کنید.
  2. System Reasoning Model را روی مدل MindBase تازه‌ساخته‌شده بگذارید تا همه اپ‌های جدید از آن استفاده کنند.

برای ایندکس اسناد (Knowledge Base) می‌توانید یک مدل از نوع Text Embedding هم با همین پلاگین و همان Base URL اضافه کنید؛ Dify برای Embeddings مسیر /v1/embeddings را صدا می‌زند که مایندبیس ارائه می‌دهد. در تنظیمات Embedding مقدار Encoding Format را روی float بگذارید.

تست نهایی

  1. یک اپ Chatbot بسازید و در Orchestration مدل MindBase را انتخاب کنید.
  2. یک پرامپت فارسی بدهید و پاسخ استریم را ببینید؛ سپس Knowledge را وصل کنید تا RAG هم روی همان مدل کار کند.

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

  • خطا هنگام ذخیره مدل: API Base URL باید دقیقاً https://api.mindbase.ir/v1 باشد؛ آدرس کامل تا /chat/completions ندهید — Dify خودش مسیر را می‌سازد.
  • مدل در لیست انتخاب اپ نیست: مدل را فقط از همان فضای کاری (Workspace) ببینید که در آن تعریف شده و دسترسی مدیر داشته باشید؛ تعریف مدل‌ها فقط برای Owner/Admin است.
  • Rerank کار نمی‌کند: مایندبیس اندپوینت Rerank ندارد؛ این اسلات را خالی بگذارید — بازیابی اسناد بدون Rerank هم کار می‌کند.
  • خطای ۴۰۱: کلید اشتباه است؛ کلید mb_ را از پروفایل مایندبیس دوباره کپی کنید. حذف آخرین کلیدِ یک مدل در Dify، خود مدل را هم حذف می‌کند — مراقب باشید.

جمع‌بندی

Dify با پلاگین OpenAI-API-compatible و دو مقدار ثابت — کلید mb_ و Base URL با v1 — به مایندبیس وصل می‌شود. تنها تفاوت با بقیه ابزارها، تعریف دستی مدل‌ها است که یک‌بار انجام می‌شود و بعد همه اپ‌ها، ایجنت‌ها و ورک‌فلوهای Dify روی مدل‌های مایندبیس اجرا می‌شوند.

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

چرا لیست مدل‌های مایندبیس در Dify خودکار نمی‌آید؟

پلاگین OpenAI-API-compatible به‌صورت عمدی مدل‌ها را دستی تعریف می‌کند (روش customizable-model)؛ هر مدل را با نام دقیق و همان Base URL یک‌بار اضافه کنید.

در API Base URL هم v1 لازم است؟

بله؛ پلاگین Dify آدرس شما را به‌عنوان Base می‌گیرد و مسیر /chat/completions یا /embeddings را می‌چسباند. بدون /v1، درخواست به ریشه دامنه می‌رود و خطا می‌دهد.

آیا Function Calling در ایجنت‌های Dify کار می‌کند؟

بله؛ در تنظیمات مدل LLM گزینه Function Call Type را روی Tool Call بگذارید — مدل‌های مایندبیس فراخوانی تابع استاندارد OpenAI را پشتیبانی می‌کنند.

می‌توانم چند مدل مایندبیس را همزمان داشته باشم؟

بله؛ برای هر شناسه مدل یک Add Model جدا بزنید. بعد از آن در هر اپ می‌توانید بین مدل‌ها (مثلاً MindBase برای چت و GLM-5.3-Flash برای کارهای سبک) جابجا شوید.