readme.md

# 🤖 RAG Система для Анализа Нормативных Документов

## 📋 Описание

Интеллектуальная система для анализа и поиска информации в нормативных документах, построенная на основе технологии RAG (Retrieval-Augmented Generation). Система позволяет загружать документы различных форматов, автоматически обрабатывать их содержимое и предоставляет точные ответы на вопросы пользователей с указанием источников.

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

- **Поддержка множества форматов**: PDF, DOCX, TXT, CSV, XLSX, JSON
- **Интеллектуальная обработка текста**: Семантическое разделение на фрагменты с учетом контекста
- **Динамическое управление базой знаний**: Возможность добавления, обработки и удаления документов
- **Точные ответы с источниками**: Каждый ответ содержит ссылки на конкретные разделы документов
- **Русскоязычная специализация**: Оптимизировано для работы с российскими нормативными документами

## 🏗️ Архитектура системы

### Основные компоненты

```

app.py              # Gradio интерфейс пользователя

├── config.py       # Конфигурация и настройки системы

├── document_processor.py  # Обработка документов различных форматов

├── rag_engine.py   # RAG система и поисковый движок

└── requirements.txt # Зависимости проекта

```

### Структура данных

```

uploaded_documents/     # Папка с загруженными файлами

processed_chunks.csv   # Обработанные фрагменты документов

index_state.json      # Состояние индекса системы

```

## ⚙️ Технические характеристики

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

- **LLM**: Google Gemini 2.5 Flash
- **Embeddings**: sentence-transformers/all-MiniLM-L6-v2
- **Vector Store**: LlamaIndex VectorStoreIndex
- **UI Framework**: Gradio
- **Text Processing**: scikit-learn, pandas, numpy

### Алгоритм обработки документов

1. **Извлечение текста** из файлов различных форматов
2. **Предобработка текста**: Очистка, нормализация, удаление лишних символов
3. **Создание первичных фрагментов** с размером 1000 символов и перекрытием 150 символов
4. **Семантическое слияние**: Объединение похожих фрагментов на основе cosine similarity > 0.7
5. **Извлечение метаданных**: Определение разделов и подразделов документов
6. **Создание векторного индекса** для быстрого поиска

### Параметры конфигурации

```python

# Размеры фрагментов

CHUNK_SIZE = 1000              # Базовый размер фрагмента

CHUNK_OVERLAP = 150            # Перекрытие между фрагментами

MAX_CHUNK_SIZE = 2500          # Максимальный размер после слияния

MIN_CHUNK_SIZE = 1000          # Минимальный размер для сохранения



# Параметры поиска

SIMILARITY_THRESHOLD = 0.7     # Порог для слияния фрагментов

RETRIEVER_TOP_K = 10          # Количество возвращаемых фрагментов

RETRIEVER_SIMILARITY_CUTOFF = 0.7  # Порог релевантности при поиске

```

## 🚀 Установка и запуск

### Требования

- Python 3.8+
- API ключ Google AI Studio

### Пошаговая установка

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

git clone <repository-url>

cd rag-document-analyzer

```

2. **Установка зависимостей**
```bash

pip install -r requirements.txt

```

3. **Настройка API ключа**
Отредактируйте `config.py` и укажите ваш Google API ключ:
```python

GOOGLE_API_KEY = "your-api-key-here"

```

4. **Запуск приложения**
```bash

python app.py

```

5. **Открытие интерфейса**
Откройте браузер и перейдите по адресу `http://localhost:7860`

## 📖 Руководство пользователя

### Загрузка документов

1. Перейдите на вкладку "📤 Управление документами"
2. Нажмите "Выберите файлы для загрузки" и выберите нужные документы
3. Нажмите "📤 Загрузить файлы"
4. После загрузки нажмите "⚙️ Обработать документы"

### Поиск информации

