Разработка минимального FastAPI-сервиса

2. Pydantic-схемы запроса и ответа

Когда клиент отправляет JSON на эндпоинт, FastAPI должен понять, что именно ожидается на входе и что вернуть на выходе. Именно для этого используются Pydantic-схемы — классы, унаследованные от BaseModel, которые описывают структуру данных с типами. Для ML-сервиса обычно нужны две схемы: одна для запроса, другая для ответа.

from pydantic import BaseModel

class InputData(BaseModel):
    Store: int
    DayOfWeek: int
    Promo: int
    SchoolHoliday: int

class PredictResponse(BaseModel):
    predicted_sales: float

Здесь InputData описывает признаки, которые клиент передаёт в теле POST-запроса: номер магазина, день недели, флаг акции и школьных каникул. PredictResponse фиксирует, что в ответе будет одно поле — predicted_sales типа float. FastAPI читает аннотации типов и делает сразу несколько вещей автоматически:

• если клиент пришлёт строку вместо int в поле Store, сервер вернёт 422 Unprocessable Entity с описанием, какое именно поле некорректно;
• если поле вообще отсутствует в JSON, та же ошибка;
• схемы попадают в автодокументацию на /docs — там будет видно, какие поля обязательны и каких типов. Подключение схем к эндпоинту выглядит так:

@app.post("/predict", response_model=PredictResponse)
def predict(data: InputData):
    # data.Store, data.DayOfWeek и т.д. уже валидированы
    ... 

Параметр response_model=PredictResponse говорит FastAPI: сериализуй возвращаемый объект по этой схеме. Это значит, что если внутри функции случайно вернуть лишние поля, они будут отфильтрованы и не попадут клиенту. Важный момент: поля в InputData должны соответствовать тому, что реально приходит с фронтенда или из пайплайна. Если модель обучена на признаках Store, DayOfWeek, Promo, SchoolHoliday — именно они и должны быть в схеме, ничего лишнего. Pydantic не делает «мягкого» приведения типов для бизнес-логики — он только проверяет структуру.