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

Open WebUI محبوب‌ترین رابط وب متن‌باز برای چت با مدل‌های هوش مصنوعی است؛ معمولاً کنار Ollama نصب می‌شود، اما همین‌قدر خوب با هر سرویس سازگار با OpenAI کار می‌کند. مایندبیس علاوه بر مسیر چت و مدل‌ها، اندپوینت Embeddings هم ارائه می‌دهد؛ یعنی در Open WebUI علاوه بر گفتگو، قابلیت‌های RAG و جستجوی سند هم با مدل‌های مایندبیس کار می‌کند.

در این مقاله اتصال API Mindbase به Open WebUI را از دو راه آموزش می‌دهیم: از طریق رابط مدیریت (پیشنهادی) و با متغیرهای محیطی برای نصب‌های Docker.

پیش‌نیازها

  • یک نصب فعال Open WebUI (نسخه جدید ترجیحاً از طریق Docker یا pip).
  • دسترسی مدیر (Admin) در Open WebUI — اتصال‌ها فقط از پنل مدیریت قابل افزودن‌اند.
  • کلید API و Base URL مایندبیس (گام صفر پایین).

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

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

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

روش اول: افزودن اتصال از پنل مدیریت (پیشنهادی)

محیط واقعی Open WebUI — آموزش تنظیم اتصال به مایندبیس
  1. وارد Open WebUI شوید و از منوی پروفایل (آواتار بالا) گزینه Admin Panel را باز کنید.
  2. به Settings ← Connections بروید.
  3. در بخش Manage OpenAI API Connections روی Add Connection کلیک کنید.
  4. در فیلد URL بنویسید: https://api.mindbase.ir/v1 — دقیقاً با v1 و بدون اسلش انتهایی.
  5. در فیلد API Key کلید mb_... مایندبیس را وارد کنید.
  6. روی دکمه Verify Connection کنار فیلد URL بزنید؛ Open WebUI اندپوینت /models را با توکن Bearer صدا می‌زند و پیام Server connection verified باید ببینید.
  7. Save کنید.

بعد از ذخیره، Open WebUI فهرست مدل‌های مایندبیس را خودکار از /v1/models واکشی می‌کند؛ مدل MindBase و بقیه مدل‌ها در انتخابگر چت ظاهر می‌شوند. اگر خواستید فقط مدل‌های خاصی نمایش داده شوند، در تنظیمات همان اتصال فیلد Model IDs را باز کنید، شناسه مدل (مثلاً MindBase) را بنویسید و با آیکون + اضافه کنید.

روش دوم: متغیرهای محیطی (نصب Docker)

اگر Open WebUI را با Docker اجرا می‌کنید، می‌توانید اتصال مایندبیس را از ابتدا در متغیرهای محیطی تعریف کنید:

OPENAI_API_BASE_URL="https://api.mindbase.ir/v1"
OPENAI_API_KEY="mb_xxxxxxxxxxxxxxxxxxxxxxxx"

برای چند اتصال همزمان (مثلاً مایندبیس + سرور محلی) از حالت لیستی استفاده کنید؛ مقادیر با سمی‌کالن جدا می‌شوند و به‌ترتیب با هم جفت می‌شوند:

OPENAI_API_BASE_URLS="https://api.mindbase.ir/v1;http://localhost:11434/v1"
OPENAI_API_KEYS="mb_xxxxxxxxxxxxxxxxxxxxxxxx;"

بعد از تغییر متغیرها، کانتینر را بازسازی (recreate) کنید. برای ایندکس اسناد (RAG) با مدل‌های مایندبیس نیازی به تنظیم اضافه نیست؛ اندپوینت /v1/embeddings همان اتصال استفاده می‌شود.

تست نهایی

  1. به صفحه چت برگردید و از انتخابگر مدل، مدل MindBase را انتخاب کنید.
  2. یک پیام فارسی بفرستید؛ پاسخ باید استریم شود.
  3. برای تست RAG، یک سند در بخش دانش (Knowledge) بارگذاری و درباره محتوایش سوال بپرسید.

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

  • پیام «Server connection verified» نمی‌آید: اول مطمئن شوید URL با v1 و بدون اسلش انتهایی وارد شده؛ خطاهای ۴۰۰/۴۰۱/۴۰۳ در Verify لزوماً یعنی ناسازگاری نیست — کلید و آدرس را بازبینی و در صورت نیاز مدل را دستی در Model IDs اضافه کنید؛ چت همچنان کار می‌کند.
  • مدل‌ها در لیست نمی‌آیند: ذخیره اتصال، لیست مدل‌ها را بلافاصله رفرش می‌کند؛ اگر کش مانده، سوییچ Cache Base Model List را چک یا اتصال را دوباره ذخیره کنید.
  • خطا در حالت Docker با آدرس localhost: داخل کانتینر، localhost به خود کانتینر اشاره دارد؛ برای سرویس روی میزبان از host.docker.internal استفاده کنید (برای مایندبیس که آدرس عمومی دارد موضوع مهم نیست).
  • تایم‌اوت در واکشی مدل‌ها: متغیر AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST را روی 30 بگذارید.

جمع‌بندی

با یک اتصال OpenAI در پنل مدیریت، Open WebUI به یک رابط کامل روی مدل‌های مایندبیس تبدیل می‌شود: چت استریم، انتخاب مدل، مدیریت پرامپت و حتی RAG با اندپوینت Embeddings. مقدار کلیدی همان https://api.mindbase.ir/v1 است و بقیه کار را خودِ Open WebUI انجام می‌دهد.

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

آیا مدل‌های مایندبیس به‌صورت خودکار در Open WebUI ظاهر می‌شوند؟

بله. Open WebUI بعد از ذخیره اتصال، فهرست مدل‌ها را از اندپوینت /v1/models مایندبیس می‌گیرد؛ افزودن دستی Model IDs فقط برای محدودکردن لیست یا شرایط خاص لازم است.

آیا Embeddings مایندبیس برای RAG کار می‌کند؟

بله؛ مایندبیس اندپوینت /v1/embeddings را ارائه می‌دهد و Open WebUI برای ایندکس اسناد از همان اتصال استفاده می‌کند.

آیا باید Ollama هم نصب باشد؟

نه. Open WebUI به Ollama نیازی ندارد؛ می‌توانید فقط با اتصال OpenAI به مایندبیس کار کنید و هر وقت خواستید مدل محلی هم اضافه کنید، به‌صورت اتصال دوم کنار مایندبیس می‌نشیند.

چرا Verify Connection خطای ۴۰۱ می‌دهد؟

یعنی کلید API درست ارسال نشده؛ کلید mb_ را بدون فاصله و کاراکتر اضافه از پروفایل مایندبیس کپی کنید و مطمئن شوید کلید حذف یا بازتولید نشده است.