diff --git a/README.md b/README.md index 60bca0d..ccc9fe0 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ - Базовые темы - [Введение во фреймворк](./pages/introduction.md) - - Работа с фреймворком, основные компоненты + - [Работа с фреймворком, основные компоненты](./pages/components-simple.md) - Размещение приложения на основе шаблона - Подробно - [API модулей](./pages/api-module.md) diff --git a/pages/components-simple.md b/pages/components-simple.md new file mode 100644 index 0000000..19eede5 --- /dev/null +++ b/pages/components-simple.md @@ -0,0 +1,122 @@ + +# Работа с фреймворком, обзор основных компонентов + +- [Работа с фреймворком, основные компоненты](#работа-с-фреймворком-основные-компоненты) + - [Модули](#модули) + - [Структура базового модуля](#структура-базового-модуля) + - [Репозиторий](#репозиторий) + + +## Модули + +Фреймворк разделяет три типа модулей: + +1. Базовый модуль - приложение, которое решает прикладную задачу. +2. MLOps-модуль - библиотека или набор подпрограмм, которые модифицируют работу базового модуля. +3. Модуль данных - набор данных, оформленный в соответствии с интерфейсом, который поддерживается фреймворком. + +Основной тип модулей, которые развёртываются на фреймворке - базовые. + + +## Структура базового модуля + +Базовый модуль состоит из нескольких частей, которые вместе складываются в приложение. + +- Git-репозиторий + - Программный код, решающий прикладную задачу + - Интерфейс взаимодействия с фреймворком + - Компоненты модуля + - MLComponent + - ExperimentPipeline + - APIComponent + - DataBox +- Системные компоненты, подключающие модуль к фреймворку + - Secret + - Repository + - PlatformApp +- Образы Docker + + +## Репозиторий + +Репозиторий модуля, который развёрнут на фреймворке, содержит: + +- Исходный код проекта +- Зависимости проекта, по которым можно воссоздать виртуальную среду для работы с ним +- Dockerfile +- Папку с манифестами (файлами YAML) компонентов модуля + +## Образ Docker + +Образ Docker должен быть собран на основе файла Dockerfile из репозитория модуля. + +Образ должен содержать только основную программу, включая интерфейс взаимодействия с фреймворком, и зависимости, необходимые для её запуска. Образ должен быть основан на `-slim` версии базового образа Python. + +В образе не должно быть лишних данных, таких как: + +- папка `.git` +- данные для тестов +- веса ИИ-моделей +- артефакты сборки + +Необходимые для работы данные нужно подключать через файловое хранилище S3: + +- Для [MLComponent](./mlcmp.md) - через пункты манифеста `modelPath` и `modelBox`. +- Для [ExperimentPipeline](./pipeline.md) - через входную переменную, к которой прописан явный путь в `mountFrom`. + +## DataBox + +Компонент [DataBox](./databox.md) позволяет модулю использовать файловое хранилище S3. В одном модуле может быть несколько таких компонентов, которые отвечают за разные виды данных. Например, данные конечных пользователей модуля (загруженные для расчётов файлы) и данные разработчика модуля (веса моделей ИИ). + +## MLComponent + +[MLComponent](./mlcmp.md) - это компонент, который позволяет создать сервис синхронной обработки вычислительных запросов. + +Основной элемент кода разработчика, к которому подключается MLComponent - *функция* Python с заранее определённым интерфейсом ("функция inference"). В неё передаются данные, присланные пользователем, а так же модель машинного обучения, определённая в манифесте MLComponent. + +Разработчик указывает, среди прочего: + +- Docker-образ, который содержит реализацию функции inference +- Путь к функции inference в Docker-контейнере +- Путь в Docker-контейнере по которому можно загрузить модель ИИ +- Настройки запуска Docker-контейнера - лимиты ресурсов, переменные окружения +- Детали подключения файлового хранилища S3 к файловой системе контейнера + - Какие компоненты DataBox используются + - Соответствие путей в файловом хранилище S3 путям в файловой системе контейнера + + +## ExperimentPipeline + +Компонент [ExperimentPipeline](./pipeline.md) ("пайплайн") позволяет создать сервис для асинхронной обработки запросов пользователей. + +В пайплайнах основной элемент кода разработчика - это *контейнер Docker*. Взаимодействие контейнера с фреймворком организуется через файловую систему и переменные окружения. Входные и выходные данные монтируются в файловую систему контейнера, и локальные пути к ним передаются в контейнер как переменные окружения. Таким образом, порядок работы контейнера: + +- Считать переменные окружения, получить пути к входным данным и к папкам для размещения выходных данных. +- Считать данные из полученных путей к входным данным +- Произвести вычисления +- Сохранить результаты в полученные пути для размещения выходных данных + +Компонент ExperimentPipeline позволяет организовывать вычисления в несколько этапов, каждый из которых запускается со своим набором входных и выходных данных. Каждый контейнер соответствует одному этапу. + +В самом манифесте ExperimentPipeline разработчик, помимо прочего, указывает: + +- Docker-образ, который будет запускаться + - В том числе настройки запуска - переменные окружения, лимиты ресурсов +- Входные и выходные переменные этапов + - Могут указываться детали их подключения - путь к файловом хранилище S3, путь в файловой системе контейнера +- Детали подключения файлового хранилища S3 к файловой системе контейнера + - Какие компоненты DataBox используются + - Соответствие путей в файловом хранилище S3 путям в файловой системе контейнера по умолчанию + +## APIComponent + +Компонент APIComponent предоставляет доступ к элементам модуля через API. Есть четыре основных вида компонентов APIComponent: + +1. Файловый API +2. API пайплайнов в целом +3. API отдельного MLComponent +4. API отдельного ExperimentPipeline + +Первые три вида APIComponent определяются похожим образом, и с точки зрения разработчика отличаются добавлением соответствующего поля в манифест. + +APIComponent отдельного ExperimentPipeline определяет всю структуру взаимодействия с соответствующим пайплайном через API, то есть входные и выходные переменные, их типы данных и описания. diff --git a/pages/deployment-template.md b/pages/deployment-template.md new file mode 100644 index 0000000..4912368 --- /dev/null +++ b/pages/deployment-template.md @@ -0,0 +1,17 @@ +# Размещение модуля на основе шаблона + +## Процесс подключения модуля + +1. Существует программа, решающая прикладные задачи. Для простоты - проект на Python. Разработчик хочет развернуть эту программу на фреймворке, чтобы через веб-запросы можно было с ней взаимодействовать. Разработчик определяет, какие из элементов программы подходят для такого взаимодействия, и какой из вариантов организации лучше подходит для каждого элемента - ML-компонент или пайплайн. Например, программа распознавания объектов может содержать ML-компонент для работы с отдельными изображениями и пайплайн для работы с видео. +2. Разработчик реализует интерфейс взаимодействия с фреймворком, соответствующий выбранному компоненту. + - Для ML-компонента это функция inference. + - Для пайплайна это организация входных и выходных данных через файлы и переменные окружения. + - В обоих случаях готовится образ Docker с основной программой и интерфейсом взаимодействия с фреймворком. + - Работу интерфейса можно протестировать без подключения модуля к фреймворку, запуская модуль из образа Docker. +3. Разработчик готовит манифесты компонентов модуля и размещает их в репозитории. +4. Приложение подключается к фреймворку с помощью системных компонентов. +5. Разработчик загружает необходимые для работы данные в DataBox приложения, если нужно. +6. Приложение готово к использованию. + +При создании приложения через личный кабинет с использованием шаблонов, приложение сразу подключается к фреймворку с базовым набором компонентов. После этого шаблонные компоненты и код необходимо заменить настоящими, соответствующими решению прикладной задачи. + diff --git a/pages/introduction.md b/pages/introduction.md index b31f6fc..6d09c96 100644 --- a/pages/introduction.md +++ b/pages/introduction.md @@ -1,32 +1,18 @@ -# Введение в работу с фреймворком +# Введение Фреймворк решает проблему размещения проектов в сфере искусственного интеллекта в виде веб-сервисов. -Основная модель работы предполагает, что существует проект, +В частности: -Что существует: - -- Исследовательский проект -- Подзадачи проекта, которые можно выделить в вычислительные конвейеры: "получить данные A, B и C, произвести вычисления, вывести данные X, Y и Z" - -Какие задачи может решить фреймворк: - -- "Живая" демонстрация работы проекта на любых совместимых данных +- "Живая" демонстрация работы проекта на любых совместимых данных через веб-сервис - Запуск вычислительных экспериментов и их организация -- Запуск вычислительных задач через веб-сервис - Управление пользователями, ограничение доступа -Внедрение проекта во фреймворк можно разделить на три этапа: -1. Подготовка существующего проекта -2. Реализация интерфейса взаимодействия с фреймворком -3. Настройка системных компонентов фреймворка +## Размещаемые проекты -## Подготовка проекта к внедрению во фреймворк - - -Чтобы существующий проект мог быть подключен к фреймворку, в нём должна быть выделена задача с явно заданными входными и выходными данными. +Чтобы существующий проект мог быть подключен к фреймворку, в нём должна быть выделена задача с явно заданными входными и выходными данными: "получить данные A, B и C, произвести вычисления, вывести данные X, Y и Z". - Хороший пример - оптическое распознавание символов. На входе изображение, на выходе текст с этого изображения. - Плохой пример - приложение с базой данных, где основные взаимодействия с приложением регулярно обновляют эту базу данных. @@ -35,43 +21,9 @@ - Хороший пример - тот же код, оформленный в виде скрипта `.py`. - - - - Фреймворк предоставляет два варианта организации вычислительных задач: 1. Веб-сервис для быстрых синхронных вычислений - MLComponent 2. Асинхронный запуск вычислительных экспериментов - ExperimentPipeline -Как правило, если вычислительная задача требует доли секунды для выполнения - её уместно организовывать как ML-компонент, иначе - пайплайн. - -## Структура базового модуля - -Базовый модуль - состоит из нескольких частей, которые вместе складываются в приложение, которое решает прикладную задачу. - -- Git-репозиторий - - Программный код, решающий прикладную задачу - - Включая интерфейс взаимодействия с фреймворком - - Компоненты модуля - - MLComponent - - ExperimentPipeline - - APIComponent - - DataBox -- Системные компоненты, подключающие модуль к фреймворку -- Образы Docker - -Общий принцип работы следующий: - -1. Существует программа, решающая прикладные задачи. Для простоты - проект на Python. Разработчик хочет развернуть эту программу на фреймворке, чтобы через веб-запросы можно было с ней взаимодействовать. Разработчик определяет, какие из элементов программы подходят для такого взаимодействия, и какой из вариантов организации лучше подходит для каждого элемента - ML-компонент или пайплайн. Например, программа распознавания объектов может содержать ML-компонент для работы с отдельными изображениями и пайплайн для работы с видео. -2. Разработчик реализует интерфейс взаимодействия с фреймворком, соответствующий выбранному компоненту. - - Для ML-компонента это функция inference. - - Для пайплайна это организация входных и выходных данных через файлы и переменные окружения. - - В обоих случаях готовится образ Docker с основной программой и интерфейсом взаимодействия с фреймворком. - - Работу интерфейса можно протестировать без подключения модуля к фреймворку, запуская модуль из образа Docker. -3. Разработчик готовит манифесты компонентов модуля и размещает их в репозитории. -4. Приложение подключается к фреймворку с помощью системных компонентов. -5. Разработчик загружает необходимые для работы данные в DataBox приложения, если нужно. -6. Приложение готово к использованию. - -При создании приложения через личный кабинет с использованием шаблонов, приложение сразу подключается к фреймворку с базовым набором компонентов. После этого шаблонные компоненты и код необходимо заменить настоящими, соответствующими решению прикладной задачи. +Как правило, если вычислительная задача требует доли секунды для выполнения, её уместно организовывать как ML-компонент, иначе - пайплайн.