From 629defd57975ca31849470caa35a80d000615fbb Mon Sep 17 00:00:00 2001 From: Georgii Zhulikov Date: Mon, 24 Mar 2025 10:40:17 +0300 Subject: [PATCH] Update API doc --- pages/api-module.md | 108 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 105 insertions(+), 3 deletions(-) diff --git a/pages/api-module.md b/pages/api-module.md index 2a7022b..3ad920e 100644 --- a/pages/api-module.md +++ b/pages/api-module.md @@ -9,7 +9,7 @@ Все API запросы работают по ссылкам вида `https://platform.stratpro.hse.ru/app-name/`. -Здесь `app-name` - название приложение, оно же указано в пункте `namespace` во всех компонентах приложения. +Здесь `app-name` - название приложения, оно же указано в пункте `namespace` во всех компонентах приложения. ## Файловый API @@ -22,8 +22,17 @@ URL запросов к файловому API имеют вид `https://platfo Файловый API позволяет загружать файлы в файловое хранилище и получать уже загруженные файлы. Загрузка папок со всем содержимым не предусмотрена, в таких случаях предполагается автоматизация запросов на загрузку отдельных файлов. +`` в запросах к файловому API может быть путём как к файлу, так и к файловой группе (папке). Тип пути определяется так: -#### Пример загрузки и скачивания файла через сервис `files`. + +1. Если путь состоит из одного сегмента, это файловая группа. `.../files/box-name/data` - путь к файловой группе `data`. +2. Если путь состоит из нескольких сегментов, и заканчивается на `/`, это путь к файловой группе. `.../files/box-name/data/images/` - путь к файловой группе `data/images`. +3. Если путь состоит более, чем из одного сегмента, и заканчивается не на `/`, это путь к файлоу. `.../files/box-name/data/images/example.png` - путь к файлу `example.png`, расположенному в файловой группе `data/images` + +Названия файлов не влияют на то, указывает ссылка на файл или на файловую группу. Например, `.../files/box-name/example.png` - это путь к файловой группе, а не файлу. + + +### Загрузка файлов через сервис `files` Для загрузки файла можно использовать следующий запрос `PUT`: @@ -57,12 +66,46 @@ curl -X PUT -T local/path/to/my_file.txt "<Длинная pre-signed ссылк Здесь `local/path/to/my_file.txt` - локальный путь к файлу. +### Скачивание файлов через сервис `files` + +Для скачивания нужно сделать запрос такого же формата, как для загрузки файла, но запрос GET. + +```sh +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:" +``` + +Ответ такой же, как при загрузке - pre-signed в формате json, но теперь на скачивание. + +```json +{ + "name": "app-name/files/box-name/my_dir/my_file.txt", + "presigned_get_url": "<Длинная pre-signed ссылка скачивания>" +} +``` + +GET-запрос к файловой группе возвращает список файлов, которые она содержит. + +```json +{ + "name": "app-name/files/box-name/my_dir/", + "files": [ + { + "name": "app-name/files/box-name/my_dir/file1.png", + "presigned_get_url": "<Длинная pre-signed ссылка скачивания>" + }, + { + "name": "app-name/files/box-name/my_dir/file2.txt", + "presigned_get_url": "<Длинная pre-signed ссылка скачивания>" + } + ] +} +``` ## ML-компонент ML-компоненты проводят расчёты при получении соответствующих запросов и присылают результат в ответе на запрос. -Каждый развёрнутый ML-компонент содержит OpenAPI спецификацию запросов к себе. Её можно получить следующим запросом: +Каждый развёрнутый ML-компонент содержит OpenAPI спецификацию с информацией о себе. Её можно получить следующим запросом: ``` curl -X GET https://platform.stratpro.hse.ru/app-name/API_NAME/modelversion -H "Content-Type: application/json" -u ":" @@ -71,6 +114,18 @@ curl -X GET https://platform.stratpro.hse.ru/app-name/API_NAME/modelversion -H " Тело запроса на выполнения расчёта - это объект с полями, которые в точности копируют поля из функции inference в [MLComponent](mlcmp.md#функция-inference). +* `inputs` - список входных данных, где каждый элемент - это словарь. Ключи словаря: + * `name` - название, произвольная строка, используется в коде модуля. Например, `"image"`. + * `datatype` - тип входных данных, одна из строк `"FP32", "FP64", "INT32", "FILE", "str", "dict"`. + * `content_type` - тип содержимого файла, если тип входной переменной `datatype` - это `"FILE"`. Обычно предполагается MIME-type. Например, `application/json`, `text/csv`. Для специализированных данных тип может быть любым - `bed`, `docx` и так далее. + * `data` - строка с путём к входному файлу или одномерный список входных данных соответствующего типа. + * `shape` - размерность входной переменной как массива, применимо даже к файлам. +* `output_fields` - список выходных данных, где каждый элемент - это словарь. Ключи словаря: + * `name`, `datatype`, `content_type` - аналогично `inputs` + * `data` - строка с путём к выходному файлу. Если передаётся `data`, результат будет записан в переданный файл. Иначе - записан во временный файл и возвращён в ответ на запрос. +* `model_parameters` - список пар `[name, value]`, произвольных параметров примитивных типов. Передаются в качестве переменной `parameters` в расчётную функцию. + + ### Пример запроса Пример тела запроса к ML-компоненту @@ -120,4 +175,51 @@ curl -X GET https://platform.stratpro.hse.ru/app-name/pipelines -H "Content-Type ``` # Получить список запусков пайплайнов curl -X GET https://platform.stratpro.hse.ru/app-name/trials -H "Content-Type: application/json" -u ":" +``` + +## Отдельный пайплайн + + +Пайпланы проводят расчёты при получении соответствующих запросов и сохраняют результаты в файлы. + +Структура запроса на запуск пайплайна: + + +``` +curl -X POST -d @data.json https://platform.stratpro.hse.ru/app-name/pipelines/PIPELINE_NAME/trials -H "Content-Type: application/json" -u ":" +``` + +Тело запроса на выполнения расчёта - это объект с полями, похожими на поля запроса к MLComponent. + + +* `inputs` - список входных данных, где каждый элемент - это словарь. Ключи словаря: + * `name` - название, произвольная строка, используется в коде модуля. Например, `"image"`. + * `datatype` - тип входных данных, одна из строк `"FP32", "FP64", "INT32", "FILE", "str", "dict"`. Должен соответствовать одному из `datatypes`, определённых в API пайплайна. + * `content_type` - тип содержимого файла, если тип входной переменной `datatype` - это `"FILE"`. Обычно предполагается MIME-type. Например, `application/json`, `text/csv`. Для специализированных данных тип может быть любым - `bed`, `docx` и так далее. + * `data` - строка с путём к входному файлу или одномерный список входных данных соответствующего типа. + * `shape` - размерность входной переменной как массива, применимо даже к файлам. +* `output_fields` - список выходных данных, где каждый элемент - это словарь. Ключи словаря: + * + * `data` - строка с путём к выходному файлу. Если передаётся `data`, результат будет записан в переданный файл. Иначе - записан во временный файл и возвращён в ответ на запрос. +* `model_parameters` - список пар `[name, value]`, произвольных параметров примитивных типов. Передаются в качестве переменной `parameters` в расчётную функцию. + + +``` +{ + "inputs": [ + { + "name": "image", + "data": "pipeline_data/input/image1.png", + "datatype": "FILE", + "content_type": "image/png", + "shape": 0 + } + ], + "output_vars": [ + { + "name": "report", + "data": "pipeline_data/output/report/" + } + ] +} ``` \ No newline at end of file