Climat-RAG Telegram Бот

RAG (Retrieval-Augmented Generation) система для ответов на вопросы по документации климатического оборудования через Telegram бота.

Возможности

Обработка документов: Скачивает и обрабатывает PDF документы по URL
Векторный поиск: Использует Qdrant для семантического поиска по фрагментам документов
Кэширование: Кэширование на Redis для улучшения производительности
Интеграция с Telegram: Удобный интерфейс бота с командами
Локальные модели: Использует sentence-transformers для эмбеддингов (без внешних API)

Архитектура

Telegram Бот: Обрабатывает взаимодействие с пользователями и сообщения
RAG Сервис: Основная логика для поиска документов и генерации ответов
Search Boost Сервис: Повышение релевантности результатов поиска через keyword boosting
Процессор документов: Скачивание PDF, извлечение текста и разбиение на фрагменты
Сервис кэша: Кэширование на Redis для результатов запросов
Векторное хранилище: Qdrant для хранения и поиска по эмбеддингам документов

Установка

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

Docker и Docker Compose
Make (для команд сборки)

Настройка окружения

Скопируйте файл sample.env в .env и настройте переменные:

cp sample.env .env

Затем отредактируйте .env файл и установите ваши значения:

Важно: Получите токен Telegram бота от @BotFather и установите его в переменную TELEGRAM_TOKEN.

# Конфигурация Telegram Бота
TELEGRAM_TOKEN=your_telegram_bot_token_here

# Конфигурация векторной базы данных Qdrant
QDRANT_COLLECTION_NAME=documents

# Конфигурация LLM
LLM_MODEL_NAME=qwen2.5:1.5b

# Конфигурация модели
EMBEDDING_MODEL_NAME=sentence-transformers/all-MiniLM-L6-v2

# Конфигурация обработки документов
CHUNK_SIZE=512
CHUNK_OVERLAP=50

# Конфигурация кэша
CACHE_TTL=3600

# Конфигурация логирования
LOG_LEVEL=INFO

# Пример переопределения (опционально)
# OLLAMA_URL=http://custom-ollama:11434
# QDRANT_URL=http://custom-qdrant:6333
# REDIS_URL=redis://custom-redis:6379

Примечание: URL сервисов (OLLAMA_URL, QDRANT_URL, REDIS_URL) автоматически настраиваются Docker Compose по именам сервисов. Переопределяйте их в .env только если нужна кастомная конфигурация.

Запуск с Docker

Собрать Docker образы:

make build

Настроить модели Ollama (только при первом запуске):

make setup-ollama

Запустить все сервисы:

make up

Бот автоматически начнет опрашивать Telegram сообщения. Примечание: Сначала нужно загрузить документы (см. раздел Загрузка документов ниже).

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

Перед тем как бот сможет отвечать на вопросы, нужно заполнить векторную базу данных документами:

Способ 1: Загрузка из URL командной строки

# Один документ
make exec-ai CMD="python load_documents.py --urls https://example.com/document.pdf"

# Несколько документов  
make exec-ai CMD="python load_documents.py --urls https://example.com/doc1.pdf https://example.com/doc2.pdf"

# Принудительное пересоздание коллекции (замена всех документов)
make exec-ai CMD="python load_documents.py --urls https://example.com/document.pdf --force"

Способ 2: Загрузка из файла

# Сначала создайте файл с URL документов (по одному на строку)
# Можете использовать предоставленный example_documents.txt как шаблон
cp climat-rag/example_documents.txt my_documents.txt

# Отредактируйте my_documents.txt и добавьте ваши URL документов

# Загрузите документы из файла
make exec-ai CMD="python load_documents.py --file my_documents.txt"

Быстрый старт с примерами документов:

# Загрузить примеры климатических документов из файла example_documents.txt (самый простой способ)
make load-example-docs

Примечание: Команда make load-example-docs автоматически загружает предопределенные документы из файла climat-rag/example_documents.txt, который содержит руководства по климатическому оборудованию.

Кастомная загрузка документов:

# Загрузить конкретные климатические документы напрямую
make exec-ai CMD="python load_documents.py --urls https://daichi-aircon.com/upload/iblock/d39/5jta2yrfq6qnds1iigf7bleef3k4r207/IOM-ICE95_DC21_02.02.05.v2.pdf"

# Или вручную загрузить из файла примеров
make exec-ai CMD="python load_documents.py --file example_documents.txt"

Примечания:

Документы должны быть публично доступными PDF файлами
Скрипт покажет прогресс и результаты для каждого документа
Используйте флаг --force для замены существующих документов вместо добавления
Большие документы могут обрабатываться несколько минут

Доступные команды

