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

Pi ایجنت کدنویسی ترمینالی مینیمالِ Mario Zechner (سازنده معروف libgdx) است؛ یک عامل سبک و شفاف که فلسفه‌اش «کمترین جادو، بیشترین کنترل» است. مدل‌های Pi از یک فایل کانفیگ ساده به نام models.json می‌آیند و مایندبیس با تعریف یک Provider باز-سازگار در همین فایل وصل می‌شود.

پیش‌نیازها

  • Node.js نسخه ۲۲.۱۹ به بالا.
  • نصب Pi: npm install -g --ignore-scripts @earendil-works/pi-coding-agent یا اسکریپت رسمی pi.dev.
  • کلید API مایندبیس (گام صفر پایین).

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

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

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

مرحله اول: ساخت models.json

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

فایل ~/.pi/agent/models.json را بسازید (این مسیر پیش‌فرض است؛ با متغیر PI_CODING_AGENT_DIR قابل تغییر است):

{
  "$schema": "https://pi.dev/schemas/models.schema.json",
  "providers": {
    "mindbase": {
      "name": "MindBase",
      "baseUrl": "https://api.mindbase.ir/v1",
      "api": "openai-completions",
      "apiKey": "mb_xxxxxxxxxxxxxxxxxxxxxxxx",
      "models": [
        { "id": "MindBase", "name": "MindBase" },
        { "id": "GLM-5.3-Max", "name": "GLM 5.3 Max" }
      ]
    }
  }
}

سه نکته تعیین‌کننده:

  • api حتماً باید "openai-completions" باشد؛ مقادیر دیگر (مثل anthropic-messages یا openai-responses) به مسیرهایی می‌زنند که مایندبیس ارائه نمی‌دهد.
  • baseUrl با /v1؛ این همان قالبی است که خود مستندات Pi برای مثال‌ها استفاده می‌کند.
  • شناسه مدل‌ها را دقیقاً همان‌طور که در صفحه مدل‌های مایندبیس است بنویسید؛ MindBase مدل پیش‌فرض و نقطه شروع خوبی است.

اگر کلید را نمی‌خواهید داخل فایل بگذارید، به‌جای مقدار مستقیم از ارجاع محیطی استفاده کنید: "apiKey": "$MINDBASE_API_KEY" — Pi هم $NAME و هم ${NAME} را از متغیرهای محیطی می‌خواند.

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

pi --model mindbase/MindBase

یا داخل جلسه با دستور /model مدل mindbase/MindBase را انتخاب کنید؛ تغییر فایل models.json بدون خروج از جلسه هم اعمال می‌شود (Pi فایل را دوباره می‌خواند). با Ctrl+P هم می‌توانید بین مدل‌های اخیر جابجا شوید.

مرحله سوم: یک جلسه کاری معمول

  1. در ریشه پروژه، Pi را با مدل MindBase اجرا کنید.
  2. درخواست بدهید؛ مثلاً: «باگ حلقه بی‌نهایت در ماژول sync را پیدا و اصلاح کن».
  3. Pi پیشنهاد تغییرات را می‌دهد و با تایید شما اعمال می‌کند — مصرف از انرژی حساب مایندبیس کم می‌شود.

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

  • مدل در /model دیده نمی‌شود: فایل در مسیر درست است؟ (~/.pi/agent/models.json) و JSON معتبر است؟ خطای نگارشی در JSON باعث پنهان شدن کل Provider می‌شود.
  • خطای ۴۰۴: مقدار api را چک کنید — باید openai-completions باشد؛ baseUrl هم باید با /v1 تمام شود.
  • خطای ۴۰۱: کلید را از پروفایل مایندبیس دوباره کپی کنید؛ اگر از $VAR استفاده می‌کنید، متغیر باید قبل از اجرای Pi ست شده باشد.
  • اجرا با خطای Node: نسخه Node را چک کنید (node -v)؛ Pi به ۲۲.۱۹ به بالا نیاز دارد.

جمع‌بندی

Pi با یک بلوک Provider در models.json — baseUrl با /v1، api روی openai-completions و کلید mb_ — به مایندبیس وصل می‌شود. مینیمالیسم Pi در کنار مدل‌های مایندبیس نتیجه‌اش یک ایجنت کدنویسی سبک، شفاف و با پرداخت ریالی است.

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

چرا مقدار api مهم است؟

چون Pi بر اساس آن پروتکل درخواست را انتخاب می‌کند؛ فقط openai-completions به مسیر Chat Completions مایندبیس می‌رود و بقیه مقادیر خطای ۴۰۴ می‌دهند.

کلید امن‌تر کجاست؟

در متغیر محیطی با ارجاع $MINDBASE_API_KEY داخل models.json؛ مخصوصاً اگر پروفایل یا اسکریپت‌هایتان را در گیت نگه می‌دارید.

می‌توان چند مدل مایندبیس را در آرایه models گذاشت؟

بله؛ هر آیتم یک id می‌خواهد. مدل‌های Flash برای کارهای سبک و Max برای کارهای سنگین — همه با همان Provider مشترک.

آیا Pi حین جلسه فایل کانفیگ را دوباره می‌خواند؟

بله؛ تغییر models.json با دستور /model اعمال می‌شود و نیازی به خروج از جلسه نیست.