RAG README и доработка quickstart
This commit is contained in:
191
rag/README.md
Normal file
191
rag/README.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# 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` (v3.8+), `pip`
|
||||
2. Запустить сервер Ollama: `../up`
|
||||
3. Установить модели 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.
|
||||
@@ -1,7 +1,13 @@
|
||||
#!/bin/bash
|
||||
|
||||
command -v python3 >/dev/null 2>&1 || { echo >&2 "Ошибка: python3 не установлен"; exit 1; }
|
||||
command -v pip >/dev/null 2>&1 || { echo >&2 "Ошибка: pip не установлен"; exit 1; }
|
||||
is_installed() {
|
||||
command -v $1 >/dev/null 2>&1 || { echo >&2 "Ошибка: $1 не установлен"; exit 1; }
|
||||
}
|
||||
|
||||
is_installed curl
|
||||
is_installed jq
|
||||
is_installed python3
|
||||
is_installed pip
|
||||
|
||||
[ ! -f .env ] && cp .env.example .env
|
||||
source .env
|
||||
@@ -20,6 +26,7 @@ source venv/bin/activate
|
||||
[ "$(pip install --dry-run beautifulsoup4 2>&1 | grep -c 'Would install')" -gt 0 ] && pip install beautifulsoup4
|
||||
|
||||
echo "Начало работы"
|
||||
../up
|
||||
./1_download_page.sh "$@" || exit 1
|
||||
python3 ./2_html_to_md.py
|
||||
python3 ./3_rag.py --action build
|
||||
|
||||
Reference in New Issue
Block a user