آموزش اتصال 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. هر دو از سایت مایندبیس قابل دریافت هستند:
- وارد حساب کاربری خود در mindbase.ir شوید (ثبتنام رایگان است).
- از منوی پروفایل، بخش «کلیدهای API» را باز کنید.
- روی «+ کلید جدید» بزنید و یک نام دلخواه بدهید؛ مثلاً
Hermes. - مقدار کلید را کپی کنید — این کلید با پیشوند
mb_شروع میشود. - Base URL نیز در همین صفحه نمایش داده میشود:
https://api.mindbase.ir/v1
مرحله اول: کلید در .env
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 با پنجره بزرگتر پایدارتر عمل میکند.