AI Бот Terra

Интеллектуальный Telegram бот, разработанный для работы в качестве AI ассистента в рамках проекта TERRA. Он использует обширную базу знаний, построенную на основе Google Таблиц и релевантной истории чатов Telegram, обогащенную механизмом извлечения вопросов и ответов с помощью больших языковых моделей (LLM). Бот предоставляет точные, контекстно-зависимые ответы и предлагает мощные инструменты администрирования для управления базой знаний.

Возможности

• Контекстуальные AI Ответы (RAG): Использует архитектуру Retrieval Augmented Generation (RAG) для предоставления ответов на основе постоянно обновляемой базы знаний, обеспечивая точность и актуальность.
• Динамические Источники Базы Знаний:
  • Google Таблицы: Интегрируется с указанной Google Таблицей для получения структурированных пар "вопрос-ответ".
  • Чаты Telegram: Автоматически парсит истории указанных чатов Telegram, извлекая релевантные пары "вопрос-ответ" с использованием продвинутого процесса LLM-разметки.
• LLM-Разметка Q&A: Применяет модели OpenAI для интеллектуального выявления и извлечения ценной информации "вопрос-ответ" из исходных сообщений чатов Telegram, категоризируя их по типу (вопрос, ответ, шум) и теме.
• Настраиваемые Режимы Ответа: Поддерживает различные операционные режимы (тестовый, белый список, личные сообщения, все чаты) для контроля зон ответов бота.
• Полный Набор Инструментов Администрирования: Набор Telegram команд для администраторов, позволяющий:
  • Обновлять базу знаний из Google Таблиц, Telegram или обоих источников.
  • Экспортировать всю базу знаний в файл JSON.
  • Удалять дублирующиеся записи из базы знаний.
  • Получать подробную статистику и примеры из источников базы знаний.
  • Просматривать и обновлять основной промпт LLM непосредственно из Telegram.
  • Отлаживать результаты поиска в векторном хранилище.
• Постоянное Хранение Знаний: Использует ChromaDB в качестве локальной векторной базы данных для хранения встраиваний документов и метаданных, обеспечивая сохранение данных при перезапусках бота.
• Детальное Логирование: Комплексное логирование в файл (bot.log) и консоль для мониторинга активности бота, ошибок и производительности.
• Управление Историей Чата: Поддерживает краткосрочную историю чата для каждого пользователя для улучшения потока беседы.

Используемые Технологии

• Python: Основной язык программирования (рекомендуется 3.10+).
• Pyrogram: Асинхронный клиент Telegram MTProto API.
• LangChain: Фреймворк для разработки приложений на основе языковых моделей.
• OpenAI: Поставщик больших языковых моделей (серии GPT) и эмбеддингов.
• ChromaDB: Векторная база данных с открытым исходным кодом для локального хранения знаний.
• Pydantic Settings: Для надежного управления переменными окружения.
• tiktoken: Токенизатор OpenAI для управления ограничениями по токенам.
• python-dotenv: Для загрузки переменных окружения из файла .env.
• requests: Для HTTP-запросов, в основном к Google Таблицам.
• pysqlite3: Используется как замена sqlite3 для обеспечения совместимости, особенно в определенных средах или для конкретных версий ChromaDB.

Установка

1. Клонируйте репозиторий:

   git clone <адрес_вашего_репозитория>
   cd terra_ai_bot

2. Создайте виртуальное окружение (рекомендуется):

   python -m venv venv
   # Для Windows
   venv\Scripts\activate
   # Для macOS/Linux
   source venv/bin/activate

3. Установите зависимости: Создайте файл requirements.txt (если его нет) со следующим содержимым:

   pyrogram
   pydantic-settings
   langchain-core
   langchain-openai
   chromadb
   tiktoken
   python-dotenv
   requests
   openai
   # Убедитесь, что pysqlite3 установлен, если возникнут проблемы с SQLite и ChromaDB
   pysqlite3-binary
   

   Затем установите:

   pip install -r requirements.txt

Настройка

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

# Ключ OpenAI API (обязательно)
OPENAI_API_KEY="ваш_ключ_openai_api"

# Модель OpenAI (обязательно)
# Например, gpt-4o, gpt-4-turbo, gpt-3.5-turbo
MODEL="gpt-4o-mini" 

# Учетные данные Telegram API (обязательно для клиента Pyrogram)
# Получите их на my.telegram.org (API Development)
API_ID="ваш_api_id"
API_HASH="ваш_api_hash"

# Токен Telegram бота (не используется напрямую в этом коде, но необходим для получения BOT_ID)
# Этот бот использует режим клиента Pyrogram, а не режим бота, для расширенных разрешений.
# Тем не менее, вам все равно нужно создать бота через BotFather, чтобы получить BOT_ID.

