Пишем простой ML веб-сервис на FastAPI

Данный туториал пошагово разбирает процесс создания веб-приложения для определения тональности текста на основе NLP-модели.

Мы будем использовать модель из библиотеки Hugging Face Hub, но описанный подход подойдет для любой задачи машинного обучения.

План:

1. Загрузка и подготовка модели машинного обучения для использования в веб-сервисе.

2. Создание веб-сервиса с помощью FastAPI.

3. Изучение пользовательского интерфейса FastAPI для удобного ручного тестирования и демонстрации работы приложения.

4. Написание автоматических тестов с помощью библиотеки pytest.

5. Запуск приложения в Docker-контейнере.

Код доступен на GitHub.

0. Организация кода. Разделяем код ML и код приложения

Будем придерживаться следующей структуры:

Разделение пакетов ml и app помогает организовать код проекта более логично и удобно для его дальнейшей поддержки и развития.

• ml содержит код для работы с моделью машинного обучения.

• app содержит код для запуска веб-приложения.

Кроме этого, в проекте есть другие важные файлы и директории, такие как:

• tests: содержит скрипты для тестирования кода. В рамках проекта мы также будем отдельно тестировать ml-код и приложение.

• setup.py: содержит информацию о пакете и его зависимостях.

• requirements-dev.txt и requirements.txt: это списки зависимостей для локальной разработки и запуска приложения соответственно.

• Dockerfile: содержит инструкции для создания Docker-контейнера.

1. Загрузка и подготовка модели машинного обучения

Очень полезная практика оформить ML-код так, чтобы с ним можно было работать как с черным ящиком. Позже сервис будет получать всю ML-логику через функцию load_model.

В зависимости от вашей задачи, load_model будет включать:

• всю логику работы с признаками и препроцессинг,

• загрузку модели и необходимых артефактов из хранилища,

• инференс модели,

• постпроцессинг предсказаний,

• ...

Начнем с загрузки модели. В нашем примере загрузим модель cointegrated/rubert-tiny-sentiment-balanced из Hugging Face Hub:

from transformers import pipeline

model_hf = pipeline("sentiment-analysis", model="cointegrated/rubert-tiny-sentiment-balanced")

Опишем формат, который будет возвращать модель и с которым будет позже работать сервис. Для этого удобно использовать dataclass:

from dataclasses import dataclass

@dataclass
class SentimentPrediction:
    """Class representing a sentiment prediction result."""

    label: str
    score: float

Теперь главное: model - функция, которую будет вызывать сервис, чтобы получить предсказания. Она содержит всю необходимую логику с моделью, пре и пост-процессингом данных. В нашем случае model_hf - уже пайплайн, который содержит препроцессинг текста и токенизацию, инференс модели и постпроцессинг предсказаний. Мы только оставим предсказания лучшего класса и вернем ответ в виде экземпляра класса SentimentPrediction:

def model(text: str) -> SentimentPrediction:
    pred = model_hf(text)
    pred_best_class = pred[0]
    return SentimentPrediction(
        label=pred_best_class["label"],
        score=pred_best_class["score"],
    )

Теперь код, связанный с ML закончен. На этом шаге еще полезно вспомнить, что мы использовали константы при загрузке модели из HF.

Любые константы лучше выносить в отдельные конфиги, чтобы:

• иметь быстрый доступ ко всем параметрам модели,

• удобно настраивать параметры модели, не залезая в код.

В нашем случае для конфигурации будем использовать YAML-файл config.yaml:

task: sentiment-analysis
model: cointegrated/rubert-tiny-sentiment-balanced

Тогда скрипт получения модели model.py будет выглядеть следующим образом:

from dataclasses import dataclass
from pathlib import Path

import yaml
from transformers import pipeline

# load config file
config_path = Path(__file__).parent / "config.yaml"
with open(config_path, "r") as file:
    config = yaml.load(file, Loader=yaml.FullLoader)


@dataclass
class SentimentPrediction:
    """Class representing a sentiment prediction result."""

    label: str
    score: float


def load_model():
    """Load a pre-trained sentiment analysis model.

    Returns:
        model (function): A function that takes a text input and returns a SentimentPrediction object.
    """
    model_hf = pipeline(config["task"], model=config["model"], device=-1)

    def model(text: str) -> SentimentPrediction:
        pred = model_hf(text)
        pred_best_class = pred[0]
        return SentimentPrediction(
            label=pred_best_class["label"],
            score=pred_best_class["score"],
        )

    return model

Мы также добавили device=-1, чтобы модель запускалась на CPU.

2. Пишем приложение на FastAPI

Простейшее приложение на FastAPI выглядит так:

from fastapi import FastAPI

app = FastAPI()

# create a route
@app.get("/")
def index():
    return {"text": "Sentiment Analysis"}

Но, оно пока ничего не умеет делать, в частности, ничего не знает о модели, которую мы подготовили в пакете ml. Добавим загрузку модели во время старта приложения:

from ml.model import load_model

model = None

# Register the function to run during startup
@app.on_event("startup")
def startup_event():
    global model
    model = load_model()

