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 только если нужна кастомная конфигурация.

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

make build

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

make setup-ollama

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

make up

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

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

# Один документ
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"

# Сначала создайте файл с 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

Система поддерживает различные локальные модели через 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 фрагмента в ответе

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 после буста
• Специальные сообщения для важных находок

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

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

• Руководство Daichi ICE95
• Руководство Dantex Vita

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

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+

1. Внесите изменения в код
2. Отформатируйте и проверьте качество кода:

   make format ruff-check lint

3. Протестируйте приложение:

   make up

1. Следуйте существующей структуре кода
2. Добавляйте аннотации типов ко всем функциям
3. Используйте рабочий процесс разработки:

   make format ruff-check lint

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

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