# Как ускорить локальную LLM: спекулятивное декодирование, батчинг и кэш KV

> AI Release · @ai_release1 · https://ai-release.org/guides/kak-uskorit-lokalnuyu-llm-spekulyativnoe-dekodirovanie.html

## TL;DR
- Время выполнения: 45–70 минут на первый прогон, 10 минут на повторную настройку.
- Уровень сложности: Intermediate.
- Понадобится: Linux или Windows с WSL2; GPU NVIDIA + драйвер (версию сверьте с документацией CUDA); сборка `llama.cpp` с `-DGGML_CUDA=ON`; опционально `vLLM` для серверного батчинга; целевая модель в формате GGUF; draft-модель (маленькая «черновая» модель того же семейства); `curl` и `jq`; запас VRAM (сколько именно — измеряете сами, см. Шаг 1).

## Требования и подготовка
![Иллюстрация к разделу «Требования и подготовка»](https://ai-release.org/guides/img/kak-uskorit-lokalnuyu-llm-spekulyativnoe-dekodirovanie-ru-1.jpg?v=1794926742)


- ОС: Linux (Ubuntu/Debian-подобная) или Windows + WSL2. На Windows без WSL2 сборка с CUDA не соберётся «из коробки» — сверьтесь с документацией по вашей связке драйвер/CUDA.
- GPU: NVIDIA, драйвер установлен, `nvidia-smi` отвечает.
- Пакеты сборки: `git`, `cmake`, `build-essential`, CUDA Toolkit.
- Модели: целевая `<ваша-модель>.gguf` и `<ваша-draft-модель>.gguf` — draft обязана использовать **тот же токенизатор**, иначе спекулятивное декодирование не даст выигрыша.
- Свободное место: целевая модель + draft + временные файлы сборки.
- Свободный порт для сервера: `llama-server` по умолчанию слушает `8080`, `vLLM` — `8000`.

Три техники, которые разбираем, и их «цена»:

| Техника | Что ускоряет | Чем платите | Где НЕ работает |
|---|---|---|---|
| Спекулятивное декодирование | генерацию токенов при `--parallel 1` | VRAM под draft-модель, падение при низком acceptance | при параллельных слотах и при высокой температуре сэмплинга |
| Батчинг (параллельные слоты / continuous batching) | суммарную пропускную способность при многих запросах | контекст делится между слотами | на одиночном запросе выигрыша нет |
| Квантованный KV-кэш (`q8_0`) | экономию VRAM под кэш | незначительную потерю качества | без Flash Attention квантование V-кэша не включается |

Терминология в одну строку: **KV-кэш** — сохранённые состояния внимания для уже прочитанных токенов, чтобы не пересчитывать промпт заново; **спекулятивное декодирование** — маленькая модель предлагает несколько токенов, большая их проверяет пачкой; **TTFT** — время до первого токена; **батчинг** — обработка нескольких запросов одновременно.

Чек-лист перед стартом:
- [ ] `nvidia-smi` показывает GPU и объём VRAM
- [ ] `cmake --version` и `nvcc --version` отвечают
- [ ] обе GGUF-модели скачаны локально
- [ ] порт `8080` свободен (`ss -ltnp | grep 8080`)

Подключение локального сервера к клиентам (Claude Code через OpenAI-совместимый API) разобрано отдельно: [Как подключить локальную модель к Claude Code: llama-server, OpenAI-совместимый API и лаунчер](https://ai-release.org/guides/kak-podklyuchit-lokalnuyu-model-k-claude-code-llama-ser.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

## Шаг 1. Базовая линия: замерьте tokens/s и TTFT до любых оптимизаций

**Что сделать:** соберите `llama.cpp` с поддержкой CUDA и снимите эталонный замер до включения спекуляции и батчинга.

```bash
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j
ls build/bin | grep -E 'llama-bench|llama-server'
```

**Зачем:** без цифры «до» вы не отличите ускорение от шума. Один и тот же прогон потом повторяется с теми же `-p`/`-n`, иначе сравнение бессмысленно.

**Пример:** замер фиксированного профиля — 512 токенов промпта, 128 токенов генерации, все слои на GPU:

```bash
./build/bin/llama-bench -m models/<ваша-модель>.gguf -p 512 -n 128 -ngl 99
```

Вывод — таблица с колонками `model | size | params | backend | ngl | test | t/s`. Строки `pp512` (обработка промпта) и `tg128` (генерация) дают два ваших опорных числа. Конкретные значения зависят от GPU — впишите их в свою таблицу замеров, эталонных «правильных» цифр не существует.

Второй замер — через сервер, чтобы видеть то же, что увидит клиент:

```bash
./build/bin/llama-server -m models/<ваша-модель>.gguf -ngl 99 -c 8192 --port 8080 &

curl -s http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"local","messages":[{"role":"user","content":"Перечисли 5 фактов о KV-кэше."}],"max_tokens":256}' \
  | jq '.timings'
```

**Как проверить:** в ответе есть блок `timings` с полями `prompt_per_second` и `predicted_per_second`. Запишите оба числа — это ваша базовая линия. Если `jq` не установлен, уберите его и смотрите сырой JSON.

Почему это работает: `llama-bench` гоняет синтетический профиль без сети и клиента, поэтому его числа стабильнее, чем замер через HTTP, где добавляется сетевая и JSON-разметка.

## Шаг 2. Включите три рычага: спекулятивное декодирование, батчинг слотов и квантованный KV-кэш
![Иллюстрация к разделу «Шаг 2. Включите три рычага: спекулятивное декодирование, батчинг слотов и квантованный KV-кэш»](https://ai-release.org/guides/img/kak-uskorit-lokalnuyu-llm-spekulyativnoe-dekodirovanie-ru-2.jpg?v=1794926746)


**Что сделать:** запустите сервер с draft-моделью, квантованным кэшем и Flash Attention, затем отдельным прогоном — с параллельными слотами.

Спекуляция + квантованный KV-кэш (одиночные запросы):

```bash
./build/bin/llama-server \
  -m models/<ваша-модель>.gguf \
  -md models/<ваша-draft-модель>.gguf \
  --draft-max 8 --draft-min 4 --draft-p-min 0.7 \
  -ngl 99 --gpu-layers-draft 99 \
  -fa --cache-type-k q8_0 --cache-type-v q8_0 \
  -c 8192 --port 8080
```

Батчинг (много одновременных запросов):

```bash
./build/bin/llama-server \
  -m models/<ваша-модель>.gguf \
  -ngl 99 -fa --cache-type-k q8_0 --cache-type-v q8_0 \
  -c 32768 --parallel 4 --cont-batching \
  --port 8080
```

**Зачем:** каждая опция бьёт в своё узкое место.
- `-md` включает спекулятивное декодирование: draft-модель предлагает до `--draft-max` токенов, целевая проверяет их одним проходом. Работает, пока доля принятых предложений высокая.
- `--parallel 4` создаёт 4 слота, `--cont-batching` разрешает подставлять новые запросы в освободившийся слот, не дожидаясь остальных.
- `--cache-type-k/v q8_0` хранит кэш в 8-битном формате — при длинном контексте это освобождает VRAM. Квантование V-кэша требует Flash Attention, поэтому `-fa` обязателен.

Важно: `-c` — это **общий** контекст. При `--parallel 4` и `-c 32768` каждому слоту достанется около 8192 токенов. Хотите по 16k на слот — ставьте `-c 65536`, если хватает VRAM.

Для серверного сценария с высоким RPS альтернатива — `vLLM`; там те же идеи называются `--max-num-seqs`, `--max-model-len`, `--gpu-memory-utilization`, `--enable-prefix-caching`:

```bash
vllm serve <ваша-модель> \
  --max-model-len 8192 \
  --max-num-seqs 8 \
  --gpu-memory-utilization 0.90 \
  --enable-prefix-caching
```

`--enable-prefix-caching` переиспользует KV-кэш для одинаковых начал промпта (системный промпт, инструкции) — это прямой аналог «кэша KV» на уровне запросов.

**Пример:** как выглядит проверка, что draft-модель действительно подключилась — сервер при старте печатает загрузку двух моделей и строку о спекулятивном декодировании с параметрами `draft_max/draft_min`. Если в логе только одна модель — флаг не распознан или путь неверный.

Настройка VRAM на ноутбуках с ограниченной видеопамятью имеет свою специфику (сколько слоёв реально влезает, что уходит в RAM): [Как запустить локальную LLM на ноутбуке с Ryzen 9 8940HX и RTX 5060: настройка, VRAM и скорость](https://ai-release.org/guides/kak-zapustit-lokalnuyu-llm-na-noutbuke-s-ryzen-9-8940hx.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

**Как проверить:** за один прогон сервера квантование и Flash Attention подтверждаются отсутствием ошибки аллокации и ростом доступной VRAM:

```bash
nvidia-smi --query-gpu=memory.used,memory.total --format=csv
curl -s http://127.0.0.1:8080/health
```

Ожидаемо: `/health` возвращает `{"status":"ok"}`, а `memory.used` после старта ниже, чем была при том же `-c` без `--cache-type-k/v`. Точные имена флагов в вашей сборке сверьте с `llama-server --help` — набор опций меняется между версиями.

## Шаг 3. Проверка результата: A/B-замер и приёмка
![Иллюстрация к разделу «Шаг 3. Проверка результата: A/B-замер и приёмка»](https://ai-release.org/guides/img/kak-uskorit-lokalnuyu-llm-spekulyativnoe-dekodirovanie-ru-3.jpg?v=1794926753)


**Что сделать:** повторите замер из Шага 1 на новой конфигурации и сравните три метрики: генерация (tokens/s), обработка промпта (tokens/s) и TTFT.

```bash
for i in 1 2 3; do
  curl -s -o /dev/null -w "ttft_total=%{time_total}\n" \
    http://127.0.0.1:8080/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{"model":"local","messages":[{"role":"user","content":"Напиши 200 слов про инференс LLM."}],"max_tokens":256}'
done

./build/bin/llama-bench -m models/<ваша-модель>.gguf -p 512 -n 128 -ngl 99
```

Для батчинга нужен параллельный прогон — иначе вы измеряете не то:

```bash
for i in $(seq 1 4); do
  curl -s http://127.0.0.1:8080/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{"model":"local","messages":[{"role":"user","content":"Кратко: что такое continuous batching?"}],"max_tokens":128}' &
done; wait
```

**Зачем:** суммарная пропускная способность при батчинге и скорость одиночного запроса — разные метрики. Оптимизация под RPS может ухудшить latency одного пользователя, и наоборот.

**Как проверить:** успех фиксируется по таблице «до/после», а не на глаз:

- [ ] `tg` (генерация) вырос по сравнению с базовой линией при `--parallel 1`
- [ ] `pp` (промпт) не просел больше, чем на единицы процентов
- [ ] при `--parallel 4` четыре одновременных запроса завершаются без ошибок контекста
- [ ] `memory.used` в `nvidia-smi` оставляет запас, а не упирается в потолок

Если хотя бы один пункт не выполнен — откатывайте по одному флагу за прогон: сначала `--cache-type-k/v`, потом `--parallel`, потом спекуляцию. Так видно, какой рычаг дал отрицательный эффект.

Почему это работает: спекуляция ускоряет только ту часть, где целевая модель «соглашается» с draft; если доля принятых токенов мала, вы платите за лишние проходы. Именно поэтому сравнение делается на ваших реальных промптах, а не на синтетике.

## Возможные проблемы и решения

**Проблема. Сервер падает при старте после включения `--parallel` или увеличения `-c`.**
- Ошибка: `CUDA error: out of memory`
- Причина: KV-кэш аллоцируется под весь `-c` сразу; при `--parallel 4` и большом `-c` требуемый объём превышает VRAM.
- Решение: уменьшайте `-c` или число слотов, затем добавляйте квантование кэша:
```bash
./build/bin/llama-server -m models/<ваша-модель>.gguf -ngl 99 -fa \
  --cache-type-k q8_0 --cache-type-v q8_0 -c 16384 --parallel 4 --port 8080
```
Проверка: сервер доходит до строки `listening on http://127.0.0.1:8080`.

**Проблема. `vLLM` не стартует на выбранной длине контекста.**
- Ошибка: `ValueError: The model's max seq len (32768) is larger than the maximum number of tokens that can be stored in KV cache (16384). Try increasing gpu_memory_utilization or decreasing max_model_len.`
- Причина: под `--max-model-len` не хватает памяти под KV-кэш на доступной VRAM.
- Решение: снизить `--max-model-len` до влезающего значения или поднять `--gpu-memory-utilization` (не выше разумного предела, оставляющего память драйверу):
```bash
vllm serve <ваша-модель> --max-model-len 16384 --gpu-memory-utilization 0.90
```

**Проблема. Запрос через API падает, хотя одиночный `llama-bench` работает.**
- Ошибка: `{"error":{"message":"the request exceeds the available context size, try increasing it"}}`
- Причина: при `--parallel N` контекст `-c` поделён на слоты, и длинный промпт + `max_tokens` не влезают в слот, хотя суммарно контекст «большой».
- Решение: считать бюджет как `-c / --parallel`. Нужно 8k на запрос при 4 слотах — ставьте `-c 32768`; либо уменьшите `--parallel`:
```bash
./build/bin/llama-server -m models/<ваша-модель>.gguf -ngl 99 -c 32768 --parallel 4
```

Отдельный случай: генерация стала **медленнее** после включения `-md`. Это не ошибка, а низкая доля принятых draft-токенов — чаще всего из-за draft-модели из другого семейства или высокой температуры сэмплинга. Решение: взять draft того же семейства и снизить `--draft-max`.

## Резюме и следующие шаги

Снимите базовую линию, включайте рычаги по одному и принимайте результат только по таблице «до/после» на своих промптах. Дальше имеет смысл сравнить бэкенды инференса на одной модели — например, по инструкции [Как ускорить DeepSeek с помощью DeepInfer: установка и настройка инференса](https://ai-release.org/guides/kak-uskorit-deepseek-s-pomoschyu-deepinfer-ustanovka-i.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide), а при выносе в кластер — [Как развернуть локальную ИИ-модель на Kubernetes: пошаговое руководство](https://ai-release.org/guides/kak-razvernut-lokalnuyu-ii-model-na-kubernetes-poshagov.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

## FAQ

**Что такое спекулятивное декодирование простыми словами?**
Маленькая draft-модель предлагает несколько следующих токенов, а большая проверяет их за один проход. Если предложения совпали с тем, что выдала бы большая модель, они принимаются пачкой — генерация ускоряется.

**Почему спекулятивное декодирование не ускоряет работу при батчинге?**
В `llama.cpp` спекуляция рассчитана на один слот: при `--parallel` больше 1 несколько запросов уже заполняют вычислительные блоки, и «пачка» от draft перестаёт экономить проходы. Точное поведение вашей версии сверьте с выводом сервера при старте — там печатаются активные параметры.

**Можно ли квантовать KV-кэш без Flash Attention?**
Квантование V-кэша (`--cache-type-v`) требует включённого Flash Attention (`-fa`). Без него сборка либо откажется принимать флаг, либо стартует без квантования — проверяйте список активных опций в логе запуска.

**Как понять, что батчинг вообще дал эффект?**
Замером: одиночный запрос почти не изменится, а четыре параллельных (`curl ... &` + `wait`) закончатся заметно быстрее, чем четыре последовательных. Если разницы нет — проверьте, что `--cont-batching` включён и слоты не упираются в общий `-c`.