Теперь осталось добавить предсказание модели. Для начала определим формат ответа SentimentResponse. Используем pydantic для валидации выходных данных:

from pydantic import BaseModel

class SentimentResponse(BaseModel):
    text: str
    sentiment_label: str
    sentiment_score: float

Мы будем возращать:

• text — исходный текст,

• sentiment_label — название класса, который предсказала модель,

• sentiment_score — значение скора предсказания.

Напишем GET-запрос для получения предсказания по заданному тексту. Благодаря тому, что model хранит всю логику модели внутри себя, нам достаточно передать ей сырой текст. Вспомним, что model возвращает предсказание в виде объекта класса SentimentPrediction, который мы задали ранее в пакете ml. Далее формируем ответ согласно заданному формату SentimentResponse.

# Your FastAPI route handlers go here
@app.get("/predict")
def predict_sentiment(text: str):
    sentiment = model(text)

    response = SentimentResponse(
        text=text,
        sentiment_label=sentiment.label,
        sentiment_score=sentiment.score,
    )

    return response

На этом приложение готово! Весь код app.py занял 40 строк:

from fastapi import FastAPI
from pydantic import BaseModel

from ml.model import load_model

model = None
app = FastAPI()


class SentimentResponse(BaseModel):
    text: str
    sentiment_label: str
    sentiment_score: float


# create a route
@app.get("/")
def index():
    return {"text": "Sentiment Analysis"}


# Register the function to run during startup
@app.on_event("startup")
def startup_event():
    global model
    model = load_model()


# Your FastAPI route handlers go here
@app.get("/predict")
def predict_sentiment(text: str):
    sentiment = model(text)

    response = SentimentResponse(
        text=text,
        sentiment_label=sentiment.label,
        sentiment_score=sentiment.score,
    )

    return response

3. Настраиваем окружение и запускаем тесты на ML-код

Для локального запуска в процессе разработки удобно использовать виртуальные окружения venv. Внутри виртуальных окружений можно устанавливать и использовать необходимые пакеты и библиотеки без влияния на глобальное окружение Python на системе. Создадим и активируем виртуальное окружение:

# Create a virtual environment
python3.11 -m venv env

# Activate the virtual environment
source env/bin/activate

Теперь соберем питоновский пакет, описанный в setup.py, с зависимостями из requirements.txt. Это означает, что мы создадим пакет, который будет включать в себя весь код, описанный в нашем репозитории, а также все необходимые библиотеки, указанные в файлах setup.py.

# Install/upgrade dependencies
pip install -U -e .

Следующий этап - тестирование ML-кода. Тесты помогают выявлять ошибки в коде на ранних этапах разработки, предотвращать появление новых ошибок при внесении изменений в код, а также сокращать время и затраты на тестирование вручную.

Для тестирования будет использовать библиотеку pytest. Чтобы установить эту библиотеку и другие зависимости, которые необходимы только для разработки, а не для использования проекта в продакшн-среде, мы указали их в файле requirements-dev.txt. Информация о зависимостях также прописана в файле setup.py, поэтому для их установки мы можем использовать команду:

pip install -U -e .[dev]

Тесты на код машинного обучения хранятся в test_ml.py. В данном примере у нас 3 теста, которые проверяют, корректно ли модель определяет положительную, отрицательную и нейтральную тональность в тексте:

import pytest

from ml.model import SentimentPrediction, load_model


@pytest.fixture(scope="function")
def model():
    # Load the model once for each test function
    return load_model()


@pytest.mark.parametrize(
    "text, expected_label",
    [
        ("очень плохо", "negative"),
        ("очень хорошо", "positive"),
        ("по-разному", "neutral"),
    ],
)
def test_sentiment(model, text: str, expected_label: str):
    model_pred = model(text)
    assert isinstance(model_pred, SentimentPrediction)
    assert model_pred.label == expected_label

Библиотека pytest предоставляет удобный и интуитивно понятный синтаксис для написания тестов. Здесь мы использовали:

• фикстуры — позволяют задавать начальные условия для тестов. В нашем случае, фикстура model загружает модель перед началом каждого тестового запуска.

• параметризация — задает различные значения для тестовых параметров, уменьшая необходимость в дублировании кода.

В данном случае, тест проверяет, что модель верно определяет тональность текста, и для каждого параметра (text, expected_label) проверяет соответствующее значение предсказания модели. Если значение не соответствует ожидаемому результату, тест выдает ошибку.

Для запуска тестов нужно воспользоваться командой:

pytest tests/test_ml.py

4. Запуск приложения и удобный интерфейс FastAPI

С использованием uvicorn, мы можем запустить наше приложение и обрабатывать входящие HTTP-запросы. Для запуска приложения с помощью uvicorn выполним следующую команду:

# Run app
uvicorn app.app:app --host 0.0.0.0 --port 8080

где app.app — это путь к файлу с нашим приложением, app — имя экземпляра приложения, --host — параметр, указывающий IP‑адрес, на котором будет запущен сервер (в данном случае 0.0.0.0), и --port — параметр, указывающий порт, на котором будет запущен сервер (в данном случае 8080).

