Development Of Web Services With RAG MCP

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 или выше

Проверка:

# На macOS и Linux обычно используется python3
python3 --version

# На Windows может быть python
python --version

Если версия Python ниже 3.10, необходимо обновить:

Обновление Python на macOS:

Вариант 1: Через Homebrew (рекомендуется)

# Установка 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 (для управления несколькими версиями)

# Установка 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 или создайте алиас:

# Создание алиаса (добавьте в ~/.zshrc или ~/.bashrc)
alias python=python3
alias pip=pip3

Выполнение:

# Создание виртуального окружения
python3 -m venv venv

# Активация (Linux/Mac)
source venv/bin/activate

# Активация (Windows)
venv\Scripts\activate

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

Требование: Установлены все необходимые Python пакеты

Выполнение:

pip install --upgrade pip
pip install -r requirements.txt

Проверка установки:

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

1. Получение API ключа:

- В настройках сервисного аккаунта создайте авторизованный ключ - Сохраните service_account_id, key_id и private_key - Или создайте API ключ для сервисного аккаунта

1. Получение Folder ID:

- В Yandex Cloud Console перейдите в нужный каталог (folder) - Скопируйте ID каталога из URL или настроек

1. Настройка переменных окружения:

   cp .env.example .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 каталога или используйте полный путь модели.

Проверка:

# Проверка переменных окружения
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:

   mkdir -p data/wines.txt data/regions.txt

1. Поместите файл wine-price-ru.xlsx в директорию data/

1. Добавьте текстовые файлы о винах и регионах в соответствующие директории

Проверка:

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 - Следуйте инструкциям для создания бота - Сохраните полученный токен

1. Настройка в .env:

   TELEGRAM_TOKEN=your_telegram_bot_token_here

Проверка:

python3 -c "from app.config import settings; print('Telegram token:', 'set' if settings.telegram_token else 'not set')"

Установка и запуск

Полная установка

# 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 сервера

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Запуск только Telegram бота

python3 -c "from app.telegram_bot import start_telegram_bot; start_telegram_bot()"

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

После выполнения всех шагов установки, проверьте готовность системы:

# Быстрая проверка окружения
python3 check_environment.py

# Инициализация структуры данных
python3 init_data.py

Скрипт проверит:

• ✅ Наличие необходимых директорий
• ✅ Наличие файлов данных
• ✅ Корректность конфигурации

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

Документация API

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

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Примеры запросов

Отправка сообщения

curl -X POST "http://localhost:8000/api/v1/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Какое вино подходит к стейку?",
    "thread_id": "user123"
  }'

Получение истории диалога

curl "http://localhost:8000/api/v1/chat/user123/history"

Очистка истории

curl -X DELETE "http://localhost:8000/api/v1/chat/user123/history"

Python пример

import requests

# Отправка сообщения
response = requests.post(
    "http://localhost:8000/api/v1/chat",
    json={
        "message": "Какое самое дешевое красное вино из Италии?",
        "thread_id": "test_user"
    }
)

print(response.json())

Запуск примера API клиента

# Убедитесь, что сервер запущен в другом терминале
python3 example_api_client.py

Многоагентное тестирование

Система многоагентного тестирования позволяет проверить работу ассистента с помощью других AI-агентов, имитирующих пользователей.

Запуск тестового примера

python3 example_test.py

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

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']}")

Архитектура системы

Компоненты

1. Agent (app/agents/agent.py): Основной класс для управления диалогами с поддержкой function calling
2. RAG Service (app/services/rag_service.py): Сервис для семантического поиска по базе знаний
3. Tools (app/models/tools.py): Pydantic модели для function calling
4. API Routes (app/api/routes.py): REST API endpoints
5. Telegram Bot (app/telegram_bot.py): Интеграция с Telegram

Поток обработки запроса

1. Пользователь отправляет сообщение
2. Agent получает сообщение и проверяет историю тредов
3. Отправляет запрос в Yandex Cloud AI Assistant API
4. Если модель вызывает функцию - обрабатывает вызов
5. Отправляет результаты функции обратно в модель
6. Возвращает финальный ответ пользователю
7. Сохраняет историю в тред

Конфигурация

Все настройки находятся в файле .env. Основные параметры:

• API_KEY: API ключ Yandex Cloud
• FOLDER_ID: ID каталога Yandex Cloud
• MODEL: Модель для использования
• 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 окружения

# На macOS используйте python3
python3 --version
# Должно быть: Python 3.10 или выше

# Если версия ниже 3.10, обновите Python:
# brew install python@3.12
# или используйте pyenv (см. раздел "Предварительные требования")

Шаг 2: Установка зависимостей

pip install -r requirements.txt
pip list | grep -E "(fastapi|openai|pydantic)"
# Должны быть установлены все пакеты

Шаг 3: Настройка Yandex Cloud

# Проверка переменных окружения
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: Инициализация данных

python3 init_data.py
# Должен создать директории и проверить файлы

Шаг 5: Запуск сервера

python3 run.py
# Сервер должен запуститься на http://localhost:8000

Шаг 6: Проверка API

# В другом терминале
curl http://localhost:8000/api/v1/health
# Должен вернуть статус "healthy"

Шаг 7: Тестирование

# Запуск многоагентного теста
python3 example_test.py

# Запуск API клиента
python3 example_api_client.py

Контакты

Для вопросов и предложений создайте issue в репозитории проекта.