Medical RAG System

Система обработки медицинских PDF-документов с использованием векторного и графового RAG (Retrieval-Augmented Generation). Оптимизирована для работы на машинах с ограниченными ресурсами (GPU 4-8 ГБ).

Ключевые особенности

• Три стратегии векторного RAG: Fixed chunking, Semantic chunking, Hierarchical chunking
• Графовый RAG: Извлечение медицинских сущностей и связей с помощью AirLLM
• Гибридный поиск: Комбинация векторного и графового подходов
• Оптимизация памяти: 4-bit квантизация LLM, on-disk хранилище Qdrant
• Локальная работа: Все компоненты работают локально без облачных сервисов

Требования к системе

Минимальные требования

• Python: 3.10 или выше
• GPU: NVIDIA с CUDA support, 4-8 ГБ VRAM
• RAM: 8-16 ГБ
• Диск: 50+ ГБ свободного места (для моделей и данных)
• ОС: Windows 10/11, Linux (Ubuntu 20.04+), macOS

Программное обеспечение

• CUDA Toolkit (для GPU поддержки)
• Docker (опционально, для Qdrant)
• Redis (для FalkorDB)

Установка

1. Клонирование репозитория

git clone <repository-url>
cd medical-rag-system

2. Создание виртуального окружения

ВАЖНО: Всегда используйте виртуальное окружение!

# Создать venv
python -m venv .venv

# Активировать venv
# Windows PowerShell:
.\.venv\Scripts\Activate.ps1

# Windows CMD:
.venv\Scripts\activate.bat

# Linux/macOS:
source .venv/bin/activate

3. Установка зависимостей

Вариант A: Полная установка (рекомендуется для production)

pip install -r requirements.txt

Этот файл содержит все зависимости с точными протестированными версиями.

Вариант B: Минимальная установка (быстрее)

pip install -r requirements-minimal.txt

Устанавливает только основные пакеты, остальные подтянутся автоматически.

ВАЖНО для PyTorch с CUDA:

# Если нужна GPU поддержка, установите torch с CUDA 11.8
pip install torch==2.7.1+cu118 torchaudio==2.7.1+cu118 torchvision==0.22.1+cu118 \
    --index-url https://download.pytorch.org/whl/cu118

Подробная документация по установке: См. INSTALL.md

4. Настройка переменных окружения

# Скопировать шаблон
cp .env.example .env

# Отредактировать .env под вашу систему
venv\Scripts\activate.bat

# Linux/macOS:
source venv/bin/activate

3. Установка зависимостей

# Обновить pip
pip install --upgrade pip

# Установить зависимости
pip install -r requirements.txt

# Для GPU поддержки установить PyTorch с CUDA
# Пример для CUDA 11.8:
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

4. Настройка переменных окружения

# Скопировать шаблон
cp .env.example .env

# Отредактировать .env файл с вашими настройками

Основные переменные в .env:

# Пути
CLINIC_DOCS_PATH=./Clinic
QDRANT_STORAGE_PATH=./data/qdrant_storage
LOGS_PATH=./logs

# Qdrant
QDRANT_HOST=localhost
QDRANT_PORT=6333

# FalkorDB
FALKORDB_HOST=localhost
FALKORDB_PORT=6379

# AirLLM
AIRLLM_MODEL=meta-llama/Meta-Llama-3-8B
AIRLLM_MAX_GPU_MEMORY=6GB

# Memory limits
MAX_GPU_MEMORY_GB=8
MAX_RAM_MEMORY_GB=16

Настройка баз данных

Вариант A: Docker Compose (рекомендуется)

Запуск всех сервисов одной командой:

# Запустить Qdrant, Qdrant Web UI и FalkorDB
docker-compose up -d

# Проверить статус
docker-compose ps

# Посмотреть логи
docker-compose logs -f

Доступ к сервисам:

• Qdrant API: http://localhost:6333
• Qdrant Web UI: http://localhost:3000
• FalkorDB: localhost:6379

Подробная документация: См. DOCKER.md

Вариант B: Ручная установка

Qdrant (векторная БД)

Docker:

docker run -p 6333:6333 -v $(pwd)/data/qdrant_storage:/qdrant/storage qdrant/qdrant

Локальная установка:

Следуйте инструкциям на https://qdrant.tech/documentation/quick-start/

FalkorDB (графовая БД)

Docker:

docker run -p 6379:6379 -v $(pwd)/data/falkordb_data:/data falkordb/falkordb

Локальная установка:

# Windows: Скачать с https://redis.io/download или использовать WSL
# Linux:
sudo apt-get install redis-server
sudo systemctl start redis

# macOS:
brew install redis
brew services start redis

Проверка подключения:

redis-cli ping
# Должен вернуть: PONG

Инициализация схем БД

После запуска сервисов:

python scripts/setup_databases.py

Обработка документов

Подготовка данных

Поместите PDF документы в папку Clinic/ (26 медицинских документов).

Запуск обработки

python scripts/process_documents.py --folder ./Clinic

Процесс обработки:

