Создание плагина провайдера моделей

Плагины провайдеров моделей объявляют бэкенд для инференса — OpenAI-совместимую точку входа, сервер Anthropic Messages, API Responses в стиле Codex или нативный интерфейс Bedrock — через который Hermes может направлять вызовы AIAgent. Все встроенные провайдеры (OpenRouter, Anthropic, GMI, DeepSeek, Nvidia, …) поставляются как такие плагины. Сторонние разработчики могут добавить свои, разместив директорию в $HERMES_HOME/plugins/model-providers/ без каких-либо изменений в репозитории.

Как работает обнаружение

providers/__init__.py._discover_providers() выполняется лениво при первом вызове get_provider_profile() или list_providers(). Порядок обнаружения:

1. Встроенные плагины — <repo>/plugins/model-providers/<name>/ — поставляются с Hermes

2. Пользовательские плагины — $HERMES_HOME/plugins/model-providers/<name>/ — можно разместить в любой директории; перезагрузка для последующих сессий не требуется

3. Устаревшие однофайловые — <repo>/providers/<name>.py — обратная совместимость для внешних редактируемых установок

Пользовательские плагины переопределяют встроенные с тем же именем, поскольку register_provider() работает по принципу «последний записавший побеждает». Разместите директорию $HERMES_HOME/plugins/model-providers/gmi/, чтобы заменить встроенный профиль GMI без изменения репозитория.

Структура директории

plugins/model-providers/my-provider/
├── __init__.py       # Calls register_provider(profile) at module-level
├── plugin.yaml       # kind: model-provider + metadata (optional but recommended)
└── README.md         # Setup instructions (optional)

Единственный обязательный файл — __init__.py. plugin.yaml используется hermes plugins для интроспекции и общим PluginManager для маршрутизации плагина к нужному загрузчику; без него общий загрузчик использует эвристику на основе исходного текста.

Минимальный пример — простой провайдер с API-ключом

# plugins/model-providers/acme-inference/__init__.py
from providers import register_provider
from providers.base import ProviderProfile

acme = ProviderProfile(
    name="acme-inference",
    aliases=("acme",),
    display_name="Acme Inference",
    description="Acme — OpenAI-compatible direct API",
    signup_url="https://acme.example.com/keys",
    env_vars=("ACME_API_KEY", "ACME_BASE_URL"),
    base_url="https://api.acme.example.com/v1",
    auth_type="api_key",
    default_aux_model="acme-small-fast",
    fallback_models=(
        "acme-large-v3",
        "acme-medium-v3",
        "acme-small-fast",
    ),
)

register_provider(acme)

# plugins/model-providers/acme-inference/plugin.yaml
name: acme-inference
kind: model-provider
version: 1.0.0
description: Acme Inference — OpenAI-compatible direct API
author: Your Name

Вот и всё. После размещения этих двух файлов следующее автоматически связывается без каких-либо других правок:

Поля ProviderProfile

Полное определение в providers/base.py. Наиболее полезные:

Переопределяемые хуки

Унаследуйтесь от ProviderProfile для нестандартных особенностей:

from typing import Any
from providers.base import ProviderProfile

