OTUS Production Code

Описание структуры проекта и файлов развертывания

Файлы развертывания

Dockerfile.prod

Этот файл описывает, как собрать Docker-образ для продакшн-версии приложения.

Ключевые моменты:

• Базовый образ: python:3.11.4-slim-buster (облегченная версия Python 3.11.4)
• Рабочая директория: /app
• Установка переменных окружения:
  • PYTHONPATH=/app
  • FLASK_APP=src/app.py
• Копирование и установка зависимостей из requirements.txt
• Копирование всех файлов проекта в контейнер
• Открытие порта 5000
• Использование entrypoint.sh в качестве точки входа

entrypoint.sh

Этот bash-скрипт служит точкой входа для Docker-контейнера.

Последовательность действий:

1. Запуск пайплайна:

   echo "Starting pipeline"
   python3 src/pipeline.py

   Это запускает процесс обучения модели.

2. Запуск Flask-сервера:

   echo "Starting Flask server"
   flask run --host=0.0.0.0 --port=5000

   Запускает Flask-приложение, делая его доступным на всех интерфейсах контейнера на порту 5000.

Процесс развертывания

1. Docker-образ собирается с использованием Dockerfile.prod.
2. При запуске контейнера выполняется entrypoint.sh.
3. Скрипт сначала запускает пайплайн - для обучения модели.
4. Затем запускается Flask-сервер, который обслуживает API предсказаний.

Этот подход обеспечивает автоматизированное развертывание приложения в контейнере, включая подготовку модели и запуск веб-сервиса.

Описание структуры и содержания папки src

Папка src содержит основной исходный код проекта для создания и обслуживания модели машинного обучения для классификации ирисов. Проект использует Flask для создания веб-сервиса, который предоставляет предсказания на основе обученной модели.

Структура папки

src/
│
├── app.py
├── inference.py
├── pipeline.py
├── preprocessing.py
└── train.py

Описание файлов

app.py

Этот файл содержит основной сервис приложения, реализованный с использованием Flask.

Ключевые компоненты:

• Инициализация Flask-приложения
• Загрузка обученной модели
• Определение маршрутов:
  • /: Проверка работоспособности сервиса
  • /predict: Эндпоинт для получения предсказаний

Маршрут /predict принимает POST-запросы с данными об ирисе в формате JSON и возвращает предсказанный вид ириса.

inference.py

Модуль для загрузки модели и выполнения предсказаний.

Основные функции:

• load_model(model_path: str) -> BaseEstimator: Загружает модель из файла
• predict(model: BaseEstimator, df: pd.DataFrame) -> List[int]: Выполняет предсказания на новых данных

pipeline.py

Этот файл содержит основной пайплайн проекта.

Основные этапы:

1. Загрузка данных
2. Разделение данных на обучающую и тестовую выборки
3. Обучение модели
4. Сохранение модели
5. Оценка модели

preprocessing.py

Модуль для загрузки и предобработки данных.

Основные функции:

• load_data() -> pd.DataFrame: Загружает набор данных ирисов из sklearn и преобразует его в pandas DataFrame
• split_data(df: pd.DataFrame, ...) -> Tuple[pd.DataFrame, pd.DataFrame]: Разделяет данные на обучающую и тестовую выборки

train.py

Модуль для обучения и оценки модели.

Основные функции:

• train_model(train: pd.DataFrame, ...) -> RandomForestClassifier: Обучает модель случайного леса на тренировочных данных
• evaluate_model(model: RandomForestClassifier, test: pd.DataFrame) -> float: Оценивает точность модели на тестовых данных

Процесс работы

1. Скрипт pipeline.py запускает полный процесс от загрузки данных до оценки модели.
2. Обученная модель сохраняется в папке models.
3. Сервис в app.py загружает сохраненную модель и использует ее для предсказаний.

Этот проект демонстрирует полный цикл разработки модели машинного обучения: от подготовки данных и обучения модели до развертывания модели в виде веб-сервиса.

Описание CI/CD пайплайна GitHub Actions

