Wine Assistant Web Service
Веб-сервис для создания продвинутого AI-ассистента с поддержкой RAG (Retrieval Augmented Generation), Function Calling, многоагентного тестирования и интеграции с Telegram.
> Важно для macOS: На macOS команда python может быть недоступна. Используйте python3 во всех командах. Если хотите использовать python, создайте алиас: alias python=python3 (добавьте в ~/.zshrc или ~/.bashrc).
Основные возможности
- Треды (Threads): Поддержка множественных сессий диалога с сохранением истории
- RAG (Retrieval Augmented Generation): Семантический поиск по текстовой базе знаний
- Function Calling: Вызов внешних функций для работы с данными (поиск вин, корзина, передача оператору)
- Многоагентное тестирование: Система тестирования ассистента с помощью других агентов
- Telegram интеграция: Бот для взаимодействия через Telegram
- REST API: FastAPI endpoints для программного доступа
Предварительные требования
1. Python окружение
Требование: Python 3.10 или выше
Проверка:```bash
На macOS и Linux обычно используется python3
python3 --version
На Windows может быть python
python --version
**Если версия Python ниже 3.10**, необходимо обновить:
#### Обновление Python на macOS:
**Вариант 1: Через Homebrew (рекомендуется)**```bash
# Установка Homebrew (если не установлен)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Установка Python 3.12
brew install python@3.12
# Проверка установки
python3.12 --version
# Использование новой версии
python3.12 -m venv venv
Вариант 2: Через официальный установщик
1. Скачайте Python 3.10+ с python.org
2. Установите через .pkg файл
3. После установки проверьте: python3 --version
Вариант 3: Использование pyenv (для управления несколькими версиями)```bash
Установка pyenv через Homebrew
brew install pyenv
Добавьте в ~/.zshrc:
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
Перезагрузите терминал или выполните:
source ~/.zshrc
Установка Python 3.12
pyenv install 3.12.0
pyenv global 3.12.0
Проверка
python3 --version
**Примечание**: На macOS команда `python` может быть недоступна. Используйте `python3` или создайте алиас:```bash
# Создание алиаса (добавьте в ~/.zshrc или ~/.bashrc)
alias python=python3
alias pip=pip3
Выполнение:```bash
Создание виртуального окружения
python3 -m venv venv
Активация (Linux/Mac)
source venv/bin/activate
Активация (Windows)
venv\Scripts\activate
### 2. Установка зависимостей
**Требование**: Установлены все необходимые Python пакеты
**Выполнение**:```bash
pip install --upgrade pip
pip install -r requirements.txt
Проверка установки:```bash
pip list | grep -E "(fastapi|openai|pydantic|telebot)"
### 3. Yandex Cloud API доступ
**Требование**: Настроены учетные данные для Yandex Cloud AI Assistant API
**Шаги выполнения**:
1. **Создание сервисного аккаунта в Yandex Cloud**:
- Войдите в Yandex Cloud Console
- Перейдите в раздел "Сервисные аккаунты"
- Создайте новый сервисный аккаунт
- Назначьте роль `ai.languageModels.user` или `editor`
2. **Получение API ключа**:
- В настройках сервисного аккаунта создайте авторизованный ключ
- Сохраните `service_account_id`, `key_id` и `private_key`
- Или создайте API ключ для сервисного аккаунта
3. **Получение Folder ID**:
- В Yandex Cloud Console перейдите в нужный каталог (folder)
- Скопируйте ID каталога из URL или настроек
4. **Настройка переменных окружения**:```bash
cp .env.example .env
Отредактируйте .env файл:```env
API_KEY=your_api_key_here
FOLDER_ID=your_folder_id_here
BASE_URL=https://rest-assistant.api.cloud.yandex.net/v1
MODEL=gpt://{FOLDER_ID}/yandexgpt/rc
**Важно**: Замените `{FOLDER_ID}` на реальный ID каталога или используйте полный путь модели.
**Проверка**:```bash
# Проверка переменных окружения
python3 -c "from app.config import settings; print(f'Model: {settings.model}')"
4. Данные для работы
Требование: Наличие файлов с данными о винах
Структура данных:```
data/
├── wine-price-ru.xlsx # Прайс-лист вин (Excel)
├── wines.txt/ # Текстовые файлы о сортах вин
│ ├── Каберне.txt
│ ├── Мерло.txt
│ └── ...
└── regions.txt/ # Текстовые файлы о регионах
├── Бордо.txt
├── Тоскана.txt
└── ...
**Формат прайс-листа (wine-price-ru.xlsx)**:
Excel файл со столбцами:
- `Id` - ID вина
- `Name` - Название вина
- `Country` - Код страны (IT, FR, RU, и т.д.)
- `Price` - Цена
- `WHPrice` - Оптовая цена
- `Acidity` - Кислотность (Сухое, Полусухое, и т.д.)
- `Color` - Цвет (Красное, Белое, Розовое)
- `Volume` - Объем
**Выполнение**:
1. Создайте директорию `data`:```bash
mkdir -p data/wines.txt data/regions.txt
-
Поместите файл
wine-price-ru.xlsxв директориюdata/ -
Добавьте текстовые файлы о винах и регионах в соответствующие директории
Проверка:```bash
ls -la data/
ls -la data/wines.txt/ | head -5
ls -la data/regions.txt/ | head -5
### 5. Telegram Bot (опционально)
**Требование**: Токен Telegram бота для интеграции
**Шаги выполнения**:
1. **Создание бота через BotFather**:
- Откройте Telegram и найдите @BotFather
- Отправьте команду `/newbot`
- Следуйте инструкциям для создания бота
- Сохраните полученный токен
2. **Настройка в .env**:```env
TELEGRAM_TOKEN=your_telegram_bot_token_here
Проверка:```bash
python3 -c "from app.config import settings; print('Telegram token:', 'set' if settings.telegram_token else 'not set')"
## Установка и запуск
### Полная установка```bash
# 1. Клонирование/переход в директорию проекта
cd /path/to/project
# 2. Создание виртуального окружения
python3 -m venv venv
source venv/bin/activate # Linux/Mac
# или
venv\Scripts\activate # Windows
# 3. Установка зависимостей
pip install --upgrade pip
pip install -r requirements.txt
# 4. Настройка переменных окружения
cp .env.example .env
# Отредактируйте .env файл с вашими учетными данными
# 5. Инициализация структуры данных
python3 init_data.py
# Это создаст необходимые директории и проверит конфигурацию
# 6. Подготовка данных
# Поместите wine-price-ru.xlsx в data/
# Добавьте текстовые файлы о винах в data/wines.txt/
# Добавьте текстовые файлы о регионах в data/regions.txt/
# 7. Запуск приложения
python3 run.py
Запуск только API сервера```bash
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
### Запуск только Telegram бота```bash
python3 -c "from app.telegram_bot import start_telegram_bot; start_telegram_bot()"
Проверка установки
После выполнения всех шагов установки, проверьте готовность системы:```bash
Быстрая проверка окружения
python3 check_environment.py
Инициализация структуры данных
python3 init_data.py
Скрипт проверит:
- ✅ Наличие необходимых директорий
- ✅ Наличие файлов данных
- ✅ Корректность конфигурации
## Использование API
### Документация API
После запуска сервера документация доступна по адресам:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
### Примеры запросов
#### Отправка сообщения```bash
curl -X POST "http://localhost:8000/api/v1/chat" \
-H "Content-Type: application/json" \
-d '{
"message": "Какое вино подходит к стейку?",
"thread_id": "user123"
}'
Получение истории диалога```bash
curl "http://localhost:8000/api/v1/chat/user123/history"
#### Очистка истории```bash
curl -X DELETE "http://localhost:8000/api/v1/chat/user123/history"
Python пример```python
import requests
Отправка сообщения
response = requests.post(
"http://localhost:8000/api/v1/chat",
json={
"message": "Какое самое дешевое красное вино из Италии?",
"thread_id": "test_user"
}
)
print(response.json())
### Запуск примера API клиента```bash
# Убедитесь, что сервер запущен в другом терминале
python3 example_api_client.py
Многоагентное тестирование
Система многоагентного тестирования позволяет проверить работу ассистента с помощью других AI-агентов, имитирующих пользователей.
Запуск тестового примера```bash
python3 example_test.py
### Пример использования системы тестирования:```python
from app.agents.agent import Agent
from app.models.tools import SearchWinePriceList, AddToCart, ShowCart, Handover
from app.testing.multi_agent_tester import create_default_tester
# Создание ассистента
assistant = Agent(
instruction="Ты - опытный сомелье...",
tools=[SearchWinePriceList, AddToCart, ShowCart, Handover]
)
# Создание тестера
tester = create_default_tester(assistant)
# Запуск тестового диалога
conversation = tester.run_conversation(
test_agent_name="user",
initial_message="Добрый день! Поможете мне выбрать вино?",
max_turns=10
)
# Вывод результатов
for msg in conversation:
print(f"{msg['role']}: {msg['content']}")
Архитектура системы
Компоненты
- Agent (
app/agents/agent.py): Основной класс для управления диалогами с поддержкой function calling - RAG Service (
app/services/rag_service.py): Сервис для семантического поиска по базе знаний - Tools (
app/models/tools.py): Pydantic модели для function calling - API Routes (
app/api/routes.py): REST API endpoints - Telegram Bot (
app/telegram_bot.py): Интеграция с Telegram
Поток обработки запроса
- Пользователь отправляет сообщение
- Agent получает сообщение и проверяет историю тредов
- Отправляет запрос в Yandex Cloud AI Assistant API
- Если модель вызывает функцию - обрабатывает вызов
- Отправляет результаты функции обратно в модель
- Возвращает финальный ответ пользователю
- Сохраняет историю в тред
Конфигурация
Все настройки находятся в файле .env. Основные параметры:
API_KEY: API ключ Yandex CloudFOLDER_ID: ID каталога Yandex CloudMODEL: Модель для использованияTELEGRAM_TOKEN: Токен Telegram бота (опционально)HOST,PORT: Настройки сервера
Устранение неполадок
Ошибка подключения к API
Проблема: Error connecting to Yandex Cloud API
Решение:
1. Проверьте правильность API_KEY и FOLDER_ID в .env
2. Убедитесь, что сервисный аккаунт имеет необходимые права
3. Проверьте доступность BASE_URL
Ошибка загрузки данных
Проблема: FileNotFoundError: wine-price-ru.xlsx
Решение:
1. Убедитесь, что файл существует в data/wine-price-ru.xlsx
2. Проверьте права доступа к файлу
3. Установите openpyxl для работы с Excel: pip install openpyxl
RAG не работает
Проблема: Векторное хранилище не инициализируется
Решение:
1. Проверьте наличие файлов в data/wines.txt/ и data/regions.txt/
2. Убедитесь, что установлен chromadb и sentence-transformers
3. Проверьте логи при запуске приложения
Telegram бот не отвечает
Проблема: Бот не реагирует на сообщения
Решение:
1. Проверьте правильность TELEGRAM_TOKEN в .env
2. Убедитесь, что бот запущен (проверьте логи)
3. Проверьте, что бот не заблокирован пользователем
Разработка
Структура проекта```
.
├── app/
│ ├── agents/ # Классы агентов
│ ├── api/ # API endpoints
│ ├── models/ # Pydantic модели
│ ├── services/ # Бизнес-логика
│ ├── testing/ # Система тестирования
│ ├── config.py # Конфигурация
│ ├── main.py # FastAPI приложение
│ └── telegram_bot.py # Telegram интеграция
├── data/ # Данные (не в git)
├── .env # Переменные окружения (не в git)
├── .env.example # Пример конфигурации
├── requirements.txt # Зависимости
├── run.py # Точка входа
└── README.md # Документация
### Добавление новых функций
1. Создайте Pydantic модель в `app/models/tools.py`
2. Добавьте обработчик в `Agent._process_tool_call()`
3. Добавьте функцию в список tools при создании Agent
## Лицензия
Этот проект создан в образовательных целях.
## Демонстрация выполнения требований
### Шаг 1: Проверка Python окружения```bash
# На macOS используйте python3
python3 --version
# Должно быть: Python 3.10 или выше
# Если версия ниже 3.10, обновите Python:
# brew install python@3.12
# или используйте pyenv (см. раздел "Предварительные требования")
Шаг 2: Установка зависимостей```bash
pip install -r requirements.txt
pip list | grep -E "(fastapi|openai|pydantic)"
Должны быть установлены все пакеты
### Шаг 3: Настройка Yandex Cloud```bash
# Проверка переменных окружения
python3 -c "from app.config import settings; print(f'API Key: {\"set\" if settings.api_key else \"not set\"}'); print(f'Folder ID: {settings.folder_id}'); print(f'Model: {settings.model}')"
Шаг 4: Инициализация данных```bash
python3 init_data.py
Должен создать директории и проверить файлы
### Шаг 5: Запуск сервера```bash
python3 run.py
# Сервер должен запуститься на http://localhost:8000
Шаг 6: Проверка API```bash
В другом терминале
curl http://localhost:8000/api/v1/health
Должен вернуть статус "healthy"
### Шаг 7: Тестирование```bash
# Запуск многоагентного теста
python3 example_test.py
# Запуск API клиента
python3 example_api_client.py
Контакты
Для вопросов и предложений создайте issue в репозитории проекта.
