🏠 Главная › Developer Guide › adding providers

sidebar_position: 5 title: "Adding Providers" description: "How to add a new inference provider to Hermes Agent — auth, runtime resolution, CLI flows, adapters, tests, and docs" lang: ru

Добавление провайдеров

Hermes уже может общаться с любой конечной точкой, совместимой с OpenAI, через собственный путь провайдера. Не добавляйте встроенного поставщика, если вам не нужен первоклассный UX для этого сервиса:

Если поставщик является просто «еще одним базовым URL-адресом и ключом API, совместимым с OpenAI», может быть достаточно именованного пользовательского поставщика.

Ментальная модель

Встроенный провайдер должен работать на нескольких уровнях:

  1. hermes_cli/auth.py решает, как будут найдены учетные данные.
  2. hermes_cli/runtime_provider.py превращает это в данные времени выполнения:
  3. provider
  4. api_mode
  5. base_url
  6. api_key
  7. source
  8. run_agent.py использует api_mode, чтобы решить, как формируются и отправляются запросы.
  9. hermes_cli/models.py и hermes_cli/main.py позволяют отображать поставщика в CLI. (hermes_cli/setup.py делегирует main.py автоматически — никаких изменений здесь не требуется.)
  10. agent/auxiliary_client.py и agent/model_metadata.py поддерживают работу побочных задач и бюджета токенов.

Важная абстракция — api_mode.

Сначала выберите путь реализации

Путь A — OpenAI-совместимый поставщик

Используйте это, когда провайдер принимает стандартные запросы в стиле чата.

Типичная работа:

Обычно вам не нужен новый адаптер или новый api_mode.

Путь Б — Родной провайдер

Используйте это, когда провайдер не ведет себя как завершение чата OpenAI.

Примеры в дереве сегодня:

Этот путь включает в себя все, начиная с пути А, плюс:

Контрольный список файлов

Требуется для каждого встроенного поставщика

  1. hermes_cli/auth.py
  2. hermes_cli/models.py
  3. hermes_cli/runtime_provider.py
  4. hermes_cli/main.py
  5. agent/auxiliary_client.py
  6. agent/model_metadata.py
  7. тесты
  8. Документы для пользователей под website/docs/.

:::совет hermes_cli/setup.py не требует изменений. Мастер настройки делегирует выбор поставщика/модели select_provider_and_model() в main.py — любой добавленный туда поставщик автоматически становится доступным в hermes setup.

Дополнительно для собственных/не-OpenAI провайдеров

  1. agent/<provider>_adapter.py
  2. run_agent.py
  3. pyproject.toml, если требуется SDK поставщика

Шаг 1. Выберите один канонический идентификатор провайдера

Выберите один идентификатор провайдера и используйте его везде.

Примеры из репо:

Тот же идентификатор должен появиться в:

Если идентификаторы в этих файлах различаются, провайдер будет чувствовать себя неуверенно: аутентификация может работать, в то время как /model, настройка или разрешение во время выполнения молча пропускают ее.

Шаг 2. Добавьте метаданные аутентификации в hermes_cli/auth.py

Для поставщиков ключей API добавьте запись ProviderConfig в PROVIDER_REGISTRY с помощью:

Также добавьте псевдонимы к _PROVIDER_ALIASES.

Используйте существующих поставщиков в качестве шаблонов:

Вопросы, на которые можно ответить здесь:

Если провайдеру нужно нечто большее, чем «поиск ключа API», добавьте специальный преобразователь учетных данных вместо того, чтобы помещать логику в несвязанные ветки.

Шаг 3: Добавьте каталог моделей и псевдонимы в hermes_cli/models.py

Обновите каталог поставщиков, чтобы поставщик работал в меню и в синтаксисе provider:model.

Типичные правки:

Если поставщик предоставляет список действующих моделей, сначала отдайте предпочтение этому и сохраните _PROVIDER_MODELS в качестве статического запасного варианта.

Этот файл также обеспечивает работу таких входных данных:

anthropic:claude-sonnet-4-6
kimi:model-name

Если здесь отсутствуют псевдонимы, провайдер может пройти проверку подлинности правильно, но синтаксический анализ /model все равно не удастся.

Шаг 4. Разрешение данных времени выполнения в hermes_cli/runtime_provider.py

resolve_runtime_provider() — это общий путь, используемый CLI, шлюзом, cron, ACP и вспомогательными клиентами.

Добавьте ветку, которая возвращает dict как минимум:

{
    "provider": "your-provider",
    "api_mode": "chat_completions",  # or your native mode
    "base_url": "https://...",
    "api_key": "...",
    "source": "env|portal|auth-store|explicit",
    "requested_provider": requested_provider,
}

Если поставщик совместим с OpenAI, api_mode обычно должен оставаться chat_completions.

Будьте осторожны с приоритетом ключей API. Hermes уже содержит логику, позволяющую избежать утечки ключа OpenRouter на несвязанные конечные точки. Новый провайдер должен одинаково четко указывать, какой ключ к какому базовому URL-адресу относится.

