добавить README для веб-сервиса

README.md

@@ -8,9 +8,15 @@
 ](https://www.kaggle.com/datasets/vijayaadithyanvg/car-price-predictionused-cars/data) —
 продажа подержанных автомобилей на рынке в Индии.
 
-## Установка
+## Сервис предсказания цен
 
-### Общий порядок
+См. `services/ml_service.md`.
+
+## Исследовательская часть проекта
+
+### Установка
+
+#### Общий порядок
 
 **Внимание**: Здесь описан только общий порядок установки. Определённые части проекта могут требовать установки по отдельным инструкциям.
 
@@ -47,13 +53,13 @@
 
 5. **При необходимости** скачайте данные. Каноническое расположение для данных проекта: `data/`.
 
-### Зависимости
+#### Зависимости
 
-#### Общие зависимости
+##### Общие зависимости
 
 Зависимости — пакеты Python — записаны в файле `requirements/requirements.txt` (см. **Пакеты Python**).
 
-#### Пакеты Python
+##### Пакеты Python
 
 Установка/обновление пакетов Python в активное окружение из файла `requirements/requirements.txt`:
 
@@ -61,10 +67,10 @@
 pip install -U -r requirements/requirements.txt
 ```
 
-## Разведочный анализ данных (EDA)
+### Разведочный анализ данных (EDA)
 
 См. `eda/README.md`.
 
-## Исследование и настройка предсказательной модели
+### Исследование и настройка предсказательной модели
 
 См. `research/README.md`.

services/ml_service/README.md

@@ -0,0 +1,71 @@
+# Сервис предсказания цен
+
+Веб-сервис предсказания цен на подержанные автомобили; только stateless API. Об используемой предсказательной модели см. `research/README.md`.
+
+## API
+
+**Базовый URL**: `/api`. Все указанные далее URL записаны **относительно базового URL**, если не указано иное.
+
+* Полная интерактивная документация (Swagger UI): `/docs`.
+
+* Предсказать цену подержанного автомобиля: `/predict`.
+
+  Пример запроса:
+
+  * 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
+    }
+    ```
+
+* Тестовый эндпоинт: `/`
+
+  Возвращает простой демонстрационный объект JSON.
+
+  Может использоваться для проверки состояния сервиса.
+
+## Развёртывание
+
+### Файл модели
+
+Файл используемой предсказательной модели `model.pkl` можно извлечь из MLFlow скриптом `services/models/fetch_model_as_pickle_from_mlflow.py`. Файл модели можно разместить в директории проекта, а именно в `services/models/`.
+
+Например, извлечь модель по имени (`<model-name>`) и версии (`<model-version>`) (например, `UsedCardPricePredictionFinal/1`) (команда запускается из корневой директории проекта &mdash; от этого зависит путь к создаваемому файлу):
+
+    python services/models/fetch_model_as_pickle_from_mlflow.py --model "models:/<model-name>/<model-version>" services/models/model.pkl
+
+Можно указать адрес tracking сервера MLFlow, например: `--tracking-uri "http://localhost:5000"`.
+
+Информация о других опциях доступна:
+
+    python services/models/fetch_model_as_pickle_from_mlflow.py --help
+
+### Образ Docker
+
+Сборка образа (замените `<version>` на номер версии) (команда запускается из корневой директории проекта &mdash; от этого зависит путь к директории):
+
+    docker build -t ml_service:<version> services/ml_service/
+
+Запуск образа (замените `<version>` на номер версии образа, `<models-dir>` на **абсолютный** путь к директории, где размещён файл предсказательной модели `model.pkl`, `<port>` на порт для запуска веб-сервиса (например, `8000`)):
+
+    docker run -v "<models-dir>:/models" -p <port>:8000 ml_service:<version>
+
+Модель может быть размещена в директории проекта; тогда, например, при запуске команды из корна проекта: `$(pwd)/services/models` (здесь `$(pwd)` используется потому, что необходим абсолютный путь).