آموزش اتصال API هوش مصنوعی Mindbase به VS Code (Copilot BYOK)

VS Code پرکاربردترین ادیتور توسعه‌دهنده‌های دنیاست و از نسخه‌های جدید، قابلیت BYOK («آوردن کلید خودتان») کامل دارد: با نوع Provider جدید Custom Endpoint (جانشین OpenAI Compatible) می‌توانید هر سرویس سازگار با OpenAI — از جمله مایندبیس — را به چت Copilot اضافه کنید، آن‌هم با پشتیبانی Tool Calling برای Agent. بدون اشتراک Copilot هم بخش زیادی از این مسیر باز است.

پیش‌نیازها

  • VS Code به‌روز (بخش Chat و Manage Language Models در نسخه‌های اخیر است).
  • اکانت GitHub برای خود Copilot (این فقط برای لایه‌های سازمانی/سمانتیک لازم است؛ مدل Chat می‌تواند BYOK باشد).
  • کلید API مایندبیس (گام صفر پایین).

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

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

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

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

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

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

در پنل Chat، روی منوی مدل (جایی که نام مدل نوشته شده) کلیک کنید و Manage Language Models… را بزنید؛ یا از Command Palette دستور Chat: Manage Language Models را اجرا کنید. در ستون کناری، دکمه Add Models… ← Custom Endpoint را انتخاب کنید و یک نام گروه بگذارید (مثلاً MindBase).

[
  {
    "name": "MindBase",
    "vendor": "customendpoint",
    "apiKey": "mb_xxxxxxxxxxxxxxxxxxxxxxxx",
    "apiType": "chat-completions",
    "models": [
      {
        "id": "MindBase",
        "name": "MindBase",
        "url": "https://api.mindbase.ir/v1/chat/completions",
        "toolCalling": true,
        "vision": false,
        "maxInputTokens": 128000,
        "maxOutputTokens": 16000
      }
    ]
  }
]

مرحله دوم: ثبت مایندبیس در chatLanguageModels.json

VS Code فایل chatLanguageModels.json را باز می‌کند. این بلوک را اضافه کنید (کلید را جای mb_… بگذارید یا از ${input:…} استفاده کنید):

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

ادیتور را یک‌بار ری‌استارت کنید. در منوی مدل چت، گروه MindBase ← مدل MindBase ظاهر می‌شود. برای دیدن در Agent حتماً "toolCalling": true باشد (مدل بدون tools از لیست ایجنت مخفی می‌شود). یک سوال فارسی بپرسید؛ پاسخ با همان مدل مایندبیس می‌آید. برای ویرایش بعدی: Manage Language Models ← آیکون چرخ‌دنده کنار provider.

نکات مهم

  • آدرس کامل: url را با مسیر کامل …/v1/chat/completions بدهید؛ اگر فقط /v1 بدهید، ویرایشگر تلاش می‌کند مدل‌ها را از سرویس کشف کند.
  • استریم: فیلد streaming پیش‌فرض true است؛ اگر سرویسی استریم نداشت false کنید (مایندبیس استریم استاندارد OpenAI دارد).
  • سقف توکن: maxInputTokens/maxOutputTokens را مطابق مدل خود پر کنید.
  • اکانت سازمانی: در Copilot Business/Enterprise باید سیاست «Bring Your Own Language Model Key» در سازمان فعال باشد. قابلیت‌هایی مثل سمانتیک‌سرچ هنوز با اکانت GitHub کار می‌کنند.

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

  • خطای ۴۰۴: url بدون مسیر /chat/completions داده‌اید؛ آدرس کامل را در models[].url بگذارید.
  • خطای ۴۰۱: apiKey را چک کنید؛ کلید با mb_ شروع می‌شود و Bearer Sender خود VS Code می‌فرستد.
  • مدل در Agent نیست: toolCalling: true را فعال کنید — مدل بدون tools در سلکتور ایجنت نمایش داده نمی‌شود.

جمع‌بندی

VS Code با Custom Endpoint در سه حرکت — Manage Models، یک بلوک JSON، انتخاب مدل — به مایندبیس وصل می‌شود؛ چت و ایجنت ادیتور محبوب شما، حالا روی مدل‌های مایندبیس با پرداخت ریالی.

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

فرق Custom Endpoint با OpenAI Compatible چیست؟

Custom Endpoint نام جدید همان سازگاری OpenAI است که در نسخه‌های اخیر VS Code معرفی شده و انواع API (Chat Completions، Responses، Messages) را پشتیبانی می‌کند؛ برای مایندبیس نوع Chat Completions را انتخاب کنید.

آیا Chat بدون اشتراک Copilot کار می‌کند؟

بله؛ مدل‌های BYOK مستقل از اعتبار اشتراک اجرا می‌شوند — فقط برخی قابلیت‌های سازمانی به اکانت GitHub وصل‌اند.

مدل در لیست نیست؟

ادیتور را ری‌استارت کنید و ساختار JSON را چک کنید؛ vendor باید customendpoint و apiType برابر chat-completions باشد.