🚀 TurboHackathon RAG Chatbot Service

Retrieval‑Augmented Generation (RAG) сервис, который превращает ваши документы в живой, говорящий источник знаний. Build once — chat everywhere.

---

О проекте

TurboHackathon RAG Chatbot Service — это микросервис, который позволяет за минуты развернуть интеллектуального ассистента, способного отвечать на вопросы на естественном языке, опираясь на ваши внутренние документы и базы знаний. Сервис разработан в рамках Turbo Hackathon 2025 и оптимизирован для быстрого прототипирования и деплоя в облачной или on‑prem среде.

Ключевые сценарии использования

• 📚 Корпоративная база знаний — чат‑бот, который знает ответы на вопросы сотрудников по внутренним регламентам и политикам.
• 🛠 Поддержка клиентов — мгновенные ответы на большинство FAQ, с ссылками на релевантные документы.
• 🏢 Навигация по проектной документации — поиск точных фрагментов ГОСТ/ISO, тех‑заданий, контрактов.

---

✨ Возможности

	Описание
⚡ Мгновенный онбординг	Загрузите PDF/Word/HTML/справку сайта — и чат‑бот сразу готов к диалогу
🔍 Точная выдача	Использует hybrid‑search (BM25 + векторный pgvector) для поиска контекста
🧠 Ссылки на источники	Каждое сообщение содержит цитаты с координатами в исходном документе
🌐 REST + WebSocket API	Интегрируйте в телеграм‑бота, мобильное приложение или Slack
🐳 Docker‑first	Один docker compose up — и сервис запущен локально
🔐 RBAC и токены	Ограничьте доступ к датасетам по ролям и API‑ключам
🌍 Мультиязычность	Русский / English; автоматическое обнаружение языка запроса

---

🏗️ Технологический стек

Уровень	Технологии
Язык	Python 3.11
Фреймворк	FastAPI + Uvicorn
RAG ядро	LangChain / LlamaIndex
LLM провайдеры	OpenAI (GPT‑4o) · Ollama (Mistral 7B) · Gemini‑Pro
Хранилище эмбеддингов	PostgreSQL + pgvector (по умолчанию) · ChromaDB (опция)
Очереди	Redis RQ (фоновая обработка)
Обёртка	Docker & Docker Compose
CI/CD	GitHub Actions → Docker Hub → Fly.io/K8s

---

⚙️ Быстрый старт

### Prerequisites

• Docker ≥ 24
• Docker Compose v2
• Ключ OpenAI или локальный Ollama с моделью mistral / llama3.

# 1. Клонируем репозиторий
$ git clone https://github.com/screengreen/rag_chatbot_service.git
$ cd rag_chatbot_service

# 2. Копируем пример переменных окружения
$ cp .env.example .env
#   ⚙️  отредактируйте OPENAI_API_KEY или укажите USE_OLLAMA=true

# 3. Запускаем
$ docker compose up --build

# 4. Открываем
#   API:      http://localhost:8000/docs  (Swagger UI)
#   Frontend: http://localhost:3000        (Streamlit)

TIP: для продакшн‑запуска используйте файл docker-compose.prod.yml и переменную ENV=production.

---

🗂️ Структура репозитория

rag_chatbot_service/
├── rag/                 # Python‑пакет: логика RAG, загрузчики, векторизация
│   ├── api/             # FastAPI endpoints & схемы Pydantic
│   ├── ingestion/       # Скрипты для заливки данных (CLI)
│   ├── llm/             # Адаптеры к OpenAI, Ollama, Gemini
│   └── utils/           # Вспомогательные функции
├── frontend/            # Streamlit UI
├── tests/               # pytest
├── docker/              # Dockerfiles, entrypoint‑скрипты
├── scripts/             # Dev‑helpers (format, lint, benchmark)
├── .env.example         # Шаблон переменных окружения
└── docker‑compose.yml   # Быстрый запуск

---

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

Переменная	По умолчанию	Назначение
OPENAI_API_KEY	―	Ключ OpenAI для GPT‑4/3.5
USE_OLLAMA	false	Использовать ли локальный Ollama
DATABASE_URL	postgres://rag:rag@db:5432/rag	Строка подключения к Postgres + pgvector
EMBEDDING_MODEL	text-embedding-3-small	Модель эмбеддингов
CHUNK_SIZE	512	Размер чанка токенов при индексации

Полный список переменных смотрите в .env.example.

---

🛠️ Основные команды для разработчика

Команда	Действие
make dev	Lint + tests + запуск hot‑reload сервера
make ingest path=/docs	Индексировать все документы из папки docs
make benchmark question="…"	Измерить время ответа и качество извлечения

---

🏛️ Архитектура (Mermaid)

flowchart TD
    subgraph Ingestion
        A[Документы\n(PDF/Docx/HTML)] --> B(Loader)
        B --> C(Embedder)
        C --> D[(Vector DB)]
    end
    subgraph Serving
        U[Пользователь] -->|Запрос| R(API Gateway)
        R --> Q(Retriever)
        Q --> D
        Q --> L(LLM)
        L -->|Ответ + ссылки| U
    end

Loading

---

🛡️ Лицензия

Проект распространяется под лицензией MIT. См. файл LICENSE для подробностей.

---

👥 Команда

Участник	Роль	Контакты
Andrey Sukhov	Team Lead / ML Engineer	GitHub · Telegram: @screengreen
Daria Denisova	Data Scientist	GitHub: … · Telegram: …
Anton Pembek	Backend Engineer	GitHub: … · Telegram: …
Artemiy Tereshchenko	DevOps Engineer	GitHub: … · Telegram: …

---

English version

About

TurboHackathon RAG Chatbot Service is a plug‑and‑play micro‑service that turns your private documents into a chat companion powered by Retrieval‑Augmented Generation. It ships with a FastAPI backend, optional Streamlit UI, Docker‑first deployment and multiple LLM back‑ends (OpenAI, Gemini, Ollama).

Features

• Hybrid retrieval (BM25 + vectors) for high‑precision context lookup
• Source citations in every answer
• REST & WebSocket API ready for any client (web, Slack, Telegram)
• Instant Docker deployment
• Role‑based access control for datasets and tokens
• Multilingual interface (RU/EN)

Quick Start

docker compose up --build
# Swagger UI → http://localhost:8000/docs

For detailed instructions, switch back to the Russian section above.

Happy hacking!