README.uk.md

RAG Система - Локальний Q&A для Документів

Локальна система Retrieval-Augmented Generation (RAG) для запитів до документів з використанням open-source LLM. Створена для швидкого прототипування та proof-of-concept розгортань.

Огляд

Цей проєкт реалізує повний RAG pipeline, який:

• Конвертує документи (PDF, DOCX, TXT) у текст для пошуку
• Розбиває контент на семантичні chunks
• Генерує embeddings за допомогою локальних моделей
• Зберігає вектори в ChromaDB
• Відповідає на запитання використовуючи LLM через Ollama

Система працює повністю локально без зовнішніх API залежностей.

Можливості

• Обробка Документів: Автоматична конвертація PDF, DOCX та TXT файлів
• Семантичний Пошук: Vector-based пошук з використанням sentence transformers
• Локальний LLM: Генерація відповідей через Ollama (llama3.2 за замовчуванням)
• Streaming Відповіді: Генерація відповідей в реальному часі
• Мультимовність: Підтримка запитів англійською, українською та російською
• Веб-Інтерфейс: UI на базі Gradio для швидкого тестування

Архітектура

┌─────────────┐
│  Документи  │
│ (PDF/DOCX)  │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│   Конвертація   │
│   (PyMuPDF)     │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  Розбиття       │
│  (LangChain)    │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐      ┌──────────────┐
│   Embeddings    │◄─────┤ Запит        │
│ (all-MiniLM-L6) │      └──────────────┘
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│   ChromaDB      │
│ (Vector Store)  │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  Пошук          │
│  Контексту      │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  LLM (Ollama)   │
│  llama3.2       │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  Відповідь +    │
│  Джерела        │
└─────────────────┘

Технологічний Стек

Компонент	Технологія	Призначення
Парсинг Документів	PyMuPDF, python-docx	Витягування тексту з файлів
Обробка Тексту	LangChain	Розбиття документів з overlap
Embeddings	sentence-transformers	Генерація векторних представлень
Vector Database	ChromaDB	Зберігання та пошук embeddings
LLM Runtime	Ollama	Локальний inference моделей
Веб-Інтерфейс	Gradio	UI для швидкого прототипування

Вимоги

• Python 3.9+
• Ollama встановлений та запущений
• 4GB+ RAM (рекомендовано 8GB+)
• ~2GB дискового простору для моделей

Швидкий Старт

1. Встановіть Ollama

# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh

# Завантажте модель
ollama pull llama3.2

2. Налаштуйте Python Середовище

# Клонуйте репозиторій
git clone <repository-url>
cd rag-python-rag

# Створіть віртуальне середовище
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Встановіть залежності
pip install -r requirements.txt

3. Запустіть Застосунок

python main.py

Застосунок:

1. Завантажить тестовий документ (Think Python PDF)
2. Обробить та проіндексує його (~30 секунд)
3. Запустить веб-інтерфейс на http://localhost:7860

4. Додайте Свої Документи

Помістіть PDF, DOCX або TXT файли в директорію documents/ та перезапустіть застосунок.

Конфігурація

Відредагуйте config.py для налаштування:

# Модель embeddings
EMBEDDING_MODEL_NAME = "all-MiniLM-L6-v2"

# LLM модель
OLLAMA_MODEL_NAME = "llama3.2"

# Розбиття тексту
CHUNK_SIZE = 1000
CHUNK_OVERLAP = 200

# Результати пошуку
DEFAULT_N_RESULTS = 5

Змінні Середовища

Скопіюйте .env.example в .env та налаштуйте:

OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=llama3.2
EMBEDDING_MODEL=all-MiniLM-L6-v2

Структура Проєкту

rag-python-rag/
├── config.py              # Конфігурація
├── document_converter.py  # PDF/DOCX в markdown
├── text_splitter.py       # Логіка розбиття
├── vector_store.py        # Інтерфейс ChromaDB
├── llm_handler.py         # Інтеграція Ollama
├── main.py                # Точка входу
├── requirements.txt       # Python залежності
├── documents/             # Вихідні документи (gitignored)
├── processed_docs/        # Конвертований markdown (gitignored)
└── chroma_db/            # Vector database (gitignored)

Приклади Використання

Python API

from vector_store import retrieve_context
from llm_handler import stream_llm_answer

# Запит до документів
question = "Як працюють цикли в Python?"
context, sources = retrieve_context(question, n_results=5)

# Stream відповідь
for token in stream_llm_answer(question, context):
    print(token, end='', flush=True)

Веб-Інтерфейс

1. Перейдіть на http://localhost:7860
2. Введіть запитання будь-якою підтримуваною мовою
3. Перегляньте відповідь з посиланнями на джерела

Обмеження

Дивіться LIMITATIONS.md для детальних обмежень включно з:

• Підтримкою мов embedding моделлю
• Обмеженнями форматів документів
• Вимогами до обладнання
• Прогалинами готовності до production

Розгортання

Це локальний застосунок, який потребує Python backend та Ollama runtime.

Дивіться DEPLOYMENT.md для опцій розгортання:

• Hugging Face Spaces (рекомендовано для демо)
• Хмарні платформи (Render, Fly.io, Railway)
• Локальне використання

Примітка: GitHub Pages та статичний хостинг не підтримуються.

Roadmap

• Підтримка Excel та PowerPoint файлів
• Кешування embeddings для швидшого запуску
• REST API endpoints
• Контекст розмови з кількома документами
• Витягування зображень та таблиць з PDF
• Docker контейнеризація

Внесок

Внески вітаються. Будь ласка:

1. Зробіть fork репозиторію
2. Створіть feature branch
3. Надішліть pull request з чітким описом

Ліцензія

MIT License - дивіться файл LICENSE для деталей.

Цей проєкт призначений для освітніх цілей та прототипування.

Подяки

Створено з:

• Ollama - Локальний LLM runtime
• ChromaDB - Vector database
• LangChain - Обробка тексту
• Sentence Transformers - Embeddings
• Gradio - Веб-інтерфейс

Натхнення: Побудова RAG Системи за Один Вечір

---

Статус: Proof of concept / Освітній проєкт
Підтримка: Активна розробка
Python: 3.9+