diff --git a/pages/pipeline.md b/pages/pipeline.md index c555831..04d3709 100644 --- a/pages/pipeline.md +++ b/pages/pipeline.md @@ -161,7 +161,6 @@ spec: Каждый этап работает с собственными входными и выходными данными. Переменные, определённые здесь, в пайплайне, но не определённые в API, считаются внутренними переменными. Например, в примере выше такой переменной является `model`. - ### Манифест APIComponent отдельного пайплайна Пример манифеста API пайплайна @@ -207,3 +206,109 @@ spec: ``` +Здесь, + +- `metadata.name` - название компонента API. +- `spec.published` - "включен" ли API. +- `spec.experimentPipeline` - название компонента `ExperimentPipeline`, запуску которого соответствует этот компонент API. +- `spec.apiSpec` - определение интерфейса вызова пайплайна. То есть, определение самого API. В частности, +- `inputs` - входные переменные, со следующими полями + - `name` - имя переменной, используется при вызове API, при доступе в контейнере и при определении самого пайплайна в `ExperimentPipeline`. + - `description` - описание переменной, выводится при запросе спецификации API, необязательно. + - `required` - обязательно ли передавать переменную для вызова пайплайна? По умолчанию `true`. + - `type.datatypes` - список возможных типов передаваемых данных. Подробнее ниже. + - `type.contentTypes` - список возможных типов файлов, если тип передаваемых данных - `FILE`. +- `outputs` - выходные данные. Используют те же поля, что `inputs`, со следующими отличиями: + - `required` не указывается и всегда считается `false`. Все выходные переменные необязательны. + - `type.datatypes` почти всегда равно `[ "FILE" ]`. Выходные данные передаются только файлами. Для модуля построения отчётов используется тип `website`. + +Подробнее о типах файлов в **spec.type.datatypes**. + +Потенциальные возможные типы данных - `["FP32", "FP64", "INT32", "dict", 'str', "FILE"]`. Если типа данных не указан, считаются разрешёнными все типы данных. Аналогично с типами файлов. Если `contentTypes` - это пустой список `[]`, считаются допустимыми любые типы файлов. + +Образы в любом случае должны работать **только с файлами**. Передача данных в другом виде, например в `FP32`, означает формат при вызове пайплайна через API, но не при работе с данными в контейнере модуля. + +Если данные переданы не в виде файла, они сохраняются в файл, и этот файл уже передаётся в контейнер. Данные сохраняются простым преобразованием в строку и сохранением этой строки в текстовый файл. + + +### Манифест APIComponent пайплайнов в целом + +```yaml +apiVersion: "unified-platform.cs.hse.ru/v1" +kind: APIComponent +metadata: + name: api-pipelines + namespace: pu-username-pa-bm99 +spec: + published: true + pipelines: + enabled: true + restfulApi: + auth: + basic: + credentials: bm99-apis-cred + identityPassThrough: true +``` + +Главное отличие от других APIComponent - пункт `pipelines.enabled: true`. Изменяемые разработчиком пункты - имя приложения `metadata.namespace`, имя самого компонента `metadata.name` и имя секрета с реквизитами `spec.restfulApi.auth.basic.credentials` + +### Изменение пути монтирования отдельных переменных (необязательно). + +Иногда необходимо подключить к модулю данные из файлового хранилища, которые не загружал пользователь. Частый пример - веса ИИ-моделей, которые используются при запросах всех пользователей. В таких случаях для входной переменной можно указать конкретный путь, к которому она будет подключена, вместо того, чтобы выводить её в API. + +Пример: + +```yaml +... + name: my-pipeline + namespace: pu-username-pa-bm99 +spec: + vars: + - name: xy_train + path: /data + mountFrom: + box: + name: global-data-box + boxPath: users/developer/file_groups/my_dataset + - name: xy_test + - name: extra_parameters + - name: testing_results + - name: model + + stages: + - name: stage1 + image: +... +``` + +В этом примере переменная `xy_train` монтируется напрямую к пути в ящике `global-data-box`. Таким образом, данные из этого ящика будут всегда доступны при запуске пайплайна, как будто они были переданы во входой переменной `xy_train`. + +В этом примере данные размещены в ящике `global-data-box`. Чтобы можно было к ним обратиться, нужно описать подключение ящика `global-data-box` в разделе `connectedBoxes`. + +```yaml + connectedBoxes: + - name: data-box + path: /path/to/mountpoint + default: true + mountS3Box: + s3BoxName: mymodule-data-box + - name: global-data-box + path: /path/to/another/mountpoint + default: false + mountS3Box: + s3BoxName: my-global-data-box +``` + +Общая структура примера выше: + +- В приложении есть DataBox с названием `my-global-data-box`. +- В `connectedBoxes` этот компонент подключается к пайплайну с именем `global-data-box`. Теперь во всём остальном файле для него используется имя `global-data-box`. +- Также в `connectedBoxes` указано, куда ящик `global-data-box` монтируется по умолчанию - в `/path/to/another/mountpoint`. Это означает, что по умолчанию переменные, монтируемые к ящику `global-data-box` будут соответствовать путям `/path/to/another/mountpoint/...` в файловой системе контейнера. +- Для более точного контроля в любом указании переменной (вход/выход или список `vars`) можно добавить поля: + - `path` - глобальный путь внутри контейнера. Например `/home/user/data` или просто `/data`. + - `mountFrom` - блок, указывающий расположение монтируемого пути в хранилище S3. + - `box.name` - имя ящика из раздела `connectedBoxes`, к которому монтируется переменная. + - `box.boxPath` - путь внутри S3, к которому монтируется переменная. + +При указании `boxPath` путь начинается с системных папок `users//file_groups/`, которые недоступны пользователям при запросах через файловый API. Когда пользователь `USERNAME` загружает через API файл с путём `myfolder/FILE.txt`, то в S3 этот файл появляется в `users/USERNAME/file_groups/myfolder/FILE.txt`. Соответственно, можно выделить специального системного пользователя (в примерах - `developer`), который загружает "общие" файлы, и указать в манифестах путь к этим общим файлам. Например, это могут быть файлы с весами ИИ-модели, которую использует модуль. +