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

goose ایجنت متن‌باز بلاک‌اسپیر (متفکران بلاکچین) است که هم CLI دارد هم دسکتاپ. مسیر رسمی برای سرویس‌های ایرانی: ثبت «Custom Provider» با نوع OpenAI Compatible — آدرس، کلید، مدل؛ و در dسکتاپ همان‌جا روشن/خاموش استریم.

پیش‌نیازها

  • goose نصب‌شده (CLI یا اپ دسکتاپ).
  • کلید API مایندبیس (گام صفر پایین).

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

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

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

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

مرحله اول: افزودن پروایدر

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

دسکتاپ: Settings → Models → «Configure providers» → «Add Custom Provider» و نوع را OpenAI Compatible بگذارید. CLI: goose configure ← Configure Providers ← Add A Custom Provider. در هر دو: Display Name = MindBase، API URL = آدرس سرویس، کلید = mb_…

// ~/.config/goose/custom_providers/mindbase.json
{
  "engine": "openai",
  "base_url": "https://api.mindbase.ir/v1",
  "api_key_env": "MINDBASE_API_KEY",
  "supports_streaming": true
}
# config.yaml: providers.mindbase.model = MindBase (کلید در env)

مرحله دوم: مدل و استریم

در Custom Provider، مدل‌های در دسترس را با MindBase اعلام کنید و «Streaming Support» را روشن بگذارید. نام مدل را می‌توانید در config.yaml (بخش providers) یا متغیر GOOSE_MODEL قفل کنید.

مرحله سوم: کلید امن

goose عمداً کلید را در config.yaml ذخیره نمی‌کند — آن را در keyring، secrets.yaml یا متغیر محیطی MINDBASE_API_KEY بگذارید؛ فایل کانفیگ فقط ارجاع می‌دهد.

نکات مهم

  • کلید در کانفیگ نه: اسناد رسمی: کلید در config.yaml نادیده گرفته می‌شود؛ keyring/محیط تنها مسیرهای معتبرند.
  • خطای ۴۰۴: در مسیر provider رسمی OpenAI مسیر پیش‌فرض /v1/chat/completions است؛ در custom، API URL کامل بدهید.
  • کانفیگ فایل: custom_providers/*.json با engine=openai، base_url، api_key_env، supports_streaming همان ساختار مستندات است.

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

  • «No api key passed in»: کلید در فایل کانفیگ است — به keyring/env منتقلش کنید.
  • ۴۰۴: API URL کامل با /v1 در custom provider.
  • مدل نیست: providers.mindbase.model یا GOOSE_MODEL=MindBase.

جمع‌بندی

goose با Custom Provider از نوع OpenAI Compatible — آدرس، کلید در env، مدل MindBase — روی مایندبیس می‌نشیند؛ ایجنت دسکتاپ/CLI بلاک‌اسپیر حالا فارسی‌زبان هم کار می‌کند.

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

پروایدر رسمی OpenAI یا Custom؟

Custom Provider با نوع OpenAI Compatible مسیر رسمی سرویس‌های سفارشی است؛ provider openai برای آدرس‌دهی به سرویس خود OpenAI است.

goose configure مدل جدید نمی‌گیرد؟

CLI فقط مدل‌های شناخته‌شده را لیست می‌کند؛ نام دلخواه را در Desktop یا config.yaml ست کنید.

استریم؟

سوئیچ Streaming Support در همان فرم Custom Provider؛ مایندبیس استریم استاندارد دارد.