После выполнения этой команды, uvicorn запустит наше приложение и начнет принимать входящие HTTP‑запросы на указанном порту. Информацию о запуске приложения мы увидим в терминале:

Откроем эту ссылку в браузере и увидим то самое сообщение, которое мы указали, когда начинали писать приложение на FastAPI.

FastAPI дополнительно предоставляет очень удобный интерфейс для отправки запросов. Он доступен, если в строке браузера добавить /docs:

Здесь можно руками потыкать приложение. Нажав на "Try it out", можно вводить любые входные данные и проверять, как отрабатывает приложение:

Использование виртуального окружения удобно для разработки и тестирования приложения на локальной машине. Далее обсудим, как запускать приложения в Docker-контейнере.

5. Запуск приложения в Docker-контейнере и тестирование приложения

Docker дает возможность упаковать приложение и запускать его на любой машине. Некоторые из его преимуществ:

1. Абстракция от хост-системы: Docker-контейнер позволяет упаковать приложение со всеми зависимостями и настройками в единый образ, который может быть запущен на любой машине, где установлен Docker.

2. Изоляция: запуск приложения в Docker-контейнере обеспечивает изоляцию от других процессов и приложений на хост-машине, что уменьшает риск взаимодействия с другими приложениями и позволяет управлять ресурсами контейнера.

3. Управление зависимостями: Docker-контейнер позволяет явно определить все зависимости и версии, необходимые для запуска приложения.

Для начального ознакомления с Docker подойдет их страница. Здесь же есть ссылки на инструкции, как установить Docker на разные системы.

Начнем с Dockerfile. Dockerfile — это текстовый файл, который содержит инструкции по созданию образа Docker. Он используется для автоматической сборки образа Docker, который включает все необходимые зависимости, настройки и код для запуска приложения в изолированном контейнере. Наш Dockerfile:

FROM python:3.11

COPY requirements.txt requirements-dev.txt setup.py /workdir/
COPY app/ /workdir/app/
COPY ml/ /workdir/ml/

WORKDIR /workdir

RUN pip install -U -e .

# Run the application
CMD ["uvicorn", "app.app:app", "--host", "0.0.0.0", "--port", "80"]

• Первая инструкция указывает, что мы хотим использовать готовый образ Python версии 3.11 как основу для создания нашего образа.

• Затем мы копируем весь рабочий код в рабочую директорию /workdir/ внутри контейнера.

• Строка WORKDIR /workdir устанавливает рабочую директорию для последующих команд в Dockerfile. Это означает, что все следующие команды в Dockerfile будут выполняться относительно этой директории.

• Далее собираем пакет, по аналогии с тем, как делали в виртуальном окружении.

• В последней строке указывается команда, которая будет выполнена при запуске контейнера: запуск приложения с помощью uvicorn на порту 80.

Создаем новый Docker-образ с именем ml-app, используя Dockerfile, находящийся в текущей директории:

docker build -t ml-app .

После того, как образ собрался, командой

docker run -p 80:80 ml-app

запускаем контейнер из образа ml-app и привязывает порт 80 внутри контейнера к порту 80 на хосте.

Контейнер будет запущен и доступен по адресу http://localhost:80 в браузере. Приложение также можно протестировать вручную, используя UI от FastAPI, как описано в предыдущем пункте.

Мы также можем написать несколько тестов для тестирования приложения, запущенного в контейнере. Будем использовать те же примеры, которые мы использовали для ML-кода. Только теперь будем отправлять HTTP-запросы в сервис, поднятый в контейнере, используя библиотеку requests.

import pytest
import requests


@pytest.mark.parametrize(
    "input_text, expected_label",
    [
        ("очень плохо", "negative"),
        ("очень хорошо", "positive"),
        ("по-разному", "neutral"),
    ],
)
def test_sentiment(input_text: str, expected_label: str):
    response = requests.get("http://0.0.0.0/predict/", params={"text": input_text})
    assert response.json()["text"] == input_text
    assert response.json()["sentiment_label"] == expected_label

Для запуска тестов можно использовать созданное нами ранее виртуальное окружение env, так как там уже стоит библиотека pytest. Тогда в другом терминале, не останавливая запущенный контейнер, запустим тесты, предварительно активировав окружение env:

source env/bin/activate
pytest tests/test_app.py

deactivate

Заключение

• В этом туториале мы создали веб-приложение для определения тональности текста с помощью FastAPI.

• Мы также коснулись важных аспектов при разработке приложения: организация кода, тестирование, конфигурация, запуск приложения в Docker-контейнере.

• Описанный подход может быть использован для любой задачи машинного обучения.

• Код приложения доступен на GitHub и его можно использовать как отправную точку для создания собственного веб-сервиса.

---

Следующую статью планирую написать про запуск ML-пайплайна с помощью Airflow. А пока подписывайтесь на мой телеграм-канал. Там будут анонсы новых статей, а также советы для работы и более короткие мысли по DS/ML/AI.