1. Парсинг PDF документов
2. Создание чанков (3 стратегии)
3. Генерация эмбеддингов
4. Сохранение в Qdrant
5. Извлечение сущностей и связей (AirLLM)
6. Сохранение графа в FalkorDB

Примерное время: 2-4 часа для 26 документов (зависит от железа)

Мониторинг прогресса

Статус обработки сохраняется в data/processing_status.json и доступен через API:

curl http://localhost:8000/processing-status

Запуск API

uvicorn src.api.main:app --reload --host 0.0.0.0 --port 8000

API будет доступен по адресу: http://localhost:8000

Документация API

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Использование API

Пример запроса (векторный поиск)

curl -X POST "http://localhost:8000/query" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Какие симптомы острого синусита?",
    "strategy": "vector_semantic",
    "top_k": 5,
    "max_tokens": 512
  }'

Пример запроса (гибридный поиск)

curl -X POST "http://localhost:8000/query" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Лечение аллергического ринита у детей",
    "strategy": "hybrid",
    "top_k": 10,
    "max_tokens": 512
  }'

Доступные стратегии

• vector_fixed: Векторный поиск с fixed chunking
• vector_semantic: Векторный поиск с semantic chunking
• vector_hierarchical: Векторный поиск с hierarchical chunking
• graph: Графовый поиск по сущностям и связям
• hybrid: Комбинация векторного и графового поиска

Проверка здоровья системы

curl http://localhost:8000/health

Возвращает:

• Статус системы
• Использование памяти (GPU/RAM)
• Статус загрузки LLM
• Количество векторов в коллекциях
• Статистику графа

Qdrant Web UI

Для визуализации векторных данных используйте Qdrant Web UI:

Вариант A: Docker Compose (автоматически)

Если вы запустили сервисы через docker-compose up -d, Web UI уже доступен:

http://localhost:3000

Web UI автоматически подключен к Qdrant и готов к использованию.

Вариант B: Ручной запуск

cd qdrant-web-ui
npm install
npm start

Web UI будет доступен по адресу: http://localhost:3000

Использование Web UI

1. Откройте http://localhost:3000
2. Выберите коллекцию (clinical_fixed_chunks, clinical_semantic_chunks, clinical_hierarchical_chunks)
3. Просмотрите векторы и метаданные
4. Выполните поиск по векторам
5. Визуализируйте распределение векторов

Валидация системы

Запустите валидацию для проверки корректности работы:

python scripts/validate_system.py

Проверяет:

• Round-trip валидацию векторного поиска
• Извлечение минимального количества сущностей
• Покрытие документов
• Генерирует отчет валидации

Тестирование

# Все тесты
pytest tests/ -v

# Только unit тесты
pytest tests/unit/ -v

# Только property-based тесты
pytest tests/property/ -v

# Только интеграционные тесты
pytest tests/integration/ -v

# Пропустить медленные тесты
pytest -m "not slow" -v

# С покрытием кода
pytest --cov=src --cov-report=html tests/

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

medical-rag-system/
├── src/                    # Исходный код
│   ├── parsers/           # PDF парсинг
│   ├── embeddings/        # Генерация эмбеддингов
│   ├── pipelines/         # RAG пайплайны
│   ├── graph/             # Графовый RAG с AirLLM
│   ├── storage/           # Qdrant и FalkorDB
│   ├── api/               # FastAPI endpoints
│   ├── memory/            # Управление памятью
│   ├── utils/             # Утилиты
│   └── config/            # Конфигурация
├── tests/                 # Тесты
│   ├── unit/             # Unit тесты
│   ├── property/         # Property-based тесты
│   └── integration/      # Интеграционные тесты
├── scripts/              # Скрипты обработки
├── data/                 # Данные Qdrant
├── logs/                 # Логи
├── Clinic/               # PDF документы
└── qdrant-web-ui/        # Web UI для Qdrant

Логи

Логи сохраняются в папке logs/:

• medical_rag.log: Основные логи приложения (10 МБ, 5 бэкапов)
• validation_errors.log: Ошибки валидации (5 МБ, 3 бэкапа)

Troubleshooting

GPU Out of Memory

# Проверить использование GPU
import torch
print(torch.cuda.memory_allocated() / 1e9)  # GB

# Очистить кеш
torch.cuda.empty_cache()

Решения:

• Уменьшить batch_size в конфигурации
• Использовать меньшую модель (Mistral-7B вместо Llama-3-8B)
• Убедиться, что используется 4-bit квантизация

Qdrant connection refused

Проверка:

curl http://localhost:6333/health

Решение: Запустить Qdrant сервер (см. раздел "Настройка баз данных")

FalkorDB connection error

Проверка:

redis-cli ping

Решение: Запустить Redis сервер

ModuleNotFoundError

Причина: venv не активирован или зависимости не установлены

Решение:

# Активировать venv
.\venv\Scripts\Activate.ps1  # Windows

# Установить зависимости
pip install -r requirements.txt

Документация

• Спецификация требований
• Дизайн системы
• План задач
• Steering guides

Лицензия

[Укажите лицензию]

Контакты

[Укажите контактную информацию]