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

n8n محبوب‌ترین پلتفرم اتوماسیون متن‌باز است و برای هوش مصنوعی، زیرسیستم گره‌های AI دارد: AI Agent، Basic LLM Chain و ده‌ها ابزار کمکی. قلب این گره‌ها، نود OpenAI Chat Model است که برخلاف تصور اولیه، مخصوص سرویس رسمی OpenAI نیست — در Credential آن یک فیلد Base URL وجود دارد که با گذاشتن آدرس مایندبیس، همه مدل‌های مایندبیس در ورک‌فلوهای شما اجرا می‌شوند.

در این آموزش اتصال API Mindbase به n8n را قدم‌به‌قدم می‌بینیم؛ هم برای چت (OpenAI Chat Model) و هم برای Embeddings (ایندکس دانش در AI Agent). یک نکته بحرانی هم دارد: سوییچ «Use Responses API» که اگر روشن بماند درخواست‌ها به مسیری می‌روند که مایندبیس ارائه نمی‌دهد.

پیش‌نیازها

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

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

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

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

مرحله اول: ساخت Credential مایندبیس

محیط واقعی n8n — آموزش تنظیم اتصال به مایندبیس
  1. ورک‌فلو را باز کنید و یک گره Basic LLM Chain (یا AI Agent) اضافه کنید.
  2. روی کانکتور ورودی Model کلیک و از لیست، OpenAI Chat Model را انتخاب کنید.
  3. در پنل نود، زیر Credential روی Create new credential کلیک کنید.
  4. در پنجره Credential نوع OpenAI این مقادیر را وارد کنید:
    • API Key: کلید mb_... مایندبیس
    • Organization ID: خالی بگذارید
    • Base URL: https://api.mindbase.ir/v1 — با v1
  5. Save کنید. n8n بلافاصله اتصال را با صدا زدن /v1/models تست می‌کند و نشان سبز «Tested successfully» باید ببینید — چون مایندبیس همین اندپوینت استاندارد را ارائه می‌دهد.

مرحله دوم: انتخاب مدل — و مهم‌ترین نکته این آموزش

  1. در فیلد Model نود، حالت From List را بزنید؛ فهرست مدل‌ها مستقیم از مایندبیس واکشی می‌شود و مدل MindBase را انتخاب کنید.
  2. اگر لیست برای هر دلیلی خالی بود، مود فیلد را روی ID بگذارید و دستی بنویسید: MindBase.
  3. سوییچ «Use Responses API» را خاموش کنید. در نسخه‌های جدید نود OpenAI Chat Model این گزینه به‌صورت پیش‌فرض روشن است و درخواست را به /v1/responses می‌فرستد — مسیری که مایندبیس ارائه نمی‌دهد و با خطای ۴۰۴ مواجه می‌شوید. بعد از خاموش‌کردن، نود به مسیر استاندارد /v1/chat/completions می‌رود.

مرحله سوم: استفاده در AI Agent و حافظه

همین Credential برای بقیه گره‌های هوش مصنوعی n8n هم کار می‌کند:

  • AI Agent: مدل عامل را همان OpenAI Chat Model با Credential مایندبیس بگذارید؛ ابزارها (Tool) از طریق فراخوانی تابع استاندارد OpenAI اجرا می‌شوند.
  • Embeddings OpenAI: برای ایندکس دانش (Vector Store) از همان Credential استفاده کنید؛ مایندبیس اندپوینت /v1/embeddings را ارائه می‌دهد. در گزینه‌های نود، Dimensions را دست نزنید (برای مدل‌های غیر OpenAI بی‌اثر است).
  • در Options نود می‌توانید Temperature، سقف توکن خروجی و Timeout را تنظیم کنید؛ گزینه «Model Supports Reasoning» فقط برای مدل‌های استدلالی است و برای کارهای عادی لازم نیست.

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

  1. ورک‌فلو را ذخیره و اجرا کنید؛ یک پیام تست به Chat Model بدهید (مثلاً با گره Manual Trigger و Set).
  2. خروجی فارسی و استریم را در اجرای ورک‌فلو ببینید. برای سناریوهای طولانی، مدل‌های Flash (سریع‌تر و اقتصادی‌تر) را هم در Credential دوم تعریف کنید.

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

  • خطای ۴۰۴ روی /responses: سوییچ Use Responses API روشن است؛ خاموشش کنید تا نود از Chat Completions استفاده کند.
  • Credential تست نمی‌شود: Base URL باید دقیقاً https://api.mindbase.ir/v1 باشد؛ اسلش انتهایی اضافه نکنید و کلید را بدون فاصله کپی کنید.
  • خطای ۴۰۱: کلید نامعتبر است؛ از پروفایل مایندبیس دوباره کپی کنید و مطمئن شوید کلید حذف نشده باشد.
  • ابزارها (Tool) در Agent اجرا نمی‌شوند: مدل باید از فراخوانی تابع پشتیبانی کند؛ مدل MindBase مایندبیس این قابلیت را دارد، اما مدل‌های خیلی سبک را برای Agent انتخاب نکنید.
  • پیام هشدار «not all models might be chat-compatible»: فقط یک اطلاع‌رسانی n8n برای سرویس‌های شخص ثالث است؛ برای مایندبیس مشکلی ایجاد نمی‌کند.

جمع‌بندی

با یک Credential سه‌فیلدی (کلید mb_، Base URL با v1 و Organization خالی) n8n به مایندبیس وصل می‌شود؛ فقط یادتان باشد سوییچ Use Responses API را خاموش کنید. بعد از آن، اتوماسیون‌های شما — از خلاصه‌سازی ایمیل تا ایجنت‌های چندابزاری — با مدل‌های مایندبیس و پرداخت ریالی اجرا می‌شوند.

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

چرا Use Responses API باید خاموش باشد؟

چون این سوییچ درخواست را به اندپوینت /v1/responses می‌فرستد که مخصوص سرویس OpenAI است؛ مایندبیس استاندارد Chat Completions را ارائه می‌دهد و مسیر Responses را ندارد.

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

بله؛ برای سرویس‌های سفارشی، n8n فیلتر مدل‌ها را برمی‌دارد و همه مدل‌های خروجی /v1/models مایندبیس را نشان می‌دهد. حالت ID هم همیشه به‌عنوان راه جایگزین هست.

یک Credential کافی است یا باید برای هر ورک‌فلو بسازم؟

Credential در n8n سراسری است؛ یک‌بار می‌سازید و در همه ورک‌فلوها — چت، Embeddings و ایجنت — استفاده می‌کنید.

آیا استریم در n8n کار می‌کند؟

بله؛ کلاینت داخلی n8n پاسخ استریم مایندبیس (SSE) را می‌خواند و نیازی به تنظیم اضافه ندارد.