پرش به مطلب اصلی

اتصال Hermes Agent به چابکان

Hermes Agent یک عامل خط فرمان است که می‌تواند از provider سفارشی OpenAI-compatible استفاده کند. مسیر پیشنهادی برای چابکان، chat_completions است.

Hermes Agent چیست؟​

Hermes یک AI agent قابل اجرا در ترمینال است. برخلاف یک چت ساده که فقط متن تولید می‌کند، agent می‌تواند برای انجام یک هدف چند مرحله برنامه‌ریزی کند، ابزار مناسب را فراخوانی کند و نتیجه ابزار را دوباره به مدل برگرداند. این الگو برای تحقیق، کار با فایل‌ها، اجرای فرمان‌های کنترل‌شده و خودکارسازی وظایف چندمرحله‌ای مفید است.

اتصال Hermes به چابکان زمانی مناسب است که رابط خط فرمان و سیستم ابزارهای Hermes را می‌خواهید، اما قصد دارید مدل و مصرف API را از سرویس هوش مصنوعی چابکان مدیریت کنید. کیفیت اجرای عامل به انتخاب مدلی با context کافی و tool calling پایدار وابسته است؛ مدل چت معمولی ممکن است پاسخ متنی بدهد اما نتواند چرخه ابزار را درست کامل کند.

جریان اتصال​

Hermes → https://ai.chabokan.net/v1/chat/completions → مدل انتخابی → پاسخ یا tool call

Hermes ابزارها را روی سیستم شما اجرا می‌کند؛ چابکان فقط درخواست مدل را پردازش می‌کند. بنابراین دسترسی فایل، shell، مرورگر و سایر ابزارهای Hermes را جداگانه و با حداقل مجوز تنظیم کنید.

۱. پیش‌نیازها​

پیش از نصب، این موارد را آماده کنید:

موردمقدار یا معیار
Base URLhttps://ai.chabokan.net/v1
API Keyیک کلید فعال با پیشوند sk-chbk-
Transport پیشنهادیchat_completions
Model IDشناسه دقیق از زبانه «مدل‌های قابل استفاده»
Contextدست‌کم ۶۴ هزار توکن طبق پیش‌نیاز Hermes
ابزارخوانیوجود tools در supported_parameters مدل

برای مشاهده مشخصات مدل‌ها از API:

curl --fail-with-body https://ai.chabokan.net/v1/models \
  -H "Authorization: Bearer $CHABOKAN_AI_API_KEY"

اگر jq نصب است، خروجی خلاصه‌تری بگیرید:

curl --silent --show-error --fail https://ai.chabokan.net/v1/models \
  -H "Authorization: Bearer $CHABOKAN_AI_API_KEY" \
  | jq '.data[] | {id, context_length, supported_parameters}'
هشدار

مدلی با context کمتر از ۶۴ هزار توکن برای Hermes انتخاب نکنید. برای کار agentic نیز پاسخ ساده کافی نیست؛ مدل باید function/tool calling را پشتیبانی کند.

۲. نصب Hermes​

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

سپس نصب را بررسی کنید:

hermes --version
hermes doctor

۳. روش پیشنهادی: تنظیم تعاملی​

  1. دستور زیر را اجرا کنید:

    hermes model

  2. گزینه افزودن Custom endpoint را انتخاب کنید.

  3. نام provider را chabokan بگذارید.

  4. Base URL را https://ai.chabokan.net/v1 وارد کنید.

  5. API Key ساخته‌شده در پنل را paste کنید.

  6. transport را chat_completions انتخاب کنید.

  7. Model ID را بدون تغییر و دقیقاً مطابق پنل وارد کنید.

  8. مقدار context را مطابق context_length همان مدل تعیین کنید؛ حداقل قابل قبول Hermes برابر 64000 است.

  9. تنظیم را ذخیره و provider چابکان را به‌عنوان مدل فعال انتخاب کنید.

۴. روش دستی: فایل‌های تنظیمات​

Hermes secretها را در ~/.hermes/.env و تنظیمات غیرمحرمانه را در ~/.hermes/config.yaml نگه می‌دارد.

در ~/.hermes/.env بنویسید:

CHABOKAN_AI_API_KEY=sk-chbk-کلید-واقعی-شما

در ~/.hermes/config.yaml یک provider اضافه کنید:

