documentation/pages/databox.md

Компонент DataBox и работа с файлами

DataBox

Компонент DataBox позволяет хранить данные, необходимые для работы модуля, в файловом хранилище S3.

Рекомендуемая структура расположения данных:

1. Образ Docker:
   1. Код проекта
   2. Системные библиотеки и прочие программные зависимости
   3. Постоянные файлы настроек
2. DataBox для данных:
   1. Веса предобученных моделей машинного обучения.
   2. Большие и постоянные наборы внешних данных (например, исторические погодные данные для модуля прогноза погоды).
3. DataBox для пользователей:
   1. Изначально бокс пуст.
   2. В боксе хранятся загруженные пользователями входные данные и рассчитанные модулем выходные данные работы ML-компонентов и пайплайнов.

Пример манифеста компонента DataBox

apiVersion: "unified-platform.cs.hse.ru/v1"
kind: DataBox
metadata:
  name: userdata
  namespace: my-app
spec:
  s3DefaultStorage:
    capacity: 1G

В данном примере userdata - это имя компонента DataBox, по которому к нему в дальнейшем смогут обращаться другие компоненты и пользователи. Например, в ML-компонентах это имя используется в разделе connectedBoxes.

Поле spec.s3DefaultStorage.capacity определяет размер выделенного под DataBox дискового пространства. Можно не указывать capacity, тогда поле будет выглядеть так:

spec:
  s3DefaultStorage: {}

Если capacity не указано, по умолчанию выделяется 1ГБ пространства.

Пути

Файловое хранилище

В файловом хранилище имена файлов имеют следующую структуру:

/my-app/userdata/users/test_user/file_groups/my_file_group/file.txt

Здесь:

• my-app - имя приложения. Файлы разных приложений хранятся изолированно отдельно друг от друга.
• userdata - имя компонента DataBox.
• users - системная часть пути, означающая "далее идут файлы, загруженные пользователями".
• test_user - имя пользователя, который загрузил данные
• file_groups - системная часть пути
• my_file_group - созданная пользователем файловая группа (можно считать это "папкой" в хранилище S3)
• file.txt - файл в хранилище S3

Имена файлов не должны содержать пробельные и системные символы, символ *.

Компоненты модуля

Компоненты MLComponent и ExperimentPipeline взаимодействуют с данными из хранилища S3. Это взаимодействие контролируется разделом connectedBoxes, а также параметром mountFrom в переменных пайплайнов.

Структура пути в манифестах MLComponent и ExperimentPipeline:

users/developer/file_groups/my_file_group_file.txt

Здесь:

• Имя приложения заранее известно, так как во всех компонентах уже указано, какому приложению они принадлежат
• Имя компонента DataBox указывается отдельно от пути в соответствующем поле манифеста
• Остальные компоненты пути повторяют структуру файлового хранилища, начиная с системной части пути - users

Пример:

  connectedBoxes:
    - name: model-box
      path: /home/myproject/data/weights/
      mountS3Box:
        subPath: users/developer/file_groups/models_pretrained
        s3BoxName: model-box

Здесь подключается компонент DataBox с именем model-box:

• Путь users/developer/file_groups/models_pretrained в DataBox (в хранилище S3)
• Путь /home/myproject/data/weights/ в локальной файловой системе контейнера
• Название компонента DataBox контролируется полем s3BoxName
• Название смонтированного компонента для упоминания внутри манифеста контролируется полем name. В этом примере эти два названия совпадают.

Файловый API

Доступ к файлам через API производится по ссылкам со следующей структурой

https://platform.stratpro.hse.ru/my-app/model-box/my_file_group/file.txt

Здесь:

• my-app - имя приложения
• model-box - имя DataBox, в который загружаются данные или из которого скачиваются данные
• my_file_group/file.txt путь к файлу, соответствующий пути после file_groups в хранилище
• Имя пользователя в участке пути users/USERNAME/file_groups определяется, исходя из того, реквизиты какого пользователя используются при выполнении запроса.