313 lines
21 KiB
Markdown
313 lines
21 KiB
Markdown
# Сложный пайплайн (mldev)
|
||
|
||
[MLDev](https://gitlab.com/mlrep/mldev) - программное обеспечение, упрощающее запуск воспроизводимых вычислительных экспериментов.
|
||
|
||
С помощью MLDev можно создавать более сложные вычислительные эксперименты (пайплайны) для использования на фреймворке, а также более удобно работать с обычными пайплайнами.
|
||
|
||
Принцип работы с фреймворком при помощи MLDev:
|
||
|
||
1. Разработчик создаёт манифест эксперимента, аналогичный манифесту пайплайна.
|
||
2. На основе манифеста эксперимента с помощью mldev автоматически генерируется манифест пайплайна и собираются docker-образы.
|
||
3. Разработчик добавляет сгенерированный манифест пайплайна и docker-образы к модулю как при обычном создании пайплайна.
|
||
|
||
|
||
- [Подготовка элементов mldev](#подготовка-элементов-mldev)
|
||
- [config.yaml](#configyaml)
|
||
- [stages.py](#stagespy)
|
||
- [experiment-unip-pipeline.yaml](#experiment-unip-pipelineyaml)
|
||
- [unip-pipeline.yaml](#unip-pipelineyaml)
|
||
- [UnipPipeline](#unippipeline)
|
||
- [ContainerStage](#containerstage)
|
||
- [build](#build)
|
||
- [code](#code)
|
||
- [BasicStage](#basicstage)
|
||
- [MLOps-модули](#mlops-модули)
|
||
|
||
|
||
# Подготовка элементов mldev
|
||
|
||
В примере далее рассматривается следующая структура файлов, относящихся к MLDev.
|
||
|
||
```
|
||
experiments
|
||
├── .mldev
|
||
│ ├── config.yaml
|
||
│ └── stages.py
|
||
├── experiment-unip-pipeline.yaml
|
||
└── unip-pipeline.yaml
|
||
```
|
||
|
||
- `config.yaml` - настройки MLDev, такие как параметры запуска, уровень логирования и шаблон названия docker-образов.
|
||
- `stages.py` - загрузка используемых компонентов MLDev с помощью выражения `import`.
|
||
- `experiment-unip-pipeline.yaml` - mldev-пайплайн сборки эксперимента, запускаемый разработчиком.
|
||
- `unip-pipeline.yaml` - основной пайплайн, используется пайплайном сборки для построения вычислительного эксперимента.
|
||
|
||
## config.yaml
|
||
|
||
Пример содержимого `config.yaml`:
|
||
|
||
```yaml
|
||
logger:
|
||
level: DEBUG
|
||
extras:
|
||
base: mldev.experiment_objects
|
||
containers: mldev_containers.containers
|
||
environ:
|
||
IMAGE_TAG_TEMPLATE: 'platform-reg.stratpro.hse.ru/myproject/${name}:${revision}'
|
||
UNIP_MLDEV_PIPELINE_OUTPUT: ./build/pipelines
|
||
EXPERIMENT_FILE: ./experiments/unip-pipeline.yaml
|
||
FORCE_RUN: True
|
||
```
|
||
|
||
- `logger.level` - уровень логирования, `DEBUG`, `INFO` или `ERROR`.
|
||
- `extras` - дополнительные модули MLDev, необходимые для взаимодействия с фреймворком.
|
||
- `environ` - переменные окружения
|
||
- `IMAGE_TAG_TEMPLATE` - шаблон названия образа Docker. `${name}` будет автоматически заменено на название этапа из файла эксперимента, а `${revision}` - на короткий хэш последнего коммита в репозитории проекта
|
||
- `UNIP_MLDEV_PIPELINE_OUTPUT` - путь, куда будет сохранён сгенерированный манифест пайплайна для фреймворка
|
||
- `EXPERIMENT_FILE` - файл с вычислительным экспериментом
|
||
- `FORCE_RUN` - параметр, заставляющий MLDev собирать эксперимент заново, даже если не найдено изменений с прошлой сборки
|
||
|
||
|
||
## stages.py
|
||
|
||
Пример файла `stages.py`:
|
||
|
||
```python
|
||
from mldev_containers import ContainerStage, StageCode, StageVar
|
||
from unip.mldev_pipeline.unip_pipeline import UnipPipeline
|
||
from unip.mldev_pipeline.dataloader import StageSrc
|
||
```
|
||
|
||
- `UnipPipeline`, `StageCode`, `StageVar`, `ContainerStage` - классы компонентов, необходимых для работы с пайплайнами
|
||
- `StageSrc` - класс подключения модуля данных
|
||
|
||
Аналогично модулю данных в примере, для подключения других специализированных этапов, таких как подключение к суперкомпьютеру cHARISMa и автоматическая генерация отчёта об эксперименте, необходимо добавлять соответствующие классы в `stages.py`.
|
||
|
||
|
||
## experiment-unip-pipeline.yaml
|
||
|
||
В этом файле определяется небольшой вычислительный эксперимент MLDev, в результате которого должен быть собран полноценный эксперимент из файла `unip-pipeline.yaml`.
|
||
|
||
Здесь определяются параметры запуска и переменные окружения полноценного эксперимента, а также добавляются вспомогательные команды.
|
||
|
||
Пример файла `experiment-unip-pipeline.yaml`
|
||
|
||
```yaml
|
||
pipeline: !GenericPipeline
|
||
runs:
|
||
- !BasicStage
|
||
name: experiment
|
||
env:
|
||
PYTHONPATH: './experiments/.mldev'
|
||
MLDEV_CONFIG_PATH: './experiments/.mldev/config.yaml'
|
||
PIP_EXTRA_INDEX_URL: '${env.PIP_EXTRA_INDEX_URL}'
|
||
script:
|
||
- mkdir -p ./build/containers
|
||
- mkdir -p ./build/pipelines
|
||
- rm -rf ./build/containers/*
|
||
- rm -rf ./build/pipelines/*
|
||
- mldev run pipeline -f ./experiments/unip-pipeline.yaml
|
||
|
||
```
|
||
|
||
- `pipeline: !GenericPipeline` - указывает, что это объект класса `GenericPipeline` - стандартный пайплайн библиотеки MLDev, не относящийся к фреймворку.
|
||
- `runs` - список этапов, которые будут выполнены в ходе выполнения пайплайна GenericPipeline
|
||
- `!BasicStage` - указывает, что текущий этап - это объект класса `BasicStage`, стандартного класса этапа пайплайна в MLDev.
|
||
- `name: experiment` - имя этапа. Не используется далее
|
||
- `env:` - переменные окружения, с которыми запускается этап сборки полноценного пайплайна,
|
||
- `PYTHONPATH` - чтобы модули MLDev, импортированные в файле `stages.py` были загружены, нужно указать в PYTHONPATH путь к папке с этим файлом. В данном примере, `./experiments/.mldev`
|
||
- `MLDEV_CONFIG_PATH` - путь к используемому в полноценном эксперименте файлу настроек MLDev.
|
||
- `PIP_EXTRA_INDEX_URL` - дополнительные индексы для установки пакетов Python. Используются для установки пакетов фреймворка, которые не размещены в индексе PyPI. Значение `'${env.PIP_EXTRA_INDEX_URL}'` означает, что переменная окружения `PIP_EXTRA_INDEX_URL` копирует содержимое такой же переменной из среды, которая запускает эксперимент.
|
||
- `script` = команды, которые выполяются в текущем этапе `experiment`. В данном примере это создание папок `./build/containers` и `./build/pipelines`, удаление их содержимого и запуск сборки полноценного пайплайна.
|
||
|
||
|
||
## unip-pipeline.yaml
|
||
|
||
Этот файл полностью описывает вычислительный эксперимент, аналогично компоненту `ExperimentPipeline`.
|
||
|
||
### UnipPipeline
|
||
|
||
Основной объект вычислительного эксперимента, который должен быть определён в файле `unip-pipeline.yaml` - это объект `pipeline:!UnipPipeline` со следующей структурой:
|
||
|
||
```yaml
|
||
pipeline: !UnipPipeline
|
||
name: my-project
|
||
namespace: pu-username-pa-appname
|
||
variables:
|
||
- name: preparation_data
|
||
- name: internal_state
|
||
- name: user_report
|
||
runs:
|
||
- *container_stage_prepare
|
||
- *container_stage_complete
|
||
connected_boxes:
|
||
- name: user-box
|
||
path: /userdata/
|
||
default: true
|
||
mount_s3_box:
|
||
s3_box_name: users
|
||
```
|
||
|
||
- `name: my-project` - имя, которое будет использовано далее при генерации имени компонента `ExperimentPipeline`.
|
||
- `namespace` - пространство имён приложения, аналогично с остальными манифестами компонентов.
|
||
- `variables` - список переменных, которые используются во всех этапах, вместе взятых. Аналогично `ExperimentPipeline`. Для каждой переменной помимо поля `name` можно указать поля `path` (точка монтирования в контейнере) и `mountFrom` (DataBox и точка монтирования в хранилище S3).
|
||
- `runs` - список этапов пайплайна. В примере - ссылки на отдельно определённые компоненты.
|
||
- `connected_boxes` - раздел, полностью аналогичный такому же разделу в `ExperimentPipeline` - определение связанных компонентов `DataBox`, указание пути монтирования по умолчанию и внутреннего имени DataBox, которое используется в этом файле далее. В отличие от `ExperimentPipeline`, где используется camelCase, здесь используется snake_case.
|
||
|
||
### ContainerStage
|
||
|
||
Отдельный этап пайплайна `UnipPipeline` - это `ContainerStage`. Такой этап соответствует этапу `ExperimentPipeline`.
|
||
|
||
|
||
```yaml
|
||
container_stage_prepare: !ContainerStage &container_stage_prepare
|
||
name: my-prepare
|
||
base_image: platform-reg.stratpro.hse.ru/my_org/myproject-prepare:718e2b0
|
||
stage: *stage_prepare
|
||
build:
|
||
<<: *build
|
||
code: *code
|
||
env:
|
||
MY_CUSTOM_FLAG: "True"
|
||
resource_limits:
|
||
cpu: "1"
|
||
memory: 500M
|
||
```
|
||
|
||
- `container_stage_prepare: !ContainerStage &container_stage_prepare`:
|
||
- `container_stage_prepare:` - корень объекта этапа
|
||
- `!ContainerStage` - класс, на основе которого будет создан этап
|
||
- `&container_stage_prepare` - имя, по которому на этот этап можно ссылаться. Это имя используется в `UnipPipeline`
|
||
- `my-prepare` - название этапа. Используется как название этапа в `ExperimentPipeline` и в названии Docker-образа
|
||
- `base_image` - образ Docker, на основе которого будет создан этап. Это может быть как стандартный образ вида `python:3.11.10-slim-bullseye`, так и образ, загруженный в реестр фреймворка вида `platform-reg.stratpro.hse.ru/my_org/myproject-prepare:718e2b0`.
|
||
- `stage: *stage_prepare` - объект вида `BasicStage`, в котором определяются входные, выходные данные и точка входа, запускающая вычисления.
|
||
- `build` - параметры сборки Docker-образа, здесь определяются отдельным объектом.
|
||
- `code` - объект типа `StageCode`, который определяет устанавливаемые через `requirements.txt` зависимости, а также файл с исходным кодом проекта, добавляемые в контейнер.
|
||
- `env` - набор произвольных переменных окружения, которые будут установлены при запуске контейнера.
|
||
- `resource_limits` - лимиты ресурсов в терминах Kubernetes, аналогично `ExperimentPipeline`.
|
||
|
||
#### build
|
||
|
||
В данном определении используется несколько ссылок на внешние объекты. Объект `build` имеет структуру
|
||
|
||
```yaml
|
||
build_params: &build
|
||
root: .
|
||
output: build/containers
|
||
```
|
||
|
||
Это означает, что корнем сборки Docker-контейнера выступает корень репозитория, а сгенерированные скрипты сборки и Dockerfile-ы появятся в папке `build/containers` в репозитории.
|
||
|
||
#### code
|
||
|
||
Объект `StageCode` имеет структуру
|
||
|
||
```yaml
|
||
code: !StageCode &code
|
||
requirements: ./requirements.txt
|
||
src:
|
||
- ./myproject/
|
||
- ./my_static_config.json
|
||
- ./.mldev/
|
||
- ./experiments/unip-pipeline-paper.yaml
|
||
```
|
||
|
||
- Это объект типа `StageCode`, на который далее можно ссылаться по имени `code`.
|
||
- `requirements` - файл с зависимостями, который будет скопировать в контейнер и использован для установки зависимостей
|
||
- `src` - список файлов или папок, которые будут скопированы в рабочую директорию контейнера. По умолчанию это `/unip`.
|
||
|
||
Объект `StageCode` предполагает единый проект, даже если в его рамках запускаются разные файлы. Если несколько контейнеров объединяются в один пайплайн с разными `StageCode`, то в результате сгенерируется несколько объектов `ExperimentPipeline`, составляющих цепочку запуска.
|
||
|
||
#### BasicStage
|
||
|
||
Объект `BasicStage` определяет входные, выходные данные этапа пайплайна, а также точку входа.
|
||
|
||
```yaml
|
||
stage_prepare: !BasicStage &stage_prepare
|
||
name: stage_prepare
|
||
inputs:
|
||
- !StageVar
|
||
name: preparation_data
|
||
path: ./data/preparation
|
||
outputs:
|
||
- !StageVar
|
||
name: internal_state
|
||
script:
|
||
- python src/prepare.py
|
||
```
|
||
|
||
- `stage_prepare: !BasicStage &stage_prepare` - аналогично предыдущим компонентам, объект `stage_prepare` класса `BasicStage`, на который можно ссылаться как `stage_prepare`.
|
||
- `name` - название этапа
|
||
- `inputs` - список входных переменных
|
||
- `!StageVar` - переменная типа `StageVar`. Это обычный тип переменных по умолчанию, аналогичный переменным `ExperimentPipeline`.
|
||
- `name` - название переменной, используется далее в пайплайне и в контейнере.
|
||
- `path` - путь монтирования переменной внутри контейнера. Если передан относительный путь, он рассчитывается от рабочей директории контейнера - `/unip`.
|
||
- `outputs` - аналогично `inputs`
|
||
- `script` - точка входа в этап эксперимента.
|
||
- При этом точкой входа в контейнер будет команда MLDev `mldev run stage_prepare -f /unip/experiments/unip-pipeline.yaml`, а уже запущенный ей процесс выполнит команду из поля `script`.
|
||
|
||
# Сборка пайплайна
|
||
|
||
## Запуск сборки
|
||
|
||
Чтобы запустить сборку пайплайна нужно выполнить следующие условия:
|
||
|
||
1. В `PATH` доступна команда `mldev`. Например, в используемой виртуальной среде установлен пакет Python `mldev`.
|
||
2. В переменной окружения `PIP_EXTRA_INDEX_URL` указаны ссылки на используемые реестры пакетов Python фреймворка с указанием рекизитов.
|
||
|
||
Дополнительные индексы пакетов Python указываются в формате
|
||
|
||
```sh
|
||
export PIP_EXTRA_INDEX_URL="https://my_username:mypassword_or_token_abcdef1234@platform-forgejo.stratpro.hse.ru/api/packages/MY_ORG/pypi/simple https://my_username:mypassword_or_token_abcdef1234@platform-forgejo.stratpro.hse.ru/api/packages/ANOTHER_ORG/pypi/simple"
|
||
```
|
||
|
||
Общий набор команд для сборки эксперимента mldev может быть примерно такой:
|
||
|
||
```sh
|
||
cd /home/my_username/MLOPS/my_project/
|
||
export PIP_EXTRA_INDEX_URL="https://my_username:mypassword_or_token_abcdef1234@platform-forgejo.stratpro.hse.ru/api/packages/MY_ORG/pypi/simple https://my_username:mypassword_or_token_abcdef1234@platform-forgejo.stratpro.hse.ru/api/packages/ANOTHER_ORG/pypi/simple"
|
||
source venv/bin/activate
|
||
mldev run -f experiments/experiment-unip-pipeline-paper.yaml
|
||
```
|
||
|
||
После завершения сборки в корневой папке проекта должна появиться следующая структура:
|
||
|
||
```
|
||
/build
|
||
├── containers
|
||
│ ├── my-complete.dockerfile
|
||
│ ├── my-complete.dockerignore
|
||
│ ├── my-complete.sh
|
||
│ ├── my-prepare.dockerfile
|
||
│ ├── my-prepare.dockerignore
|
||
│ └── my-prepare.sh
|
||
└── pipelines
|
||
└── my-project-qzv828.yaml
|
||
```
|
||
|
||
Здесь в `containers` хранятся файлы, используемые для сборки контейнеров отдельных этапов, а в `pipelines` - сгенерированный манифест `ExperimentPipeline`. Сами собранные образы этапов должны быть доступны в Docker, например, видны в команде `docker images`.
|
||
|
||
## Подключение к базовому модулю
|
||
|
||
Чтобы подключить сгенерированный манифест `ExperimentPipeline` к фреймворку, следует его переименовать, изменить в содержимом манифеста поле `name` на желаемое название пайплайна и поместить манифест в папку `app` в репозитории.
|
||
|
||
Компонент `APIComponent` не генерируется при сборке пайплайна MLDev, его нужно создать вручную.
|
||
|
||
Собранные образы Docker нужно загрузить в репозиторий образов в Harbor.
|
||
|
||
## Разделение на несколько пайплайнов
|
||
|
||
`ExperimentPipeline` поддерживает последовательный запуск нескольких пайплайнов - [подробнее здесь](./split-pipeline.md).
|
||
|
||
Во время сборки эксперимента через MLDev этапы с разными объектами `StageCode` считаются достаточно сильно отличными друг от друга. Такие этапы разделяются в отдельные объекты `ExperimentPipeline` и связываются через `continueWith`.
|
||
|
||
|
||
# MLOps-модули
|
||
|
||
MLOps-модули фреймворка и некоторые другие дополнительные возможности работают за счёт замены стандартных классов `ContainerStage`, `BasicStage` и `StageVar` на свои варианты.
|
||
|
||
Например:
|
||
|
||
- `CharismaStage` вместо `ContainerStage` позволяет отправить вычислительную задачу на суперкомпьютер cHARISMa.
|
||
- `StageSrc` вместо `StageVar` позволяет использовать данные из модуля данных.
|
||
- `Report` вместо `BasicStage` позволяет сгенерировать отчёт о проведённом вычислительном эксперименте.
|