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

Hermes Agent ایجنت ترمینالی متن‌باز تیم Nous Research است؛ یک عامل کدنویسی و اتوماسیون با رابط TUI، خروجی ابزارهای استریمی و حلقه یادگیری داخلی برای مهارت‌ها. Hermes پشتیبانی کاملی از Providerهای سفارشی دارد و مایندبیس با تعریف یک Provider در config.yaml و کلید در .env به آن وصل می‌شود.

پیش‌نیازها

  • نصب Hermes Agent با اسکریپت رسمی Nous Research (لینوکس/مک/WSL2 یا پاورشل ویندوز).
  • کلید API مایندبیس (گام صفر پایین).

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

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

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

مرحله اول: کلید در .env

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

Hermes راز‌ها (کلیدها) را در فایل ~/.hermes/.env نگه می‌دارد و بقیه تنظیمات در ~/.hermes/config.yaml. اول کلید را در .env بگذارید:

MINDBASE_API_KEY=mb_xxxxxxxxxxxxxxxxxxxxxxxx

مرحله دوم: تعریف Provider در config.yaml

model:
  default: "mindbase/MindBase"

providers:
  mindbase:
    base_url: "https://api.mindbase.ir/v1"
    api_key: ${MINDBASE_API_KEY}
    api_mode: chat_completions

سه نکته مهم:

  • base_url با /v1؛ Hermes مسیرهای درخواست را خودش کامل می‌کند.
  • api_mode را صریحاً chat_completions بگذارید. Hermes برای هاست‌های ناشناخته حالت را تشخیص خودش انتخاب می‌کند و ممکن است اشتباه حدس بزند؛ مقدار صریح از دردسر بعدی جلوگیری می‌کند.
  • ارجاع ${MINDBASE_API_KEY} از فایل .env خوانده می‌شود؛ کلید را مستقیم داخل config.yaml نگذارید (کار می‌کند اما توصیه رسمی نیست).

روش سریع‌تر: ویزارد داخلی

اگر ترجیح می‌دهید فایل دست نزنید، Hermes یک ویزارد دارد:

hermes model custom-endpoint

همین دستور به‌صورت تعاملی آدرس، کلید و مدل را می‌پرسد، کلید را خودش در .env با نام هش‌شده ذخیره می‌کند و ارجاعش را در config.yaml می‌نویسد. انتخاب مدل هم با دستور hermes model یا داخل جلسه با /model mindbase/MindBase انجام می‌شود.

مرحله سوم: اجرا و تست

hermes

داخل TUI یک درخواست فارسی بدهید؛ مثلاً: «این مخزن را بررسی کن و سه بهبود پیشنهاد بده». پاسخ‌ها از مدل MindBase مایندبیس استریم می‌شود و فراخوانی ابزارها (خواندن فایل، اجرای دستور) هم از طریق همان مدل انجام می‌شود.

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

  • خطای ۴۰۴: api_mode را صریحاً chat_completions کنید و مطمئن شوید base_url با /v1 است.
  • خطای ۴۰۱: کلید در .env را بازبینی کنید؛ نام متغیر دقیقاً همان باشد که در config.yaml ارجاع داده‌اید و بعد از تغییر، جلسه را دوباره باز کنید.
  • مدل در /model دیده نمی‌شود: شناسه مدل در default باید با الگوی provider/model بنویسید: mindbase/MindBase.
  • اجرای ابزارها قطع می‌شود: برای کارهای ایجنتی طولانی، مدل‌های توان بالاتر مایندبیس (GLM-5.3) را انتخاب کنید؛ فراخوانی‌های تابع پی‌درپی روی مدل‌های سبک ناپایدارتر است.

جمع‌بندی

Hermes Agent با یک بلوک سه‌خطی Provider (base_url با /v1، کلید ارجاع‌شده از .env و api_mode صریح) به مایندبیس وصل می‌شود. بعد از آن، ایجنت ترمینالی Nous Research با حافظه مهارت‌ها و ابزارهای خودش، روی مدل‌های مایندبیس و پرداخت ریالی اجرا می‌شود.

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

کلید را داخل config.yaml بگذارم یا .env؟

.env؛ طبق مستندات خود Hermes، کلید داخل config.yaml کار می‌کند اما discouraged است. الگوی ${VAR} امن‌ترین و تمیزترین راه است.

چرا api_mode را دستی می‌نویسیم؟

چون تشخیص خودکار Hermes برای هاست‌های ناشناخته ممکن است حالت دیگری (مثل فرمت Anthropic) حدس بزند؛ مقدار صریح chat_completions درخواست را به مسیر درست مایندبیس هدایت می‌کند.

می‌توان چند Provider همزمان داشت؟

بله؛ زیر providers چند کلید (مثلاً mindbase و یک سرویس دیگر) تعریف کنید و بین‌شان با /model جابجا شوید.

کدام مدل برای حلقه یادگیری Hermes مناسب است؟

مدل پیش‌فرض MindBase شروع خوبی است؛ برای جلسات طولانی با ابزارهای زیاد، GLM-5.3-Max با پنجره بزرگ‌تر پایدارتر عمل می‌کند.