# Строка сессии для Pyrogram (генерируется при первом запуске, опционально, если предоставляете вручную)
# SESSION_STRING="ваша_строка_сессии_pyrogram"

# Настройки Базы Знаний
GOOGLE_SHEET_URL="https://docs.google.com/spreadsheets/d/ваш_id_таблицы/edit#gid=0"
DAYS_OFFSET=30 # Количество дней для парсинга истории чатов Telegram (от текущей даты)
ENABLE_LLM_FALLBACK=True # Если True, LLM попытается сгенерировать ответ, даже если не найдено высокорелевантного контекста в базе знаний

# Управление Чатами и Пользователями
# Список ID пользователей Telegram для администраторов (через запятую, без пробелов)
ADMINS="12345,67890" 
# Пример: ADMINS="123456789,987654321"

# ID вашего Telegram бота (получите от @BotFather через команду /token)
# Используется парсером чатов для идентификации сообщений, отправленных самим ботом.
BOT_ID=1234567890 

# ID чата Telegram для основной группы (например, -10012345678)
# Используется для обновлений и сообщений о статусе от бота во время операций с базой знаний.
TELEGRAM_CHAT_ID=-1001234567890 

# Список разрешенных ID чатов, в которых бот может отвечать (через запятую, без пробелов)
ALLOWED_CHAT_IDS="-1001111111111,-1002222222222" 
# Список разрешенных имен пользователей чатов (например, "имя_пользователя_моего_канала,имя_пользователя_моей_группы")
ALLOWED_CHAT_USERNAMES="мой_разрешенный_канал,моя_разрешенная_группа"

# Режим Ответа Бота (выберите один)
# - "test": Бот отвечает только в жестко закодированном тестовом чате (ID -1001945870336 в commands.py)
# - "whitelist": Бот отвечает только в чатах, перечисленных в ALLOWED_CHAT_IDS или ALLOWED_CHAT_USERNAMES
# - "private": Бот отвечает только на прямые личные сообщения
# - "all": Бот отвечает во всех чатах, в которых он является участником (используйте с осторожностью!)
REGIME="whitelist" 

# Прокси OpenAI (опционально, если вам нужно маршрутизировать вызовы OpenAI API через прокси)
# OPENAI_PROXY="http://ваш.прокси.ком:порт"

Важные Примечания:

• Telegram API_ID и API_HASH: Получите их на my.telegram.org. Войдите с помощью своего номера телефона и перейдите в раздел "API Development".
• ADMINS: Замените на ваш(и) ID(ы) пользователя Telegram. Вы можете найти свой ID пользователя, переслав любое сообщение боту, такому как @userinfobot.
• TELEGRAM_CHAT_ID: Замените на ID основной группы/канала Telegram, куда вы хотите, чтобы бот отправлял обновления прогресса и общие уведомления. Для ID групп они обычно отрицательные (например, -1001234567890).
• BOT_ID: Получите это от @BotFather после создания вашего бота. Это числовой ID самого вашего бота.

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

1. Запуск Бота:

   python main.py

   • Первый Запуск (Сессия Pyrogram): При первом запуске main.py Pyrogram предложит вам ввести ваш номер телефона Telegram (связанный с вашим API_ID/API_HASH), код подтверждения и пароль, если у вас включена двухфакторная аутентификация. Этот процесс генерирует файл terra_bot.session, который позволяет боту автоматически входить в систему при последующих запусках.
   • Инициализация ChromaDB: ChromaDB создаст директорию chroma_data в корне вашего проекта для хранения векторной базы данных.

2. Взаимодействие с Ботом (Пользовательские Команды):

   • /start: Начать разговор с ботом.
   • /help: Получить список доступных команд.
   • Задайте любой вопрос о TERRA! Бот попытается найти ответы в своей базе знаний.

3. Администраторские Команды: Эти команды доступны только пользователям, чьи ID указаны в переменной окружения ADMINS.

   • /update (all|sheets|telegram):
     • all: Обновляет базу знаний из Google Таблиц и истории чатов Telegram (рекомендуется для первоначальной настройки и периодических полных обновлений).
     • sheets: Обновляет только из настроенной Google Таблицы.
     • telegram: Обновляет только из истории чатов Telegram с использованием LLM-извлечения вопросов/ответов.
     • Пример: /update all
   • /kb_stats: Отображает статистику базы знаний, включая количество записей из каждого источника (Google Таблицы, Telegram) и примеры содержимого.
   • /export_kb: Экспортирует всю базу знаний (вопросы, ответы, метаданные) в файл JSON и отправляет его администратору.
   • /remove_duplicates: Сканирует базу знаний на наличие дубликатов Q&A записей (на основе хэша содержимого) и удаляет их, предоставляя отчет о очистке.
   • /get_prompt: Отображает текущий основной промпт LLM, используемый ботом.
   • /set_prompt <новый_текст_промпта>: Позволяет администраторам установить новый основной промпт LLM непосредственно через Telegram.
   • /add_qa Вопрос? Ответ!: Вручную добавляет одну пару "Вопрос-Ответ" в базу знаний.
   • /debug_search <запрос>: Выполняет необработанный поиск по векторной базе данных и показывает лучшие результаты с оценками релевантности, полезно для отладки.

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

