From 667b6ac96655435b987585c12cf5013a3c345175 Mon Sep 17 00:00:00 2001 From: syropiatovvv Date: Mon, 8 Dec 2025 21:17:57 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B1=D0=B0=D0=B7=D0=BE=D0=B2=D0=B0?= =?UTF-8?q?=D1=8F=20=D0=B4=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82=D0=B0?= =?UTF-8?q?=D1=86=D0=B8=D1=8F=20=D0=B2=D1=81=D0=B5=D0=B3=D0=BE=20=D1=81?= =?UTF-8?q?=D0=B5=D1=80=D0=B2=D0=B8=D1=81=D0=B0=20=D0=B8=20=D1=80=D0=B0?= =?UTF-8?q?=D0=B7=D0=B2=D1=91=D1=80=D1=82=D1=8B=D0=B2=D0=B0=D0=BD=D0=B8?= =?UTF-8?q?=D1=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- services/README.md | 131 ++++++++++++++++++++++++++++++++++ services/ml_service/README.md | 71 ------------------ 3 files changed, 132 insertions(+), 72 deletions(-) create mode 100644 services/README.md delete mode 100644 services/ml_service/README.md diff --git a/README.md b/README.md index 4584903..4cf0109 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ ## Сервис предсказания цен -См. `services/ml_service/README.md`. +См. `services/README.md`. ## Исследовательская часть проекта diff --git a/services/README.md b/services/README.md new file mode 100644 index 0000000..a233418 --- /dev/null +++ b/services/README.md @@ -0,0 +1,131 @@ +# Сервис предсказания цен + +Веб-сервис предсказания цен на подержанные автомобили. Мониторинг в комплекте. + +Обзор сервисов (по `compose.yaml`, см. о развёртывании ниже): + +| Профили Compose | Имя | Объекты | Описание | +|-----------------|------------------|------------------|------------------| +| — | `prices-predictor` | код: `ml_service/` | Веб-сервис предсказания цен, только stateless API. Об используемой предсказательной модели см. `research/README.md`. | +| — | `prometheus` | конфигурация: `prometheus/` | Мониторинг сервиса ([Prometheus](https://prometheus.io/)). | +| — | `grafana` | | Аналитика и визуализация данных мониторига сервиса ([Grafana](https://grafana.com/)). | +| `with-testers` | `load-tester` | код: `load-tester/` | Генератор потока случайных запросов к `prices-predictor` для тестирования. | + +Дополнительно: + +* `models/` — расположение файла модели `model.pkl` для использования сервисом `prices-predictor`. + * `fetch_model_as_pickle_from_mlflow.py` — скрипт для экспорта предиктивной модели scikit-learn из MLFlow в файл. + +## API сервиса предсказания цен + +**Базовый URL**: `/api`. Все указанные далее URL записаны **относительно базового URL**, если не указано иное. + +* Полная интерактивная документация (Swagger UI): `/docs`. + +* Предсказать цену подержанного автомобиля: `/predict` (POST). + + Пример запроса: + + * requst query: `item_id=16` (параметр `item_id` необходим!); + + * request body: + + ```json + { + "selling_price": 5.59, + "driven_kms": 27000.0, + "age": 5.0, + "fuel_type": "petrol", + "selling_type": "dealer", + "transmission_type": "manual" + } + ``` + + * response body: + + ```json + { + "item_id": 16, + "price": 3.743508852258851 + } + ``` + +* Тестовый эндпоинт: `/` (GET). + + Возвращает простой демонстрационный объект JSON. + + Может использоваться для проверки состояния сервиса. + +## Развёртывание + +### Файл модели + +Файл используемой предсказательной модели можно извлечь из MLFlow скриптом `models/fetch_model_as_pickle_from_mlflow.py`. Файл модели можно размещается в `models/model.pkl`. + +Например, извлечь модель по имени (``) и версии (``) (например, `UsedCardPricePredictionFinal/1`) (команда запускается из корневой директории проекта — от этого зависит путь к создаваемому файлу): + + python services/models/fetch_model_as_pickle_from_mlflow.py --model "models://" services/models/model.pkl + +Можно указать адрес tracking сервера MLFlow, например: `--tracking-uri "http://localhost:5000"`. + +Информация о других опциях доступна: + + python services/models/fetch_model_as_pickle_from_mlflow.py --help + +### Образы Docker + +#### `ml_model` (для сервиса `prices-predictor`) + +**Сборка образа** (замените `` на номер версии) (команда запускается из корневой директории проекта — от этого зависит путь к директории): + + docker build -t ml_service: services/ml_service/ + +**Независимый запуск** (замените `` на номер версии образа, `` на **абсолютный** путь к директории, где размещён файл предсказательной модели `model.pkl`, `` на порт для запуска веб-сервиса (например, `8000`)): + + docker run -v ":/models" -p :8000 ml_service: + +Модель может быть размещена в `models/`; тогда, например, при запуске команды из корна проекта: `$(pwd)/services/models` (здесь `$(pwd)` используется потому, что необходим абсолютный путь). + +#### `load-tester` (для сервиса `load-tester`) + +**Сборка образа** (замените `` на номер версии) (команда запускается из корневой директории проекта — от этого зависит путь к директории): + + docker build -t load_tester: services/load_tester/ + +**Независимый запуск** (замените `` на номер версии образа, `` на базовый URL сервиса `prices-predictor` (например, `http://prices-predictor:8000/api`)): + + docker run -e "API_BASE_URL=" ml_service: + +### Развёртывание сервиса посредством Compose + +Конфигурация описана в файле `compose.yaml`. Имя системы: `mpei-iis-system`. + +Рекомендуется (не обязательно) использовать env-файл `compose.env`. Используйте файл `compose.env.template` как шаблон. + +**Директория `models/` используется сервисом `prices-predictor` как том** с файлом модели `model.pkl`. Поместите туда файл модели, см. [Файл модели](#файл-модели). + +**Управление сервисом с мониторингом** (замените `` и `[options...]`): + + docker compose -f services/compose.yaml --env-file services/compose.env [options...] + +**Для запуска вместе с генераторами тестовых запросов** используйте опцию compose `--profile=with-tester`. + +Основные команды `docker compose`: + +* `up`: создать и запустить контейнеры (также тома, сети и прочее); оставляет вывод логов прикреплённым к терминалу, `SIGINT` останавливает контейнеры, **но не удаляет созданные объекты**; + * опция `-d`: то же, но открепляет процесс от терминала. +* `down`: остановить и удалить контейнеры (также сети и прочее; для удаления томов используйте опцию `-v`). +* `start`: запустить существующие контейнеры. +* `stop`: остановить контейнеры. +* `restart`: перезапустить контейнеры. + +**Открытые на хосте интерфейсы**: + +* `localhost:8010`: Сервис `prices-predictor`. Базовый URL: `/api`. +* `localhost:9090`: UI Prometheus. +* `localhost:3000`: Grafana. + +**Доступные на хосте тома**: + +* `mpei-iis-system_prometheus-storage`: БД Prometheus. +* `mpei-iis-system_grafana-storage`: БД Grafana. diff --git a/services/ml_service/README.md b/services/ml_service/README.md deleted file mode 100644 index 89d20f4..0000000 --- a/services/ml_service/README.md +++ /dev/null @@ -1,71 +0,0 @@ -# Сервис предсказания цен - -Веб-сервис предсказания цен на подержанные автомобили; только stateless API. Об используемой предсказательной модели см. `research/README.md`. - -## API - -**Базовый URL**: `/api`. Все указанные далее URL записаны **относительно базового URL**, если не указано иное. - -* Полная интерактивная документация (Swagger UI): `/docs`. - -* Предсказать цену подержанного автомобиля: `/predict` (POST). - - Пример запроса: - - * requst query: `item_id=16` (параметр `item_id` необходим!); - - * request body: - - ```json - { - "selling_price": 5.59, - "driven_kms": 27000.0, - "age": 5.0, - "fuel_type": "petrol", - "selling_type": "dealer", - "transmission_type": "manual" - } - ``` - - * response body: - - ```json - { - "item_id": 16, - "price": 3.743508852258851 - } - ``` - -* Тестовый эндпоинт: `/` (GET). - - Возвращает простой демонстрационный объект JSON. - - Может использоваться для проверки состояния сервиса. - -## Развёртывание - -### Файл модели - -Файл используемой предсказательной модели `model.pkl` можно извлечь из MLFlow скриптом `services/models/fetch_model_as_pickle_from_mlflow.py`. Файл модели можно разместить в директории проекта, а именно в `services/models/`. - -Например, извлечь модель по имени (``) и версии (``) (например, `UsedCardPricePredictionFinal/1`) (команда запускается из корневой директории проекта — от этого зависит путь к создаваемому файлу): - - python services/models/fetch_model_as_pickle_from_mlflow.py --model "models://" services/models/model.pkl - -Можно указать адрес tracking сервера MLFlow, например: `--tracking-uri "http://localhost:5000"`. - -Информация о других опциях доступна: - - python services/models/fetch_model_as_pickle_from_mlflow.py --help - -### Образ Docker - -Сборка образа (замените `` на номер версии) (команда запускается из корневой директории проекта — от этого зависит путь к директории): - - docker build -t ml_service: services/ml_service/ - -Запуск образа (замените `` на номер версии образа, `` на **абсолютный** путь к директории, где размещён файл предсказательной модели `model.pkl`, `` на порт для запуска веб-сервиса (например, `8000`)): - - docker run -v ":/models" -p :8000 ml_service: - -Модель может быть размещена в директории проекта; тогда, например, при запуске команды из корна проекта: `$(pwd)/services/models` (здесь `$(pwd)` используется потому, что необходим абсолютный путь).