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

Zed ادیتور پرسرعت ساخته سازندگان Atom است که ایجنت هوش مصنوعی داخلی‌اش (Agent Panel) از هر Provider سازگار با OpenAI می‌پذیرد. Zed یک نوع Provider ویژه به نام openai_compatible دارد که دقیقاً برای سرویس‌هایی مثل مایندبیس طراحی شده: آدرس api_url می‌دهید، مدل تعریف می‌کنید و کلید را در UI یا متغیر محیطی می‌گذارید.

پیش‌نیازها

  • Zed نصب‌شده (zed.dev) برای مک، لینوکس یا ویندوز.
  • کلید API مایندبیس (گام صفر پایین).

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

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

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

مرحله اول: تعریف Provider در settings.json

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

پالت دستورات Zed را باز کنید (Ctrl+, یا cmd+,) و open settings را اجرا کنید. این بلوک را اضافه کنید:

{
  "language_models": {
    "openai_compatible": {
      "mindbase": {
        "api_url": "https://api.mindbase.ir/v1",
        "available_models": [
          {
            "name": "MindBase",
            "display_name": "MindBase",
            "max_tokens": 110000,
            "max_output_tokens": 8192,
            "capabilities": {
              "tools": true,
              "images": false,
              "parallel_tool_calls": false,
              "chat_completions": true
            }
          }
        ]
      }
    }
  }
}

نکات این کانفیگ:

  • api_url با /v1؛ Zed مسیر /chat/completions را خودش می‌سازد.
  • مقدار max_tokens پنجره بافتار مدل است — برای MindBase مقدار ۱۱۰ هزار؛ برای مدل‌های GLM-5.3 تا یک میلیون.
  • با chat_completions: true می‌گویید Zed از مسیر Chat Completions استفاده کند (گزینه پیش‌فرض باز-سازگارها و همان چیزی که مایندبیس ارائه می‌دهد).
  • طبق توصیه رسمی Zed، کلید API را داخل settings.json نگذارید — گام بعدی.

مرحله دوم: تنظیم کلید API

دو راه دارید:

  • UI (ساده‌تر): پالت دستورات ← agent: open settings ← در بخش LLM Providers، کنار Provider «mindbase» کلید را وارد کنید.
  • متغیر محیطی: Zed برای Provider باز-سازگار، متغیری به شکل نام‌PROVIDER_API_KEY می‌سازد؛ برای Provider با نام mindbase یعنی:
# ویندوز (PowerShell)
$env:MINDBASE_API_KEY = "mb_xxxxxxxxxxxxxxxxxxxxxxxx"

# مک/لینوکس
export MINDBASE_API_KEY=mb_xxxxxxxxxxxxxxxxxxxxxxxx

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

  1. Agent Panel را باز کنید (کلید ? یا آیکون ایجنت در نوار پایین).
  2. در پروفایل ایجنت (Model selector)، مدل MindBase از گروه mindbase را انتخاب کنید.
  3. یک درخواست فارسی بدهید؛ مثلاً «این فایل را بازبینی کن» — Zed ابزارهای ایجنت (خواندن/ویرایش فایل، ترمینال) را با فراخوانی تابع اجرا می‌کند.

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

  • خطای ۴۰۴: api_url بدون /v1 است؛ آدرس کامل را بدهید.
  • خطای ۴۰۱: کلید در UI یا متغیر محیطی درست ست نشده؛ بعد از ست‌کردن env، Zed را از همان ترمینال اجرا کنید تا متغیر را ببیند.
  • مدل در سلکتور نیست: ساختار JSON (تو در توی openai_compatible و available_models) را چک کنید؛ Zed فایل settings.json را با validation نشان می‌دهد.
  • ابزارهای ایجنت خطا می‌دهند: مطمئن شوید tools: true در capabilities فعال است؛ مدل MindBase فراخوانی تابع استاندارد دارد.

جمع‌بندی

Zed با Provider باز-سازگار و دو مقدار ثابت — api_url با /v1 و کلید mb_ — به مایندبیس وصل می‌شود؛ بعد از آن Agent Panel و Inline Assistant با مدل MindBase اجرا می‌شوند: همان تجربه ایجنت‌محور Zed، این‌بار روی مدل‌های مایندبیس با پرداخت ریالی.

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

چرا openai_compatible و نه provider openai؟

Provider معمولی openai در Zed به سرویس رسمی OpenAI وصل می‌شود؛ نوع openai_compatible مخصوص آدرس‌های سفارشی است و api_url شما را مبنای درخواست قرار می‌دهد.

کلید را کجا بگذارم؟

در UI تنظیمات Agent یا متغیر محیطی MINDBASE_API_KEY؛ مستندات Zed صراحتاً توصیه می‌کند کلید داخل settings.json نوشته نشود.

چطور مدل‌های دیگری مثل GLM-5.3 را اضافه کنم؟

در همان آرایه available_models یک آیتم دیگر با نام دقیق مدل (مثلاً GLM-5.3-Max) و max_tokens یک میلیون اضافه کنید.

آیا Inline Assistant هم با مدل سفارشی کار می‌کند؟

بله؛ مدل‌های Provider باز-سازگار در Agent Panel و Inline Assistant قابل انتخاب‌اند.