Рекомендательная система для пользователей московских библиотек. Решение команды Pegasus.

Данный репозиторий хранит код и документацию решения задачи Рекомендательная система для пользователей московских библиотек команды Pegasus.

API решения доступен по адресу http://178.154.240.169:5000/get_recommendations/ (отвечает в формате JSON)

Формат запроса к API, на примере ID пользователя 1: http://178.154.240.169:5000/get_recommendations/1

Веб-интерфейс решения доступен по ссылке http://178.154.240.169

Общий подход решения:

Раз в сутки запускается процесс расчёта рекомендаций, которые загружаются в базу данных.
В онлайн режиме база данных опрашивается через API или веб-интерфейс: по ID пользователя можно получить рекомендации этого пользователя, а также его историю (последние 20 полученных книг).

Мы выдаём рекомендации для всех пользователей из базы пользователей в файле readers.csv, а не только для тех 100 что были в файле dataset_knigi.xlsx.

Детальное описание:

Бекенд
Фронтенд
Рекомендательный движок
- ALS (основной)
- Item2vec (дополнительный вариант)

Бекенд

Общее описание бекенда

Бекенд реализован на Python. Разработка и тестирование велись на Python 3.8 в операционной системе Ununtu 20.04. Все необходимые зависимости для Python прописаны в файле requirements.txt в корне проекта (устанавливаются через pip).

Бекенд реализован как приложение фреймворка FastAPI.

В качестве HTTP сервера выступает Gunicorn, запускающий приложение бекенда на асинхронных воркерах uvicorn.

В качестве базы данных используется RDBMS MySQL.

Запуск бекенда

Запуск бекенда через консоль на нашем сервере (сейчас он запущен в сессии tmux):

cd /home/mos_lib_hack/mos_lib_hack

source .venv/bin/activate (в данном окружении установлены пакеты из файла requirements.txt)

gunicorn backend_server:app --bind=0.0.0.0:5000 -w 4 -k uvicorn.workers.UvicornWorker --timeout=3600

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

Адрес API (на примере ID пользователя 1): http://178.154.240.169:5000/get_recommendations/1 (GET-запрос по URL).

Формат ответа - JSON по спецификации ТЗ хакатона.

Документация API в формате OPENAPI/Swagger: http://178.154.240.169:5000/docs . Здесь же можно запустить пробные запросы к API.

Модули бекенда

Код бекенд сервера находится в корне репозитория в файле backend-server.py.

API хендлеры (работающий сейчас, а также тестовый mock) - в api/recommendations_api.py.

Дополнительные сервисы и утилиты находятся в директории services/.

За загрузку данных в базу отвечает модуль ml_pipelines.data_db_loader.

Работа с базой данных

База данных (БД) для целей хакатона размещена на том же сервере, что и бекенд, и фронтенд.

Конфигурирование БД

Необходимая конфигурация БД для загрузки больших файлов с рекомендациями и историей пользователя прописывается в файле:

interactive_timeout = 600000
wait_timeout = 600000
mysqlx_wait_timeout = 600000
mysqlx_interactive_timeout = 600000
max_allowed_packet=964M
innodb_lock_wait_timeout = 6000
innodb_rollback_on_timeout=1

После изменения файла конфигурации нужно запустить команду systemctl restart mysql.service.

При клонировании репозитория на новый сервер возможны проблемы с авторизацией в БД через питоновский драйвер. В таком случае необходимо для бекенда создать нового юзера в БД и работать в коде через него (предпочтительный вариант), либо изменить плагин юзера root на mysql_native_password.

Работа с данными в БД

Данные в базу загружаются пайплайном загрузки, размещённом в модуле ml_pipelines.data_db_loader.

Исходные файлы для загрузки в БД рекомендаций и истории пользователя - data/recommendations.csv и data/history.csv.

Эти файлы появляются в своих директориях в результате работы модели машинного обучения.

Файлы загружаются в базу mos_lib_hack, в таблицы recommendations и history. Именно к этим таблицам обращается бекенд при запросе через API или веб-интерфейс.

Фронтенд

Приложение создано для показа рекомендаций и истории пользователей библиотек.

Интерфейс

Интерфейс содержит одну страницу, на которой можно вбить id пользователя библиотеки и получить список рекомендуемых книг и историю.

Логика работы

Приложение получает id пользователя библиотеки либо из url-a при открытии страницы host/users/<user_id>, либо из формы на странице.
Делается запрос к бэкенду для получения рекомендаций и истории по id.
Полученные данные отображаются на странице.

Технологии

Для запуска фронтенда используется Docker. Docker позволяет быстро развертывать и масштабировать приложения в любой среде и сохранять уверенность в том, что код будет работать.
Приложение написано на React. React - JavaScript-библиотека для создания пользовательских интерфейсов. React предоставляет высокую скорость, простоту и масштабируемость.
В качестве веб-сервера используется Nginx. Nginx позволяет обрабатывать сотни тысяч единовременных подключений на одном физическом сервере.

Запуск приложения

Для запуска приложения нужно выполнить следующие две команды:

docker build -t client-app .
docker run -p 80:80 client-app

Структура кода

Основные файлы

Dockerfile - докерфайл для запуска приложения;
src/App.js и src/index.js - код с реализацией логики React приложения;
nginx/nginx.conf и nginx/site.conf - файлы с конфигурацией nginx.

sergei3000 / mos_lib_hack