ollama/rag/README.md

# RAG для Confluence-документации

## Что такое RAG?

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

Основные компоненты RAG:
- **Индексация**: Документы преобразуются в векторные представления (эмбеддинги) и сохраняются в векторной базе данных
- **Поиск**: При поступлении запроса система ищет наиболее релевантные фрагменты из индексированной базы
- **Генерация**: Найденные фрагменты используются как контекст для генерации ответа с помощью языковой модели

Преимущества RAG:
- Повышает точность ответов засчёт использования актуальной и специфической информации
- Позволяет отвечать на вопросы, требующих знаний, не входящих в обучающие данные модели
- Дает возможность проверить источник информации в сгенерированном ответе
- Может работать с проприетарными или конфиденциальными данными без дообучения модели

Этот проект представляет собой систему RAG, которая позволяет преобразовывать документацию из Confluence в формат, пригодный для работы с локальной Ollama, и задавать вопросы по содержимому документации.

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

```
rag/
├── .env.example         # Пример файла конфигурации для подключения к Confluence
├── 1_download_page.sh   # Скрипт для загрузки страниц из Confluence
├── 2_html_to_md.py      # Скрипт конвертации HTML в Markdown
├── 3_rag.py             # Основной скрипт RAG системы
├── quickstart.sh        # Скрипт быстрого запуска всего процесса
├── input_html/          # Входные HTML файлы (загруженные из Confluence)
├── output_md/           # Конвертированные Markdown файлы
├── ready_rag/           # Готовая векторная база данных для RAG
└── README.md            # Этот файл
```

## Стек

* bash
* python, venv, pip
* [docker](https://docker.com)
* [ollama](https://ollama.com)
* [open-webui](https://docs.openwebui.com)

## Предварительные требования

1. Установить ПО: `curl`, `jq`, `python3`, `pip`
2. Установить зависимости python:

```bash
source venv/bin/activate
pip install chromadb numpy requests beautifulsoup4
```

3. Запустить сервер Ollama: `../up`
4. Установить модели Ollama (рекомендуется):
   - `nomic-embed-text:latest` — для эмбеддингов  
     (установить через `../models/nomic-embed-text/latest`)
   - `phi4-mini:3.8b` или другая подходящая модель — для генерации ответов  
     (установить через `../models/phi4/mini:3.8b`)

## Настройка

1. Создайте файл конфигурации на основе примера: `cp .env.example .env`
2. Отредактируйте файл `.env`, указав свои данные

Файл используется только для подключения к Confluence.

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

### Способ 1: Быстрый запуск (рекомендуется)

Запустите скрипт быстрого старта, указав ID страницы Confluence:

```bash
cd rag
./quickstart.sh 123456789
```

где `123456789` - ID страницы Confluence, которую вы хотите обработать.

Скрипт автоматически:
- Создаст виртуальное окружение Python
- Установит необходимые зависимости
- Загрузит страницу и все дочерние страницы
- Конвертирует HTML в Markdown
- Построит векторную базу данных
- Запустит интерактивный режим чата

### Способ 2: Пошаговая настройка

#### 1. Загрузка страниц из Confluence

```bash
./1_download_page.sh 123456789
```

Этот скрипт:
- Загружает указанную страницу и все её дочерние страницы
- Сохраняет HTML-файлы в директорию `input_html/`
- Рекурсивно обрабатывает всю иерархию страниц

#### 2. Конвертация HTML в Markdown

```bash
python3 2_html_to_md.py
```

Этот скрипт:
- Обрабатывает все HTML-файлы в директории `input_html/`
- Конвертирует их в Markdown с сохранением структуры
- Сохраняет результаты в директории `output_md/`
- Очищает от Confluence-специфичной разметки

#### 3. Построение RAG базы данных

```bash
python3 3_rag.py --action build
```

Этот скрипт:
- Создает векторную базу данных на основе Markdown-файлов
- Генерирует эмбеддинги с помощью Ollama
- Сохраняет базу данных в директории `ready_rag/`

#### 4. Взаимодействие с RAG системой

```bash
python3 3_rag.py --action interactive
```

В интерактивном режиме:
- Введите свой вопрос и нажмите Enter
- Система найдет релевантные документы и сгенерирует ответ
- Введите `exit` для выхода
- Введите `stats` для просмотра статистики

Также можно выполнить одиночный запрос:

```bash
python3 3_rag.py --action query --question "Ваш вопрос здесь"
```

## Конфигурация

Вы можете настроить параметры RAG системы через аргументы командной строки:

```bash
python3 3_rag.py \
  --md-folder output_md \
  --embed-model nomic-embed-text \
  --chat-model phi4-mini:3.8b \
  --results 5
```

Доступные параметры:
- `--md-folder`: Папка с Markdown файлами (по умолчанию: `output_md`)
- `--embed-model`: Модель для генерации эмбеддингов (по умолчанию: `nomic-embed-text`)
- `--chat-model`: Модель для генерации ответов (по умолчанию: `phi4-mini:3.8b`)
- `--results`: Количество возвращаемых результатов (по умолчанию: `10`)
- 
## Пример использования

1. Загрузите страницу документации:
   ```bash
   ./1_download_page.sh 123456789
   ```

2. Конвертируйте в Markdown:
   ```bash
   python3 2_html_to_md.py
   ```

3. Постройте RAG базу:
   ```bash
   python3 3_rag.py --action build
   ```

4. Задайте вопрос:
   ```bash
   python3 3_rag.py --action query --question "Как настроить систему мониторинга?"
   ```

## Особенности обработки

Система автоматически обрабатывает следующие элементы Confluence:

- **Заметки (Note макросы)**: Конвертируются в формат `📝 **Примечание:** Текст заметки`
- **Таблицы**: Преобразуются в Markdown-таблицы с сохранением структуры
- **JSON блоки**: Форматируются и отображаются как кодовые блоки
- **Диаграммы (DrawIO)**: Заменяются на заглушки
- **Содержание (TOC)**: Заменяется на заглушки

## Лицензия

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

Скрипты на языке python сгенерированы моделью claude-sonnet-4.