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
• ollama
• open-webui

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

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

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:

cd rag
./quickstart.sh 123456789

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

Скрипт автоматически:

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

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

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

./1_download_page.sh 123456789

Этот скрипт:

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

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

python3 2_html_to_md.py

Этот скрипт:

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

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

python3 3_rag.py --action build

Этот скрипт:

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

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

python3 3_rag.py --action interactive

В интерактивном режиме:

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

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

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

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

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

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. Загрузите страницу документации:

   ./1_download_page.sh 123456789
   

2. Конвертируйте в Markdown:

   python3 2_html_to_md.py
   

3. Постройте RAG базу:

   python3 3_rag.py --action build
   

4. Задайте вопрос:

   python3 3_rag.py --action query --question "Как настроить систему мониторинга?"
   

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

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

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

Лицензия

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

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