Skip to content

PSLSP/AI-RAG-Telegram-Assistant

BranchesTags

Repository files navigation

🤖 RAG Telegram Assistant

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

Python License Telegram

📋 Содержание

🎯 Описание

RAG Telegram Assistant — это интеллектуальный бот, который использует технологию RAG для ответов на вопросы пользователей на основе предоставленной базы знаний. Бот объединяет:

  • Векторный поиск (FAISS) для быстрого нахождения релевантной информации
  • LLM модель (Claude Sonnet 4.5) для генерации точных ответов
  • Кеширование для оптимизации производительности
  • Оценку качества через RAGAS метрики

Как это работает?

  1. Пользователь задает вопрос в Telegram
  2. Система проверяет кеш на наличие готового ответа
  3. Если ответа нет, выполняется векторный поиск по базе знаний
  4. Найденный контекст передается в LLM для генерации ответа
  5. Ответ сохраняется в кеш и отправляется пользователю

✨ Возможности

  • 💬 Интеллектуальные ответы на основе базы знаний
  • 🔍 Векторный поиск с использованием FAISS
  • 💾 Кеширование ответов для быстрого доступа
  • 📊 Статистика системы в реальном времени
  • 🎯 Оценка качества через RAGAS метрики
  • 🚀 Telegram интерфейс для удобного взаимодействия
  • 📚 Поддержка больших документов с умным chunking

🛠 Технологии

Основные библиотеки

  • python-telegram-bot (21.0+) - Telegram Bot API
  • anthropic (0.34.0+) - Claude API через ProxyAPI
  • openai (1.3.0+) - OpenAI API для embeddings
  • faiss-cpu (1.7.4+) - Векторный поиск
  • ragas (0.2.0+) - Оценка качества RAG систем

Модели

  • LLM: Claude Sonnet 4.5 (через ProxyAPI)
  • Embeddings: text-embedding-3-small (OpenAI)
  • Vector DB: FAISS (IndexFlatIP для cosine similarity)

📦 Установка

Требования

  • Python 3.11+
  • pip
  • Git

Шаги установки

  1. Клонируйте репозиторий:
git clone https://github.com/yourusername/rag-telegram-assistant.git
cd rag-telegram-assistant
  1. Создайте виртуальное окружение:
python -m venv venv

  1. Активируйте виртуальное окружение:

    • Windows (PowerShell): 
      .\venv\Scripts\Activate.ps1
    • Windows (CMD): 
      venv\Scripts\activate.bat
    • Linux/Mac: 
      source venv/bin/activate

  2. Установите зависимости:

pip install -r requirements.txt

⚙️ Настройка

1. Получите API ключи

Telegram Bot Token

  1. Откройте @BotFather в Telegram
  2. Отправьте команду /newbot
  3. Следуйте инструкциям для создания бота
  4. Сохраните полученный токен

Anthropic API Key (ProxyAPI)

  1. Зарегистрируйтесь на ProxyAPI
  2. Получите API ключ для Anthropic
  3. Сохраните ключ

OpenAI API Key

  1. Зарегистрируйтесь на OpenAI
  2. Создайте API ключ
  3. Сохраните ключ

2. Создайте файл .env

Создайте файл .env в корне проекта со следующим содержимым:

# Telegram Bot
TELEGRAM_BOT_TOKEN=your-telegram-bot-token-here

# Anthropic API (ProxyAPI)
ANTHROPIC_API_KEY=your-anthropic-api-key-here

# OpenAI API (для embeddings)
OPENAI_API_KEY=your-openai-api-key-here

3. Подготовьте базу знаний

Поместите ваши документы в папку data/. Поддерживаются текстовые файлы (.txt).

Пример структуры:

data/
  ├── FAQ.txt           # Часто задаваемые вопросы
  ├── Инструкции.txt    # Инструкции
  └── Описание услуг.txt # Описание услуг

Примечание: Вы можете объединить все документы в один файл docs.txt или использовать несколько файлов. Система автоматически загрузит все документы при первом запуске.

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

Запуск бота

  1. Убедитесь, что виртуальное окружение активировано
  2. Убедитесь, что файл .env создан и заполнен
  3. Запустите бота:
python app.py

Вы должны увидеть:

✅ Бот запущен и готов к работе!
Нажмите Ctrl+C для остановки

Первое использование

  1. Найдите вашего бота в Telegram (по имени, которое вы указали при создании)
  2. Отправьте команду /start
  3. Начните задавать вопросы!

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

