Почти полная переработка всего rag

- включение qdrant в контур - использование нормальной эмб-модели - векторизация текста - README и туча мелочей
2025-08-25 01:55:46 +08:00
parent c6e498a0c8
commit a9328b4681
19 changed files with 509 additions and 1075 deletions
--- a/rag/README.md
+++ b/rag/README.md
@@ -1,11 +1,27 @@
-# RAG для Confluence-документации
+# Базовый RAG для локального запуска
+
+Этот проект представляет собой систему RAG, которая позволяет преобразовывать документацию из Confluence или других источников в формат, пригодный для работы с локальной Ollama, и задавать вопросы по содержимому документов.
+
+## Быстрый старт
+
+```bash
+cd ..; ./up; cd -
+python3 -m venv .venv
+source ./venv/bin/activate
+pip install beautifulsoup4 markdownify sentence-transformers qdrant-client langchain transformers hashlib
+pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
+./download.sh 123456789
+python3 convert.py
+python3 vectorize.py
+python3 rag.py --interactive
+```

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

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

-Основные компоненты RAG:
+Основные шаги подготовки RAG:
 - **Индексация**: Документы преобразуются в векторные представления (эмбеддинги) и сохраняются в векторной базе данных
 - **Поиск**: При поступлении запроса система ищет наиболее релевантные фрагменты из индексированной базы
 - **Генерация**: Найденные фрагменты используются как контекст для генерации ответа с помощью языковой модели
@@ -16,183 +32,189 @@ RAG (Retrieval-Augmented Generation) — это архитектура, кото
 - Дает возможность проверить источник информации в сгенерированном ответе
 - Может работать с проприетарными или конфиденциальными данными без дообучения модели

-Этот проект представляет собой систему 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            # Этот файл
+├── input_html/         # Входные файлы HTML, загруженные из Confluence
+├── input_md/           # Входные (конвертированные) файлы Markdown
+├── download.sh    # Скрипт для загрузки страниц из Confluence
+├── convert.py       # Скрипт конвертации HTML в Markdown
+├── vectorize.py        # Скрипт векторизации Markdown
+├── rag.py              # Основной скрипт RAG системы
+├── clear.sh            # Скрипт очистки html/md файлов
+└── README.md           # Этот файл
 ```

 ## Стек

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

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

-1. Установить ПО: `curl`, `jq`, `python3`, `pip`
-2. Установить зависимости python:
+1. Запустить среду из корня репозитория: [../README.md](../README.md)
+2. Установить ПО: `curl`, `jq`, `python3`, `pip`
+3. Установить зависимости python:

 ```bash
-source venv/bin/activate
-pip install chromadb numpy requests beautifulsoup4
+python3 -m venv .venv
+source ./venv/bin/activate
+pip install beautifulsoup4 markdownify sentence-transformers qdrant-client langchain transformers
+pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
 ```

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

-## Настройка
+## Подготовка данных

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

-Файл используется только для подключения к Confluence.
+Открыть страницу (раздел) Confluence, который необходимо получить.
+Например, `https://conf.company.ltd/pages/viewpage.action?pageId=123456789`.  

-## Использование
-
-### Способ 1: Быстрый запуск (рекомендуется)
-
-Запустите скрипт быстрого старта, указав ID страницы Confluence:
+Скопировать значение `pageId` и подставить в команду `./download.sh <pageId>`.
+Например,

 ```bash
-cd rag
-./quickstart.sh 123456789
+./download.sh 123456789
 ```

-где `123456789` - ID страницы Confluence, которую вы хотите обработать.
+В результате сама страница и все её дочерние будут сохранены в директорию `./input_html/`.
+Файлы будут названы по заголовкам страниц.

-Скрипт автоматически:
- Создаст виртуальное окружение Python
- Установит необходимые зависимости
- Загрузит страницу и все дочерние страницы
- Конвертирует HTML в Markdown
- Построит векторную базу данных
- Запустит интерактивный режим чата
+> [!IMPORTANT]
+> В начале каждого файла будет сохранена исходная ссылка в формате `@@https://conf.company.ltd/pages/viewpage.action?pageId=123456789@@`.
+> Это сделано для того, чтобы в диалоге с моделью источники информации отображались в виде ссылок, а не названий файлов.

-### Способ 2: Пошаговая настройка
+> [!IMPORTANT]
+> Confluence не позволяет получить готовые макросы в HTML-виде.
+> В файлах будет находиться HTML-текст с готовыми к загрузками макросами, но не загруженными.
+> Хотя в них часто есть очень полезная информация, но её приходится выбрасывать просто потому, что загрузка макросов происходит при загрузке страницы браузером.
+> Поэтому, например, содержания, списки дочерних страниц, встраиваемые диаграммы и пр. плюшечки будут вырезаны.
+> 
+> Да, можно запросить страницы простым curl/wget, но (1) см. предыдущее замечание и (2) даже после очистки HTML-тегов в тексте останется очень много мусора (меню, футер, навигация...)

-#### 1. Загрузка страниц из Confluence
+### Конвертация страниц в Markdown
+
+Этот формат наиболее хорошо подходит для цитирования, потому что не содержит лишних символов, которые будут мешать хорошей токенизации и векторизации.
+
+Для конвертации следует выполнить команду:

 ```bash
-./1_download_page.sh 123456789
+python3 convert.py
 ```

