🔍 HabrRAG: Retrieval-Augmented Generation API

HabrRAG — это асинхронный REST API для Retrieval-Augmented Generation (RAG), использующий LangGraph для управления пайплайном.

🚀 Основные возможности

• ✅ FastAPI - асинхронный веб-фреймворк
• ✅ LangGraph - граф-ориентированный RAG пайплайн
• ✅ Pydantic - типизация и валидация данных
• ✅ Qdrant + BM25 - гибридный поиск документов
• ✅ Cross-Encoder - переранжирование результатов
• ✅ ChatOpenAI - интеграция с LLM
• ✅ Асинхронность - полная поддержка async/await
• ✅ Кэширование - сохранение ответов в PostgreSQL

📋 Структура проекта

HabrRAG/
├── main.py                   # FastAPI приложение
├── ui/
│   ├── chainlit_app.py       # Chainlit чат-интерфейс
│   └── chainlit.md           # Документация Chainlit
├── src/
│   ├── logger.py             # Логирование в консоль
│   ├── schemas.py            # Pydantic модели (AppState, RAGRequest, RAGResponse)
│   ├── settings.py           # Конфигурация из переменных окружения
│   ├── caching.py            # Кэширование ответов в PostgreSQL
│   ├── build_sources.py      # Построение источников данных
│   ├── lifespan.py           # Управление жизненным циклом приложения
│   ├── summarization.py      # Суммаризация документов
│   ├── chunking.py           # Чанкирование документов
│   ├── retrievers.py         # Создание Qdrant + BM25 ретривера
│   └── rag/
│       ├── graph.py          # LangGraph RAG пайплайн
│       ├── schemas.py        # Дополнительные схемы
│       ├── state.py          # Pydantic модели RAGState и Document
│       └── prompts.py        # Системные промпты для LLM
├── db/
│   ├── answer_cache.sql      # Инициализация таблицы кэша
│   └── db_chainlit.sql       # Скрипты для Chainlit БД
├── notebooks/
│   ├── GenerateSynthQA.ipynb  # Генерация синтетических Q&A
│   └── qa_dataset.jsonl      # Датасет вопросов и ответов
├── evaluation/               # Инструменты оценки RAG системы
│   ├── create_langfuse_dataset.py  # Создание датасета в Langfuse
│   ├── run_dataset.py        # Запуск RAG на датасете Langfuse
│   ├── evaluate_dataset_run.py     # Оценка результатов запуска
│   ├── metrics.py            # Метрики оценки
│   ├── structures.py         # Структуры данных
│   ├── data/                 # Тестовые датасеты
│   └── logs/                 # Отчеты об оценке
├── Dockerfile.app            # Docker для FastAPI приложения
├── Dockerfile.chainlit       # Docker для Chainlit интерфейса
├── docker-compose.yml        # Docker Compose конфигурация
├── pyproject.toml            # Зависимости проекта
└── .env.example              # Шаблон переменных окружения

🚀 Быстрый старт

⚠️⚠️⚠️
Чанкирование и векторизация будут проведены заново
Советуем:

1. Предварительно поставить в .env параметр RAG_APP__SPLIT_DATASET=train[:2]
2. Запустить поднятие docker
3. Подождать несколько минут инициализации приложения
4. Загрузить подготовленный snapshot https://drive.google.com/file/d/1sHARsAjnrDR72dgbSYqxPviEC0Q0YIbj/view?usp=sharing в qdrant прямо через интерфейс
5. Готово, вы великолепны

⚠️⚠️⚠️

1. Получение API ключа

• Перейти на https://openrouter.ai/
• Зарегистрироваться и получить API ключ
• Создать .env файл на основе .env.example

2. Генерация секрета для Chainlit

• Выполнить команду chainlit create-secret и скопировать сгенерированный секрет
• Добавить в .env файл: CHAINLIT_AUTH_SECRET=ваш_секрет

3. 🐳 Docker

docker-compose up --build

Сервисы и доступы

Ниже приведены доступные сервисы и их параметры подключения:

FastAPI

• URL: http://localhost:8000/docs

Chainlit (чат-интерфейс)

• URL: http://localhost:8001
• Логин: любой
• Пароль: любой

Qdrant (векторная база данных)

• URL: http://localhost:6333/dashboard#/collections

Langfuse (логирование и оценка)

• URL: http://localhost:3000

PostgreSQL

• Host: localhost
• Host name/address: db
• Port: 5432
• Username: chainlit_user
• Password: chainlit_pass

PgAdmin

• URL: http://localhost:8080
• Логин: admin@admin.com
• Пароль: admin

📡 API Эндпоинты

GET /health

Проверка статуса приложения

curl http://localhost:8000/health

POST /answer

Получить ответ от RAG системы. Запросы можно отправлять через Swagger UI по адресу http://localhost:8000/docs

Примеры запросов:

{ "query": "Who was the original owner of the lot of items being sold?" }

{ "query": "What are some of the skills taught in the Trail Patrol Training course?" }

{ "query": "Who were the two convicted killers that escaped from an upstate New York maximum-security prison?" }

Сохранение историй чатов

Истории чатов автоматически сохраняются в PostgreSQL базе данных. Chainlit управляет созданием таблиц и хранением данных пользователей, сессий и сообщений.

• Чаты в Chainlit кэшируются в базу данных chainlit_db
• Вопросы и ответы RAG кэшируются в базу данных postgres_db в таблице answer_cache

🔬 Валидация и оценка RAG системы

Оценка с использованием Langfuse

Langfuse запускается локально через Docker Compose. После запуска всех сервисов:

• Перейти на http://localhost:3000
• Создать новый проект
• В настройках проекта скопировать Public Key и Secret Key
• Добавить их в .env файл:

  LANGFUSE_PUBLIC_KEY=your_public_key
  LANGFUSE_SECRET_KEY=your_secret_key
  

Папка evaluation содержит инструменты для комплексной оценки качества RAG-системы с использованием Langfuse. Процесс включает три этапа: создание датасета, запуск RAG цепочки и автоматическую оценку результатов.

Подробное описание процесса см. в evaluation/README.md.

🛠️ Используемые технологии

Технология	Назначение
FastAPI	REST API фреймворк
LangGraph	Граф-ориентированный пайплайн
LangChain	Работа с LLM и документами
Pydantic	Валидация данных
Qdrant	Векторный поиск
ChatOpenAI	Интеграция с OpenAI API
PyTorch	Работа с эмбедингами
Chainlit	Чат-интерфейс с авторизацией
Qdrant	Векторная база данных для документов
PostgreSQL	Реляционная база данных для чатов
Langfuse	Логирование и оценка RAG пайплайна