rag-telegram-assistant/
├── app.py                 # Telegram бот (главный файл)
├── rag_pipeline.py        # RAG pipeline (основная логика)
├── vector_store.py        # Векторное хранилище (FAISS)
├── cache.py              # Кеширование ответов
├── evaluate_ragas.py     # Оценка качества через RAGAS
├── requirements.txt       # Зависимости проекта
├── .env                  # Переменные окружения (не в git)
├── README.md             # Документация
│
├── data/                 # База знаний
│   ├── FAQ.txt
│   ├── Инструкции.txt
│   └── Описание услуг.txt
│
├── faiss_db/             # Векторная база данных (FAISS)
│   ├── *.index
│   └── *.pkl
│
└── *.db                  # Базы данных кеша (SQLite)

🤖 Команды бота

/start

Приветствие и информация о боте. Показывает список доступных команд.

/help

Подробная справка по использованию бота и всех доступных команд.

/stats

Показывает статистику системы:

  • Количество документов в векторном хранилище
  • Размер и количество записей в кеше
  • Информация о модели и режиме работы

/clear

Очищает кеш ответов. Полезно при обновлении базы знаний.

/evaluate

Запускает оценку качества RAG системы через RAGAS. Выполняет:

  • Подготовку тестового датасета
  • Оценку по метрикам RAGAS (Faithfulness, Context Precision)
  • Вывод детальных результатов

Время выполнения: 1-2 минуты

Текстовые сообщения

Любой текст, отправленный боту (кроме команд), обрабатывается как вопрос. Бот найдет релевантную информацию и сгенерирует ответ.

📊 Метрики оценки

Команда /evaluate использует следующие метрики RAGAS:

Основные метрики

  1. Faithfulness (Точность ответа)

    • Оценивает соответствие ответа предоставленному контексту
    • Диапазон: 0.0 - 1.0 (1.0 = полное соответствие контексту)

  2. Context Precision (Точность контекста)

    • Оценивает качество извлеченного контекста для ответа на вопрос
    • Диапазон: 0.0 - 1.0 (1.0 = идеальный контекст)

Интерпретация результатов

  • ≥ 0.7 - Отличное качество ✅
  • 0.5 - 0.7 - Удовлетворительное качество ⚠️
  • < 0.5 - Требует улучшения ❌

📸 Скриншоты

Главный экран бота

Главный экран

Команда /start показывает приветствие и список команд

Пример диалога

Диалог с ботом

Бот отвечает на вопросы на основе базы знаний

Статистика системы

Статистика

Команда /stats показывает детальную статистику

Оценка качества

Оценка RAGAS

Команда /evaluate показывает результаты оценки по всем метрикам

Детальные результаты

Детальные результаты

Детальные результаты оценки по каждому вопросу

🔧 Разработка

Архитектура

Проект состоит из следующих модулей:

app.py

Telegram бот с обработчиками команд и сообщений. Использует python-telegram-bot для взаимодействия с Telegram API.

rag_pipeline.py

Основной pipeline RAG системы:

  • Проверка кеша
  • Векторный поиск
  • Формирование промпта
  • Генерация ответа через LLM
  • Сохранение в кеш

vector_store.py

Векторное хранилище на основе FAISS:

  • Загрузка и chunking документов
  • Создание embeddings через OpenAI
  • Поиск по векторам (cosine similarity)
  • Сохранение индекса на диск

cache.py

Кеширование ответов в SQLite:

  • Хранение пар вопрос-ответ
  • Быстрый поиск по хешу запроса
  • Статистика использования

evaluate_ragas.py

Оценка качества системы через RAGAS:

  • Подготовка тестового датасета
  • Запуск метрик оценки
  • Вывод результатов

