---
name: hermes-auxiliary-local-models
description: "Use when routing Hermes auxiliary tasks to local Ollama."
version: 1.0.0
author: Agent
---

# Hermes Auxiliary Local Models

## Когда использовать

Когда main-модель Hermes облачная (polza.ai, DeepSeek, Claude, ...), а auxiliary-задачи
(vision/анализ картинок, web_extract, title_generation, session_search, compression)
хочется переложить на локальную Ollama-модель: экономия облачных токенов, приватность
(картинки не уходят в облако), скорость. Компаньон скилла `hermes-mixed-model-delegation`
(тот про delegate_task/subagents, этот про auxiliary).

## Как устроен auxiliary в Hermes (факты из agent/auxiliary_client.py)

- Раздел конфига: `auxiliary.<task>.provider/model/base_url/api_key` в config.yaml.
- `provider: auto` = цепочка: (1) main-провайдер, (2) OpenRouter, (3) Nous Portal,
  (4) custom endpoint, (5) Anthropic, (6) прямые провайдеры. Для vision отдельная цепочка.
- Только `compression` имеет жёсткий минимум контекста: `MINIMUM_CONTEXT_LENGTH = 64_000`
  (agent/model_metadata.py). Остальные задачи (vision, title, web_extract, session_search)
  — без флора, могут работать на малом контексте.
- Для локальной Ollama: `provider: custom` + `base_url: http://localhost:11434/v1` +
  `api_key: ollama` (любая непустая строка). Hermes зарезолвит OpenAI-совместимый клиент.
- Vision-поддержку локальной модели Hermes определяет через `query_ollama_supports_vision`
  (поле `capabilities` в `/api/show`).

## Конфигурация (проверенный пример: vision на qwen3-vl:8b)

```bash
hermes config set auxiliary.vision.provider custom
hermes config set auxiliary.vision.model qwen3-vl:8b
hermes config set auxiliary.vision.base_url http://localhost:11434/v1
hermes config set auxiliary.vision.api_key ollama
```

Остальные auxiliary оставить `auto` (уходят на облачный main-провайдер). Изменения вступают
в силу после `/reset` (новой сессии).

## Подбор модели под VRAM

- 16 GB (RTX 5060 Ti, 14 GB free): qwen3-vl:8b ≈ 7.2 GB при ctx 4096/8192.
  Плюс bge-m3 (эмбеддинги) ≈ 1.2 GB. Итого ~8.5 GB, остаётся ~7 GB запаса.
- qwen3:8b (текст) ≈ 5.2 GB, но GGUF-контекст 40960 < 64K флора compression —
  текстовые aux можно, compression НЕТ (оставить на облаке).
- Всегда проверяй реальный GGUF-контекст: `/api/show` → `model_info.*.context_length`
  (имена тегов "-64k"/"-65k" часто лгут).

## Проверка vision E2E (без UI)

1. Прямой тест Ollama `/api/chat` с картинкой (base64) + `options: {num_ctx: 8192}`.
2. OpenAI-совместимый путь `/v1/chat/completions` с `image_url: data:image/png;base64,...` —
  именно его использует Hermes.
3. Резолв из Python (сигнатура важна: `explicit_base_url`/`explicit_api_key`, НЕ base_url/api_key):
```python
from agent.auxiliary_client import _resolve_task_provider_model, resolve_provider_client
provider, model, base_url, api_key, api_mode = _resolve_task_provider_model(task="vision")
client, resolved = resolve_provider_client(provider=provider, model=model,
    explicit_base_url=base_url, explicit_api_key=api_key, is_vision=True, task="vision")
```

## Pitfalls

- **Тестовая картинка должна быть ≥ 32×32 px.** Qwen3-VL image processor в Ollama падает
  с panic `height:1 or width:1 must be larger than factor:32` на картинках меньше 32 px —
  это выглядит как 500/EOF runner, но это баг размера картинки, а не конфигурации.
- **GGUF-контекст qwen3-vl:8b = 262144** — KV cache при полном контексте ~309 GB, физически
  не влезает. Ollama по умолчанию грузит с num_ctx 4096 (нормально); для запросов можно
  задавать `options: {num_ctx: 8192}`. Не доверяй GGUF-контексту при планировании VRAM.
- **`hermes chat --provider custom` в CLI может не подхватить ключ** — это не показатель
  поломки: auxiliary резолвится из config.yaml напрямую. Проверяй через Python-резолвер
  (см. выше), а не через CLI-запуск.
- **Пустой content при vision-ответе** — если картинка слишком мала/простая, content может
  быть пустым при `finish_reason: stop` (reasoning ушёл в `reasoning`/`reasoning_content`).
  Перепроверь на картинке 256×256.
- Модель держится в VRAM (~7-10 мин keep_alive по умолчанию), потом выгружается. Освободить
  принудительно: `docker exec ollama ollama stop qwen3-vl:8b`.
- Ollama в Docker: CLI-команды через `docker exec ollama ollama ...`.

## Откат

```bash
hermes config set auxiliary.vision.provider auto
hermes config set auxiliary.vision.model ""
docker exec ollama ollama stop qwen3-vl:8b
```

Подробный разбор сессии с транскриптом ошибок: `references/qwen3-vl-ollama-setup.md`.