Initial commit: RAG Service

README.md

@@ -0,0 +1,92 @@
+# RAG Service
+
+Сервис векторного скоринга текстов с использованием ruBERT.
+
+## Возможности
+
+- **Скоринг** — оценка текстов на основе векторного сходства с примерами
+- **Примеры** — добавление положительных и отрицательных примеров для обучения
+- **Персистентность** — автоматическое сохранение векторов на диск
+- **API авторизация** — защита через API ключ
+
+## Быстрый старт
+
+```bash
+# Клонировать репозиторий
+git clone <repository-url>
+cd rag-service
+
+# Создать .env файл
+cp env.example .env
+
+# Сгенерировать API ключ
+python -c "import secrets; print(secrets.token_urlsafe(32))"
+# Добавить ключ в .env (RAG_API_KEY=...)
+
+# Запустить
+docker-compose up -d --build
+```
+
+## API
+
+### Endpoints
+
+| Метод | URL | Описание | Авторизация |
+|-------|-----|----------|-------------|
+| GET | `/api/v1/health` | Проверка здоровья | Нет |
+| POST | `/api/v1/score` | Расчет скора текста | Да |
+| POST | `/api/v1/examples/positive` | Добавить положительный пример | Да |
+| POST | `/api/v1/examples/negative` | Добавить отрицательный пример | Да |
+| GET | `/api/v1/stats` | Статистика сервиса | Да |
+| POST | `/api/v1/warmup` | Прогрев модели | Да |
+| POST | `/api/v1/save` | Сохранить векторы | Да |
+
+### Авторизация
+
+Передавать API ключ в заголовке `X-API-Key`:
+
+```bash
+curl -H "X-API-Key: YOUR_API_KEY" http://localhost/api/v1/stats
+```
+
+### Примеры запросов
+
+```bash
+# Health check
+curl http://localhost/api/v1/health
+
+# Расчет скора
+curl -X POST http://localhost/api/v1/score \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Текст для оценки"}'
+
+# Добавить положительный пример
+curl -X POST http://localhost/api/v1/examples/positive \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Хороший пост"}'
+```
+
+## Конфигурация
+
+Переменные окружения (см. `env.example`):
+
+| Переменная | Описание | По умолчанию |
+|------------|----------|--------------|
+| `RAG_API_KEY` | API ключ для авторизации | — |
+| `RAG_MODEL` | Модель HuggingFace | `DeepPavlov/rubert-base-cased` |
+| `RAG_MAX_EXAMPLES` | Макс. количество примеров | `10000` |
+| `RAG_AUTOSAVE_INTERVAL` | Интервал автосохранения (сек) | `600` |
+
+## Swagger UI
+
+Документация API доступна по адресу `/docs`.
+
+## Технологии
+
+- Python 3.11
+- FastAPI
+- Transformers (ruBERT)
+- NumPy
+- Docker