Каталог моделей

Hermes загружает кураторские списки моделей для OpenRouter и Nous Portal из JSON-манифеста, размещённого рядом с сайтом документации. Это позволяет сопровождающим обновлять списки без выпуска нового релиза hermes-agent.

Если манифест недоступен (офлайн, заблокированная сеть, сбой хостинга), Hermes молча откатывается к встроенному снимку из репозитория, поставляемому с CLI. Манифест никогда не ломает интерфейс выбора модели — в худшем случае вы увидите список, встроенный в вашу установленную версию.

URL живого манифеста

https://hermes-agent.nousresearch.com/docs/api/model-catalog.json

Публикуется при каждом слиянии в main через существующий пайплайн GitHub Pages deploy-site.yml. Источник истины находится в репозитории по адресу website/static/api/model-catalog.json.

Схема

{
  "version": 1,
  "updated_at": "2026-04-25T22:00:00Z",
  "metadata": {},
  "providers": {
    "openrouter": {
      "metadata": {},
      "models": [
        {"id": "z-ai/glm-5.2",         "description": "default", "default": true},
        {"id": "moonshotai/kimi-k3",   "description": "recommended", "metadata": {}},
        {"id": "openai/gpt-5.4",       "description": ""}
      ]
    },
    "nous": {
      "metadata": {},
      "models": [
        {"id": "z-ai/glm-5.2", "default": true},
        {"id": "anthropic/claude-opus-4.7"},
        {"id": "moonshotai/kimi-k3"}
      ]
    }
  }
}

Описание полей:

version — целочисленная версия схемы. Будущие схемы увеличивают это значение; Hermes отклоняет манифесты с неизвестными версиями и откатывается к встроенному снимку.
metadata — свободный словарь на уровне манифеста, провайдера и модели. Любые ключи. Hermes игнорирует неизвестные поля, так что можно аннотировать записи ("tier": "paid", "tags": [...], и т.д.) без согласования изменений схемы.
description — только для OpenRouter. Определяет текст бейджа в интерфейсе выбора ("recommended", "free", "default" или пусто). Nous Portal это поле не использует.
default — ровно одна запись на провайдера может иметь "default": true. Эта модель — тихий дефолт: то, на чём Hermes останавливается, если пользователь так и не выбрал модель (карточка подтверждения при GUI-онбординге, provider настроен без model, пустой model.default). Читается только из кэша во время работы (get_default_model_from_cache), так что горячие пути разрешения модели никогда не обращаются к сети; если кэшированного манифеста нет, Hermes откатывается к встроенной в репозиторий константе PREFERRED_SILENT_DEFAULT_MODEL, которая должна совпадать с помеченной записью. Это позволяет сопровождающим менять тихий дефолт без выпуска релиза. Модель для этой роли выбирается сознательно недорогая и достаточно способная — никогда самый дорогой флагман.
Цены и длина контекста НЕ включены в манифест. Они поступают из живых API провайдеров (эндпоинты /v1/models, models.dev) во время загрузки.

Поведение при загрузке

Когда	Что происходит
`/model` или `hermes model`	Загружает, если кэш на диске устарел, иначе использует кэш
Шлюз запущен	Фоновое обновление каждые `ttl_minutes` (по умолчанию 20), поэтому список отстаёт от опубликованного манифеста не больше чем на одно окно
Кэш на диске свежий (< TTL)	Нет обращений к сети
Сбой сети при наличии кэша	Молчаливый откат к кэшу, одна строка в логе
Сбой сети, кэш отсутствует	Молчаливый откат к встроенному снимку
Манифест не прошёл валидацию схемы	Считается недоступным

Расположение кэша: ~/.hermes/cache/model_catalog.json.

Списки моделей по провайдерам в графическом пикере

Пикеры десктопа, TUI и дашборда (model.options) собирают строку каждого провайдера из живого каталога, закэшированного на диске (~/.hermes/provider_models_cache.json), а если кэша ещё нет — из курируемого списка. Открытие пикера никогда не ждёт ни зонда /v1/models провайдера, ни проверки аутентификации: устаревшие или отсутствующие каталоги обновляются в фоновом потоке и появятся при следующем открытии. Поэтому один медленный, упёршийся в лимиты или недоступный провайдер не держит весь пикер в состоянии загрузки. Refresh models (или /model --refresh) — явное действие, которое сбрасывает кэш и опрашивает всех провайдеров вживую.

Конфигурация

model_catalog:
  enabled: true
  url: https://hermes-agent.nousresearch.com/docs/api/model-catalog.json
  ttl_minutes: 20
  providers: {}

Установите enabled: false для полного отключения удалённой загрузки и постоянного использования встроенного снимка (заодно выключится и фоновое обновление у шлюза). Параметр ttl_minutes задаёт сразу и срок жизни кэша, и частоту обновления у шлюза; старый ключ ttl_hours по-прежнему учитывается, если задать его явно.

URL переопределения для конкретного провайдера

Третьи стороны могут самостоятельно размещать свой кураторский список, используя ту же схему. Укажите провайдеру пользовательский URL:

model_catalog:
  providers:
    openrouter:
      url: https://example.com/my-openrouter-curation.json

Переопределяющий манифест должен заполнять только нужный блок провайдера. Остальные провайдеры продолжают разрешаться через основной URL.

Скрытие провайдеров из пикера

excluded_providers позволяет скрыть конкретных провайдеров из пикера /model, даже если для них есть валидные учётные данные. Полезно, когда учётные данные сохранились для устаревших или тестовых провайдеров, которым не место в обычном использовании (например, старый токен Copilot или OpenRouter, всё ещё закэшированный в auth.json или обнаруженный через gh CLI).

model_catalog:
  excluded_providers:
    - copilot
    - openrouter
    - openai

Исключение сравнивается без учёта регистра со всеми ключами, под которыми может проявляться провайдер — id Hermes и id models.dev (для встроенных сопоставленных провайдеров), pid оверлея и разрешённый slug Hermes (для оверлейных провайдеров), канонический slug (для канонических провайдеров) — поэтому одна запись вроде copilot скрывает провайдера независимо от того, из какой секции он появляется. Это учитывается на каждой поверхности пикера /model: интерактивных и текстовых пикерах шлюза, пикере TUI и интерактивном пикере CLI hermes model. Пустой список (или отсутствие ключа) ни на что не влияет.

Обновление манифеста

Для сопровождающих:

# Перегенерировать из встроенных жёстко заданных списков (синхронизирует манифест после
# редактирования OPENROUTER_MODELS или _PROVIDER_MODELS["nous"] в hermes_cli/models.py).
python scripts/build_model_catalog.py

Затем создайте PR с результирующим изменением website/static/api/model-catalog.json в main. Сайт документации автоматически разворачивается при слиянии, и новый манифест становится доступен в течение нескольких минут.

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