-Этот скрипт:
- Загружает указанную страницу и все её дочерние страницы
- Сохраняет HTML-файлы в директорию `input_html/`
- Рекурсивно обрабатывает всю иерархию страниц
+В результате все html-файлы будут сохранены в директорию `./input_md/`.
+Файлы будут названы по заголовкам страниц, внутри также сохранится ссылка на исходную страницу `@@...@@`.

-#### 2. Конвертация HTML в Markdown
+Для получения справки по скрипту выполни команду:
+
+```
+python3 convert.py --help
+```
+
+### Векторизация (индексирование)
+
+Файлы `./input_md/*.md` должны быть проиндексированы.
+
+Для того, чтобы проиндексировать Markdown-документы, выполнить команду:

 ```bash
-python3 2_html_to_md.py
+python3 vectorize.py
 ```

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

-#### 3. Построение RAG базы данных
+Каждый чанк разбивается на токены, которые в виде векторов сохраняются в векторную СУБД Qdrant.
+При работе RAG, близость векторов токенов обеспечивает наибольшее смысловое совпадение разных слов => чанков => предложений => абзацев => документов.
+Как следствие:
+- наибольшее смысловое совпадение с вопросом пользователя;
+- молниеносный поиск по индексу чанков (частям документов);
+- корректное насыщение контекста для генеративной модели.

-```bash
-python3 3_rag.py --action build
+Впоследствии embedding-модель будет встраивать эти данные в диалог с генеративной моделью.
+Каждый запрос сначала будет обрабатывать именно она, находя подходящие по векторам документы, и подставлять их в контекст генеративной модели.
+Последняя будет всего лишь генерировать ответ, опираясь на предоставленные из документов данные, ссылаясь на них в ответе.
+
+Для получения справки по скрипту выполни команду:
+
+```
+python3 vectorize.py --help
 ```

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

-#### 4. Взаимодействие с RAG системой
+Для работы с RAG в интерактивном режиме (симуляция диалога) следует выполнить команду:

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

-В интерактивном режиме:
- Введите свой вопрос и нажмите Enter
- Система найдет релевантные документы и сгенерирует ответ
- Введите `exit` для выхода
- Введите `stats` для просмотра статистики
+> [!IMPORTANT]
+> Модель не запоминает ничего, поскольку сам диалог не попадает в контекст!
+> В целом, это похоже на гуглёж.

-Также можно выполнить одиночный запрос:
+Для разового запуска RAG следует выполнить команду:

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

-## Конфигурация
+Для получения справки по скрипту выполни команду:

-Вы можете настроить параметры RAG системы через аргументы командной строки:
-
-```bash
-python3 3_rag.py \
-  --md-folder output_md \
-  --embed-model nomic-embed-text \
-  --chat-model phi4-mini:3.8b \
-  --results 5
+```
+python3 rag.py --help
 ```

-Доступные параметры:
- `--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
-   ```
+Если хочется уточнить роль генеративной модели, можно создать файл `sys_prompt.txt` и прописать туда всё необходимое, учитывая следующие правила:

-2. Конвертируйте в Markdown:
-   ```bash
-   python3 2_html_to_md.py
-   ```
+1. Шаблон `{{context}}` будет заменён на цитаты документов, найденные в qdrant
+2. Шаблон `{{query}}` будет заменён на запрос пользователя
+3. Если этих двух шаблонов не будет в промпте, результаты будут непредсказуемыми
+4. Каждая цитата в списке цитат формируется в формате:
+    ```
+    --- Source X ---
+    Lorem ipsum dolor sit amet
+    <пустая строка>
+    ```
+5. Если в этой директории нет файла `sys_prompt.txt`, то будет применён промпт по умолчанию (см. функцию `generate_answer()`).

-3. Постройте RAG базу:
-   ```bash
-   python3 3_rag.py --action build
-   ```
+Посмотреть полный промпт можно указав аргумент `--show_prompt` при вызове `rag.py`.

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

-## Особенности обработки
+Для эмбеддинга:

-Система автоматически обрабатывает следующие элементы Confluence:
+- `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` (по умолчанию, хорошо адаптирована под русский язык)
+- `nomad-embed-text` (популярная)
+- ...

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

-## Лицензия
+- `qwen2.5:3b` (по умолчанию)
+- `gemma3n:e2b`
+- `phi4-mini:3.8b`
+- `qwen2.5:1.5b`
+- ...

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

-Скрипты на языке python сгенерированы моделью claude-sonnet-4.
+Проект родился на энтузиазме из личного любопытства.
+
+**Цель:** изучить современные технологии.
+
+**Задачи:**
+1. облегчить поиск информации о проекте среди почти 2000 тысяч документов в корпоративной Confluence, относящихся к нему;
+2. обеспечить минимум телодвижений для развёртывания RAG с нуля внутри команды.
+
+Здесь не было задачи сделать всё по красоте.
+
+Частично (в качестве агентов) в проекте участвовали семейства qwen3, clause-sonnet-4 и семейство chatgpt-4.