Версионирование и документирование API

Развёртывание ИИ в производственной среде с помощью FastAPI

Matt Eckerle

Software and Data Engineering Leader

Зачем нужно версионирование API?

Эндпоинты API как позиции меню
Постоянные клиенты не должны страдать
Новые клиенты хотят новые возможности
Развивайтесь, не затрагивая существующих клиентов

Ресторан

API для облачных задач ИИ

from pydantic import BaseModel

class AIJobV1(BaseModel):
    job_name: str
    data: bytes

class AIJobV1(BaseModel):
    job_name: str
    data: bytes
    config: dict

Логотип FastAPI AI Cloud

Версионированные эндпоинты

from pydantic import BaseModel

class AIJobV1(BaseModel):
    job_name: str
    data: bytes


class AIJobV2(BaseModel):
    job_name: str
    data: bytes
    config: dict

from fastapi import FastAPI

app = FastAPI()

@app.post("/v1/ai-job")
def ai_job_v1(job: AIJobV1):
    ...


@app.post("/v2/ai-job")
def ai_job_v2(job: AIJobV2):
    ...

Когда обновлять версию эндпоинта

Критическое изменение схемы
Изменение базовой функции
- Обновлённый код модели
- Обновлённая обучающая выборка модели
- Обновлённая пред- и постобработка

Итерация с необязательными полями

Версионирование нужно не всегда
Необязательные поля позволяют добавлять данные, не нарушая схему

from pydantic import BaseModel

class AIJobV1(BaseModel):
    job_name: str
    data: bytes


from typing import Optional

class AIJobV1(BaseModel):
    job_name: str
    data: bytes
    config: Optional[dict]

Документирование API с помощью Swagger

Стандартный инструмент документирования API
- Отслеживает эндпоинты и их версии
- Основан на метаданных стандарта OpenAPI

Логотип OpenAPI

Интерфейс Swagger UI

URL Swagger Интерфейс Swagger

Swagger UI для эндпоинта

Swagger UI FastAPI для эндпоинта

Поле description в FastAPI

from fastapi import FastAPI

app = FastAPI(
    description="AI Job API"
)

Swagger UI FastAPI с заголовком описания

Давайте потренируемся!

Развёртывание ИИ в производственной среде с помощью FastAPI