Контейнер 105 (RAG-service): RAG API (mini-lm)

Подробное описание LXC-контейнера 105 на Proxmox (192.168.1.105): сервис RAG (Retrieval-Augmented Generation) на базе sentence-transformers, API для семантического поиска и эмбеддингов. Домен: mini-lm.katykhin.ru.

Общие сведения

Хостнейм: rag-service
IP: 192.168.1.105/24
ОС: Debian 12 (bookworm)
Ресурсы: 1 core, 1 GB RAM (из архитектуры)
Доступ: с Proxmox — pct exec 105 -- bash или по SSH на 192.168.1.105, если настроен.

Диск контейнера: ~10 GB, занято ~6.8 GB (74%). Основной объём: образ Docker (~4.1 GB), build cache (~2.4 GB, можно освободить docker builder prune), данные приложения в /home/rag-service/data/ (модели ~734 MB, векторы ~2 MB). Следить за местом: при нехватке — почистить build cache и/или ограничить логи Docker (см. TODO).

Доступ и логины

Debian (CT 105): логин root (пароль — в менеджере паролей или как настраивал при установке).
RAG API: http://192.168.1.105:8000 (или через NPM: https://mini-lm.katykhin.ru). Авторизация по заголовку X-API-Key; ключ задаётся в .env (RAG_API_KEY). При RAG_ALLOW_NO_AUTH=true запросы без ключа допускаются (не рекомендуется снаружи).

Сервисы (Docker Compose)

Один проект: /home/rag-service/docker-compose.yml. Образ собирается локально из Dockerfile в том же каталоге. Сеть: rag-service_default (bridge).

Контейнер	Образ	Порты (хост)	Назначение
rag-service	rag-service-rag-service (build)	8000	FastAPI: эмбеддинги, поиск по векторам, health

1. RAG-service (приложение)

Каталог: /home/rag-service/
Compose: docker-compose.yml, переменные из .env (не коммитить). Образ: build: context: ., dockerfile: Dockerfile.

Порты: 8000 (хост) → 8000 (контейнер).
Тома:

./data/models → /app/data/models (кэш моделей sentence-transformers: all-MiniLM-L12-v2, rubert-base-cased и др.).
./data/vectors → /app/data/vectors (файл векторов, например vectors.npz; автосохранение по RAG_AUTOSAVE_INTERVAL).

Переменные окружения (из .env и compose):

Модель: RAG_MODEL (по умолчанию sentence-transformers/all-MiniLM-L12-v2), RAG_CACHE_DIR=/app/data/models.
Векторы: RAG_VECTORS_PATH=/app/data/vectors/vectors.npz, RAG_MAX_EXAMPLES, RAG_SCORE_MULTIPLIER, RAG_BATCH_SIZE, RAG_MIN_TEXT_LENGTH.
API: RAG_API_HOST=0.0.0.0, RAG_API_PORT=8000.
Безопасность: RAG_API_KEY (обязателен для продакшена), RAG_ALLOW_NO_AUTH (по умолчанию false).
Автосохранение: RAG_AUTOSAVE_INTERVAL (секунды).
Логи: LOG_LEVEL (по умолчанию INFO).

Healthcheck: GET /api/v1/health с заголовком X-API-Key (если RAG_API_KEY задан). interval 30s, start_period 60s.

Структура на хосте:

/home/rag-service/data/models/ — подкаталоги вида models--sentence-transformers--all-MiniLM-L12-v2, models--DeepPavlov--rubert-base-cased (скачанные модели). ~734 MB.
/home/rag-service/data/vectors/ — vectors.npz и др. ~2 MB.
/home/rag-service/.env — секреты и настройки. Обязательно бэкапить отдельно, не коммитить.
Исходный код приложения (app/, Dockerfile, pyproject.toml и т.д.) — в том же homedir; при пересборке образа используется этот контекст.

Команды:

cd /home/rag-service && docker compose up -d
docker logs rag-service
docker compose build --no-cache   # пересборка после изменений кода
curl -s -H "X-API-Key: <key>" http://192.168.1.105:8000/api/v1/health

Порты (сводка на хосте)

Порт	Сервис / примечание
8000	RAG API (веб, API)

Логи и ротация

