130 lines
11 KiB
Markdown
130 lines
11 KiB
Markdown
# Контейнер 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 (из [архитектуры](../architecture/architecture.md))
|
||
- **Доступ:** с 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; при пересборке образа используется этот контекст.
|
||
|
||
**Команды:**
|
||
```bash
|
||
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](../maintenance/logrotate/README.md).
|
||
- **RAG-service:** логи приложения идут в **stdout** контейнера (LOG_LEVEL из .env) и попадают в драйвер Docker **json-file** без ограничения размера и количества файлов.
|
||
- **Системный logrotate** в CT — только стандартные правила (apt, dpkg, btmp, wtmp). Отдельных правил для RAG или Docker нет.
|
||
|
||
**Риск:** при активной работе логи контейнера могут разрастаться и вместе с образом и build cache заполнить диск (уже 74%). Рекомендуется включить ограничение логов Docker и следить за местом (см. TODO).
|
||
|
||
---
|
||
|
||
## Запуск и порядок поднятия
|
||
|
||
1. Зануться в каталог: `cd /home/rag-service`.
|
||
2. При первом запуске или после изменений кода: `docker compose build` (при необходимости `docker compose up -d --build`).
|
||
3. Запуск: `docker compose up -d`.
|
||
|
||
После смены переменных в `.env`: `docker compose up -d` (пересоздание контейнера при необходимости). После смены кода или Dockerfile: `docker compose build && docker compose up -d`.
|
||
|
||
---
|
||
|
||
## Уязвимости и риски
|
||
|
||
1. **Секреты в .env:** RAG_API_KEY и прочие переменные хранятся в `/home/rag-service/.env`. Файл не должен попадать в публичный репозиторий. Ограничить права (chmod 600) и владельца.
|
||
2. **Доступ по порту 8000:** API доступен по 192.168.1.105:8000 из LAN. Снаружи доступ только через NPM (https://mini-lm.katykhin.ru). Не пробрасывать 8000 в интернет без защиты (API key обязателен при RAG_ALLOW_NO_AUTH=false).
|
||
3. **Логи Docker:** Ротация не настроена — возможен рост логов и заполнение диска (см. TODO).
|
||
4. **Мало места на диске (74%):** Образ ~4 GB, build cache ~2.4 GB. При нехватке места: `docker builder prune` (освободит кэш сборки), при необходимости увеличить диск контейнера или перенести данные моделей на отдельный том.
|
||
5. **Ресурсы:** В compose закомментированы deploy.resources (limits/reservations). При 1 GB RAM контейнера возможны OOM при тяжёлых моделях или батчах; при необходимости увеличить память CT или выставить limits в compose.
|
||
|
||
---
|
||
|
||
## TODO по контейнеру 105
|
||
|
||
- [x] **Базовая политика logrotate:** для системных логов настроена (homelab-lxc.conf — 14 дней, 50 MB, 5 архивов). См. [Logrotate — базовая политика homelab](../maintenance/logrotate/README.md).
|
||
- [ ] **Логи 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`.
|
||
|
||
---
|
||
|
||
## Связь с другими документами
|
||
|
||
- [Архитектура и подключение](../architecture/architecture.md) — таблица контейнеров, домен mini-lm.katykhin.ru, схема сети.
|
||
- [Контейнер 100 (nginx)](container-100.md) — NPM, через который проксируется mini-lm.katykhin.ru.
|