1. Перейдите на вкладку "❓ Поиск ответов"
2. Введите ваш вопрос в поле "Ваш вопрос"
3. Нажмите "🔍 Найти ответ"
4. Изучите полученный ответ и источники

### Управление системой

1. Вкладка "📊 Статус системы" содержит информацию о:
   - Количестве обработанных файлов
   - Количестве фрагментов в базе знаний
   - Времени последнего обновления
   - Списке обработанных файлов

2. Для очистки всех данных используйте кнопку "🗑️ Очистить все данные"

## 🔧 API и интеграция

### Основные функции API

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

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

processed_chunks = process_single_document(file_path)



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

processed_chunks = process_multiple_documents(file_paths)



# Создание документов для RAG

documents = create_llama_documents(processed_chunks)

```

#### RAG система
```python

# Создание поискового движка

query_engine = build_rag_system(processed_chunks)



# Поиск ответов

response = query_documents(query_engine, question)



# Форматирование ответа с источниками

formatted_response = format_response_with_sources(response)

```

### Структура ответа

```python

{

    'answer': 'Текст ответа на вопрос',

    'sources': [

        {

            'chunk_number': 1,

            'section': 'Раздел документа',

            'subsection': 'Подраздел документа',

            'chunk_id': 'Идентификатор фрагмента',

            'document_id': 'Имя документа',

            'text_preview': 'Превью текста фрагмента...'

        }

    ]

}

```

## 🔒 Требования безопасности

### Конфиденциальность данных

- Все документы обрабатываются локально
- Векторные представления хранятся в локальной файловой системе
- API ключи должны храниться в безопасном месте

### Рекомендации по безопасности

1. Не передавайте конфиденциальные API ключи в коде
2. Регулярно обновляйте зависимости
3. Ограничьте доступ к загружаемым файлам
4. Используйте HTTPS при развертывании в продакшене

## 📊 Мониторинг и логирование

### Отслеживаемые метрики

- Количество загруженных документов
- Количество обработанных фрагментов
- Время обработки документов
- Количество поисковых запросов
- Качество ответов системы

### Логи системы

Система автоматически создает логи для:
- Процесса обработки документов
- Ошибок при загрузке файлов
- Результатов поисковых запросов

## 🔄 Обновление базы знаний

### Добавление новых документов

1. Загрузите новые файлы через интерфейс
2. Нажмите "⚙️ Обработать документы"
3. Система автоматически интегрирует новые данные

### Обновление существующих документов

1. Загрузите обновленную версию файла (с тем же именем)
2. Очистите данные через "🗑️ Очистить все данные"
3. Загрузите все файлы заново и обработайте

## ❓ Часто задаваемые вопросы

**В: Какие форматы файлов поддерживаются?**
О: PDF, DOCX, TXT, CSV, XLSX, JSON

**В: Можно ли работать с документами на других языках?**
О: Система оптимизирована для русского языка, но может работать и с другими языками

**В: Как система определяет релевантность ответов?**
О: Используется векторный поиск на основе semantic similarity с порогом 0.7

**В: Можно ли изменить настройки обработки текста?**
О: Да, все параметры настраиваются в файле `config.py`

## 🤝 Техническая поддержка

### Самостоятельная поддержка

1. **Изучите документацию** в README.md
2. **Проверьте конфигурацию** в config.py
3. **Просмотрите логи** для выявления ошибок
4. **Обновите зависимости** до последних версий

### Устранение неполадок

| Проблема | Возможное решение |
|----------|-------------------|
| Ошибка API ключа | Проверьте правильность ключа в config.py |
| Медленная обработка | Уменьшите размер документов или увеличите CHUNK_SIZE |

| Нерелевантные ответы | Снизьте RETRIEVER_SIMILARITY_CUTOFF |

| Ошибки памяти | Уменьшите RETRIEVER_TOP_K или MAX_CHUNK_SIZE |



## 📄 Лицензия



Этот проект предназначен для внутреннего использования. Все права защищены.



---