# ADR-004. Матрица уровней AI (min/medium/max): модели, кванты, железо, параметры генерации

## Статус
ACCEPTED

## Контекст
Продукту нужны три уровня качества AI-обработки (`min`/`medium`/`max`,
`AiLevel` в `backend/core/plugins/config.py`) для пресетов инсталлятора 3–5.
Ограничения: только локальные модели на всех уровнях (без внешних API);
промпты `workers/summarizer/prompts/` едины и не меняются между уровнями —
качество наращивается размером модели, а не правкой промптов. Ранний опыт с
Qwen ~3B показал, что модель на пределе инструктивной сложности: reduce
упирался в `max_tokens=1024`, отсюда per-tier лимиты (reduce ≥1536); часовой
транскрипт на CPU ≈ 6,5 мин — ориентир для уровня «min».

Актуальное на момент решения поколение моделей — **Qwen3.5**: dense
0.8B/2B/4B/9B («Small», thinking ВЫКЛЮЧЕН по умолчанию), dense 27B и MoE
35B-A3B (мультимодальные, thinking ВКЛЮЧЁН по умолчанию, отключается
`chat_template_kwargs: {"enable_thinking": false}`), крупнее — 122B-A10B,
397B-A17B. Инференс поддержан llama.cpp (llama-server,
`--chat-template-kwargs`), GGUF-кванты публикуются Qwen и Unsloth.
Кандидаты Qwen3-4B/8B/14B/32B (предыдущее поколение) отклонены в пользу
более нового поколения при том же рантайме.

faster-whisper: GPU через CTranslate2 — `WhisperModel(..., device="cuda",
compute_type="float16")` (вариант `int8_float16` для экономии VRAM); нужны
cuBLAS/cuDNN 9 для CUDA 12 (`pip install nvidia-cublas-cu12
nvidia-cudnn-cu12==9.*` + `LD_LIBRARY_PATH`) и nvidia-container-toolkit.
llama.cpp: официальные CUDA-образы `ghcr.io/ggml-org/llama.cpp:server-cuda`
(CUDA 12) / `server-cuda13`; offload — `--n-gpu-layers` /
`LLAMA_ARG_N_GPU_LAYERS`.

## Решение

### Матрица уровней

| Уровень | Транскрибация | Суммаризация (LLM) | Режим |
|---|---|---|---|
| **min** | faster-whisper `small`, CPU, `int8` (~0,5 ГБ весов) | **Qwen3.5-4B**, GGUF Q4_K_M ≈ 2,5–2,8 ГБ, llama.cpp CPU | thinking выключен по умолчанию (семейство Small) |
| **medium** | faster-whisper `medium` (~1,5 ГБ): CPU `int8`; при GPU — `cuda`/`float16` (VRAM ~2–3 ГБ) | **Qwen3.5-9B**, GGUF Q4_K_M ≈ 6,2 ГиБ, llama.cpp CPU или GPU (полный offload от ~8 ГБ VRAM) | thinking выключен по умолчанию |
| **max** | faster-whisper `large-v3` (~3 ГБ), только GPU, `cuda`/`float16` (VRAM ~4,5–5 ГБ) | **Qwen3.5-35B-A3B** (MoE, ~3B активных), GGUF Q4_K_M ≈ 20–22 ГБ, llama.cpp GPU (полный offload от ~24 ГБ VRAM; допустим гибрид GPU+RAM за счёт скорости) | thinking ПРИНУДИТЕЛЬНО отключается: `LLAMA_ARG_CHAT_TEMPLATE_KWARGS='{"enable_thinking":false}'` на llama-server |

Замена более раннего варианта (Qwen2.5-3B → Qwen3.5-4B на min) — сопоставимый
размер/скорость, новее поколение, лучшее следование инструкциям; промпты
не трогаем — они едины для всех уровней. Точные имена GGUF-файлов фиксируются в
`deploy/llm/download-model.sh` при реализации (репозитории `Qwen/…-GGUF` /
`unsloth/…-GGUF`); размеры выше — ориентиры для инсталлятора.

### Per-tier параметры генерации (промпты неизменны)

