Просмотреть исходный

Инструкция

# 🤖 ROBIN - Ассистент по поиску в документах

Telegram бот для интеллектуального поиска информации в корпоративных документах с использованием технологий машинного обучения и векторных представлений (embeddings).

## 📋 Описание проекта

ROBIN - это ассистент компании, который помогает пользователям быстро находить ответы на вопросы в регламентах и инструкциях. Бот использует современные технологии обработки естественного языка для поиска релевантной информации в загруженных документах.

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

- **Интеллектуальный поиск** по содержимому документов
- **Загрузка документов** в различных форматах (PDF, DOC, DOCX, TXT и др.)
- **Работа в личных чатах** и **группах Telegram**
- **Управление документами** (просмотр списка, удаление)
- **Интеграция с LLM** для генерации точных ответов
- **Ограничение размера файлов** до 20MB

## 🏗️ Архитектура и инфраструктура

### Компоненты системы

1. **Telegram Bot** (`app.py`) - основной интерфейс взаимодействия с пользователями
2. **API для поиска** - внешний сервис для обработки запросов и поиска в документах
3. **База документов** - хранилище загруженных файлов и их векторных представлений
4. **Docker** - контейнеризация для легкого развертывания

### Технологии

- **Python 3.9+**
- **Aiogram 3.13+** - фреймворк для Telegram ботов
- **aiohttp** - асинхронные HTTP запросы
- **Requests** - HTTP клиент для API
- **Docker & Docker Compose** - контейнеризация

## 📦 Установка и развертывание

### Локальная разработка

1. **Клонируйте репозиторий:**
```bash
git clone <repository-url>
cd document-search-telegram-bot
```

2. **Установите зависимости:**
```bash
pip install -r requirements.txt
```

3. **Настройте переменные окружения:**
```bash
cp .env.example .env
```

Отредактируйте `.env` файл:
```env
# URL внешнего API для поиска в документах
API_URL=http://localhost:8000/retriever

# Токен Telegram бота (получить у @BotFather)
BOT_TOKEN=your_bot_token_here

# Имя бота в Telegram (например @your_bot)
BOT_NAME=@your_bot_name

# Маршруты API (обычно не нужно менять)
QUESTION_ROUTE=/internal/question
DOCUMENT_ROUTE=/documents
GROUP_ROUTE=/document-groups
```

4. **Запустите бота:**
```bash
python app.py
```

### Развертывание на сервере с Docker

1. **Убедитесь, что установлен Docker и Docker Compose**

2. **Соберите и запустите контейнер:**
```bash
# Сборка образа
docker-compose build

# Запуск бота
docker-compose up -d
```

3. **Проверьте логи:**
```bash
docker-compose logs -f tgbot-test
```

### Переменные окружения

| Переменная | Описание | Пример |
|------------|----------|---------|
| `API_URL` | URL сервиса для поиска в документах | `http://localhost:8000/retriever` |
| `BOT_TOKEN` | Токен Telegram бота от BotFather | `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11` |
| `BOT_NAME` | Имя бота в Telegram | `@robin_assistant_bot` |
| `QUESTION_ROUTE` | Маршрут для запросов вопросов | `/internal/question` |
| `DOCUMENT_ROUTE` | Маршрут для управления документами | `/documents` |
| `GROUP_ROUTE` | Маршрут для групп документов | `/document-groups` |

## 💬 Использование бота

### В личном чате

1. **Начало работы:**
- Отправьте команду `/start`
- Бот представится и объяснит свои возможности

2. **Задать вопрос:**
- Просто напишите вопрос в чат
- Пример: *"Как оформить отпуск?"*

3. **Загрузка документов:**
- Отправьте файл (PDF, DOC, DOCX, TXT и т.д.)
- Максимальный размер: 20MB
- Бот подтвердит успешную загрузку

4. **Управление файлами:**
- `/files` - посмотреть список всех загруженных файлов
- `delete <ID>` - удалить файл по его ID

### В группах Telegram

1. **Добавьте бота в группу** как участника

2. **Упоминание бота:**
- Напишите `@имя_бота ваш_вопрос`
- Пример: `@robin_assistant_bot Как подключить интернет?`

3. **Бот ответит** на ваш вопрос, используя загруженные документы

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

| Команда | Описание | Пример использования |
|---------|----------|---------------------|
| `/start` | Приветствие и начало работы | `/start` |
| `/files` | Показать список всех файлов | `/files` |
| `delete <ID>` | Удалить файл по ID | `delete 12345` |
| *Файл* | Загрузить документ | Отправьте PDF или DOC файл |
| *Вопрос* | Искать ответ в документах | *"Какие правила безопасности?"* |

### Особенности работы

- **Длинные ответы:** Если ответ превышает 1000 символов, бот предложит показать полный текст
- **Форматирование:** Ответы поддерживают HTML-разметку для лучшего отображения
- **Обработка ошибок:** Бот gracefully обрабатывает сетевые ошибки и недоступность API
- **Логирование:** Все запросы и ответы логируются для отладки

## 🔧 Настройка и конфигурация

### Ограничения

- **Размер файла:** максимум 20MB (ограничение Telegram)
- **Длина ответа:** до 4096 символов в одном сообщении
- **Количество файлов:** не ограничено (зависит от внешнего API)

### Мониторинг

Бот логирует все действия:
- Входящие вопросы пользователей
- Ответы от API
- Загрузку и удаление файлов
- Ошибки и исключения

Логи доступны через Docker:
```bash
docker-compose logs tgbot-test
```

## 🧪 Тестирование

Тестовый бот доступен по адресу: https://t.me/robin_search_bot

### Запуск тестов

```bash
# Запуск в режиме тестирования
docker-compose -f docker-compose-test.yml up -d
```

## 📚 API интеграция

Бот взаимодействует с внешним API через следующие endpoints:

- **POST** `/document-groups` - создание группы документов
- **GET** `/internal/question` - поиск ответов на вопросы
- **POST** `/documents` - загрузка документов
- **GET** `/documents` - получение списка документов
- **DELETE** `/documents/{id}` - удаление документа

## 🐛 Устранение неисправностей

### Проблемы с запуском

1. **Проверьте токен бота** - убедитесь, что токен действительный
2. **Проверьте API URL** - сервис поиска должен быть доступен
3. **Проверьте логи** - `docker-compose logs`

### Проблемы с поиском

1. **Нет документов** - загрузите документы через бота
2. **API недоступен** - проверьте подключение к сервису поиска
3. **Неправильный вопрос** - переформулируйте вопрос более конкретно

## 📝 Лицензия

[Укажите лицензию проекта]

## 👥 Контакты

[Укажите контактную информацию для поддержки]