--- id: shared.crossmap title: Матрица связей LLM ↔ llama.cpp type: reference status: review last_reviewed: 2026-11-15 --- # Матрица связей LLM ↔ llama.cpp Машиночитаемая истина о типизированных связях между справочниками (типы — по [CONVENTIONS](../../meta/CONVENTIONS.md#2-типы-связей)). Этап 4: из этих таблиц CI генерирует страницы-навигаторы «Концепт → Реализация» и проверяет двусторонность каждой связи. > ✅ **Версия зафиксирована:** llama.cpp **v1.0.0** (коммит `b1b770d`, 2026-11-13; > закупка и пиннинг 2026-11-15). Соответствия «концепт ↔ флаг» и дефолты карточек `p.*` > верифицированы по закупленным docs/help этого тега > ([sources/llama-cpp/v1.0.0](../../sources/llama-cpp/v1.0.0/MANIFEST.md)). Смена версии — > перекачка скриптом и точечная правка. ## A. Концепт → реализация (`implements`) | Концепт LLM | Реализация в llama.cpp | Статья lcp.* | Примечание | |---|---|---|---| | `llm.what-is-llm` | весь проект: локальный инференс без зависимостей | `lcp.overview`, `lcp.build` | две точки входа в одну тему; сборка — в lcp.build | | `llm.model-selection` | скачивание `-hf`, встроенные пресеты моделей, выбор кванта под VRAM | `lcp.llama-cli`, `lcp.quant-types` | факты имён — из docs v1.0.0 (models.md, пресеты cli) | | `llm.tokenization` | токенизатор хранится в GGUF (vocabulary, спецтокены); `/tokenize`, `/detokenize` | `lcp.gguf`, `lcp.server-api` | | | `llm.transformer` | тензоры и метаданные архитектуры (`general.architecture`) в GGUF | `lcp.gguf` | детали загрузки — вне MVP | | `llm.attention` | `-fa/--flash-attn` (v1.0.0: `on/off/auto`, по умолчанию `auto`); поддержка зависит от бэкенда | `lcp.common-flags`, `lcp.backends` | FA быстрее и экономнее по памяти; нужен для квантованного KV | | `llm.attention-variants` (GQA/MLA) | вариант attention определяет размер KV-кэша → сколько влезет в VRAM | `lcp.diag-oom` | связь через `g.mha-gqa` | | `llm.embeddings` | `--embeddings`, `llama-embedding`, endpoint `/embedding` | `lcp.embeddings-usage` | | | `llm.context-window` | `-c/--ctx-size` (0 = из модели); переполнение — context shift **выключен** по умолчанию в v1.0.0 | `lcp.common-flags` | см. также `err.ctx-overflow`, `p.context-shift` | | `llm.rope-scaling` | `--rope-scaling`, `--rope-freq-base`, `--rope-freq-scale`, `--yarn-*` | `lcp.common-flags` | | | `llm.inference` (префилл/декод) | метрики pp/tg в `llama-bench`; `-b`/`-ub` на префилл; запуск как сервис — `llama-server` | `lcp.benchmarks`, `lcp.llama-server` | | | `llm.kv-cache` | `-fa`; квантование KV: `-ctk`/`-ctv` (требуют FA); бюджет VRAM/RAM | `lcp.common-flags`, `lcp.diag-oom` | | | `llm.batching` | `-b`, `-ub`, `--parallel`/`-np`, continuous batching сервера | `lcp.batching-flags` | | | `llm.sampling` | флаги сэмплирования + параметры запросов сервера | `lcp.sampler-flags` | карточки параметров — раздел B | | `llm.quantization` | `llama-quantize`, типы `q.*`, importance matrix | `lcp.quantize`, `lcp.quant-types` | | | `llm.chat-templates` | `--chat-template`; шаблон в метаданных GGUF | `lcp.chat-templates` | | | `llm.constrained-decoding` | `--grammar`/`--grammar-file` (GBNF), `-j` (JSON Schema); `grammar`/`json_schema` в API; опц. бэкенд LLGuidance (`-DLLAMA_LLGUIDANCE=ON`) | `lcp.grammar` | | | `llm.lora` | `--lora`, `--lora-scaled`; конвертация адаптера | `lcp.lora-usage` | | | `llm.training` | — | — | **не применимо в MVP**: обучение вне скоупа; экспериментальный `llama-finetune` — parking lot | | `llm.evaluation` | частично: `llama-perplexity` для сравнения квантов | `lcp.diag-quality` | полные eval-сьюиты — вне MVP | ## B. Параметр → флаг (`exposes`) Каждая строка — будущая карточка параметра (`p.*`): концепт-статья даёт смысл и физику, `lcp.*`-статья — представление в llama.cpp. «Запрос» — поле тела запроса API, «старт» — флаг запуска `llama-server`/`llama-cli`. | Параметр | Что делает | llama-cli | llama-server | Концепт | |---|---|---|---|---| | `p.temperature` | разогрев/остывание распределения вероятностей | `--temp` | запрос: `temperature` | `llm.sampling` | | `p.top-k` | рассматривать только k самых вероятных токенов | `--top-k` | запрос: `top_k` | `llm.sampling` | | `p.top-p` | ядро вероятностной массы (nucleus) | `--top-p` | запрос: `top_p` | `llm.sampling` | | `p.min-p` | отсечение по доле от вероятности лидера | `--min-p` | запрос: `min_p` | `llm.sampling` | | `p.repeat-penalty` | штраф за уже сгенерированные токены | `--repeat-penalty` | запрос: `repeat_penalty` | `llm.sampling` | | `p.seed` | воспроизводимость сэмплирования | `-s/--seed` | запрос: `seed` | `llm.sampling` | | `p.ctx-size` | размер контекстного окна | `-c/--ctx-size` | старт: `--ctx-size` | `llm.context-window` | | `p.n-gpu-layers` | сколько слоёв уходит на GPU | `-ngl` | старт: `-ngl` | `g.offload` → `lcp.gpu-offload` | | `p.batch-size` | логический батч (обработка промпта) | `-b` | старт: `-b` | `llm.batching` | | `p.ubatch-size` | физический микро-батч вычислений | `-ub` | старт: `-ub` | `llm.batching` | | `p.parallel` | число слотов/параллельных запросов | `--parallel`/`-np` | старт: `--parallel` | `llm.batching` | | `p.threads` | CPU-потоки инференса | `-t` (генерация), `-tb` (батч) | старт: `-t` | `lcp.perf-tuning` | | `p.flash-attn` | включить FlashAttention | `-fa/--flash-attn` | старт: `-fa` | `llm.attention`, `llm.kv-cache` | | `p.cache-type-k` | тип квантования K-кэша | `-ctk` | старт: `-ctk` | `llm.kv-cache`; требует `-fa` | | `p.cache-type-v` | тип квантования V-кэша | `-ctv` | старт: `-ctv` | `llm.kv-cache`; требует `-fa` | | `p.rope-scaling` | режим растяжения контекста (linear/ntk/yarn…) | `--rope-scaling` + `--rope-freq-*`, `--yarn-*` | старт: те же | `llm.rope-scaling` | | `p.chat-template` | переопределение чат-шаблона | `--chat-template` | старт: `--chat-template` | `llm.chat-templates` | | `p.grammar` | GBNF-грамматика вывода | `--grammar`, `--grammar-file` | запрос: `grammar`, `json_schema` | `llm.constrained-decoding` | | `p.host`, `p.port` | адрес/порт сервера (v1.0.0: 127.0.0.1:9931) | — | старт: `--host`, `--port` | без LLM-концепта (чисто серверный параметр) | | `p.load-mode` | режим загрузки модели (auto/mmap/mlock/dio) | `-lm/--load-mode` | старт: `-lm` | `g.mmap` (заменил `--no-mmap`/`--mlock`) | | `p.context-shift` | сдвиг контекста при переполнении | `--context-shift/--no-context-shift` | старт | `llm.context-window` (по умолчанию **выключен**) | | `p.fit` | авто-подгонка unset-аргументов под память GPU | `-fit/--fit` (+`-fitt`, `-fitc`) | старт | `lcp.diag-oom` (по умолчанию **включен**) | ## C. Артефакт → формат/утилита (`handles`) | Артефакт | Утилита / флаг | Результат | Статья | |---|---|---|---| | модель на HF (safetensors) | `convert_hf_to_gguf.py` | GGUF f16/bf16 | `lcp.gguf-convert` | | GGUF f16 | `llama-quantize` | GGUF `q.q4-k-m`, `q.q8-0`, I-кванты… | `lcp.quantize` | | калибровочные данные | расчёт importance matrix (`--imatrix`) | I-кванты заметно лучше держат качество | `lcp.quantize` | | LoRA-адаптер (HF) | `convert_lora_to_gguf.py` → `--lora` | GGUF-LoRA поверх базовой модели | `lcp.lora-usage` | | текст промпта | токенизатор из GGUF; `/tokenize` | последовательность token id | `llm.tokenization` | | GBNF-файл `.gbnf` | `--grammar-file` | вывод, ограниченный грамматикой | `lcp.grammar` | | чат-шаблон (jinja в GGUF) | `--chat-template` (переопределение) | промпт с ролями и спецтокенами | `lcp.chat-templates` | | готовый GGUF из HF-реп сообщества | без конвертации → `-m` | сразу рабочий файл модели | `tut.run-model` | ## D. Симптом → диагностика (`diagnoses`) | Симптом | Типичная причина | Статья | |---|---|---| | `err.oom-gpu-load` — «CUDA out of memory» / ошибка аллокации VRAM при загрузке | веса + KV-кэш не влезают: `-ngl`, тип кванта, `-c` | `lcp.diag-oom` | | `err.oom-ram` — процесс убит по памяти на CPU | модель/контекст больше RAM | `lcp.diag-oom` | | `err.slow-gen` — генерация единицы t/s | потоки, не тот бэкенд, слабый оффлоад, тяжёлый квант | `lcp.diag-slow` | | `err.slow-pp` — долго «думает» перед первым токеном | медленный префилл: `-ub`, `-fa`, длина промпта | `lcp.diag-slow` | | `err.quality-drop` — модель «поглупела» после квантования | слишком агрессивный квант без imatrix | `lcp.diag-quality` | | `err.garbage` — мусор, повторения, бессвязный текст | сэмплеры (экстремальная температура), неверный шаблон, битый файл | `lcp.diag-quality` + `lcp.sampler-flags` | | `err.wont-load` — «unsupported architecture», «bad magic» | старая сборка llama.cpp, некорректный GGUF | `lcp.diag-load` | | `err.chat-format` — игнорирует роли, «отвечает как продолжение текста» | неверный чат-шаблон | `lcp.chat-templates`, `lcp.diag-load` | | `err.ctx-overflow` — «request exceeds available context» | `-c` меньше промпта+ответа | `lcp.common-flags`, `llm.context-window` | ## E. Глоссарий-поповеры (`defines`) - Каждое `g.*` имеет одну «основную статью» (колонка в [GLOSSARY-SEED](../glossary/GLOSSARY-SEED.md)) — связь `defines`. - Первое упоминание термина в статье: ссылка на глоссарий; на сайте (этап 1) — поповер с определением и ссылкой на оба справочника. - Статья-концепт включает определение из глоссария сниппетом, а не копирует текст. - Блок «См. в другом справочнике» обязателен для статей со связями `implements`: `llm.*` → соответствующие `lcp.*`, и наоборот (генерируется из этой матрицы). ## Поддержка - Новая связь = строка здесь + поля `llm_refs`/`llama_cpp_refs`/`related` в frontmatter обеих статей. - CI (этап 4) проверяет: у каждой связи `implements`/`exposes`/`diagnoses` существует обратная; все ID существуют; каждая статья MVP-оглавления присутствует хотя бы в одной матрице (или помечена «не применимо»). - Исключения («не применимо», сознательные): - `llm.sampling-params` — страница-агрегатор карточек `p.*`; построчно покрыта разделом B. - `lcp.troubleshooting` — карта-агрегатор диагностик; построчно покрыта разделом D (`err.*` → `lcp.diag-*`). - `tut.chat`, `tut.diag`, `tut.quantize`, `tut.server` — сквозные маршруты по матрицам A–D; туториал по определению не привязан к одной связи.