little editing

pages/api-module.md

@@ -74,7 +74,7 @@ curl -X PUT -T local/path/to/my_file.txt "<Длинная pre-signed ссылк
 curl -X GET https://platform.stratpro.hse.ru/app-name/files/box-name/my_dir/my_file.txt -H "Content-Type: application/json" -u "developer:<password>"
 ```
 
-Ответ такой же, как при загрузке - pre-signed в формате json, но теперь на скачивание.
+Ответ такой же, как при загрузке - pre-signed ссылка в формате json, но теперь на скачивание.
 
 ```json
 {

pages/components-simple.md

@@ -15,7 +15,7 @@
 
 ## Модули
 
-Фреймворк разделяет три типа модулей:
+Фреймворк работает с тремя типами модулей:
 
 1. Базовый модуль - приложение, которое решает прикладную задачу.
 2. MLOps-модуль - библиотека или набор подпрограмм, которые модифицируют работу базового модуля.
@@ -26,7 +26,7 @@
 
 ## Структура базового модуля
 
-Базовый модуль состоит из нескольких частей, которые вместе складываются в приложение.
+Базовый модуль состоит из нескольких частей, в совокупности формирующих приложение.
 
 - Git-репозиторий
   - Программный код, решающий прикладную задачу
@@ -97,7 +97,7 @@ flowchart LR
 
 ## Репозиторий
 
-Репозиторий модуля, который развёрнут на фреймворке, содержит:
+Репозиторий развернутого модуля содержит:
 
 - Исходный код проекта
 - Зависимости проекта, по которым можно воссоздать виртуальную среду для работы с ним
@@ -145,7 +145,7 @@ flowchart LR
 
 ## Образ Docker
 
-Образ Docker должен быть собран на основе файла Dockerfile из репозитория модуля.
+Docker-образ должен быть собран с помощью файла Dockerfile из репозитория модуля.
 
 Образ должен содержать только основную программу, включая интерфейс взаимодействия с фреймворком, и зависимости, необходимые для её запуска. Образ должен быть основан на `-slim` версии базового образа Python, если не требуется иное.
 
@@ -156,14 +156,16 @@ flowchart LR
 - веса ИИ-моделей
 - артефакты сборки
 
-Необходимые для работы данные нужно подключать через файловое хранилище S3:
+Данные файлы рекомендуется сразу добавить в .gitignore для упрощения работы.
+
+Необходимые для работы данные нужно загружать через файловое хранилище S3:
 
 - Для [MLComponent](./mlcmp.md) - через пункты манифеста `modelPath` и `modelBox`.
-- Для [ExperimentPipeline](./pipeline.md) - через входную переменную, к которой прописан явный путь в `mountFrom`.
+- Для [ExperimentPipeline](./pipeline.md) - через входную переменную, к которой прописан полный путь в `mountFrom`.
 
 ## DataBox
 
-Компонент [DataBox](./databox.md) позволяет модулю использовать файловое хранилище S3. В одном модуле может быть несколько таких компонентов, которые отвечают за разные виды данных. Например, данные конечных пользователей модуля (загруженные для расчётов файлы) и данные разработчика модуля (веса моделей ИИ).
+Компонент [DataBox](./databox.md) позволяет модулю использовать файловое хранилище S3. В одном модуле может быть несколько компонентов, отвечающих за разные виды данных. Например, данные конечных пользователей модуля (загруженные для расчётов файлы) и данные разработчика модуля (веса моделей ИИ).
 
 
 
@@ -203,29 +205,29 @@ flowchart TB
 
 [MLComponent](./mlcmp.md) - это компонент, который позволяет создать сервис синхронной обработки вычислительных запросов.
 
-Основной элемент кода разработчика, к которому подключается MLComponent - функция Python с заранее определённым интерфейсом ("функция inference"). В неё передаются данные, присланные пользователем, а так же модель машинного обучения, определённая в манифесте MLComponent.
+Код MLComponent обязательно должен содержать функцию, написанную на языке Python, с заранее определённым интерфейсом ("функция inference"). В неё передаются данные из запроса пользователя, а так же готовая модель машинного обучения, определённая в манифесте MLComponent.
 
 Разработчик указывает, среди прочего:
 
-- Docker-образ, который содержит реализацию функции inference
+- Docker-образ компоненты, который содержит код функции inference
-- Путь к функции inference в Docker-контейнере
+- Путь к Python-модулю функции inference в Docker-контейнере
-- Путь в Docker-контейнере по которому можно загрузить модель ИИ
+- Путь в Docker-контейнере, по которому можно загрузить модель ИИ
-- Настройки запуска Docker-контейнера - лимиты ресурсов, переменные окружения
+- Настройки запуска Docker-контейнера: лимиты ресурсов, переменные окружения и т.д.
 - Детали подключения файлового хранилища S3 к файловой системе контейнера
   - Какие компоненты DataBox используются
-  - Соответствие путей в файловом хранилище S3 путям в файловой системе контейнера
+  - Соответствие путей в файловом хранилище S3 и путей в файловой системе контейнера
 
 
 ## ExperimentPipeline
 
 Компонент [ExperimentPipeline](./pipeline.md) ("пайплайн") позволяет создать сервис для асинхронной обработки запросов пользователей.
 
-В пайплайнах основной элемент кода разработчика - это контейнер Docker. Взаимодействие контейнера с фреймворком организуется через файловую систему и переменные окружения. Входные и выходные данные монтируются в файловую систему контейнера, и локальные пути к ним передаются в контейнер как переменные окружения. Таким образом, порядок работы контейнера:
+В пайплайнах важной частью кода разработчика является описание Docker-контейнера. Взаимодействие контейнера с фреймворком организуется через файловую систему и переменные окружения. Входные и выходные данные монтируются в файловую систему контейнера, и локальные пути к ним передаются в контейнер как переменные окружения. Таким образом, порядок работы контейнера:
 
 - Считать переменные окружения, получить пути к входным данным и к папкам для размещения выходных данных.
-- Считать данные из полученных путей к входным данным
+- Считать данные, используя полученные пути к входным данным
 - Произвести вычисления
-- Сохранить результаты в полученные пути для размещения выходных данных
+- Сохранить результаты, используя полученные пути для размещения выходных данных
 
 Компонент ExperimentPipeline позволяет организовывать вычисления в несколько этапов, каждый из которых запускается со своим набором входных и выходных данных. Каждый контейнер соответствует одному этапу.
 

pages/databox.md

@@ -11,11 +11,11 @@
    2. Системные библиотеки и прочие программные зависимости
    3. Постоянные файлы настроек
 2. DataBox для данных:
-   1. Предобученные веса моделей машинного обучения.
+   1. Веса предобученных моделей машинного обучения.
    2. Большие и постоянные наборы внешних данных (например, исторические погодные данные для модуля прогноза погоды).
 3. DataBox для пользователей:
-   1. Изначально - не хранится ничего.
+   1. Изначально бокс пуст.
-   2. В ходе работы - загруженные пользователями входные данные и выданные модулем выходные данные работы ML-компонентов и пайплайнов.
+   2. В боксе хранятся загруженные пользователями входные данные и рассчитанные модулем выходные данные работы ML-компонентов и пайплайнов.
 
 Пример манифеста компонента DataBox
 
@@ -30,7 +30,7 @@ spec:
     capacity: 1G
 ```
 
-В данном примере `userdata` - это имя компонента DataBox, по которому в дальнейшем смогут обращаться другие компоненты и пользователи. Например, в [ML-компонентах](./mlcmp.md) это имя используется в разделе `connectedBoxes`.
+В данном примере `userdata` - это имя компонента DataBox, по которому к нему в дальнейшем смогут обращаться другие компоненты и пользователи. Например, в [ML-компонентах](./mlcmp.md) это имя используется в разделе `connectedBoxes`.
 
 Поле `spec.s3DefaultStorage.capacity` определяет размер выделенного под DataBox дискового пространства. Можно не указывать `capacity`, тогда поле будет выглядеть так:
 
@@ -45,22 +45,24 @@ spec:
 
 ### Файловое хранилище
 
-В файловом хранилище файлы хранятся со следующей структурой:
+В файловом хранилище имена файлов имеют следующую структуру:
 
 ```
-/my-app/userdata/users/gzhulikov/file_groups/my_file_group/file.txt
+/my-app/userdata/users/test_user/file_groups/my_file_group/file.txt
 ```
 
 Здесь:
 
-- `my-app` - имя приложения. Файлы разных приложений хранятся отдельно друг от друга, между ними нет пересечения
+- `my-app` - имя приложения. Файлы разных приложений хранятся изолированно отдельно друг от друга.
 - `userdata` - имя компонента DataBox.
 - `users` - системная часть пути, означающая "далее идут файлы, загруженные пользователями".
-- `gzhulikov` - имя пользователя, который загрузил данные
+- `test_user` - имя пользователя, который загрузил данные
 - `file_groups` - системная часть пути
 - `my_file_group` - созданная пользователем файловая группа (можно считать это "папкой" в хранилище S3)
 - `file.txt` - файл в хранилище S3
 
+Имена файлов не должны содержать пробельные и системные символы, символ *. 
+
 ### Компоненты модуля
 
 Компоненты `MLComponent` и `ExperimentPipeline` взаимодействуют с данными из хранилища S3. Это взаимодействие контролируется разделом `connectedBoxes`, а также параметром `mountFrom` в переменных пайплайнов.

pages/deployment-template.md

@@ -4,14 +4,14 @@
 
 1. Существует программа, решающая прикладные задачи. Для простоты - проект на Python. Разработчик хочет развернуть эту программу на фреймворке, чтобы через веб-запросы можно было с ней взаимодействовать. Разработчик определяет, какие из элементов программы подходят для такого взаимодействия, и какой из вариантов организации лучше подходит для каждого элемента - ML-компонент или пайплайн. Например, программа распознавания объектов может содержать ML-компонент для работы с отдельными изображениями и пайплайн для работы с видео.
 2. Разработчик реализует интерфейс взаимодействия с фреймворком, соответствующий выбранному компоненту.
-   - Для ML-компонента это функция inference.
+   - Для ML-компонента необходимо реализовать функцию inference.
-   - Для пайплайна это организация входных и выходных данных через файлы и переменные окружения.
+   - Для пайплайна необходимо организовать передачу входных и выходных данных через файлы и переменные окружения.
-   - В обоих случаях готовится образ Docker с основной программой и интерфейсом взаимодействия с фреймворком.
+   - В обоих случаях создается образ Docker с основной программой и интерфейсом взаимодействия с фреймворком.
    - Работу интерфейса можно протестировать без подключения модуля к фреймворку, запуская модуль из образа Docker.
 3. Разработчик готовит манифесты компонентов модуля и размещает их в репозитории.
-4. Приложение подключается к фреймворку с помощью системных компонентов.
+4. Приложение разворачивается на платформе с помощью системных компонентов.
 5. Разработчик загружает необходимые для работы данные в DataBox приложения, если нужно.
 6. Приложение готово к использованию.
 
-При создании приложения через личный кабинет с использованием шаблонов, приложение сразу подключается к фреймворку с базовым набором компонентов. После этого шаблонные компоненты и код необходимо заменить настоящими, соответствующими решению прикладной задачи.
+При создании приложения через личный кабинет с использованием шаблонов приложение сразу разворачивается на платформе с базовым набором компонентов. После этого шаблонные части необходимо заменить на актуальный код решения.
 

pages/introduction.md

@@ -1,18 +1,18 @@
 # Введение
 
-Фреймворк решает проблему размещения проектов в сфере искусственного интеллекта в виде веб-сервисов.
+Платформа SmartMLOps решает проблему технической сложности и ресурсозатратности размещения проектов в сфере искусственного интеллекта в виде веб-сервисов. Пользователям SmartMLOps не нужно изучать дополнительные программные решения, администрировать вычислительные ресурсы и решать вопросы безопасности.
 
-В частности:
+Пользователям платформы, в частности, доступны:
 
-- "Живая" демонстрация работы проекта на любых совместимых данных через веб-сервис
+- "Живая" демонстрация работы проекта на любых подходящих данных через веб-сервис
-- Запуск вычислительных экспериментов и их организация
+- Организация и проведение вычислительных экспериментов
 - Управление пользователями, ограничение доступа
 
 
 ## Размещаемые проекты
 
 
-Чтобы существующий проект мог быть подключен к фреймворку, в нём должна быть выделена задача с явно заданными входными и выходными данными: "получить данные A, B и C, произвести вычисления, вывести данные X, Y и Z".
+Чтобы существующий проект мог быть развернут на платформе, он должен решать задачу с явно заданными входными и выходными данными: "получить данные A, B и C, произвести вычисления, вывести данные X, Y и Z".
 
 - Хороший пример - оптическое распознавание символов. На входе изображение, на выходе текст с этого изображения.
 - Плохой пример - приложение с базой данных, где основные взаимодействия с приложением регулярно обновляют эту базу данных.
@@ -21,9 +21,9 @@
   - Хороший пример - тот же код, оформленный в виде скрипта `.py`.
 
 
-Фреймворк предоставляет два варианта организации вычислительных задач:
+Платформа предоставляет два варианта организации вычислительных задач:
 
 1. Веб-сервис для быстрых синхронных вычислений - MLComponent
 2. Асинхронный запуск вычислительных экспериментов - ExperimentPipeline
 
-Как правило, если вычислительная задача требует доли секунды для выполнения, её уместно организовывать как ML-компонент, иначе - пайплайн.
+Как правило, если вычислительная задача требует доли секунды для выполнения, её разумно организовывать как ML-компонент, иначе - как пайплайн.

pages/mlcmp.md

@@ -10,15 +10,15 @@
 
 Компонент MLComponent позволяет создать сервис для синхронной обработки запросов пользователей.
 
-MLComponent подходит для быстрых вычислений, в частности запуска предобученной модели машинного обучения на небольшой выборке данных. Например, распознавание объекта на одном изображении, классификация таблицы текстовых данных. Если алгоритм работает за доли секунды, то он подходит как основа для MLComponent.
+MLComponent подходит для быстрых вычислений, в частности, запуска предобученной модели машинного обучения на небольшой выборке данных. Например, распознавание объекта на одном изображении, классификация таблицы текстовых данных. Если алгоритм работает за доли секунды, то он подходит для создания MLComponent.
 
-На основе образа Docker, указанного в манифесте MLComponent, создаётся контейнер. В него устанавливается системная библиотека платформы, которая создаёт веб-сервис. При получении запроса от пользователя веб-сервис вызывает функцию inference, указанную в манифесте MLComponent, и передаёт вывод функции пользователю.
+На основе образа Docker, указанного в манифесте MLComponent, создаётся Docker-контейнер. В него устанавливается системная библиотека платформы, которая создаёт веб-сервис. При получении запроса от пользователя веб-сервис вызывает функцию inference, указанную в манифесте MLComponent, и передаёт вывод функции пользователю.
 
 Для добавления MLComponent к модулю разработчику нужно:
 
 - Реализовать функцию, на основе которой будет создан веб-сервис.
-- Добавить в модуль манифест компонента MLComponent
+- Добавить в модуль манифест YAML компонента MLComponent
-- Добавить в модуль манифест компонента APIComponent для обращения к MLComponent
+- Добавить в модуль манифест YAML компонента APIComponent для обращения к MLComponent
 
 Также в модуле уже должен присутствовать хотя бы один компонент DataBox и соответствующий ему APIComponent.
 
@@ -63,6 +63,8 @@ def inference(parameters: List[Dict[str, Any]],
     * `shape` - размерность выходной переменной как массива, применимо даже к файлам (не размер файла в файловой системе).
 * объект модели, который можно передать в следующий вызов функции как аргумент `model`.
 
+При этом функции inference передаются уже обработанные данные - в частности, скачанные файлы. В полях output_fields данные data заменяются на None.
+
 
 ### Docstring
 
@@ -179,7 +181,7 @@ def example_inference_func(parameters: list,
 ### Логика функции inference
 
 
-Существует набор рекомендаций и особенностей реализации функции inference. Технически функция может быть реализована любым способом, который соответствует интерфейсу, но при возможности желательно следовать рекомендациям ниже.
+В этом разделе описаны особенностей реализации функции inference и рекомендации. Технически функция может быть реализована любым способом, который соответствует интерфейсу, но при возможности желательно следовать рекомендациям ниже.
 
 #### Передача модели
 

pages/pipeline.md

@@ -19,17 +19,17 @@ ExperimentPipeline подходит для вычислительных зада
 
 Для добавления ExperimentPipeline к модулю разработчику нужно:
 
-- Добавить в модуль манифест компонента ExperimentPipeline
+- Добавить в модуль манифест YAML компонента ExperimentPipeline
-- Добавить в модуль манифест компонента APIComponent для обращения к ExperimentPipeline
+- Добавить в модуль манифест YAML компонента APIComponent для обращения к ExperimentPipeline
-- Добавить в модуль манифест компонента APIComponent для работы с пайплайнами в целом (один на все пайплайны)
+- Добавить в модуль манифест YAML компонента APIComponent для работы с пайплайнами в целом (один на все пайплайны)
 
 Также в модуле уже должен присутствовать APIComponent для работы с файлами и хотя бы один компонент DataBox.
 
 Общий принцип работы пайплайнов следующий.
 
-1. Пользователь отправляет запрос с путями ко входным и выходным данным в файловом хранилище.
+1. Пользователь отправляет запрос с путями к входным и выходным данным в файловом хранилище.
-2. Пользователь получает ответ на запрос с идентификатором запуска, по которому можно отслеживать статус выполнения пайплайна.
+2. Пользователь получает ответ, содержащий идентификатор запуска, по которому можно отслеживать статус выполнения пайплайна.
-3. Создаётся и запускается контейнер Docker
+3. Создаётся и запускается контейнер Docker.
 4. Файловое хранилище монтируется к файловой системе контейнера согласно полям манифеста ExperimentPipeline
 5. Указанные в запросе пути преобразуются в пути в локальной файловой системе и передаются в контейнер как переменные окружения.
 6. Запускается расчёт, который считывает входные данные из локальных путей, переданных в переменных окружения.
@@ -88,7 +88,7 @@ var3 --> UNIP_PIPELINE_VAR3
 
 ```
 
-Данные передаются на вход и выход пайплайна, а также между его отдельными этапами через *переменные*. Эти переменные используются в нескольких частях работы пайплайна:
+Данные передаются на вход пайплайна, а также между его отдельными этапами через *переменные*. Эти переменные используются в нескольких частях работы пайплайна:
 
 - Внутри контейнера эти переменные доступны как переменные окружения.
 - При вызове пайплайна через API эти переменные отвечают за входные и выходные данные.