--- id: assistant.spec title: Спецификация LLM-интерфейса ассистента type: reference status: review last_reviewed: 2026-11-15 --- # LLM-интерфейс: спецификация слоя ассистента Справочник без LLM — это только корпус для RAG и навигация по связям. Ассистент — обязательный слой: он отвечает на вопросы по статьям, **моделирует конфигурации llama.cpp** (подбор кванта и флагов под железо, расчёт памяти, предсказание результата) и **объясняет наблюдаемый результат** (логи, вывод `llama-bench`). ## 1. Принципы 1. **LLM не источник истины.** Истина — канонический контент репозитория: статьи, глоссарий, [слой данных](../shared/data/README.md). Ассистент объясняет, но не сочиняет факты. 2. **Числа считает калькулятор, не LLM.** Размеры памяти, bpw, KV-кэш — детерминированные функции от `shared/data/*.yaml`. LLM получает результат инструмента и комментирует его. 3. **Каждый ответ цитирует ID** (`llm.*`, `lcp.*`, `tut.*`, `g.*`, `p.*`, `err.*`). Факт без ссылки — дефект ответа. 4. **Локальный провайдер по умолчанию** — `llama-server`: тот самый, которому посвящён справочник (dogfooding). Внешний API — опция для скорости/качества. 5. **Провайдер-нейтральный контракт:** OpenAI-совместимый chat completions; embeddings — через endpoint `/embedding` llama-server. Абстракция не привязана к вендору. ## 2. Провайдеры | id | тип | endpoint | назначение | |---|---|---|---| | `local` | llama.cpp | `http://127.0.0.1:8080/v1/chat/completions` | по умолчанию; как поднять — см. `lcp.llama-server` / `tut.server` | | `external` | любой OpenAI-совместимый | задаётся конфигом | когда нужна модель сильнее локальной | Конфигурация: `assistant/config.yaml` (в `.gitignore`; образец — [config.example.yaml](config.example.yaml)). Ключи — только через переменные окружения, в репозиторий не попадают. ## 3. Контракт ответа Запрос: `{scenario: qa | config | interpret | render, input, options}`. Ответ ассистента — четыре обязательных блока: 1. **Ответ** — кратко, по-русски, термины как в глоссарии. 2. **Источники** — список ID с указанием, что из каждого взято. 3. **Расчёты/инструменты** — какие инструменты вызывались, вход и выход. 4. **Неуверенность** — чего не хватило; «в справочнике этого нет» — допустимый и предпочтительный ответ вместо домысливания. ## 4. Инструменты (function calling) | Инструмент | Вход | Выход | |---|---|---| | `search_handbook(query, k)` | вопрос/ключевые слова | фрагменты: `{id, title, excerpt, score}` | | `calc_memory(model_ref, quant, n_ctx, kv_quant, ngl)` | архитектура, тип кванта, контекст, квант KV, число слоёв на GPU | разбивка: веса / KV-кэш / буферы / итог; вердикт «влезает / нет» в VRAM/RAM | | `propose_config(hw, goal)` | VRAM, RAM, ядра; цель (чат/эмбеддинги, контекст) | 2–3 варианта конфигурации (`quant`, `-ngl`, `-c`, `-b/-ub`, `-fa`) с обоснованием | Формулы калькулятора (детерминированные): - Веса: `params × bpw(quant) / 8` байт — bpw из [quants.yaml](../shared/data/quants.yaml). - KV-кэш: `2 × n_layers × n_ctx × n_kv_heads × head_dim × bytes(kv_quant)` — параметры архитектуры из `models.yaml` (этап 4). - Буферы/overhead: эвристика 10–20% сверху — всегда помечается как оценка, не точное число. Реализация: `scripts/assistant/` (этап 4). ## 5. Сценарии | id | Сценарий | Вход | Выход | Этап | |---|---|---|---|---| | A0 | «Объясни по уровню» (рендеринг) | ID статьи канона + уровень изложения (лёгкий/средний/профессиональный; или «подбери по ситуации») | та же статья, переложенная выбранным стилем; **t = 0** | 4 (MVP) | | A1 | «Спроси справочник» | вопрос пользователя | ответ с цитатами; при широком вопросе — маршрут чтения (последовательность ID) | 4 (MVP) | | A2 | «Смоделируй конфигурацию» | железо + модель/цель | конфиг с расчётом памяти, предсказание результата (что влезет, качественные ожидания скорости), что читать | 4 (MVP) | | A3 | «Объясни результат» | лог запуска / вывод `llama-bench` / симптом | интерпретация, гипотезы, ссылки на `lcp.diag-*` | 5 | | A4 | «Внутренний ревьюер» | черновик статьи | несоответствия конвенциям, потерянные связи crossmap | 5+ | ### Уровни изложения (A0): хранится один канон, стили — в промпте Три варианта текста **не хранятся** — это были бы три источника истины с тройным diff. В репозитории ровно одна версия статьи; лёгкий/средний/профессиональный — это стили **рендеринга** ассистентом из канона ([стили и правила — в промпте](prompts/system.md)). - **t = 0**: один вход (ID статьи + уровень) → одинаковый выход всегда; рендер воспроизводим и проверяем дифф-тестом (двойной прогон → идентичный текст). - **Факты не размножаются**: материал рендера — только найденные фрагменты канона и слой данных; числа/дефолты — дословно; никаких «добавим для ясности». - **Граница глубины — frontmatter**: `level` статьи (base/core/deep) задаёт каноническую глубину контента; уровень изложения управляет подачей (словарь, формулы, длина), а не объёмом фактов. Лёгкий рендер deep-статьи упрощает подачу, сохраняя главный вывод; профессиональный рендер base-статьи добавляет точность из слоя данных, не выдумывая материал. - **Выбор по ситуации**: уровень не указан → ассистент определяет по контексту диалога (маркеры опыта пользователя) и называет выбранный уровень; переключение — «объясни легче» / «глубже». - **Рендер эфемерен**: пользовательская копия не коммитится в корпус; каноничен только файл репозитория ([протокол правок — SOURCES §5](../meta/SOURCES.md)). - Оценка (этап 5): факт-чек рендера против канона + дифф-тест t=0 добавляются в eval-набор. ### Режим свежих данных Тумблер «Разрешить сбор и обновление информации» (Настройки → Служебное) при включении добавляет в системный промпт A1 разрешение дополнять ответ знаниями модели с пометкой **[вне справочника]** (конфликты решает справочник; числа — только из инструментов). Выключен по умолчанию: строгий RAG. Фоновое обновление корпуса (HF trending, docs новой версии) подхватывает этот флаг с этапа 5. ## 6. Оценка качества (eval) - [eval/qa-seed.yaml](eval/qa-seed.yaml) — вопросы → ожидаемые цитаты и ключевые факты. Метрика: ≥ 90% ответов содержат ожидаемые ID, 0 несуществующих ID. - Золотые расчёты для `calc_memory`: конфигурации с известным результатом (добавляются вместе с `models.yaml`, этап 4). - Этап 4 — прогон вручную; этап 5 — в CI при доступном провайдере. ## 7. Этапы реализации | Этап | Что делается | |---|---| | 1 (сейчас) | Контракт (этот файл), слой данных `shared/data/`, системный промпт, seed eval-набор | | 4 | ✅ Реализовано на Node (`assistant/src`, zero-dependency): adapter local/external, keyword-поиск, `calc_memory` (golden 11/11 vs v1.0.0), `propose_config`, сценарии A0/A1/A2, CLI, **веб-UI** с настройками подключаемой LLM (`node src/server.js` → :9940). Dry-eval: 8/8 | | 5 | Embeddings-поиск (через `/embedding` того же llama-server), сценарий A3, eval LLM-режима в CI, стриминг ответов |