providers:
  chabokan:
    api: https://ai.chabokan.net/v1
    key_env: CHABOKAN_AI_API_KEY
    transport: chat_completions
    default_model: openai/gpt-4o-mini
    models:
      openai/gpt-4o-mini:
        context_length: 128000
        supports_vision: true

model:
  provider: custom:chabokan
  default: openai/gpt-4o-mini

openai/gpt-4o-mini و context_length فقط نمونه‌اند. شناسه و context واقعی را از خروجی /v1/models جایگزین کنید. supports_vision را فقط برای مدلی true بگذارید که ورودی تصویر را پشتیبانی می‌کند.

حفاظت از کلید

فایل .env را در Git commit نکنید و کلید را داخل config.yaml ننویسید. برای Hermes یک کلید مجزا با سقف مصرف و تاریخ انقضای مناسب بسازید.

۵. انتخاب یا تعویض مدل​

داخل نشست Hermes:

/model custom:chabokan:openai/gpt-4o-mini

برای افزودن provider یا مدل تازه، نشست را ببندید و دوباره hermes model را اجرا کنید. دستور /model داخل نشست برای جابه‌جایی بین مدل‌هایی است که قبلاً تنظیم شده‌اند.

۶. آزمون لایه‌به‌لایه​

هر مرحله را جدا انجام دهید تا محل خطا مشخص بماند.

  1. سلامت تنظیمات:

    hermes doctor

  2. اجرای Hermes و یک پاسخ ساده:

    hermes
    فقط عبارت «اتصال برقرار است» را پاسخ بده.

  3. بررسی حافظه مکالمه:

    در پیام قبل از تو چه خواستم؟

  4. آزمون امن ابزارخوانی:

    بدون تغییر هیچ فایلی، فقط نام فایل‌های پوشه جاری را نمایش بده.

  5. ادامه آخرین نشست پس از خروج:

    hermes --continue

پس از هر آزمون، زبانه «گزارش درخواست‌ها» در پنل چابکان را بررسی کنید. دیده‌شدن درخواست آنجا یعنی درخواست تا درگاه چابکان رسیده است.

۷. transport آزمایشی Responses​

درگاه چابکان /v1/responses را نیز ارائه می‌کند و Hermes transport نوع codex_responses دارد. این مسیر را فقط وقتی استفاده کنید که مدل و نسخه Hermes شما در آزمون واقعی موفق باشند:

providers:
  chabokan_responses:
    api: https://ai.chabokan.net/v1
    key_env: CHABOKAN_AI_API_KEY
    transport: codex_responses
    default_model: openai/gpt-4o-mini
    models:
      openai/gpt-4o-mini:
        context_length: 128000

model:
  provider: custom:chabokan_responses
  default: openai/gpt-4o-mini

برای شروع و عیب‌یابی، chat_completions انتخاب پایدارتر و ساده‌تری است.

۸. مرز قابلیت‌ها​

قابلیتوضعیت
گفت‌وگوی متنی و streamingپشتیبانی‌شده از مسیر OpenAI-compatible
اجرای ابزارهای محلی Hermesوابسته به تنظیم و مجوزهای خود Hermes
Tool callingوابسته به مدل؛ supported_parameters را بررسی کنید
تصویروابسته به مدل و مقدار supports_vision
نشست و --continueقابلیت محلی Hermes
Web search یا ابزارهای اختصاصی providerخودکار و تضمین‌شده نیست
context بیشتر از ظرفیت مدلپشتیبانی نمی‌شود؛ context تنظیمی را بزرگ‌تر از مقدار واقعی نگذارید

۹. عیب‌یابی Hermes​

نشانهبررسی
401کلید در ~/.hermes/.env، نام key_env و فعال‌بودن کلید را بررسی کنید
404Base URL باید دقیقاً https://ai.chabokan.net/v1 باشد
مدل پیدا نمی‌شودModel ID را عیناً از پنل یا /v1/models کپی کنید
پاسخ ساده کار می‌کند اما ابزار نهمدل دیگری با tools در supported_parameters انتخاب کنید
مکالمه بلند خراب می‌شودcontext_length تنظیم‌شده را با مقدار واقعی مدل یکسان کنید
Hermes درخواست نمی‌فرستدhermes doctor و سپس فایل YAML را از نظر فاصله‌گذاری بررسی کنید
درخواست در گزارش چابکان نیستمشکل قبل از درگاه است: config، environment، DNS یا شبکه

منابع: Quickstart رسمی Hermes، تنظیم providerهای Hermes