Accent / Администратору

Руководство администратора

Установка на CPU и GPU, контракт API, подключение к Monolit, резервное копирование, мониторинг.

Accent

Версия Next

Введение

Accent — on-prem сервис AI-триажа уязвимостей. Он поставляется тремя контейнерами (API, модель, брокер задач) и поднимается Docker Compose. Это руководство описывает установку, профили мощности, обновление, наблюдение и типичные отказы.

До ребрендинга сервис назывался Triage LLM (в файлах модели — AI-TRIAGE): это то же изделие. Каталог установки по умолчанию — accent/, проект Compose — sdlplatform_accent. Установки, сделанные под прежним именем (triage_llm/.env.triage_llm, проект sdlplatform_triage_llm), скрипт установки распознаёт сам и обновляет под прежними именами — переносить их не нужно.

Инструкция по установке

Требования к системе

Операционная система: Linux (Ubuntu 24.04.1 LTS или выше).
ПО: Docker Engine 20.10 или новее, Docker Compose v2.
Сеть: доступ к registry поставщика на время установки и обновления.
Набор инструкций процессора: AVX2 и FMA. На виртуальной машине тип процессора задаётся как x86-64-v3 или выше, иначе гость их не увидит. Проверка внутри гостя:

grep -m1 flags /proc/cpuinfo | grep -o avx2

CPU

Режим	Процессор	Память	Свободно на диске	Ориентир `/analyze`
Минимум (`cpu4`)	4 vCPU	16 ГиБ	40 ГиБ	2–4 мин и дольше
Практический (`cpu8`)	8 vCPU	16 ГиБ	40 ГиБ	1–2 мин
Рекомендуемый (`cpu16`)	12–16 vCPU	16–32 ГиБ	60 ГиБ	45–60 с

На хостах с 16 ГиБ ОЗУ обязателен --cache-ram 0 у модели (так настроено в профилях). Иначе кеш промпта уходит в swap, и запросы зависают.

Не ставьте:

меньше 4 vCPU;
меньше 12–14 ГиБ ОЗУ под полную модель Q8;
несколько параллельных слотов модели на 4 CPU / 16 ГиБ;
несколько воркеров API при одном слоте модели на минимуме.

GPU (опционально)

Скрипт install.sh раскатывает только CPU. GPU собирается отдельным составом compose.

Режим	Свободная VRAM	Хост	Ориентир
Минимум	≥ 16 ГиБ, CUDA	4 vCPU / 16 ГиБ	15–40 с
Практический	≥ 24 ГиБ	8 vCPU / 32 ГиБ	8–25 с

Нужны драйвер NVIDIA и NVIDIA Container Toolkit. На 16 ГиБ держите один слот модели и контекст не больше 8192.

Цифры времени — ориентир, не SLA. При очереди хвост длиннее.

Установка в Docker (Docker Compose)

Установку и обновление выполняет один скрипт. Запускайте его из каталога, в котором должен появиться accent/:

curl -fsSL -o install.sh https://sdlplatform.ru/accent/install.sh && bash install.sh

Без меню:

REGISTRY_USER=... REGISTRY_PASSWORD=... \
  bash install.sh --tag 2.0.2 --profile cpu16 --port 13001 --yes

Параметр	Назначение
`--tag`	Версия образов в registry, например `2.0.2`
`--profile`	`cpu4`, `cpu8` или `cpu16` (по умолчанию — по числу ядер хоста: от 12 — `cpu16`, от 8 — `cpu8`, иначе `cpu4`)
`--port`	Порт хоста на API (по умолчанию `13001`)
`--registry`	Хост registry (по умолчанию `registry.sdlplatform.ru`)
`--dir`	Каталог установки (по умолчанию `accent`)
`--yes`	Не задавать вопросы
`--skip-host-check`	Пропустить проверку CPU / ОЗУ / диска / AVX2

