vidconf/docs/deploy/llm-setup.md

Настройка локального LLM-сервера (Qwen3.5, профили compose llm/llm-gpu)

Плагин суммаризации qwen_local (backend/core/plugins/qwen_local.py) обращается к OpenAI-совместимому серверу llama.cpp. Модель и параметры — единый источник истины ADR-004 (docs/architecture/adr/004-ai-tier-matrix.md) и константная матрица backend/services/ai_tiers.py. В обычной установке всё описанное ниже делает install.sh (см. docs/deploy/dev-setup.md) — этот раздел актуален для ручного/точечного запуска профиля без инсталлятора.

1. Компоненты

Сервис	Образ	Профиль	Назначение
llm-models-init	busybox	llm/llm-gpu	фиксирует владельца тома llm-models (обходит дефект прав доступа)
llm-model-init	curlimages/curl	llm/llm-gpu	однократное скачивание GGUF-модели и tokenizer.json уровня AI
llm	ghcr.io/ggml-org/llama.cpp:server-b<build>	llm	CPU-инференс (/v1/chat/completions), уровни min/medium
llm-gpu	ghcr.io/ggml-org/llama.cpp:server-cuda-b<build>	llm-gpu	GPU-инференс, уровень max (ADR-004: GPU обязателен)

Файлы:

• deploy/llm/download-model.sh — генерализованный скрипт скачивания (параметризован LLM_MODEL_FILE/LLM_MODEL_URL/LLM_MODEL_MIN_SIZE/ LLM_TOKENIZER_FILE/LLM_TOKENIZER_URL; их пишет install.sh по выбранному пресету — см. install.sh --help).
• deploy/docker-compose.yml — сервисы llm-models-init/llm-model-init/ llm/llm-gpu, volume llm-models, монтирование llm-models:/models/qwen:ro в сервис worker (там же считаются токены чанкером — QwenTokenCounter).

2. Модели по уровням AI (ADR-004)

Уровень	Модель	Квант	Файл (LLM_MODEL_FILE)	Источник GGUF (LLM_MODEL_URL)
min (пресет 3)	Qwen3.5-4B-Instruct	Q4_K_M ≈ 2,6 ГиБ	qwen3.5-4b-instruct-q4_k_m.gguf	unsloth/Qwen3.5-4B-GGUF
medium (пресет 4)	Qwen3.5-9B-Instruct	Q4_K_M ≈ 5,3 ГиБ	qwen3.5-9b-instruct-q4_k_m.gguf	unsloth/Qwen3.5-9B-GGUF
max (пресет 5)	Qwen3.5-35B-A3B-Instruct (MoE)	Q4_K_M ≈ 20,5 ГиБ	qwen3.5-35b-a3b-instruct-q4_k_m.gguf	unsloth/Qwen3.5-35B-A3B-GGUF

tokenizer.json (переименован под LLM_TOKENIZER_FILE — нужен QwenTokenCounter, backend/core/summarization/tokens.py) берётся из официальных репозиториев Qwen/Qwen3.5-<размер> (публичные, без gate; GGUF-репозитории Qwen/…-GGUF — gated, поэтому источник GGUF — публичное зеркало unsloth/…-GGUF, файлы идентичны по содержимому квантизации).

Имена файлов на диске (LLM_MODEL_FILE/LLM_TOKENIZER_FILE) — КОНТРАКТ с детектом доступности уровня AI (backend/services/ai_levels.py через backend/services/ai_tiers.py::TIERS[level].model_files): именно эти пути проверяются на «модель скачана» в админке.

Скачивание идемпотентно (проверка по наличию и минимальному размеру файла, LLM_MODEL_MIN_SIZE) — повторный запуск на уже заполненном томе ничего не перекачивает. Ручной запуск (прогреть volume заранее):

LLM_MODEL_FILE=qwen3.5-4b-instruct-q4_k_m.gguf \
LLM_MODEL_URL=https://huggingface.co/unsloth/Qwen3.5-4B-GGUF/resolve/main/Qwen3.5-4B-Q4_K_M.gguf \
LLM_TOKENIZER_FILE=qwen3.5-4b-instruct.tokenizer.json \
LLM_TOKENIZER_URL=https://huggingface.co/Qwen/Qwen3.5-4B/resolve/main/tokenizer.json \
docker compose -f deploy/docker-compose.yml --env-file .env --profile llm run --rm llm-model-init

3. Запуск профиля

CPU (уровни min/medium, пресеты 3/4):

docker compose -f deploy/docker-compose.yml --env-file .env \
  --profile media --profile transcribe --profile llm up -d

GPU (уровень max, пресет 5 — GPU обязателен):

docker compose -f deploy/docker-compose.yml --env-file .env \
  --profile media --profile transcribe-gpu --profile llm-gpu up -d

Проверка готовности (порт 8080 — llm, 8081 — llm-gpu на хосте; внутри docker-сети оба доступны как llm:8080/llm-gpu:8080, llm-gpu также отвечает под алиасом llm — см. комментарий в deploy/monitoring/prometheus.yml):

curl http://localhost:8080/health
# пока модель грузится:  {"error":{"code":503,"message":"Loading model",...}}
# сервер готов:          {"status":"ok"}

4. Включение провайдера qwen_local

Дефолт репозитория в config/plugins.yaml — summarizer.provider: "null" (безопасно для dev-окружений без LLM-сервера). Уровень min включается по образцу закомментированного примера в config/plugins.yaml; уровни medium/max собираются автоматически из TIERS (backend/services/ai_tiers.py) при выборе уровня AI в админке — руками их прописывать не нужно (см. backend/services/instance_settings.py::_apply_tier_overrides).

После правки config/plugins.yaml (уровень min, ручной dev-сценарий) перезапустить worker:

docker compose -f deploy/docker-compose.yml --env-file .env up -d --force-recreate worker

5. Проверка вручную

1. Поднять профиль llm/llm-gpu, дождаться docker compose ps → healthy.
2. curl http://localhost:8080/health → {"status":"ok"}.
3. Включить уровень AI в админке (или qwen_local в config/plugins.yaml для ручного dev-сценария уровня min).
4. Прогнать пайплайн на тестовом сеансе (см. docs/plugins/summarizer.md) и убедиться, что conference_sessions.summary_data заполняется.

6. Ресурсы, thinking-режим и мониторинг

• Требования CPU/RAM/GPU по пресетам — docs/architecture/adr/004-ai-tier-matrix.md.
• LLAMA_ARG_CTX_SIZE=16384 — с запасом на чанк до 8000 токенов + промпт + вывод (per-tier max_tokens_map/max_tokens_reduce, ADR-004).
• Thinking-режим (семейство Qwen3.5) отключается флагом LLAMA_ARG_REASONING=off (актуальная замена --chat-template-kwargs '{"enable_thinking":false}' из ADR-004 — та же семантика, но без деприкейшен-варнинга в логе на каждый запуск, проверено через find-docs по common/arg.cpp проекта llama.cpp).
• /metrics (LLAMA_ARG_ENDPOINT_METRICS=1) собирает Prometheus, профиль compose monitoring — deploy/monitoring/prometheus.yml, job llm.