Базовая политика LXC: в контейнере настроен logrotate /etc/logrotate.d/homelab-lxc.conf — 14 дней, 50 MB, 5 архивов (системные логи в /var/log). Подробнее: Logrotate — базовая политика homelab.
RAG-service: логи приложения идут в stdout контейнера (LOG_LEVEL из .env) и попадают в драйвер Docker json-file без ограничения размера и количества файлов.
Системный logrotate в CT — только стандартные правила (apt, dpkg, btmp, wtmp). Отдельных правил для RAG или Docker нет.

Риск: при активной работе логи контейнера могут разрастаться и вместе с образом и build cache заполнить диск (уже 74%). Рекомендуется включить ограничение логов Docker и следить за местом (см. TODO).

Запуск и порядок поднятия

Зануться в каталог: cd /home/rag-service.
При первом запуске или после изменений кода: docker compose build (при необходимости docker compose up -d --build).
Запуск: docker compose up -d.

После смены переменных в .env: docker compose up -d (пересоздание контейнера при необходимости). После смены кода или Dockerfile: docker compose build && docker compose up -d.

Уязвимости и риски

Секреты в .env: RAG_API_KEY и прочие переменные хранятся в /home/rag-service/.env. Файл не должен попадать в публичный репозиторий. Ограничить права (chmod 600) и владельца.
Доступ по порту 8000: API доступен по 192.168.1.105:8000 из LAN. Снаружи доступ только через NPM (https://mini-lm.katykhin.ru). Не пробрасывать 8000 в интернет без защиты (API key обязателен при RAG_ALLOW_NO_AUTH=false).
Логи Docker: Ротация не настроена — возможен рост логов и заполнение диска (см. TODO).
Мало места на диске (74%): Образ ~4 GB, build cache ~2.4 GB. При нехватке места: docker builder prune (освободит кэш сборки), при необходимости увеличить диск контейнера или перенести данные моделей на отдельный том.
Ресурсы: В compose закомментированы deploy.resources (limits/reservations). При 1 GB RAM контейнера возможны OOM при тяжёлых моделях или батчах; при необходимости увеличить память CT или выставить limits в compose.

TODO по контейнеру 105

Базовая политика logrotate: для системных логов настроена (homelab-lxc.conf — 14 дней, 50 MB, 5 архивов). См. Logrotate — базовая политика homelab.
Логи Docker: Включить ограничение размера логов: в docker-compose.yml добавить для сервиса logging: driver: json-file options: max-size: "50m" max-file: "3" или задать default в /etc/docker/daemon.json, перезапустить Docker и контейнер.
Мониторинг диска: Следить за местом (df -h). Уже 74% — при достижении 85%+ выполнить docker builder prune и/или оценить увеличение диска. При желании — оповещение при заполнении выше порога.
Домен и NPM: При необходимости настроить в NPM proxy для mini-lm.katykhin.ru → 192.168.1.105:8000, выпустить SSL. В клиентах использовать https и передавать X-API-Key.
Резервное копирование: Регулярный бэкап критичных данных (оценка размеров на момент документации):
- /home/rag-service/data/models — кэш моделей (sentence-transformers, rubert и др.). ~734 MB. Восстановление: при потере модели скачаются заново при первом запросе, но бэкап ускоряет восстановление.
- /home/rag-service/data/vectors — векторы (vectors.npz). ~2 MB. Важно бэкапить, если векторы содержат уникальные данные и не воссоздаются автоматически.
- /home/rag-service/.env — секреты и настройки. Обязательно; не коммитить.
- /home/rag-service/docker-compose.yml, Dockerfile, при необходимости весь каталог app/ и конфиги (pyproject.toml, env.example и т.д.) — для воспроизведения сборки. Размер кода порядка мегабайт.
Образ Docker бэкапить не обязательно (собирается из Dockerfile); при восстановлении на новом хосте: скопировать данные и код, задать .env, выполнить docker compose build && docker compose up -d.

Связь с другими документами

Архитектура и подключение — таблица контейнеров, домен mini-lm.katykhin.ru, схема сети.
Контейнер 100 (nginx) — NPM, через который проксируется mini-lm.katykhin.ru.

11 KiB Raw Blame History Unescape Escape