--- id: meta.mvp-outline title: MVP-оглавление — точный состав type: reference status: review last_reviewed: 2026-11-15 --- # MVP-оглавление Точный состав MVP к утверждению. Всё, чего нет здесь, — parking lot (P2), в MVP не пишется. **Итог: 50 статей = 20 LLM + 25 llama.cpp + 5 туториалов**, плюс 52 термина глоссария (см. [GLOSSARY-SEED](../shared/glossary/GLOSSARY-SEED.md)). Приоритеты: P0 — 29 статей, P1 — 20. Отдельная дорожка — **ассистент** (LLM-слой), объём его MVP описан [ниже](#ассистент-llm-слой-объём-mvp). Обозначения: тип и уровень — по [CONVENTIONS](CONVENTIONS.md#метаданные-статьи); P — приоритет внутри MVP. «О чём» — рабочая миссия статьи в одну строку. ## Аудитория (предложение) - **Основная:** русскоязычные разработчики и инженеры (джун+/мидл), которые хотят запускать и настраивать локальные LLM через llama.cpp и понимать, что происходит «под капотом». Уверенно пользуются CLI и читают код; ML-математика не предполагается — формулы по минимуму, с интуицией. - **Вторичная:** ML-специалисты без опыта локального инференса (их ведёт llama.cpp Handbook). - **Не аудитория (MVP):** исследователи за SOTA-обзорами; кластерные продакшн-деплои (P2). ## LLM Handbook — 20 статей (`/llm/`) | ID | Рабочее название | Тип | Уровень | P | О чём | |---|---|---|---|---|---| | `llm.what-is-llm` | Что такое LLM | concept | base | P0 | текст → токены → вероятности; параметры и «веса»; что называют инференсом; почему это «предсказание следующего токена» | | `llm.model-selection` | Какую модель развернуть: выбор под задачу и железо | comparison | base | P0 | задача → размер → квант → проверка; семейства и пресеты v1.0.0; «модель месяца» — HF GGUF trending | | `llm.tokenization` | Токенизация | concept | base | P0 | BPE/Unigram, словарь, спецтокены; почему счёт токенов ≠ счёт слов и как это режет контекст | | `llm.transformer` | Архитектура Transformer | concept | core | P0 | блок трансформера: attention + FFN, нормы, residual; где «живут» веса и что такое слой | | `llm.attention` | Attention | concept | core | P0 | QKV и softmax(QKᵀ/√d)V; каузальность; цена O(n²) — почему длинный контекст дорог | | `llm.attention-variants` | MHA, MQA, GQA, MLA | comparison | deep | P1 | варианты организации голов; как GQA/MLA уменьшают KV-кэш и что теряют | | `llm.embeddings` | Эмбеддинги | concept | base | P1 | векторные представления токенов и текстов; поиск по близости, почему для этого отдельные режимы | | `llm.context-window` | Контекстное окно | concept | base | P0 | что помещается в контекст; цена длины; что происходит при переполнении | | `llm.rope-scaling` | RoPE и масштабирование контекста | concept | deep | P1 | позиционные кодирования; linear/NTK/YaRN при выходе за обученную длину — и риски | | `llm.inference` | Инференс: авторегрессия, префилл и декод | concept | core | P0 | шаг генерации; префилл vs декод; откуда берутся t/s и почему первый токен ждётся дольше | | `llm.kv-cache` | KV-кэш | concept | core | P0 | зачем кэшировать K/V; из чего складывается размер кэша; что бывает при нехватке | | `llm.batching` | Батчинг инференса | concept | core | P1 | зачем объединять запросы; статический vs непрерывный батчинг; цена для латентности | | `llm.sampling` | Сэмплирование | concept | core | P0 | от логитов к токену; жадное vs стохастическое; как комбинируются фильтры (top-k → top-p → min-p) | | `llm.sampling-params` | Параметры сэмплирования | reference | core | P0 | карточки temperature, top-k, top-p, min-p, repeat penalty, seed: смысл, диапазон, влияние, типичные ошибки | | `llm.quantization` | Квантование | concept | core | P0 | int8/int4, поблочное квантование; когда качество проседает и почему; размер vs скорость | | `llm.chat-templates` | Чат-шаблоны | concept | base | P1 | роли, спецтокены, системный промпт; почему «голая» base-модель не умеет чат | | `llm.constrained-decoding` | Ограниченное декодирование | concept | deep | P1 | как заставить модель выдавать валидный JSON/регэксп: грамматики на этапе сэмплирования | | `llm.lora` | LoRA | concept | deep | P1 | низкоранговые адаптеры: маленькая надстройка над весами вместо полного файнтюна | | `llm.training` | Как обучают LLM | concept | core | P1 | префтрейн → SFT → RLHF/DPO; откуда берутся instruct-версии; в llama.cpp не применимо (см. crossmap) | | `llm.evaluation` | Оценка качества | concept | core | P1 | перплексия, бенчмарки, лёгкие проверки локальной модели; что реально проверить дома | ## llama.cpp Handbook — 25 статей (`/llama-cpp/`) | ID | Рабочее название | Тип | Уровень | P | О чём | |---|---|---|---|---|---| | `lcp.overview` | Что такое llama.cpp | concept | base | P0 | чистый C/C++ для локального инференса «на любом железе»; что умеет и чего не умеет | | `lcp.build` | Сборка llama.cpp | how-to | base | P0 | cmake-пресеты, включение GPU-бэкендов, где оказываются бинарники; готовые сборки | | `lcp.backends` | Бэкенды: CPU, CUDA, Vulkan, Metal, SYCL | comparison | core | P1 | чем отличаются, когда какой выбирать, как убедиться, что работает нужный | | `lcp.gguf` | Формат GGUF | reference | core | P0 | контейнер «всё в одном файле»: тензоры + метаданные (архитектура, токенизатор, чат-шаблон) | | `lcp.gguf-convert` | Конвертация модели в GGUF | how-to | core | P1 | `convert_hf_to_gguf.py`, выбор f16/bf16, типичные ошибки конвертации; когда проще скачать готовый GGUF | | `lcp.quantize` | Квантование: llama-quantize | how-to | core | P0 | команда, выбор типа, importance matrix; во что упирается результат | | `lcp.quant-types` | Типы квантования GGUF | comparison | core | P0 | Q4_0…Q6_K, I-кванты: размер/скорость/качество; что брать по умолчанию и почему K-кванты живучее | | `lcp.llama-cli` | llama-cli: запуск и чат в терминале | how-to | base | P0 | базовый запуск, интерактивный режим, ключевые флаги; когда CLI достаточно | | `lcp.llama-server` | llama-server: HTTP-сервер | how-to | base | P0 | запуск, `--host/--port`, слоты и параллелизм, встроенный веб-UI; типовая конфигурация | | `lcp.server-api` | HTTP API llama-server | reference | core | P1 | `/completion`, `/chat/completions` (OpenAI-совместимость), `/embeddings`, `/tokenize`, `/props`, `/metrics` | | `lcp.common-flags` | Общие флаги: модель, контекст, железо | reference | core | P0 | карточки `-m`, `-c`, `-ngl`, `-t/-tb`, `-b/-ub`, `-fa`, `--no-mmap`, `--mlock`, `--numa`, rope-флаги | | `lcp.sampler-flags` | Флаги сэмплирования | reference | core | P0 | `--temp`, `--top-k`, `--top-p`, `--min-p`, `--repeat-penalty`, `-s`; зеркалит карточки из `llm.sampling-params` | | `lcp.gpu-offload` | GPU-оффлоад слоёв | how-to | core | P1 | `-ngl`, прикидка VRAM (веса + KV-кэш + буферы), разделение CPU/GPU, несколько GPU (`--tensor-split`) | | `lcp.batching-flags` | Батчинг: -b, -ub, --parallel | reference | core | P1 | логический батч и физический ubatch; continuous batching на сервере, слоты | | `lcp.chat-templates` | Чат-шаблоны в llama.cpp | how-to | core | P1 | `--chat-template`, шаблон из GGUF; диагностика «модель отвечает не как чат» | | `lcp.grammar` | Грамматики GBNF | how-to | deep | P1 | `--grammar`/`--grammar-file`, JSON-схемы, типичные паттерны (JSON, выбор из списка, формат дат) | | `lcp.lora-usage` | LoRA-адаптеры в llama.cpp | how-to | deep | P1 | конвертация адаптера, `--lora`/`--lora-scaled`, во что упирается скорость | | `lcp.embeddings-usage` | Эмбеддинги: получение векторов | how-to | core | P1 | `--embeddings`/`llama-embedding`, endpoint `/embedding`, pooling; типичное применение — поиск | | `lcp.benchmarks` | llama-bench: замер производительности | how-to | core | P1 | метрики pp/tg, сравнение квантов и бэкендов, как читать таблицу результатов | | `lcp.perf-tuning` | Производительность: базовая настройка | how-to | core | P1 | потоки vs ядра, flash-attn, размеры батчей, mmap/mlock; реалистичные ожидания по t/s | | `lcp.troubleshooting` | Диагностика: карта проблем | troubleshooting | base | P0 | хаб «симптом → статья»; как собирать информацию: лог запуска, `/props`, llama-bench | | `lcp.diag-oom` | Не хватает памяти (OOM) | troubleshooting | core | P0 | GPU OOM при загрузке и в генерации, RAM OOM; `-ngl`, тип кванта, `-c`, квантование KV-кэша | | `lcp.diag-slow` | Медленная генерация | troubleshooting | core | P0 | низкие t/s: потоки, бэкенд, оффлоад, квант; отдельно — медленный префилл (`-ub`, `-fa`) | | `lcp.diag-quality` | Плохое качество после квантования | troubleshooting | core | P0 | «модель деградировала»: выбор кванта, imatrix, проверка перплексией; мусор/повторы — когда виноваты сэмплеры | | `lcp.diag-load` | Модель не загружается | troubleshooting | core | P0 | unsupported architecture, bad magic, старая версия сборки, битый GGUF, ошибки чат-шаблона | ## Туториалы — 5 сквозных сценариев (`/tutorials/`) | ID | Название | Уровень | P | Путь читателя | |---|---|---|---|---| | `tut.run-model` | Запуск первой модели локально | base | P0 | выбрать GGUF → `lcp.build`/готовая сборка → `llama-cli` → первые флаги → убедиться, что работает | | `tut.chat` | Локальный чат с моделью | base | P0 | правильный чат-шаблон → системный промпт → сэмплеры «для человеческого» режима | | `tut.server` | llama-server для себя и команды | core | P0 | запуск сервера → API → параллельные запросы → подключение клиента (curl/Python/OpenAI-SDK) | | `tut.quantize` | Квантуем модель под своё железо | core | P0 | прикидка бюджета памяти → `llama-quantize` → проверка скорости и качества → выбор кванта | | `tut.diag` | Диагностика: OOM и медленная генерация | core | P0 | воспроизводим проблемы из `tut.server` → читаем лог и `/props` → чиним по `lcp.diag-*` | ## Распределение приоритетов - **P0 (29):** все статьи из списка пользователя — глоссарий, токенизация, transformer, attention, KV-кэш, контекст, сэмплирование, квантование, GGUF, сборка, `llama-cli`, `llama-server`, диагностика (+ справочная обвязка: карточки параметров, общие флаги, overview, 5 туториалов). - **P1 (20):** embeddings, LoRA, grammar, batching, GPU offload, бэкенды, чат-шаблоны, API, бенчмарки + их концепт-пары в LLM Handbook. - Каждый концепт LLM имеет связь с llama.cpp или пометку «не применимо» — проверяется по [CROSSMAP, раздел A](../shared/crossmap/CROSSMAP.md#a-концепт--реализация-implements). Чисто серверные параметры (`p.host`, `p.port` и т.п.) существуют только как карточки без LLM-концепта — это допустимая категория. ## Ассистент (LLM-слой) — объём MVP Справочник без LLM — только корпус для RAG и навигация по связям, поэтому LLM-интерфейс обязателен. Полный контракт — [assistant/SPEC](../assistant/SPEC.md); данные — [shared/data](../shared/data/README.md). В MVP ассистента входят (реализация — этап 4, параллельно волнам 3–4 статей): - **A0 «Объясни по уровню»** — рендеринг статьи канона в лёгком/среднем/профессиональном стиле, выбор уровня по ситуации, t=0; рендеры не хранятся в корпусе. - **A1 «Спроси справочник»** — RAG-ответы по статьям и глоссарию с цитатами ID. - **A2 «Смоделируй конфигурацию»** — подбор кванта и флагов под железо: детерминированный расчёт памяти (`calc_memory`: веса + KV-кэш + буферы) + объяснение trade-off ссылками на статьи + предсказание результата. - Инфраструктура: OpenAI-совместимый adapter (провайдер по умолчанию — локальный `llama-server`, внешний — опция), поиск по ключевым словам, промпты, eval-набор из 8 кейсов. Вне MVP (этап 5): A3 «Объясни результат» (интерпретация логов/llama-bench), embeddings-поиск, внешний провайдер, eval в CI, внутренний ревьюер статей (A4). ## Статус корпуса (обновлено 2026-11-15) **Все 50 статей написаны**: LLM (20, `review`) → llama.cpp (25, `review`, заземлены на закупленный [v1.0.0](../sources/llama-cpp/v1.0.0/MANIFEST.md)) → туториалы (5, `draft` — требуют вычистки на реальном железе). Дефолты флагов и bpw квантов верифицированы по v1.0.0 и лежат в [shared/data](../shared/data/README.md). Целостность корпуса (ID↔файлы, ссылки, ID в данных) проверена скриптом: 0 нарушений. Остаток этапа 4: ревью людьми, вычистка туториалов на железе, сайт (MkDocs), CI. ## Порядок написания - **Волна 1 (10, согласованный список):** `llm.what-is-llm`, `llm.tokenization`, `llm.attention`, `llm.kv-cache`, `llm.context-window`, `llm.sampling`, `llm.quantization`, `lcp.gguf`, `lcp.build`, `lcp.llama-server`. - **Волна 2 (добираем P0):** `llm.transformer`, `llm.inference`, `llm.sampling-params`, `lcp.overview`, `lcp.quantize`, `lcp.quant-types`, `lcp.llama-cli`, `lcp.common-flags`, `lcp.sampler-flags`, `lcp.troubleshooting`. - **Волна 3 (диагностика + туториалы):** `lcp.diag-oom`, `lcp.diag-slow`, `lcp.diag-quality`, `lcp.diag-load`; туториалы пишутся по мере готовности статей, на которые ссылаются. - **Волна 4 (P1):** остальные 20 статей. ## Parking lot (P2, вне MVP — ID зарезервированы) `llm.multimodal`, `lcp.mmproj` (мультимодальность) · `llm.distributed`, `lcp.rpc` (распределённый инференс) · `lcp.perf-deep` (тонкая оптимизация: NUMA, сборка под железо) · `lcp.integrations` (клиенты и биндинги) · `llm.safety` (безопасность, джейлбреймы) · `lcp.speculative` (спекулятивное декодирование) · `llm.moe` (MoE-архитектуры) · `lcp.finetune` (llama-finetune, экспериментальное) · `llm.rag` (RAG на практике: эмбеддинги, чанки, реранкинг — асcистент уже использует принципы, статья потом). ## Чек-лист приёмки MVP Из [PLAN](PLAN.md#5-критерии-готовности-mvp), с привязкой к этому составу: - [ ] 50/50 статей со статусом ≥ review. - [ ] 50/50 терминов глоссария имеют статью-«хозяина» (`defines`). - [ ] Все связи из [CROSSMAP](../shared/crossmap/CROSSMAP.md) двусторонние и без битых ID (CI). - [ ] 5/5 туториалов проходят вычистку на реальном железе хотя бы одной конфигурации. - [ ] Зафиксирован тег llama.cpp; карточки флагов сверены с ним (`version` + `last_reviewed`). - [ ] markdownlint, lychee, проверка ID — зелёные в CI. - [ ] Ассистент A1/A2 работает на локальном llama-server и проходит eval-набор ([assistant/SPEC](../assistant/SPEC.md#6-оценка-качества-eval)).