class AcmeProfile(ProviderProfile):
    def prepare_messages(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
        """Provider-specific message preprocessing. Runs after codex
        sanitization, before developer-role swap. Default: pass-through."""
        # Example: Qwen normalizes plain-text content to a list-of-parts
        # array and injects cache_control; Kimi rewrites tool-call JSON
        return messages

    def build_extra_body(self, *, session_id=None, **context) -> dict:
        """Provider-specific extra_body fields merged into the API call.
        Context includes: session_id, provider_preferences, model, base_url,
        reasoning_config. Default: empty dict."""
        # Example: OpenRouter's provider-preferences block,
        # Gemini's thinking_config translation.
        return {}

    def build_api_kwargs_extras(self, *, reasoning_config=None, **context):
        """Returns (extra_body_additions, top_level_kwargs). Needed when some
        fields go top-level (Kimi's reasoning_effort) and some go in extra_body
        (OpenRouter's reasoning dict). Default: ({}, {})."""
        return {}, {}

    def fetch_models(self, *, api_key=None, timeout=8.0) -> list[str] | None:
        """Live catalog fetch. Default hits {models_url or base_url}/models with
        Bearer auth. Override for: custom auth (Anthropic), no REST endpoint
        (Bedrock → None), or public/unauthenticated catalogs (OpenRouter)."""
        return super().fetch_models(api_key=api_key, timeout=timeout)

Примеры хуков для справки

Посмотрите на эти встроенные плагины для изучения идиом:

Пользовательские переопределения — замена встроенного без правки репозитория

Допустим, вы хотите направить gmi на ваш частный staging endpoint для тестирования. Создайте ~/.hermes/plugins/model-providers/gmi/__init__.py:

from providers import register_provider
from providers.base import ProviderProfile

register_provider(ProviderProfile(
    name="gmi",
    aliases=("gmi-cloud", "gmicloud"),
    env_vars=("GMI_API_KEY",),
    base_url="https://gmi-staging.internal.example.com/v1",
    auth_type="api_key",
    default_aux_model="google/gemini-3.1-flash-lite-preview",
))

В следующей сессии get_provider_profile("gmi").base_url вернёт staging URL. Никаких патчей репозитория, никакой пересборки. Поскольку пользовательские плагины обнаруживаются после встроенных, вызов пользовательского register_provider() побеждает.

Выбор api_mode

Распознаются четыре значения. Hermes выбирает одно на основе:

1. Явное переопределение пользователя (model.api_mode в config.yaml)

2. Диспетчеризация по модели OpenCode (opencode_model_api_mode для Zen и Go)

3. Автоопределение по URL — суффикс /anthropic → anthropic_messages, api.openai.com → codex_responses, api.x.ai → codex_responses, /coding на доменах Kimi → chat_completions

4. Profile api_mode как запасной вариант, когда определение по URL ничего не находит

5. По умолчанию chat_completions

Установите profile.api_mode в соответствии со значением по умолчанию вашего провайдера — это служит подсказкой. Пользовательские переопределения URL всё равно имеют приоритет.

Типы аутентификации

auth_type определяет, какие пути кода обрабатывают ваш провайдер как «простой провайдер с API-ключом» — если это не api_key, PluginManager всё равно записывает манифест, но автоматизация на уровне CLI Hermes (проверки doctor, флаг --provider, делегирование мастеру настройки) может его пропустить.

Время обнаружения

Обнаружение провайдеров — ленивое — запускается при первом вызове get_provider_profile() или list_providers() в процессе. На практике это происходит рано при запуске (загрузка модуля auth.py расширяет PROVIDER_REGISTRY с нетерпением). Если вам нужно проверить, что ваш плагин загрузился, выполните:

hermes doctor

— успешный профиль с auth_type="api_key" отображается в секции Provider Connectivity с запросом /models.

Для программной проверки:

from providers import list_providers
for p in list_providers():
    print(p.name, p.base_url, p.api_mode)

Тестирование вашего плагина

Укажите HERMES_HOME на временную директорию, чтобы не загрязнять вашу реальную конфигурацию:

export HERMES_HOME=/tmp/hermes-plugin-test
mkdir -p $HERMES_HOME/plugins/model-providers/my-provider
cat > $HERMES_HOME/plugins/model-providers/my-provider/__init__.py <<'EOF'
from providers import register_provider
from providers.base import ProviderProfile
register_provider(ProviderProfile(
    name="my-provider",
    env_vars=("MY_API_KEY",),
    base_url="https://api.my-provider.example.com/v1",
    auth_type="api_key",
))
EOF

export MY_API_KEY=your-test-key
hermes -z "hello" --provider my-provider -m some-model

Интеграция с общим PluginManager

Общий PluginManager (тот, с которым работает hermes plugins) видит плагины провайдеров моделей, но не импортирует их — providers/__init__.py управляет их жизненным циклом. Менеджер записывает манифест для интроспекции и категоризирует по kind: model-provider. Когда вы помещаете немаркированный пользовательский плагин в $HERMES_HOME/plugins/, который вызывает register_provider с ProviderProfile, менеджер автоматически приводит его к kind: model-provider с помощью эвристики на основе исходного текста — так что плагин всё равно маршрутизируется корректно даже без plugin.yaml.

Распространение через pip

Как и любой плагин Hermes, провайдеры моделей могут поставляться как pip-пакет. Добавьте точку входа в ваш pyproject.toml:

[project.entry-points."hermes.plugins"]
acme-inference = "acme_hermes_plugin:register"

…где acme_hermes_plugin:register — это функция, вызывающая register_provider(profile). Общий PluginManager подхватывает плагины с точками входа во время discover_and_load(). Для pip-плагинов с kind: model-provider вам всё равно нужно объявить kind в манифесте (или полагаться на эвристику исходного текста).

См. Building a Hermes Plugin для полной настройки точек входа.

Связанные страницы

• Provider Runtime — приоритет разрешения + где каждый слой читает профиль

• Adding Providers — полный чеклист для новых бэкендов инференса (охватывает как быстрый путь плагина, так и полную интеграцию CLI/аутентификации)

• Memory Provider Plugins

• Context Engine Plugins

• Building a Hermes Plugin — общее руководство по созданию плагинов