evo-foundation-models-outline-chat-bot-lab

Демонстрационный интеллектуальный корпоративный wiki-ассистент, который сочетает поиск документов Outline с возможностями AI для ответов на вопросы. Система предоставляет как REST API сервер, так и интерфейс Telegram-бота для доступа к корпоративным базам знаний через естественный язык.

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

Основной ассистент

• Умный поиск документов: Использует извлечение ключевых слов и семантический поиск для нахождения релевантных документов
• Ответы на базе ИИ: Использует Cloud.ru Foundation Models для интеллектуальных ответов
• Многоязычная поддержка: Отвечает на вопросы на том же языке, что и запрос
• Управление токенами: Автоматическое обновление токена для Cloud.ru Foundation Models
• Контекстуальность: Сохраняет историю чата и предоставляет контекстные ответы
• Безопасность: Проверяет токены API Outline и корректно обрабатывает ошибки аутентификации

Интерфейс Telegram-бота

• Индивидуальная аутентификация: Каждый пользователь предоставляет свой собственный токен API Outline
• Общение на естественном языке: Задавайте вопросы простым языком
• Мобильная оптимизация: Оптимизирован для мобильного приложения Telegram
• Управление сессиями: Сохраняет сессии пользователей и историю чата
• Безопасность: Токены хранятся только в памяти во время сессии

A2A Сервер

• REST API: Предоставляет функционал ассистента через протокол A2A
• Готов к интеграции: Легко интегрируется с другими приложениями
• Масштабируемость: Поддерживает несколько одновременных пользователей

🏗️ Архитектура

Проект организован в два основных пакета:

Пакет ассистента (

assistant/

)

• outline_assistant.py
  — основной класс ассистента с поиском документов и AI-обработкой
• prompts.py
  — шаблоны Langchain для извлечения ключевых слов и Q&A
• retrievers.py
  — улучшенный поиск документов с предобработкой ключевых слов
• server.py
  — сервер A2A, предоставляющий ассистента через REST API

Пакет бота (

bot/

)

• telegram_bot.py
  — реализация Telegram-бота с аутентификацией пользователей
• README_telegram.md
  — подробная документация по Telegram-боту

📋 Необходимые компоненты

• Python 3.8+
• Экземпляр Outline с доступом к API
• Аккаунт Cloud.ru Foundation Models
• Токен Telegram-бота (для интерфейса бота)

🛠️ Установка

1. Создание виртуального окружения

3. Установка зависимостей

4. Конфигурация окружения

Создайте файл

в корне проекта:

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

Режим разработки

Запуск сервера ассистента

Запустите сервер A2A для предоставления ассистента через REST API:

Сервер запустится на порту 8000 (можно изменить через

).

Запуск Telegram-бота

Запустите Telegram-бота для чата:

Тестирование установки

Запустите отладочный скрипт для проверки ассистента:

Режим продакшн

Для продакшн-развертывания используйте предоставленные скрипты:

Быстрое развертывание

🔧 Детали конфигурации

Настройка Outline

1. Перейдите в ваш Outline → Settings → API Tokens
2. Создайте новый API токен с нужными правами
3. Установите
   OUTLINE_BASE_URL
   на URL вашего экземпляра Outline

Настройка Cloud.ru Foundation Models

1. Зарегистрируйтесь на Cloud.ru
2. Сгенерируйте API-ключи (Key ID и Secret)
3. Укажите свой Project ID и имя модели
4. Установите базовый URL для Foundation Models API

Настройка Telegram-бота

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

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

Эндпоинты A2A сервера

Ассистент доступен через протокол A2A. Отправляйте POST-запросы на

с JSON:

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

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

Процесс поиска документов

1. Извлечение ключевых слов: Вопрос пользователя обрабатывается цепочкой извлечения ключевых слов
2. Семантический поиск: Извлечённые ключевые слова используются для поиска документов Outline
3. Подготовка контекста: Релевантные документы форматируются с контекстом
4. AI-обработка: Cloud.ru Foundation Models генерируют ответы на основе контекста
5. Формирование ответа: Ответ возвращается на языке пользователя

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

• Проверка токенов: Все токены API Outline проверяются перед использованием
• Изоляция сессий: Каждая пользовательская сессия изолирована
• Обработка ошибок: Корректная обработка ошибок аутентификации и сетевых ошибок
• Без постоянного хранения: Токены пользователей не сохраняются на диск

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

Частые проблемы

1. "Invalid Outline API token"

   • Проверьте правильность и актуальность токена Outline
   • Убедитесь, что у токена есть необходимые права
   • Проверьте доступность
     OUTLINE_BASE_URL

2. "Failed to refresh LLM token"

   • Проверьте правильность учётных данных Cloud.ru
   • Убедитесь, что задан
     FM_MODEL_NAME
   • Проверьте правильность
     FM_BASE_URL
     для Foundation Models

3. Telegram-бот не отвечает

   • Проверьте правильность
     TELEGRAM_BOT_TOKEN
   • Убедитесь, что бот запущен
   • Проверьте логи на наличие ошибок

Режим отладки

Включите подробное логирование, установив

в

.env

:

📚 Зависимости

• langchain>=0.3.26
  — основной фреймворк Langchain
• langchain-openai>=0.3.28
  — интеграция с OpenAI
• langchain-community==0.3.27
  — интеграции сообщества
• python-telegram-bot==22.2
  — фреймворк Telegram-бота
• python-a2a==0.5.9
  — реализация протокола A2A
• pydantic==2.11.7
  — валидация данных
• python-dotenv>=1.0.0
  — управление переменными окружения

📄 Лицензия

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

🆘 Поддержка

По вопросам и проблемам:

1. Проверьте раздел решения проблем
2. Изучите логи на наличие ошибок
3. Проверьте вашу конфигурацию

🔗 Связанная документация

• Документация Outline API
• Cloud.ru Foundation Models
• Документация Langchain
• Telegram Bot API