.
├── main.py                 # Основная точка входа для бота
├── config.py               # Настройки Pydantic для управления конфигурацией
├── handlers/
│   └── commands.py         # Обработчики команд Pyrogram и основная логика обработки сообщений
├── service/
│   ├── chatai.py           # Основная логика AI (цепочка RAG, общая генерация ответов)
│   ├── chat_parser.py      # Логика для парсинга чатов Telegram и LLM-извлечения Q&A
│   ├── google_sheet_utils.py # Утилиты для парсинга Google Таблиц и взаимодействия с ChromaDB
│   └── knowledge_base.py   # Управление общей базой знаний (ChromaDB, обновления, поиск)
├── .env                    # Переменные окружения (приватные, конфиденциальные)
├── .env.example            # Пример файла .env
├── bot.log                 # Файл логов операций бота
├── chroma_data/            # Директория, где ChromaDB сохраняет свои данные
└── README.md               # Этот файл документации

Ветки Проекта

Этот проект разработан с использованием двух основных веток, каждая из которых имеет свои особенности в отношении обработки ответов системы искусственного интеллекта:

• Ветка main:

  • Эта ветка содержит все последние улучшения и оптимизации в работе системы искусственного интеллекта, направленные на повышение качества и точности ответов.
  • Рекомендуется для большинства пользователей и для развертывания в рабочей среде, так как она включает в себя наиболее продвинутые возможности AI.

• Ветка wench:

  • Эта ветка представляет собой версию проекта без улучшений в системе формирования ответов ИИ, которые присутствуют в ветке main.
  • Она может быть полезна для сравнения производительности или для использования в случаях, когда требуется базовая функциональность без дополнительных оптимизаций AI.

Для получения наилучшего опыта и использования всех функций AI рекомендуется использовать ветку main.

Устранение Неполадок

• Бот не отвечает в определенном чате:
  • Проверьте настройку REGIME в вашем файле .env.
  • Если REGIME="whitelist", убедитесь, что chat_id или username целевого чата правильно указаны в ALLOWED_CHAT_IDS или ALLOWED_CHAT_USERNAMES.
  • Убедитесь, что бот добавлен в чат и имеет необходимые разрешения (например, на чтение сообщений).
• Обновление Базы Знаний из Telegram завершается неудачно:
  • Проверьте правильность ваших API_ID и API_HASH в .env.
  • Убедитесь, что сессия Telegram бота (terra_bot.session) активна и не истекла.
  • Проверьте наличие ограничений скорости (rate limits) от Telegram или OpenAI.
  • Настройка CHATS_TO_PARS может быть слишком строгой; попробуйте увеличить ее или убедитесь, что у бота есть доступ к соответствующим чатам.
• "No module named 'pysqlite3'" или проблемы с SQLite: Этот проект использует pysqlite3 для обеспечения совместимости с определенными средами или для более надежной работы с SQLite, особенно для ChromaDB. Если вы столкнулись с проблемами, убедитесь, что pysqlite3-binary правильно установлен в вашем виртуальном окружении (pip install pysqlite3-binary). Строка __import__('pysqlite3')... в main.py предназначена именно для этого.
• Ошибки OpenAI API:
  • Проверьте правильность вашего OPENAI_API_KEY и убедитесь, что на нем достаточно средств.
  • Проверьте правильность имени MODEL в .env и его доступность.
  • Если используется OPENAI_PROXY, проверьте его конфигурацию.
• Бот отвечает "Произошла непредвиденная ошибка": Проверьте bot.log для получения подробных трассировок стека. Это указывает на общую необработанную ошибку.
• База Знаний не обновляется из Google Таблиц:
  • Убедитесь, что GOOGLE_SHEET_URL верен и общедоступен (или доступен из сетевой среды вашего бота).
  • Убедитесь, что названия столбцов в вашей Google Таблице соответствуют "вопрос" и "ответ" (без учета регистра, так как это обрабатывается парсером).
• Необходимо полностью сбросить базу знаний: Если требуется полная очистка, остановите бота и вручную удалите директорию chroma_data из корня проекта. При следующем запуске она будет пересоздана.