Сервис извлечения сущностей для поиска товаров

Описание

Хакатон: Лидеры цифровой трансформации 2025
Кейс: Бизнес #10
Заказчик: x5 group

Название кейса: Сервис для выделения сущностей из поискового запроса клиента в мобильном приложении сети "Пятёрочка".

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

Возможности

• 🧠 Извлечение сущностей: Автоматическое распознавание брендов, типов товаров, объемов и процентов
• 🔍 Интеллектуальный поиск: Фильтрация товаров по извлеченным сущностям
• 🚀 Микросервисная архитектура: Масштабируемое решение с разделением ответственности
• 📱 API для мобильного приложения: Готовый интерфейс для интеграции

Презентация проекта

Показать слайды презентации

Примеры работы

Запрос: "coca-cola 1.5л"
Извлеченные сущности: BRAND="coca-cola", VOLUME="1.5л"
Результат: Точный поиск товаров Coca-Cola объемом 1.5л

Запрос: "Простоквашино молоко 2.5% 930мл"
Извлеченные сущности: BRAND="Простоквашино", TYPE="молоко", PERCENTAGE="2.5%", VOLUME="930мл"
Результат: Поиск конкретного товара

Быстрый запуск

Режим хакатона (только ML-сервис NER)

Этот режим поднимает только ML-сервис извлечения сущностей (NER) на порту 8000.

1. Предварительные требования

• Установлен Docker и Docker Compose
  • Docker 24+ / Docker Desktop 4.31+ (или совместимая версия)
  • Docker Compose v2 (команда docker compose) или v1 (docker-compose)
• Открыт порт 8000 на вашей машине

2. Клонирование репозитория

git clone https://github.com/<your-org-or-user>/X5Case.git
cd X5Case

3. Запуск сервиса (фоново)

cd backend
docker-compose -f docker-compose.hackathon.yml up -d --build

• Первым запуском образ ML-сервиса соберётся из каталога ml/.
• Контейнер: ner_service_hackathon. Порт: 8000 (хост) → 8000 (контейнер).

4. Просмотр логов (опционально)

docker-compose -f docker-compose.hackathon.yml logs -f

5. Проверка готовности API Подождите 5–15 секунд после старта и выполните запрос:

curl -X POST "http://localhost:8000/api/predict" \
  -H "Content-Type: application/json" \
  -d '{"text": "coca-cola 1.5л"}'

Ожидаемый ответ: JSON со списком извлечённых сущностей (например, BRAND и VOLUME).

6. Остановка и очистка

• Остановить контейнеры:

docker-compose -f docker-compose.hackathon.yml down

• Полная очистка с удалением собранных образов (опционально):

docker-compose -f docker-compose.hackathon.yml down --rmi local --volumes --remove-orphans

7. Частые проблемы и решения

• Порт 8000 занят: остановите процесс, занимающий порт, либо измените маппинг порта в backend/docker-compose.hackathon.yml (например, - "8001:8000") и обращайтесь к http://localhost:8001.
• Медленная сборка образа: это нормально при первом запуске. Повторные запуски будут быстрее за счёт кеша.
• Проблемы с сетью при загрузке зависимостей: перезапустите команду запуска после восстановления сети.

Режим разработки (полная система)

Для демонстрации полного функционала с поиском товаров:

cd backend
docker-compose -f docker-compose.dev.yml up -d

Заполнение базы данных:

docker-compose -f docker-compose.dev.yml exec search_service \
  poetry run python scripts/seed.py

Тестирование:

curl -X GET "http://localhost:8000/api/v1/search?q=coca-cola 1.5л"

Технологический стек

Backend

• FastAPI - современный веб-фреймворк для Python
• SQLModel - ORM для работы с базой данных
• PostgreSQL - реляционная база данных
• Alembic - миграции базы данных
• Poetry - управление зависимостями

Machine Learning

• spaCy - библиотека для обработки естественного языка
• PyTorch - фреймворк машинного обучения
• uv - быстрый менеджер пакетов Python
• BIO-разметка - стандарт для извлечения именованных сущностей

Инфраструктура

• Docker - контейнеризация
• Docker Compose - оркестрация сервисов
• Микросервисная архитектура - разделение ответственности

Архитектура

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Фронтенд      │    │  API Gateway    │    │  NER Service    │
│  (мобильное     │◄──►│   (порт 8000)   │◄──►│   (порт 8001)   │
│   приложение)   │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │ Search Service  │◄──►│   PostgreSQL    │
                       │   (порт 8002)   │    │   (порт 5433)   │
                       └─────────────────┘    └─────────────────┘

Подробная документация

Для разработчиков и тех, кто хочет глубже изучить систему:

📚 Полная документация

• Детальное описание архитектуры
• Примеры использования
• Конфигурация и развертывание

🔧 API Gateway

• Эндпоинты и параметры
• Логика обработки запросов
• Парсинг BIO-разметки

🧠 NER Service

• Модель машинного обучения
• Типы сущностей
• Примеры работы

🔍 Search Service

• Модель данных
• Логика поиска и фильтрации
• База данных PostgreSQL

📊 Поток данных

• Детальная схема взаимодействия
• Преобразования данных
• Обработка ошибок

Результаты

Достигнутые метрики

(Раздел в разработке, добавить графики, F1 score, скорость работы, время обработки запроса и тп.)

• Поддерживаемые типы сущностей: BRAND, TYPE, VOLUME, PERCENTAGE

Команда

Проект разработан в рамках хакатона "Лидеры цифровой трансформации 2025" для кейса "Бизнес #10" сети "Пятёрочка".

Команда VibeBaton, всегда к Вашим услугам ;)