Добавление новых документов

  1. Поместите текстовые файлы в папку data/
  2. Удалите файлы индекса FAISS (если нужно переиндексировать): 
    rm -rf faiss_db/*.index faiss_db/*.pkl
  3. Перезапустите бота - документы загрузятся автоматически

Настройка параметров

Вы можете изменить параметры в app.py:

pipeline = RAGPipeline(
    collection_name="api_rag_collection",  # Имя коллекции
    cache_db_path="api_rag_cache.db",      # Путь к кешу
    data_path="data",                     # Папка с .txt файлами (загружаются все .txt файлы)
    model="claude-sonnet-4-5-20250929"    # Модель LLM
)

Изменение модели LLM

В файле rag_pipeline.py измените параметр model:

model: str = "claude-sonnet-4-5-20250929"  # Текущая модель
# Или используйте другую модель Claude

Изменение модели embeddings

В файле vector_store.py измените модель:

model="text-embedding-3-small"  # Текущая модель
# Или используйте text-embedding-3-large для большей точности

🐛 Решение проблем

Бот не запускается

Проблема: TELEGRAM_BOT_TOKEN не установлен

  • Решение: Проверьте наличие файла .env и правильность токена

Проблема: ANTHROPIC_API_KEY не установлен

  • Решение: Добавьте ключ ProxyAPI в .env

Проблема: ModuleNotFoundError: No module named 'faiss'

  • Решение: Установите зависимости: pip install -r requirements.txt

Ошибки при оценке

Проблема: Метрики не вычисляются (NaN)

  • Решение: Проверьте наличие OpenAI API ключа для embeddings

Проблема: Оценка занимает слишком много времени

  • Решение: Это нормально, оценка может занять 1-2 минуты

Проблемы с кодировкой (Windows)

Если видите ошибки с кодировкой, убедитесь, что используете UTF-8:

$env:PYTHONIOENCODING='utf-8'
python app.py

📝 Лицензия

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

👥 Авторы

🙏 Благодарности

  • RAGAS - за отличную библиотеку оценки RAG систем
  • python-telegram-bot - за удобный API для Telegram ботов
  • FAISS - за быстрый векторный поиск
  • Anthropic - за Claude модели
  • OpenAI - за embeddings модели
  • Daniil Sobolev - за концепцию и базовую структуру проекта

📞 Контакты

Если у вас есть вопросы или предложения:

📈 Примеры использования

Пример 1: Простой вопрос

Пользователь: Можно ли у вас разместить решения 1С?

Бот: Да, можно разместить решения 1С. Согласно предоставленной информации, доступны следующие варианты:

  1. Облако 1С — можно разворачивать сервисы 1С в облаке для повышения доступности и производительности проектов.
  2. Выделенные серверы 1С — адаптированы специально для работы в 1С и прошли тест Гилева с высоким результатом.

Пример 2: Сложный вопрос

Пользователь: Какие услуги вы предоставляете?

Бот: У компании есть следующие услуги:

Облачные решения:

  • Облачные базы данных (DBaaS)
  • Серверы 152-ФЗ (защищенная облачная инфраструктура на территории РФ)
  • Выделенные серверы 1С

Сервисы и администрирование:

  • DevOps as a Service (делегирование DevOps-процессов)
  • DevSecOps as a Service (делегирование DevSecOps-процессов)
  • Проектирование IT-инфраструктуры
  • Базовые задачи администрирования

Бизнес-решения:

  • Корпоративная почта на вашем домене

Отраслевые решения:

  • E-Commerce (для маркетплейсов и онлайн-магазинов)
  • Медицина (инфраструктура с защитой персональных данных)
  • IT (для запуска и тестирования цифровых продуктов)
  • Решения для интеграторов
  • Телеком (для операторов связи)

🔒 Безопасность

⚠️ Важно:

  • Никогда не коммитьте файл .env в репозиторий
  • Храните API ключи в безопасности
  • Используйте переменные окружения для продакшена
  • Регулярно обновляйте зависимости

🚧 Roadmap

  • Поддержка мультимодальных документов (изображения, PDF)
  • Веб-интерфейс для управления базой знаний
  • Интеграция с другими мессенджерами
  • Экспорт истории диалогов
  • Аналитика использования бота

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

Мы приветствуем вклад в проект! Пожалуйста:

  1. Fork проекта
  2. Создайте ветку для новой функции (git checkout -b feature/AmazingFeature)
  3. Commit изменения (git commit -m 'Add some AmazingFeature')
  4. Push в ветку (git push origin feature/AmazingFeature)
  5. Откройте Pull Request

📝 Changelog

v1.0.0 (2026-02-01)

  • ✨ Первый релиз
  • 🤖 Telegram бот интерфейс
  • 🔍 Векторный поиск через FAISS
  • 📊 Оценка качества через RAGAS
  • 💾 Кеширование ответов

🔗 Полезные ссылки

⭐ Звезды

Если проект был полезен, поставьте звезду на GitHub! Это мотивирует продолжать разработку.

Сделано с ❤️ используя RAG технологию

About

Интеллектуальный Telegram-бот с технологией RAG (Retrieval-Augmented Generation) для ответов на вопросы на основе базы знаний

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages