Inference API

HTTP-сервис инференса — inference_service (FastAPI, порт по умолчанию 8001). Полная OpenAPI-спецификация доступна в Swagger UI по адресу http://localhost:8001/docs при поднятом сервисе.

Эндпоинты

POST /predict

Основной эндпоинт: прогноз задержки для одного (текущая точка, целевая остановка).

  • Request — плоский JSON с фичами (то же множество полей, что и в FEATURES из features.tabular) плюс идентификаторы рейса/точки/цели.

  • Response — pred_delay_s (секунды), а также диагностика: pred_residual_s, cur_dev_s, версия модели, временные метки.

  • Латентность ~2 мс на запрос при ONNX fp32-пути.

POST /predict/batch

Батч-версия /predict: тот же контракт, но принимает массив объектов и возвращает массив предсказаний в том же порядке. Используется backend’ом для массового прогона обновлений с NDTP-потока.

GET /health

Проверка живости сервиса. Возвращает статус, загруженные модели, версию. Используется в docker healthcheck и оркестрации.

GET /metrics/model

Метрики модели: MAE/медиана/p90 на последних валидационных прогонах, таймстемпы обучения, размеры артефактов, латентность (latency_ms_p50, latency_ms_p95). Прокси backend’а в GET /metrics/model (порт 8000) возвращает то же тело с кешем на случай, если ML недоступен.

POST /whatif/predict

Точечный пересчёт задержки для одного ТС при заданной мере (scenario из add_reserve, adjust_interval, detour, signal_priority, hold_at_stop). Backend вызывает его пер-ТС в POST /whatif; при недоступности ML используется локальная эвристика MEASURE_EFFECT — форма ответа идентична.

GET /model/info, POST /reload

Административные эндпоинты: описание артефактов и hot-reload из ml/artifacts. Не используются фронтом (frontend/js/api.js их не зовёт) и не проксируются backend’ом — только оператор из Swagger.

Контракты и ошибки

  • Схемы request/response определены через pydantic-модели в inference_service — Swagger UI генерирует их автоматически.

  • Валидация полей — 422 при отсутствующих/некорректных фичах.

  • Внутренние ошибки — 500 с request_id для трассировки в логах.

Ссылки