Initial commit: Hermes skill hermes-auxiliary-local-models

SKILL.md

@@ -0,0 +1,91 @@
+---
+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`.