AI-помощник для покупателей в продовольственном магазине. Приложение помогает находить товары, показывает цену, наличие и местоположение на основе базы данных.
Приложения представляет собой проект на основе архитектуры MCP (Model Context Protocol), иллюстрирующий возможность использования больших языковых моделей (LLM) для обращения к внешним источникам данных. В качестве LLM здесь используются открытые популярные онлайн-модели с сайта Hugging Face (мы пробовали DeepSeek-R1-0528\Qwen3-Coder-30B-A3B-Instruct\Llama-3.1-70B-Instruct), а источником данных является SQL-БД магазина.
Основной код приложения написан на Python, интерфейс - HTML\JavaScript. БД реализована на sqlite3 в виде нескольких таблиц: products, store_sections, locations, navigation. Сложная структура БД требует написания комплексных SQL-запросов и нам хотелось продемонстрировать, что LLM под силу с этим справиться - так как именно она и составляет запрос. Для этого ей требуются знания о строении БД, а также возможность обращения к ней. Мы реализовали это с помощью библиотеки FastMCP в инструментах get_db_schema и execute_sql. Так как большинство известных LLM допускают подключение инструментов ("tools"), то мы положились на возможности LLM в самостоятельном подборе инструментов. Маршрутизация запросов к\от LLM и БД была организована с помощью собственного MCP-клиента. Процесс обработки пользовательского запроса от его ввода в терминал до окончательного ответа может быть довольно сложным и включать многократные запросы инструментов со стороны LLM; переформулированию неудачных SQL-запросов; обработки пустых, ошибочных или малоинформативных ответов БД. С помощью инструкции, переданных в LLM все это делается в автоматическом режиме - то есть LLM сама выбирает свое поведение при обработке исходного запроса. Опыт использования показал, что приемлемый ответ может быть получен даже для усложненного или ошибочного запрос.
Приложение может быть использовано в информационных терминалах в торговом зале супермаркета. Помимо информации о товаре приложение может предоставить информацию о его местонахождении. Система навигации устроена просто и может быть легко внедрена на практике: мы просто указываем нахождение отделов супермаркета опираясь на базовые ориентиры - вход, кассы, расположение у одной из стен и пр.
- Поиск товаров по названию (с обработкой опечаток)
- Информация о цене, наличии и местоположении
- Навигация по магазину
- Поддержка сложных запросов (несколько товаров)
- Работает через протокол MCP
- Не использует сторонние MCP-клиенты
- В качестве БД используется простейший вариант - база данных в формате SQLite. Реальная БД супермаркета может иметь другой формат, что потребует более сложной интеграции
- В нынешней версии приложение требует регистрации и получение токена от Hugging Face 🤗 (в настоящий момент его получение в РФ проблематично). Бесплатное пользование моделью ограничено очень небольшим ежемесячным кредитом.
- Онлайн модели с Hugging Face едва ли стоит использовать в реальном приложении, однако само подключение все равно будет онлайновое, так как установка своей LLM на каждый отдельный терминал не целесообразна
- Не все LLM допускают подключение MCP-инструментов. Это стоит учесть если будете указывать модель самостоятельно.
- Контекст модели ограничен временем между моментом ввода покупательского запроса о товаре и моментом вывода на терминал финального ответа LLM, то есть внесение уточняющей информации по товару со стороны покупателя невозможно
Проект построен на MCP-архитектуре:
- MCP Server — предоставляет инструменты для работы с БД
- Host — управляет клиентом и LLM
- Electron — интерфейс для терминала
- Python 3.11+ и
pip - Node.js 20+ и
npm - Docker (опционально, для контейнеризации)
- Hugging Face API токен (https://huggingface.co/settings/tokens)
supermarket-assistant/
├── .env # Переменные окружения
├── requirements.txt # Python-зависимости
├── create_db.py # Создание базы данных
├── mcp_server.py # MCP сервер (инструменты)
├── host.py # Класс SupermarketHost
├── main.py # FastAPI сервер
├── index.html # Интерфейс Electron
├── main.js # Electron main
├── package.json # Node.js зависимости
├── docker-entrypoint.sh # Скрипт запуска в Docker
├── Dockerfile # Для сборки образа
├── .gitignore
└── .dockerignore
pip install -r requirements.txtnpm installПри запуске приложение автоматически создает БД в случае ее отсутствия.
python create_db.pyПолучите токен к API Hugging Face. Создайте файл с переменными окружения .env в папке приложения и добавьте:
HF_TOKEN=**<ваш_токен_сюда>**
Скачайте или клонируйте репозиторий и перейдите в директорию приложения
git clone https://github.com/maresin/supermarket-assistant.git
cd supermarket-assistantВ терминале запустите основной файл бэкэнда
python main.pyОткройте другой терминал и запустите приложение Node.js
npm startПри локальном запуске из терминала приложение можно запустить в тестовом режиме. При этом приложение попытается обработать несколько заранее подготовленных пользовательских запросов по товарам.
# Запуск в тестовом режиме
python main.py --testДля запуска приложения с помощью Docker под Линукс сначала нужно получить права доступа, иначе при создании образа мы получим ошибку. Выполните эти команды по порядку:
# 1. Добавляем текущего пользователя в группу docker
sudo usermod -aG docker $USER
# 2. Применяем изменения (или просто перелогиньтесь)
newgrp docker
# 3. Проверяем, что теперь работает
docker psПосле этого ваша команда docker build должна заработать без sudo.
Сборка образа
Для сборки образа нужно перейти в папку с приложением или указать полный путь к нему. В папке с приложением должен находится скрипт для сборки Dockerfile и скрипт для запуска приложения - docker-entrypoint.sh.
# Сборка образа из папки с приложением
docker build -t supermarket-assistant .Запуск контейнера
Приложение при стартует автоматически в полноэкранном режиме
# Запуск (Linux с X11)
xhost +local:docker && \
docker run --rm -it \
-e DISPLAY=$DISPLAY \
-v /tmp/.X11-unix:/tmp/.X11-unix:rw \
--network=host \
--name assistant \
supermarket-assistant- Hugging Face Inference Providers - Supported Models
- FastMCP Framework - Get Started
- Qwen Framework - Function Calling
- Hugging Face - Qwen/Qwen3-Coder-30B-A3B-Instruct
MIT License