| Параметр | min | medium | max |
|---|---|---|---|
| temperature | 0.2 | 0.2 | 0.2 |
| max_tokens (map) | 1024 | 1024 | 1536 |
| max_tokens (reduce) | 1536 | 2048 | 2560 |
| CTX llama-server | 16384 | 16384 | 16384 |

temperature 0.2 — осознанное отступление от рекомендаций карточки модели
(0.7–1.0 для чата): суммаризация экстрактивная, нужна детерминированность.
Раздельные лимиты map/reduce требуют параметров
`max_tokens_map`/`max_tokens_reduce` в плагине `QwenLocal` (options, контракт
`Summarizer` не меняется).

### Требования железа (таблица инсталлятора и детекта админки)

| Пресет | CPU | RAM | GPU (VRAM) | Диск | Модели на диске |
|---|---|---|---|---|---|
| 1 MVP / 2 +чат | 4 vCPU | 8 ГБ | — | 40 ГБ | — |
| 3 +AI min | 8 vCPU | 16 ГБ | — | 100 ГБ | ~3,5 ГБ |
| 4 +AI medium | 12–16 vCPU | 32 ГБ | опционально ≥8 ГБ (ускорение) | 150 ГБ | ~8 ГБ |
| 5 +AI max | 16+ vCPU | 64 ГБ | ОБЯЗАТЕЛЬНО NVIDIA ≥16 ГБ (рекоменд. 24 ГБ) | 250 ГБ | ~25 ГБ |

Детект: железо определяет `install.sh` (nproc, free, nvidia-smi) и пишет в
`.env` (`HW_CPUS`, `HW_RAM_MB`, `HW_GPU_NAME`, `HW_VRAM_MB`); backend-детект
доступности уровней (`services/ai_levels.py`) читает эти переменные плюс
факт наличия скачанных моделей на томах — без зависимости от torch/nvidia-smi
внутри контейнера.

## Последствия
- **Плюс:** переключение уровней — только конфиг/админка; ядро и промпты
  неизменны; min остаётся CPU-only на всех уровнях.
- **Плюс:** thinking-режим гарантированно выключен на всех уровнях
  (Small — по умолчанию, MoE — флагом сервера), формат вывода промптов
  сохраняется.
- **Минус:** Qwen3.5 требует свежий llama.cpp — тег образа
  `ghcr.io/ggml-org/llama.cpp:server[-cuda]` фиксируется по digest в compose;
  риск несовместимости старых GGUF (арх. `qwen35`) закрывается скачиванием
  только официальных квантов.
- **Минус:** GPU-стек (nvidia-container-toolkit, cuDNN 9) — новая
  эксплуатационная зависимость пресетов 4 (опция) и 5 (обязательно).
- **Нейтрально:** 27B dense отклонён для max в пользу MoE 35B-A3B: при
  сравнимом качестве ~3B активных параметров дают кратно большую скорость
  на том же VRAM-бюджете.

## Аддендум

Флаг `LLAMA_ARG_CHAT_TEMPLATE_KWARGS='{"enable_thinking":false}'`, названный
выше для принудительного отключения thinking на уровне `max`, в актуальной
llama.cpp имеет более простой равнозначный эквивалент: `LLAMA_ARG_REASONING=off`
(`--reasoning off`) — по `common/arg.cpp` проекта llama.cpp флаг выставляет
`enable_thinking=false` в шаблоне чата сервера тем же эффектом, без
необходимости передавать сырой JSON `chat_template_kwargs` через переменную
окружения. Реализация (`deploy/docker-compose.yml`) использует
`LLAMA_ARG_REASONING=off`; сама матрица уровней и решение (thinking отключён на
`max`) не меняются.

## Ссылки
- ADR-001 (динамические конференции).
- `backend/core/plugins/{faster_whisper,qwen_local}.py`,
  `backend/services/ai_levels.py`, `config/plugins.yaml` — реализация.
- unsloth.ai/docs/models/qwen3.5 (линейка, режимы, требования памяти),
  huggingface.co/Qwen/Qwen3.5-35B-A3B (enable_thinking, Q4_K_M 9B = 6,22 ГиБ),
  github.com/SYSTRAN/faster-whisper (CUDA/CTranslate2),
  github.com/ggml-org/llama.cpp docs/docker.md (server-cuda).