Путь до пайплайна

.github/workflows/main.yml

Общая информация

Этот CI/CD (Continuous Integration/Continuous Deployment) пайплайн настроен для автоматизации процессов проверки кода, сборки и развертывания приложения при push-событиях в ветку main и при создании pull request'ов в эту ветку.

Переменные окружения

В пайплайне используются следующие переменные окружения, хранящиеся в секретах GitHub:

• DOCKER_HUB_USER: имя пользователя Docker Hub
• DOCKER_HUB_REPOSITORY: название репозитория в Docker Hub
• DOCKER_HUB_ACCESS_TOKEN: токен доступа к Docker Hub
• IMAGE_NAME: полное имя Docker-образа
• CONTAINER_NAME: имя контейнера для запуска на сервере
• SERVER_HOST: адрес сервера для развертывания
• SERVER_USER: имя пользователя на сервере
• SERVER_SSH_PRIVATE_KEY: приватный SSH-ключ для доступа к серверу

Также определены некоторые константы:

• PYTHON_VERSION: версия Python ('3.x')
• LINTERS: используемый линтер ('ruff')
• LINTER_CMD: команда для запуска линтера

Как пользоваться GitHub Secrets: https://docs.github.com/ru/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions

Перед запуском CI/CD пайплайна необходимо заполнить свои GitHub Secrets согласно списка переменных.

Для использования Docker Hub нужно зарегистрироваться на hub.docker.com и создать токен доступа.

Чтобы развернуть ВМ в Yandex.Cloud для проекта необходимо перейти в директорию infrastructure, заполнить свои переменные в файле terraform.tfvars и запустить terraform:

cd infrastructure
terraform init
terraform plan
terraform apply

Этапы пайплайна

1. Линтинг (Job: lint)

Этот этап выполняет проверку качества кода с помощью линтера.

Шаги:

1. Checkout кода из репозитория
2. Настройка окружения Python
3. Установка зависимостей (линтера)
4. Запуск линтера

2. Сборка (Job: build)

Этот этап отвечает за сборку Docker-образа и его публикацию в Docker Hub.

Шаги:

1. Checkout кода из репозитория
2. Сборка Docker-образа с использованием Dockerfile.prod
3. Аутентификация в Docker Hub
4. Публикация образа в Docker Hub

3. Развертывание (Job: deploy)

Этот этап выполняет развертывание приложения на удаленном сервере.

Шаги:

1. Подключение к удаленному серверу по SSH
2. Загрузка нового Docker-образа
3. Остановка и удаление старого контейнера (если существует)
4. Запуск нового контейнера

Последовательность выполнения

1. При push в ветку main или создании pull request'а в эту ветку запускается job lint.
2. Если lint прошел успешно, запускается job build.
3. После успешного выполнения build, запускается job deploy.

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

Особенности и преимущества

1. Автоматизация: Весь процесс от проверки кода до развертывания автоматизирован, что уменьшает вероятность человеческой ошибки.
2. Безопасность: Использование секретов GitHub для хранения чувствительных данных.
3. Изоляция: Использование Docker обеспечивает изоляцию приложения и его зависимостей.
4. Версионирование: Каждый образ тегируется с использованием SHA коммита, что обеспечивает четкое версионирование.
5. Быстрый откат: В случае проблем можно быстро откатиться к предыдущей версии, просто запустив контейнер с предыдущим тегом.

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

Как протестировать работу сервиса

Добавляем в Postman/Insomnia путь:

http://<внешний IP вашей ВМ>:5000/predict

Выбирает метод POST

В body передаем JSON:

{
    "sepal_length": 5.1,
    "sepal_width": 3.3,
    "petal_length": 1.7,
    "petal_width": 0.5,
}

В результате мы должны получить ответ в виде JSON:

{"prediction": "<класс ириса>"}

Дополнительные материалы

Quickstart for GitHub Actions
Документация GitHub Actions
Github Actions. Простой пример для уверенного знакомства
Строим домашний CI/CD при помощи GitHub Actions и Python