make help         # Показать все доступные команды
make build        # Собрать Docker образы
make up           # Запустить все сервисы
make down         # Остановить все сервисы
make logs         # Показать логи всех сервисов
make clean        # Очистить контейнеры и тома

# Управление документами
make load-example-docs # Загрузить примеры документов из example_documents.txt в векторную базу данных
make exec-ai           # Выполнить команду в AI контейнере (использование: make exec-ai CMD='command')

# Команды разработки (все выполняются в Docker)
make test         # Запустить тесты
make format       # Форматировать код с помощью ruff
make ruff-check   # Запустить проверку ruff linting
make lint         # Запустить проверку типов с mypy

# Управление Ollama
make ollama-status              # Проверить модели
make ollama-test               # Протестировать соединение
make ollama-pull MODEL=name    # Установить модель
make ollama-remove MODEL=name  # Удалить модель

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

Команды бота

/start - Приветственное сообщение и инструкции
/help - Показать доступные команды и примеры использования

Примеры запросов

"Как включить продув испарителя на сплите Dantex RK-24SVGI?"
"Как установить дренажный шланг на Daichi ICE95AVQ1?"
"Настройка таймера на кондиционере"

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

zb-test/                          # Корневая директория проекта
├── .env                          # Конфигурация окружения (создается из sample.env)
├── sample.env                    # Пример конфигурации окружения
├── docker-compose.yml            # Конфигурация Docker сервисов
├── Makefile                      # Команды сборки и разработки
├── README.md                     # Документация проекта
└── climat-rag/                   # Директория приложения
    ├── config/
    │   ├── __init__.py
    │   └── settings.py           # Настройки приложения
    ├── core/
    │   ├── __init__.py
    │   └── bot.py                # Реализация Telegram бота
    ├── services/
    │   ├── __init__.py
    │   ├── rag_service.py        # Логика RAG и поиск документов
    │   ├── search_boost_service.py # Повышение релевантности поиска через keyword boosting
    │   ├── document_processor.py # Обработка PDF и разбиение на фрагменты
    │   ├── llm_service.py        # Интеграция с LLM
    │   └── cache_service.py      # Слой кэширования Redis
    ├── main.py                   # Точка входа приложения
    ├── load_documents.py         # Утилита загрузки документов
    ├── Dockerfile                # Инструкции сборки контейнера
    ├── pyproject.toml            # Конфигурация Python проекта
    └── uv.lock                   # Файл блокировки зависимостей

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

Настройки моделей

Модель эмбеддингов: sentence-transformers/all-MiniLM-L6-v2 (384 измерения)
LLM модель: qwen2.5:1.5b (через Ollama) - Компактная многоязычная модель с отличной поддержкой русского языка
Разбиение текста: 512 символов с перекрытием в 50 символов
Векторный поиск: Косинусное сходство с порогом 0.05

Доступные LLM модели

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

Рекомендуемые модели:

qwen2.5:1.5b - Компактная многоязычная модель с отличной поддержкой русского языка (по умолчанию)
llama3.2:1b - Альтернативная компактная модель
mistral:7b - Более крупная модель с лучшим качеством (требует больше памяти)

Для установки рекомендуемой модели:

make setup-ollama

Для ручного управления моделями:

make ollama-status              # Список установленных моделей
make ollama-pull MODEL=name     # Установить конкретную модель
make ollama-remove MODEL=name   # Удалить конкретную модель

Требования к моделям:

Минимум 2GB RAM для моделей 1.5B (рекомендуется)
Минимум 4GB RAM для моделей 3B
Минимум 8GB RAM для моделей 7B
GPU ускорение опционально, но рекомендуется

Настройки производительности

TTL кэша: 1 час для результатов запросов
Лимит фрагментов: Топ 5 похожих фрагментов на запрос
Лимит ответа: Топ 3 фрагмента в ответе

Search Boost Service

SearchBoostService - это специализированный сервис для повышения релевантности результатов поиска через систему keyword boosting. Он анализирует текстовые фрагменты и применяет дополнительные баллы на основе наличия ключевых слов и фраз.

Функциональность

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

Keyword Boosting: Автоматическое повышение релевантности для документов с ключевыми словами
Группы ключевых слов: Условная логика для сложных комбинаций терминов
Модель-специфичные ключевые слова: Учет конкретных моделей оборудования
Анализ запросов: Специальная обработка для определенных типов вопросов
Конфигурируемость: Полностью data-driven система без хардкода

Типы буста:

1. Простые ключевые слова - базовые термины получают фиксированный буст:

"продув": +0.2,       # Функция продува
"испарител": +0.2,    # Компонент испарителя  
"x-fan": +0.15,       # Техническое название функции
"обдув": +0.15,       # Альтернативное название
"blow": +0.1          # Английский термин