Шаг 5: Подключите CLI к hermes_cli/main.py

Поставщика невозможно обнаружить, пока он не появится в интерактивном потоке hermes model.

Обновите их в hermes_cli/main.py:

:::совет hermes_cli/setup.py не нуждается в изменениях — он вызывает select_provider_and_model() из main.py, поэтому ваш новый провайдер автоматически появляется как в hermes model, так и в hermes setup.

Шаг 6. Обеспечьте работу дополнительных вызовов

Здесь имеют значение два файла:

agent/auxiliary_client.py

Добавьте дешевую/быструю вспомогательную модель по умолчанию в _API_KEY_PROVIDER_AUX_MODELS, если это прямой поставщик ключей API.

К вспомогательным задачам относятся такие вещи, как:

Если у провайдера нет разумного дополнительного значения по умолчанию, побочные задачи могут некорректно откатиться или неожиданно использовать дорогостоящую основную модель.

agent/model_metadata.py

Добавьте длину контекста для моделей поставщика, чтобы бюджетирование токенов, пороги сжатия и ограничения оставались в разумных пределах.

Шаг 7: Если провайдер родной, добавьте адаптер и поддержку run_agent.py

Если поставщик не является простым завершением чата, изолируйте логику, специфичную для поставщика, в agent/<provider>_adapter.py.

Сосредоточьтесь run_agent.py на оркестровке. Он должен вызывать помощники адаптера, а не вручную создавать полезные данные поставщика, встроенные по всему файлу.

Родному провайдеру обычно нужна работа в этих местах:

Новый файл адаптера

Типичные обязанности:

run_agent.py

Найдите api_mode и проверьте каждую точку переключения. Как минимум проверьте:

Также найдите run_agent.py для self.client.. Любой путь кода, предполагающий наличие стандартного клиента OpenAI, может сломаться, если собственный поставщик использует другой клиентский объект или self.client = None.

Кэширование подсказок и поля запроса, зависящие от поставщика

Быстрое кэширование и настройки, зависящие от поставщика, легко регрессировать.

Примеры уже есть в дереве:

Когда вы добавляете собственного поставщика, дважды проверьте, что Hermes отправляет только те поля, которые действительно понимает поставщик.

Шаг 8: Тесты

Как минимум потрогать тесты, охраняющие проводку провайдера.

Общие места:

В примерах только для документации точный набор файлов может отличаться. Суть в том, чтобы охватить:

Запустите тесты с отключенным xdist:

source venv/bin/activate
python -m pytest tests/test_runtime_provider_resolution.py tests/test_cli_provider_resolution.py tests/test_cli_model_command.py tests/test_setup_model_selection.py -n0 -q

Для более глубоких изменений запустите полный пакет перед отправкой:

source venv/bin/activate
python -m pytest tests/ -n0 -q

Шаг 9: Живая проверка

После тестов проведите настоящий дымовой тест.

source venv/bin/activate
python -m hermes_cli.main chat -q "Say hello" --provider your-provider --model your-model

Также проверьте интерактивные потоки, если вы изменили меню:

source venv/bin/activate
python -m hermes_cli.main model
python -m hermes_cli.main setup

Для собственных поставщиков также проверьте хотя бы один вызов инструмента, а не просто текстовый ответ.

Шаг 10. Обновите документы для пользователей

Если поставщик должен поставляться как первоклассный вариант, обновите также пользовательскую документацию:

Разработчик может идеально подключить провайдера, но при этом пользователи не смогут обнаружить необходимые переменные окружения или процесс настройки.

Контрольный список поставщиков, совместимых с OpenAI

Используйте это, если провайдер предлагает стандартные дополнения в чате.

Контрольный список собственного поставщика

Используйте это, когда провайдеру нужен новый путь протокола.

Распространенные ошибки

1. Добавляем провайдера для аутентификации, но не для разбора модели

Это обеспечивает правильное разрешение учетных данных, в то время как входные данные /model и provider:model не работают.

2. Забываем, что config["model"] может быть строкой или диктом

Большая часть кода выбора поставщика должна нормализовать обе формы.

3. Предполагается, что требуется встроенный поставщик

Если сервис просто совместим с OpenAI, индивидуальный поставщик уже может решить проблему пользователя с меньшими затратами на обслуживание.

4. Забываем вспомогательные пути

Основной путь чата может работать, когда суммирование, очистка памяти или помощники по зрению не работают, поскольку дополнительная маршрутизация никогда не обновлялась.

5. Ветки родного провайдера скрываются в run_agent.py

Найдите api_mode и self.client.. Не думайте, что очевидный путь запроса — единственный.

6. Отправка ручек, предназначенных только для OpenRouter, другим провайдерам

Такие поля, как маршрутизация поставщика, принадлежат только поставщикам, которые их поддерживают.

7. Обновление hermes model, но не hermes setup

Оба потока должны знать о провайдере.

Хорошие цели поиска при реализации

Если вы ищете все места, к которым прикасается провайдер, найдите эти символы:

Связанные документы