Установка LLM-сервера¶

LLM-инфраструктура Staffcop состоит из LLM-сервера и промежуточного сервиса LLM-прокси.

LLM-сервер запускает языковую модель и обрабатывает сообщения;
LLM-прокси обеспечивает взаимодействие между Staffcop Enterprise и LLM-сервером;
чат Semantic преобразует вопрос пользователя в запрос к полям метаданных, возвращает список подходящих событий и позволяет перейти к исходному событию в Staffcop.

В состав LLM-сервера входят:

Ollama — запуск языковых моделей;
Grafana — визуализация данных мониторинга;
Prometheus — сбор метрик;
Loki — сбор и хранение логов.

LLM-прокси и чат устанавливаются и настраиваются отдельно:

Его параметры подключения указываются в конфигурации Staffcop.

Сервер разворачивается на вашем сервере или рабочей станции. Данные не покидают ваш сервер: модели работают локально, внешние API не используются.

Начало работы ¶

Требования ¶

Программное обеспечение

Ubuntu Server;
Docker и Docker Compose. Если Docker не установлен: инструкция по установке.

Оборудование

См. требования к Staffcop Semantic

Права доступа к Docker ¶

По умолчанию скрипты запускаются через sudo, так как пользователь не состоит в группе docker. Чтобы снять это требование, добавьте пользователя в группу:

sudo usermod -aG docker $USER
newgrp docker

После этого команды можно запускать без sudo. Дальнейшая инструкция использует sudo. Если группа добавлена — игнорируйте.

Установка и первый запуск ¶

Скачайте скрипт обновления:

curl -O https://distr.staffcop.su/llm-runtime/llm_update.sh
chmod +x llm_update.sh

Запустите скрипт. Он скачает репозиторий и подготовит файлы:
```
sudo REPO_URL=https://distr.staffcop.su/llm-runtime ./llm_update.sh
```
Создайте файл конфигурации .env из шаблона:
```
sudo cp .env.default .env
```
Проверьте и установите переменные в .env. Параметры файла описаны в разделе Конфигурация LLM-сервера.
Запустите контейнеры:

sudo bash scripts/llm_start.sh

Загрузите модель:

Предупреждение

Без этого шага модель не загрузится, API будет отвечать ошибкой.
# Зайдите в контейнер Ollama
sudo docker compose -f docker-compose.ollama.yaml exec ollama bash

# Создайте модель из modelfile
ollama create qwen3:14b -f /modelfiles/qwen3_14b

# Выйдите из контейнера
exit
Список доступных modelfiles находится в каталоге ollama/modelfiles/.

После сборки сервисы доступны по адресам:

Ollama — http://localhost:11434
Grafana — http://localhost/grafana

Конфигурация LLM-сервера ¶

Параметры LLM-сервера хранятся в файле .env, который создается из шаблона .env.default.

Переменная	По умолчанию	Описание
`NVIDIA_GPU`	`0`	`1` — использовать GPU, `0` — только CPU
`REPO_URL`	`https://distr.staffcop.su/llm-runtime`	URL Git-репозитория для `llm_update.sh`
`GF_SECURITY_ADMIN_USER`	`admin`	Логин Grafana
`GF_SECURITY_ADMIN_PASSWORD`	`admin`	Пароль Grafana
`NGINX_SERVER_NAME`	`localhost`	Доменное имя для Nginx/SSL
`OLLAMA_NGINX_PORT`	`11434`	Внешний порт Ollama через Nginx
`GRAFANA_NGINX_PORT`	`80`	Внешний порт Grafana (HTTP) через Nginx
`GRAFANA_NGINX_PORT_SSL`	`443`	Внешний порт Grafana (HTTPS) через Nginx
`SSL_CERT_PATH`	`/etc/ssl/certs/llm/cert`	Путь к SSL-сертификату на хосте
`SSL_CERT_KEY_PATH`	`/etc/ssl/certs/llm/key`	Путь к SSL-ключу на хосте

Чтобы применить изменения в .env, перезапустите скрипт:

sudo bash scripts/llm_stop.sh && sudo bash scripts/llm_start.sh

Проверка работоспособности ¶

Список загруженных моделей Ollama:

curl http://localhost:11434/api/tags

Проверить ответ модели:

curl -X POST http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3:14b",
    "messages": [{"role": "user", "content": "Привет, как дела?"}],
    "reasoning_effort": "medium"
  }'

Статус сервера Grafana:

curl http://localhost:80/grafana/api/health

LLM-прокси — промежуточный сервис между Staffcop Enterprise и LLM-сервером. Он принимает запросы Staffcop, проверяет ключ доступа и передает сообщения на LLM-сервер. Конфигурационный файл LLM-прокси находится на LLM-сервере в /etc/llm-proxy/config. Изменения применяются после перезапуска LLM-прокси.

Основные параметры:

Параметр	По умолчанию	Описание
`HOST`	—	Хост, на котором работает LLM-прокси
`PORT`	—	Порт LLM-прокси
`USE_HTTPS`	—	Использовать HTTPS
`SSL_CERT_PATH`	—	Путь к SSL-сертификату
`SSL_KEY_PATH`	—	Путь к SSL-ключу
`LOG_LEVEL`	—	Уровень логирования: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. Логи записываются в `/var/log/llm-proxy/`.
`LLM_PROXY_API_KEY`	—	API-ключ для доступа к LLM-прокси. Этот же ключ указывается в Staffcop в параметре `LLM_PROXY_KEY` Внимание. Не рекомендуется использовать ключ по умолчанию. Чтобы его сменить, выполните команду: `llm-proxy set-api-key`

Дополнительные параметры обычно изменять не требуется:

Параметр	По умолчанию	Описание
`LLM_MAX_CONCURRENCY`	`10`	Максимальное количество одновременных запросов к LLM
`LLM_TIMEOUT_SECONDS`	`300`	Таймаут одного запроса к LLM, в секундах
`TASK_TTL_SECONDS`	`3600`	Время хранения результатов батча, в секундах
`CLEANUP_INTERVAL_SECONDS`	`60`	Интервал удаления просроченных батчей, в секундах
`DEBUG`	`False`	При значении `True` документация API доступна по адресу `/api/docs`

Управление LLM-прокси ¶

Запустить сервис:

llm-proxy start

Остановить сервис:

llm-proxy stop

Перезапустить сервис:

llm-proxy restart

Опасно

При перезапуске LLL-прокси данные, находящиеся в обработке, будут утеряны.

Проверить состояние:

llm-proxy status

Запустить сервис в текущем терминале без systemd, например, для отладки:

llm-proxy run

Изменение ключа по умолчанию:

llm-proxy set-api-key

Решение проблем ¶

Контейнер Ollama не запускается ¶

Посмотреть логи контейнера:

sudo docker compose -f docker-compose.ollama.yaml logs ollama

Проверить состояние контейнеров:

sudo docker ps -a | grep llm

Что дальше ¶

После установки и настройки сервера установите и подключите LLM-прокси к Staffcop:

Последнее обновление: 12.11.26