Переменные поставки: ACCENT_BASE_URL (по умолчанию https://sdlplatform.ru/accent), REGISTRY_USER и REGISTRY_PASSWORD для входа в registry без приглашения (с --yes обязательны, если docker login не выполнен заранее).

Скрипт различает установку и обновление по файлу accent/.env.accent (у установок до ребрендинга — triage_llm/.env.triage_llm).

При установке скрипт:

Проверяет Docker и Docker Compose. Если Docker не найден — предлагает поставить его с get.docker.com.
Запрашивает адрес registry и выполняет docker login.
Проверяет, что тег api:<версия> есть в registry (до трёх попыток ввода).
Спрашивает профиль CPU и порт API.
Проверяет хост: CPU, ОЗУ, диск и наборы инструкций AVX2/FMA (проверка встроена в скрипт, пороги зависят от профиля). При отказе спрашивает, продолжать ли; с --yes останавливается.
Скачивает docker-compose.yml версии TAG с https://sdlplatform.ru/accent/<TAG>/. Если версионного файла нет, берёт последний опубликованный.
Пишет accent/.env.accent (профиль CPU, ALLOW_SYNC_ANALYZE=0, Redis).
Загружает образы и поднимает проект sdlplatform_accent.

Копия install.sh сохраняется в accent/.

При установке опечатка в TAG остановит скрипт только если манифеста нет в registry. Сверяйте версию с поставщиком до запуска.

Скрипт вызывает docker через sudo. Учётная запись должна иметь право повышения привилегий.

Сервисы поставки:

api — HTTP API, воркеры задач, разбор ответа модели (порт хоста → 13001);
llama — локальный инференс (внутри сети, с хоста по умолчанию проброшен 13080);
redis — очередь задач (внутри сети, с хоста по умолчанию проброшен 6379).

Порты модели и Redis наружу не публикуйте. Снаружи нужен только API, лучше через внутренний прокси.

После установки:

API:  http://<host>:13001
Прод-контракт: POST /analyze/async | POST /analyze/sarif/async + GET /jobs/{id}

Проверка:

curl -sS "http://127.0.0.1:13001/health"

Совместная установка с Monolit

Скрипт https://sdlplatform.ru/sdlplatform/install.sh предлагает меню продуктов: Monolit и Accent. Для пункта «Accent» он скачивает и запускает тот же https://sdlplatform.ru/accent/install.sh. Номера вводятся через пробел, если нужны оба. Accent поднимается отдельным составом и подключается в Monolit как AI-интеграция по URL http://<хост>:13001.

Обновление Accent

Запускайте скрипт из того же каталога, что и установку — из родительского по отношению к accent/:

cd /путь/где/лежит/accent
bash accent/install.sh

Скрипт находит .env.accent, показывает текущую версию и спрашивает новую. Пустой ввод оставляет версию и перекачивает образы.

Если запустить скрипт изнутри accent/, он не увидит ожидаемый путь к .env так, как при штатном запуске из родителя. Обновляйте из каталога установки.

При смене TAG прежний .env.accent копируется в .env.accent.bak.<метка>; остальные значения файла не меняются. Compose скачивается заново; при ошибке скачивания возвращается предыдущий файл.

У установок до ребрендинга скрипт при первом обновлении переключает REGISTRY с проекта triage_llm на accent (все версии образов перенесены туда). Учётная запись registry выдаётся на проект: если docker login к новому проекту не проходит, запросите учётные данные у поставщика.

Смена профиля CPU при обновлении: bash install.sh --profile cpu8 — файл .env.accent перегенерируется под новый профиль, прежний остаётся в .bak. Если в файле нет PROFILE (установка старым скриптом), профиль будет предложен при первом обновлении.

Неинтерактивно:

bash install.sh --tag 2.0.2 --yes

Профили CPU

Профиль	Когда выбирать
`cpu4`	Стенд, 4 ядра. Долго, один слот, очередь задач 32
`cpu8`	Рабочий минимум
`cpu16`	Продакшен на CPU

Правило: число слотов модели = число воркеров задач = лимит одновременного инференса. На CPU это единица. Не поднимайте параллелизм модели на четырёх ядрах.

Число потоков модели задают переменные LLAMA_THREADS и LLAMA_THREADS_BATCH в файле профиля: 4 в cpu4, 8 в cpu8, 12 в cpu16. Если ядер больше, чем задано в профиле, приведите оба значения к числу ядер и перезапустите сервис:

nproc
sed -i 's/^LLAMA_THREADS=.*/LLAMA_THREADS=12/; s/^LLAMA_THREADS_BATCH=.*/LLAMA_THREADS_BATCH=12/' profiles/cpu16.env
docker compose --env-file profiles/cpu16.env -p triage-prod up -d --force-recreate

Установка на GPU

Положите полный файл весов Q8 (~7.6–8 ГиБ) на хост. Обрезанный файл (~1.8 ГиБ) модель не загрузит.

ls -lh model/ai-triage.Q8_0.gguf

docker compose \
  -f docker-compose.yml \
  -f docker-compose.override.yml \
  -f docker-compose.gpu.yml \
  --env-file profiles/gpu.env \
  -p triage-gpu up -d

Проверьте карту:

docker run --rm --gpus '"device=0"' nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

На 16 ГиБ VRAM оставьте один слот. Несколько слотов — от 24 ГиБ.

Проверка хоста без установки

MIN_CPUS=8 MIN_RAM_GIB=16 MIN_DISK_GIB=60 \
  ./scripts/check_host_requirements.sh

Пороги по умолчанию: 4 CPU, 16 ГиБ ОЗУ, 40 ГиБ диска (смотрит /var/lib/docker или /). Скрипт установки для cpu16 поднимает минимум до 8 CPU и 60 ГиБ диска.

Состав и сеть

Наружу публикуйте только порт API. Модель и Redis оставьте во внутренней сети compose; если поставка пробросила 13080 и 6379 на хост, закройте их межсетевым экраном.

API в поставке без аутентификации. Доступ должен быть только из контура Monolit, CI и рабочих мест аналитиков.

Переменные окружения

Файл установки: accent/.env.accent.

Поставка

Переменная	Смысл
`TAG`	Версия образов
`REGISTRY`	Префикс образов, например `registry.sdlplatform.ru/accent/` (до ребрендинга — `…/triage_llm/`; скрипт обновления переключает сам)
`PORT`	Порт хоста → API
`PROFILE`	`cpu4` / `cpu8` / `cpu16`

Контракт API

Переменная	Значение в поставке	Смысл
`ALLOW_SYNC_ANALYZE`	`0`	`1` включает синхронные `/analyze` и `/analyze/sarif` (только отладка)
`SARIF_MAX_RESULTS`	`20`	Потолок страницы SARIF
`JOB_BACKEND`	`redis`	Без Redis (`memory`) очередь живёт только в процессе API
`REDIS_URL`	`redis://redis:6379/0`	Брокер
`JOB_QUEUE_MAX`	`64` (на `cpu4` — 32)	Максимум задач в работе и в очереди
`JOB_TTL_SECONDS`	`7200`	Срок хранения задачи
`JOB_WORKERS`	`1` на CPU	Должно совпадать со слотами модели

Инференс

Переменная	Смысл
`LLAMA_API_URL`	Адрес chat completions модели (по умолчанию внутри compose)
`LLAMA_TIMEOUT`	Таймаут чтения ответа модели (на CPU — 900 с)
`LLAMA_CONNECT_TIMEOUT`	Короткий таймаут соединения; если модели нет, слот не держится минутами
`LLAMA_MAX_TOKENS`	Длина ответа (CPU — 512, GPU — 768)
`PROMPT_FEW_SHOT`	`none` на CPU, `compact` на GPU
`ASCII_REPROMPT_THRESHOLD`	Порог доли латиницы для повторного запроса; `1.0` — выключено
`MAX_CONCURRENT_INFERENCE`	Слоты инференса, равны `--parallel` модели
`INFERENCE_QUEUE_MAX`	Сколько запросов ждут слот
`INFERENCE_QUEUE_TIMEOUT`	`0` — ждать слот без ложного 503 по времени
`RETRY_AFTER_SECONDS`	Минимум для заголовка `Retry-After`
`CIRCUIT_FAILURE_THRESHOLD` / `CIRCUIT_OPEN_SECONDS`	После серии ошибок соединения с моделью — быстрый 503 и пауза
`UVICORN_WORKERS`	`1` при одном слоте модели
`LOAD_UNIXCODER`	`0` — не грузить дополнительную модель уверенности (~2 ГиБ)

После правки .env.accent:

cd accent
sudo docker compose --env-file .env.accent -p sdlplatform_accent up -d

REST API: служебные запросы

База: http://<хост>:13001. Пользовательский контракт — в Руководстве пользователя.

Проверка состояния

curl -sS "http://<хост>:13001/health"

Ответ всегда 200 и "status": "ok", пока процесс API жив. Нагрузка и недоступность модели не валят пробу — смотрите вложенные поля.

Узел	На что смотреть
`inference.in_use` / `waiters`	Слот модели и очередь на слот
`jobs.queued` / `jobs.running`	Принятые асинхронные задачи
`jobs.backend`	`redis` или `memory`
`llama.circuit`	Разомкнута ли защита от недоступной модели
`metrics.http_503_ratio`	Доля отказов по перегрузке
`allow_sync_analyze`	Включён ли опасный sync-режим
`sarif_max_results`	Потолок страницы

Эндпоинт подходит для пробы Kubernetes и внешнего мониторинга. Формата Prometheus сервис не отдаёт: загрузку CPU, ОЗУ и диска снимайте с хоста (cAdvisor, node_exporter).

Очередь и 503

Ситуация	Ответ
Слот свободен	Задача идёт в модель
Слоты заняты, в очереди есть место	Задача ждёт
Очередь полна	503 + `Retry-After`, работа не принята
Модель недоступна, защита разомкнута	503 + `Retry-After`, слот не удерживается
Модель сама вернула 503	Пробрасывается клиенту

Клиенту: прочитать Retry-After, подождать, повторить то же тело. Шторм повторов ухудшает очередь.

Подключение к Monolit

Убедитесь, что GET http://<хост-accent>:13001/health доступен с хоста Monolit.
В Monolit: Инструменты → Интеграция AI — укажите URL Accent.
Привяжите интеграцию к приложениям.

Рекомендуемый канал платформы — страницы POST /analyze/sarif/async и опрос GET /jobs/{id}. Синхронный POST /analyze в поставке Accent закрыт: при старом клиенте платформы включение sync на проде не чинит обрывы на балансировщике, а возвращает длинные запросы.

Резервное копирование и восстановление

Accent не хранит реестр уязвимостей. Сохранять нужно конфигурацию поставки. Вердикты должны жить у клиента (Monolit, своя БД).

Что копировать

accent/.env.accent
accent/docker-compose.yml
копию install.sh, если меняли вручную

tar -czvf /backups/accent_config_$(date +%F).tar.gz \
  /путь/к/accent/.env.accent \
  /путь/к/accent/docker-compose.yml

Redis в поставке запущен без записи на диск: перезапуск брокера теряет незавершённые задачи. Это ожидаемо. Не используйте Redis Accent как архив.

Восстановление конфигурации

Верните файлы в каталог установки и поднимите состав:

cd /путь/где/лежит/accent
sudo docker compose --env-file accent/.env.accent \
  -p sdlplatform_accent -f accent/docker-compose.yml up -d

Либо снова запустите install.sh с тем же TAG.

Мониторинг и диагностика

Журналы

cd /путь/где/лежит/accent
sudo docker compose --env-file accent/.env.accent \
  -p sdlplatform_accent logs -f

По сервисам:

sudo docker compose --env-file accent/.env.accent \
  -p sdlplatform_accent logs -f api
sudo docker compose --env-file accent/.env.accent \
  -p sdlplatform_accent logs -f llama
sudo docker compose --env-file accent/.env.accent \
  -p sdlplatform_accent logs -f redis

В журнале API ищите: 503 queue_full, 503 queue_timeout, 503 circuit_open, slot_wait_s=, job_retry.

Сбор журналов для поддержки

sudo docker compose --env-file accent/.env.accent \
  -p sdlplatform_accent logs --tail=2000 > accent-all.log 2>&1

Имена контейнеров зависят от имени проекта. Список: docker ps --format '{{.Names}}'.

Типичные отказы

Симптом	Что проверить
Контейнер `llama` не становится healthy	Объём файла GGUF, ОЗУ, `docker logs llama`, не обрезан ли вес
API не стартует	Зависимость от healthy `llama` и `redis`; `docker compose ps`
Клиенты получают 403 на `/analyze`	Штатно. Нужен async-контракт
Массовые 503	`JOB_QUEUE_MAX`, `inference.waiters`, не бьёт ли клиент пачкой sync/ретраев
Задачи пропадают после рестарта API	Должен быть `JOB_BACKEND=redis`; при `memory` очередь в RAM
404 на старой задаче	Истёк `JOB_TTL_SECONDS`
Swap и таймауты на 16 ГиБ	В команде llama должен быть `--cache-ram 0`
OOM на GPU	Слишком большой `--parallel` / `--ctx-size` для карты

Обновления и патчи

Обновление образов — через install.sh, см. Обновление Accent. Сборки на площадке заказчика нет.

Перезапуск без смены версии:

cd /путь/где/лежит/accent
sudo docker compose --env-file accent/.env.accent \
  -p sdlplatform_accent restart api

После обновления:

sudo docker compose --env-file accent/.env.accent \
  -p sdlplatform_accent ps
curl -sS "http://127.0.0.1:13001/health"

Обновляйте пакеты хоста:

sudo apt update && sudo apt upgrade -y

Безопасность

Откройте снаружи только SSH и, если нужно, порт API во внутренней сети. Порты модели и Redis закройте.
Не включайте ALLOW_SYNC_ANALYZE на контуре за балансировщиком с коротким таймаутом.
Не публикуйте /docs и API в интернет без дополнительного контроля доступа (SSO-прокси, сеть, VPN).
Исходный код находок попадает в журнал только если вы сами пишете его в отладке; не включайте подробный дамп тел запросов на проде.

Пример UFW:

sudo ufw allow OpenSSH
sudo ufw allow from <сеть-монолита> to any port 13001 proto tcp
sudo ufw enable

Часто задаваемые вопросы

Почему установка остановилась на проверке хоста?

Можно ли поднять несколько реплик API?

Как ускорить разбор?

Нужен ли интернет после установки?

Техническая поддержка

В случае проблем напишите в поддержку: support@cybear.ru. Приложите версию из .env.accent (TAG, PROFILE), вывод /health и журналы api / llama.

Руководство администратора

Введение

Инструкция по установке

Требования к системе

CPU

GPU (опционально)

Установка в Docker (Docker Compose)

Совместная установка с Monolit

Обновление Accent

Профили CPU

Установка на GPU

Проверка хоста без установки

Состав и сеть

Переменные окружения

Поставка

Контракт API

Инференс

REST API: служебные запросы

Проверка состояния

Очередь и 503

Подключение к Monolit

Резервное копирование и восстановление

Что копировать

Восстановление конфигурации

Мониторинг и диагностика

Журналы

Сбор журналов для поддержки

Типичные отказы

Обновления и патчи

Безопасность

Часто задаваемые вопросы

Техническая поддержка

Другие документы Accent

Руководство пользователя

Описание функциональных возможностей

Release notes

Не нашли ответ в документе?

Инструкция по установке

Требования к системе​

CPU​

GPU (опционально)​

Установка в Docker (Docker Compose)​

Совместная установка с Monolit​

Обновление Accent​

Профили CPU​

Установка на GPU​

Проверка хоста без установки​

Состав и сеть

Переменные окружения

Поставка​

Контракт API​

Инференс​

REST API: служебные запросы

Проверка состояния​

Очередь и 503​

Подключение к Monolit​

Резервное копирование и восстановление

Что копировать​

Восстановление конфигурации​

Мониторинг и диагностика

Журналы​

Сбор журналов для поддержки​

Типичные отказы​

Обновления и патчи

Безопасность

Часто задаваемые вопросы

Техническая поддержка

Другие документы Accent

Руководство пользователя

Описание функциональных возможностей

Release notes

Не нашли ответ в документе?

Требования к системе

CPU

GPU (опционально)

Установка в Docker (Docker Compose)

Совместная установка с Monolit

Обновление Accent

Профили CPU

Установка на GPU

Проверка хоста без установки

Поставка

Контракт API

Инференс

Проверка состояния

Очередь и 503

Подключение к Monolit

Что копировать

Восстановление конфигурации

Журналы

Сбор журналов для поддержки

Типичные отказы