2. Группы ключевых слов - сложная логика с условиями:

Детальные описания X-FAN (+0.3): Слова "10 мин", "вращается", "влаги" получают буст только при наличии "x-fan"
Режимы работы (+0.2): "охлажден", "осушен" бустятся только при наличии слова "режим"
Функции кнопок (+0.15): Требуется минимум 2 совпадения из "кнопк", "нажат", "включ"
Описания вентилятора (+0.15): Требуется наличие обоих слов "вентилятор" и "внутренн"

3. Модель-специфичные ключевые слова (+0.1):

dantex - бренд климатического оборудования
rk-24 - конкретная модель сплит-системы

4. Анализ запросов - специальная обработка для типовых вопросов:

Запросы о "продув испарителя" получают детальное логирование и анализ

Архитектура сервиса

SearchBoostService
├── boost_search_result()      # Основной метод буста
├── analyze_query_and_log_results()  # Анализ и логирование
├── get_config()              # Получение конфигурации
├── update_config()           # Обновление конфигурации
└── SEARCH_CONFIG             # Конфигурация буста
    ├── simple_keywords       # Простые ключевые слова
    ├── keyword_groups        # Группы с условиями
    ├── model_keywords        # Модель-специфичные слова
    └── query_analysis        # Анализ типов запросов

Пример работы

Входящий запрос: "Как включить продув испарителя на сплите Dantex RK-24SVGI?"

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

Исходный score: 0.4157
+ "продув": +0.2
+ "испарител": +0.2  
+ "x-fan": +0.15
+ "функция_кнопк": +0.15 (группа button_functions)
+ "rk-24": +0.1 (модель из запроса)
= Итоговый score: 1.1157

Результат: Релевантный фрагмент поднимается с 4-го места на 1-е в результатах поиска.

Расширение конфигурации

Для добавления новых правил буста отредактируйте SEARCH_CONFIG в services/search_boost_service.py:

# Добавить новое простое ключевое слово
"simple_keywords": {
    "новое_слово": 0.15,  # Буст +0.15
}

# Добавить новую группу ключевых слов
"keyword_groups": {
    "новая_группа": {
        "keywords": ["слово1", "слово2", "слово3"],
        "boost": 0.2,
        "condition": {
            "type": "min_matches",  # или "requires_keyword"
            "count": 2              # или "keyword": "обязательное_слово"
        }
    }
}

Мониторинг буста

Сервис предоставляет детальное логирование процесса буста:

Исходные scores для каждого результата
Найденные ключевые слова и примененные бусты
Финальные scores после буста
Специальные сообщения для важных находок

Логи помогают понять, почему определенные результаты получили высокий или низкий рейтинг, и настроить систему буста для лучшей производительности.

Начальные документы

Система обрабатывает эти документы при запуске:

Мониторинг

Логи

Просмотр логов приложения:

make logs        # Все сервисы
make logs -f     # Следить за логами в реальном времени

Статус сервисов

Векторное хранилище (Qdrant):

Панель управления: http://localhost:6333/dashboard
API: http://localhost:6333

LLM Сервис (Ollama):

make ollama-status    # Список установленных моделей
make ollama-test      # Тест соединения

Статистика кэша (Redis):

Информация Redis доступна через методы сервиса кэша.

Разработка

Качество кода

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

Форматирование кода с ruff:

make format      # Автоформатирование кода
make ruff-check  # Проверка стилевых проблем

Проверка типов:

make lint        # Запуск проверки типов mypy

Утилитарные команды:

make build       # Пересборка Docker образов
make clean       # Очистка контейнеров и томов
make logs        # Просмотр логов приложения

Стандарты качества

Форматтер: Ruff (заменяет Black + isort)
Линтер: Ruff для проверки стиля и ошибок
Проверка типов: MyPy со строгими настройками
Тестирование: Pytest с поддержкой async
Версия Python: 3.13+

Рабочий процесс разработки

Внесите изменения в код
Отформатируйте и проверьте качество кода:
```
make format ruff-check lint
```
Протестируйте приложение:
```
make up
```

Вклад в проект

Следуйте существующей структуре кода
Добавляйте аннотации типов ко всем функциям
Используйте рабочий процесс разработки:
```
make format ruff-check lint
```

4.Вся разработка происходит в Docker контейнерах 5.Обновляйте документацию для новых функций

Лицензия

Этот проект предназначен для образовательных целей.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
climat-rag		climat-rag
.gitignore		.gitignore
Makefile		Makefile
README.md		README.md
docker-compose.yml		docker-compose.yml
sample.env		sample.env

Savier/zb-test

Folders and files

Latest commit

History

Repository files navigation