创建算法 - CreateAlgorithm

功能介绍

创建算法接口用于在ModelArts平台上创建一个新的算法。

该接口适用于以下场景：当用户需要将自定义的算法模型上传至平台并进行管理时，可以通过此接口创建算法。使用该接口的前提条件是用户已准备好算法代码和相关配置文件，并上传至ModelArts平台，或用户已构建好自定义的镜像并上传至ModelArts平台。平台将在验证代码路径及相关配置正确后，将其添加到算法列表中。若算法代码路径或相关配置不完整、格式错误或用户无权限操作，接口将返回相应的错误信息。

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。

如果使用角色与策略授权，具体权限要求请参见权限和授权项。
如果使用身份策略授权，需具备如下身份策略权限。

授权项

访问级别

资源类型（*为必须）

条件键

别名

依赖的授权项

modelarts:aiAlgorithm:create

Write

aiAlgorithm *

-

-

-

授权项	访问级别	资源类型（*为必须）	条件键	别名	依赖的授权项
modelarts:aiAlgorithm:create	Write	aiAlgorithm *	-	-	-

URI

POST /v2/{project_id}/algorithms

表1 路径参数
参数	是否必选	参数类型	描述
project_id	是	String	参数解释：用户项目ID。获取方法请参见获取项目ID和名称。约束限制：1 - 64字符，字母、数字和中划线。取值范围：不涉及。默认取值：不涉及。

请求参数

表2 请求Body参数
参数	是否必选	参数类型	描述
metadata	否	AlgorithmMetadata object	参数解释：算法的元数据，描述算法基本信息。约束限制：不涉及。
job_config	否	AlgorithmJobConfig object	参数解释：算法配置信息，如启动文件等。约束限制：不涉及。
resource_requirements	否	Array of ResourceRequirement objects	参数解释：算法资源约束。可不设置。设置后，在算法使用于训练作业时，控制台会过滤可用的公共资源池。约束限制：不涉及。
advanced_config	否	AlgorithmAdvancedConfig object	参数解释：算法高级策略： auto_search 约束限制：不涉及。

表3 AlgorithmMetadata
参数	是否必选	参数类型	描述
id	否	Integer	参数解释：算法id，创建算法时无需填写。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
name	是	String	参数解释：算法名称。约束限制：限制为1-64位只含数字、字母、下划线和中划线的名称。取值范围：不涉及。默认取值：不涉及。
description	否	String	参数解释：对算法的描述。约束限制：字符串的长度限制为[0, 256]。取值范围：不涉及。默认取值：默认为“NULL”。
workspace_id	否	String	参数解释：指定算法所处的工作空间。约束限制：不涉及。取值范围：不涉及。默认取值：默认值为“0”。“0” 为默认的工作空间。
ai_project	否	String	参数解释：指定算法所属的ai项目。ai项目已下线，无需关注。约束限制：不涉及。取值范围：不涉及。默认取值：默认值为"default-ai-project"。

表4 AlgorithmJobConfig
参数	是否必选	参数类型	描述
code_dir	否	String	参数解释：算法的代码目录。如：“/usr/app/”。约束限制：应与boot_file一同出现。取值范围：不涉及。默认取值：不涉及。
boot_file	否	String	参数解释：算法的代码启动文件，需要在代码目录下。如：“/usr/app/boot.py”。约束限制：应与code_dir一同出现。取值范围：不涉及。默认取值：不涉及。
command	否	String	参数解释：自定义镜像算法的容器启动命令。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
parameters	否	Array of Parameters objects	参数解释：算法的运行参数。约束限制：不涉及。
inputs	否	Array of AlgorithmCreateInput objects	参数解释：算法的数据输入。约束限制：不涉及。
outputs	否	Array of AlgorithmCreateOutput objects	参数解释：算法的数据输出。约束限制：不涉及。
engine	否	AlgorithmCreateEngine object	参数解释：算法的引擎。约束限制：不涉及。
parameters_customization	否	Boolean	参数解释：算法是否允许创建训练作业时自定义超参。约束限制：不涉及。取值范围： true：允许 false：不允许默认取值：不涉及。

表5 Parameters
参数	是否必选	参数类型	描述
name	否	String	参数解释：参数名称。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
value	否	String	参数解释：参数值。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
description	否	String	参数解释：参数描述信息。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
constraint	否	ParametersConstraint object	参数解释：参数属性。约束限制：不涉及。
i18n_description	否	I18nDescription object	参数解释：国际化描述。约束限制：不涉及。

表6 ParametersConstraint
参数	是否必选	参数类型	描述
type	否	String	参数解释：参数种类。约束限制：不涉及。取值范围：枚举值如下： Integer：整数 Float：浮点数 String：字符串 Boolean：布尔值默认取值：不涉及。
editable	否	Boolean	参数解释：是否可编辑。约束限制：不涉及。取值范围： true：可编辑 false：不可编辑默认取值：不涉及。
required	否	Boolean	参数解释：是否必须。约束限制：不涉及。取值范围： true：必须 false：非必须默认取值：不涉及。
sensitive	否	Boolean	参数解释：是否敏感。该功能暂未实现。约束限制：不涉及。取值范围： true：敏感 false：不敏感默认取值：不涉及。
valid_type	否	String	参数解释：有效种类。约束限制：不涉及。取值范围：枚举值如下： Choice：枚举值 Range：范围值 None：无默认取值：不涉及。
valid_range	否	Array of strings	参数解释：有效范围。约束限制：不涉及。

表7 I18nDescription
参数	是否必选	参数类型	描述
language	否	String	参数解释：国际语种。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
description	否	String	参数解释：描述信息。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。

表8 AlgorithmCreateInput
参数	是否必选	参数类型	描述
name	否	String	参数解释：数据输入通道名称。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
description	否	String	参数解释：数据输入通道描述信息。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
remote_constraints	否	Array of RemoteConstraint objects	参数解释：数据输入约束。约束限制：不涉及。

表9 RemoteConstraint
参数	是否必选	参数类型	描述
data_type	否	String	参数解释：数据输入类型，支持数据存储位置（OBS）、ModelArts数据集两种方式。约束限制：不涉及。取值范围：枚举值如下： obs：数据存储位置（OBS） modelarts_dataset：ModelArts数据集默认取值：不涉及。
attributes	否	Array of Map<String,String> objects	参数解释：数据输入为数据集时的相关属性。枚举值： data_format：数据格式 data_segmentation：数据切分方式 dataset_type：标注类型约束限制：不涉及。

**表10** AlgorithmCreateOutput
参数	是否必选	参数类型	描述
name	是	String	参数解释：数据输出通道名称。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
description	否	String	参数解释：数据输出通道描述信息。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。

**表11** AlgorithmCreateEngine
参数	是否必选	参数类型	描述
engine_id	否	String	参数解释：算法选择的引擎规格ID。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
engine_name	否	String	参数解释：算法选择的引擎版本名称。约束限制：若填入engine_id则无需填写。取值范围：不涉及。默认取值：不涉及。
engine_version	否	String	参数解释：算法选择的引擎版本名称。约束限制：若填入engine_id则无需填写。取值范围：不涉及。默认取值：不涉及。
image_url	否	String	参数解释：算法选择的自定义镜像地址。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。

**表12** ResourceRequirement
参数	是否必选	参数类型	描述
key	否	String	参数解释：资源约束。约束限制：不涉及。取值范围：可选键值如： flavor_type（资源类型），对应值可选择CPU、GPU或Ascend； device_distributed_mode（是否支持多卡训练），对应值可选择multiple（支持）、singular（不支持）； host_distributed_mode（是否支持分布式训练），对应值可选择multiple（支持）、singular（不支持）。默认取值：不涉及。
values	否	Array of strings	参数解释：资源约束键对应值。约束限制：不涉及。
operator	否	String	参数解释：键与值关系。约束限制：当前只支持in。例如flavor_type in [CPU,GPU]。取值范围：不涉及。默认取值：不涉及。

**表13** AlgorithmAdvancedConfig
参数	是否必选	参数类型	描述
auto_search	否	AutoSearch object	参数解释：超参搜索策略。约束限制：不涉及。

**表14** AutoSearch
参数	是否必选	参数类型	描述
skip_search_params	否	String	参数解释：需要排除的超参组合。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
reward_attrs	否	Array of RewardAttrs objects	参数解释：搜索指标列表。约束限制：不涉及。
search_params	否	Array of SearchParams objects	参数解释：搜索参数。约束限制：不涉及。
algo_configs	否	Array of AlgoConfigs objects	参数解释：搜索算法配置。约束限制：不涉及。

**表15** RewardAttrs
参数	是否必选	参数类型	描述
name	否	String	参数解释：指标名称。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
mode	否	String	参数解释：搜索方向。约束限制：不涉及。取值范围： max：表示指标值越大越好 min：表示指标值越小越好默认取值：不涉及。
regex	否	String	参数解释：指标正则表达式。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。

**表16** SearchParams
参数	是否必选	参数类型	描述
name	否	String	参数解释：超参名称。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
param_type	否	String	参数解释：参数类型。约束限制：不涉及。取值范围： continuous：表示这个超参是连续类型的。连续类型的超参在算法使用于训练作业时，控制台显示为输入框 discrete：表示这个超参是离散类型的。离散类型的超参在算法使用于训练作业时，控制台显示为下拉选择框架默认取值：不涉及。
lower_bound	否	String	参数解释：超参下界。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
upper_bound	否	String	参数解释：超参上界。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
discrete_points_num	否	String	参数解释：连续型超参离散化取值个数。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
discrete_values	否	Array of strings	参数解释：离散型超参的取值列表。约束限制：不涉及。

**表17** AlgoConfigs
参数	是否必选	参数类型	描述
name	否	String	参数解释：搜索算法名称。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
params	否	Array of AutoSearchAlgoConfigParameter objects	参数解释：搜索算法参数。约束限制：不涉及。

**表18** AutoSearchAlgoConfigParameter
参数	是否必选	参数类型	描述
key	否	String	参数解释：参数键。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
value	否	String	参数解释：参数值。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
type	否	String	参数解释：参数种类。约束限制：不涉及。取值范围：枚举值如下： Float：浮点数 Integer：整数 String：字符串默认取值：不涉及。

响应参数

状态码：201

**表19** 响应Body参数
参数	参数类型	描述
metadata	metadata object	参数解释：算法的元数据，描述算法基本信息。
job_config	job_config object	参数解释：算法配置信息，如启动文件等。
resource_requirements	Array of resource_requirements objects	参数解释：算法资源约束，可不设置。设置后，在算法使用于训练作业时，控制台会过滤可用的公共资源池。
advanced_config	advanced_config object	参数解释：算法高级策略： auto_search

**表20** metadata
参数	参数类型	描述
id	Integer	参数解释：算法id，创建算法时无需填写。取值范围：不涉及。
name	String	参数解释：算法名称。限制为1-64位只含数字、字母、下划线和中划线的名称。取值范围：不涉及。
description	String	参数解释：对算法的描述，默认为“NULL”，字符串的长度限制为[0, 256]。取值范围：不涉及。
workspace_id	String	参数解释：指定算法所处的工作空间，默认值为“0”。“0” 为默认的工作空间。取值范围：不涉及。
ai_project	String	参数解释：指定算法所属的ai项目，默认值为"default-ai-project"。ai项目已下线，无需关注。取值范围：不涉及。
user_name	String	参数解释：用户名称。取值范围：不涉及。
domain_id	String	参数解释：用户的domainID。取值范围：不涉及。
source	String	参数解释：算法来源类型。取值范围：不涉及。
api_version	String	参数解释：算法api版本，标识新旧版。取值范围：不涉及。
is_valid	String	参数解释：算法可用性。取值范围：不涉及。
state	String	参数解释：算法状态。取值范围：不涉及。
tags	Array of Map<String,String> objects	参数解释：算法标签。
attr_list	Array of strings	参数解释：算法属性列表。
version_num	Integer	参数解释：算法版本数量，默认为0。取值范围：不涉及。
size	Integer	参数解释：算法大小。取值范围：不涉及。
create_time	Long	参数解释：算法创建时间戳。取值范围：不涉及。
update_time	Long	参数解释：算法更新时间戳。取值范围：不涉及。

**表21** job_config
参数	参数类型	描述
code_dir	String	参数解释：算法的代码目录。如：“/usr/app/”。应与boot_file一同出现。取值范围：不涉及。
boot_file	String	参数解释：算法的代码启动文件，需要在代码目录下。如：“/usr/app/boot.py”。应与code_dir一同出现。取值范围：不涉及。
command	String	参数解释：自定义镜像算法的容器启动命令。取值范围：不涉及。
parameters	Array of ParameterResp objects	参数解释：算法的运行参数。
inputs	Array of inputs objects	参数解释：算法的数据输入。
outputs	Array of outputs objects	参数解释：算法的数据输出。
engine	engine object	参数解释：算法的引擎。
code_tree	Array of code_tree objects	参数解释：算法的目录结构树。
parameters_customization	Boolean	参数解释：算法是否允许创建训练作业时自定义超参。取值范围： true：允许 false：不允许

**表22** ParameterResp
参数	参数类型	描述
name	String	参数解释：参数名称。取值范围：不涉及。
value	String	参数解释：参数值。取值范围：不涉及。
description	String	参数解释：参数描述信息。取值范围：不涉及。
constraint	constraint object	参数解释：参数属性。
i18n_description	i18n_description object	参数解释：国际化描述。

**表23** constraint
参数	参数类型	描述
type	String	参数解释：参数种类。取值范围：枚举值如下： Integer：整数 Float：浮点数 String：字符串 Boolean：布尔值
editable	Boolean	参数解释：是否可编辑。取值范围： true：可编辑 false：不可编辑
required	Boolean	参数解释：是否必须。取值范围： true：必须 false：非必须
sensitive	Boolean	参数解释：是否敏感。该功能暂未实现。取值范围： true：敏感 false：不敏感
valid_type	String	参数解释：有效种类。取值范围：枚举值如下： - Choice：枚举值 - Range：范围值 - None：无
valid_range	Array of strings	参数解释：有效范围。

**表24** i18n_description
参数	参数类型	描述
language	String	参数解释：国际语种。可选值如下： zh-cn（中文） en-us（英文）取值范围：不涉及。
description	String	参数解释：国际化语种的描述信息。取值范围：不涉及。

**表25** inputs
参数	参数类型	描述
name	String	参数解释：数据输入通道名称。取值范围：不涉及。
description	String	参数解释：数据输入通道描述信息。取值范围：不涉及。
remote_constraints	Array of remote_constraints objects	参数解释：数据输入约束。

**表26** remote_constraints
参数	参数类型	描述
data_type	String	参数解释：数据输入类型，包括数据存储位置、数据集两种方式。取值范围：不涉及。
attributes	Array of Map<String,String> objects	参数解释：数据输入为数据集时的相关属性。枚举值： data_format数据格式 data_segmentation数据切分方式 dataset_type标注类型

**表27** outputs
参数	参数类型	描述
name	String	参数解释：数据输出通道名称。取值范围：不涉及。
description	String	参数解释：数据输出通道描述信息。取值范围：不涉及。

**表28** engine
参数	参数类型	描述
engine_id	String	参数解释：算法选择的引擎规格ID。取值范围：不涉及。
engine_name	String	参数解释：算法选择的引擎版本名称。若填入engine_id则无需填写。取值范围：不涉及。
engine_version	String	参数解释：算法选择的引擎版本名称。若填入engine_id则无需填写。取值范围：不涉及。
image_url	String	参数解释：算法选择的自定义镜像地址。取值范围：不涉及。

**表29** code_tree
参数	参数类型	描述
name	String	参数解释：算法目录树当前层级目录名。取值范围：不涉及。
children	Object	参数解释：算法目录树当前层级目录下子文件和子目录。

**表30** resource_requirements
参数	参数类型	描述
key	String	参数解释：资源约束。取值范围：可选值如下：资源类型（flavor_type），对应值可选择CPU、GPU或Ascend 是否支持多卡训练（device_distributed_mode），对应值可选择支持（multiple）、不支持（singular）是否支持分布式训练（host_distributed_mode），对应值可选择支持（multiple）、不支持（singular）
value	Array of strings	参数解释：资源约束键对应值。
operator	String	参数解释：键与值关系，当前只支持in。例如flavor_type in [CPU,GPU]。取值范围：不涉及。

**表31** advanced_config
参数	参数类型	描述
auto_search	auto_search object	参数解释：超参搜索策略。

**表32** auto_search
参数	参数类型	描述
skip_search_params	String	参数解释：需要排除的超参组合。取值范围：不涉及。
reward_attrs	Array of reward_attrs objects	参数解释：搜索指标列表。
search_params	Array of search_params objects	参数解释：搜索参数。
algo_configs	Array of algo_configs objects	参数解释：搜索算法配置。

**表33** reward_attrs
参数	参数类型	描述
name	String	参数解释：指标名称。取值范围：不涉及。
mode	String	参数解释：搜索方向。取值范围： max：表示指标值越大越好 min：表示指标值越小越好
regex	String	参数解释：指标正则表达式。取值范围：不涉及。

**表34** search_params
参数	参数类型	描述
name	String	参数解释：超参名称。取值范围：不涉及。
param_type	String	参数解释：参数类型。取值范围： continuous：指定时表示这个超参是连续类型的。连续类型的超参在算法使用于训练作业时，控制台显示为输入框 discrete：指定时表示这个超参是离散类型的。离散类型的超参在算法使用于训练作业时，控制台显示为下拉选择框架
lower_bound	String	参数解释：超参下界。取值范围：不涉及。
upper_bound	String	参数解释：超参上界。取值范围：不涉及。
discrete_points_num	String	参数解释：连续型超参离散化取值个数。取值范围：不涉及。
discrete_values	String	参数解释：离散型超参的取值列表。取值范围：不涉及。

**表35** algo_configs
参数	参数类型	描述
name	String	参数解释：搜索算法名称。取值范围：不涉及。
params	Array of AutoSearchAlgoConfigParameterResp objects	参数解释：搜索算法参数。

**表36** AutoSearchAlgoConfigParameterResp
参数	参数类型	描述
key	String	参数解释：参数键。取值范围：不涉及。
value	String	参数解释：参数值。取值范围：不涉及。
type	String	参数解释：参数种类。取值范围：枚举值如下： obs：数据存储位置（OBS） modelarts_dataset：ModelArts数据集

请求示例

创建算法。设置算法名称为“TestModelArtsalgorithm”，描述为“This is a ModelArts algorithm”。

POST https://endpoint/v2/{project_id}/algorithms

{
  "metadata" : {
    "name" : "TestModelArtsalgorithm",
    "description" : "This is a ModelArts algorithm"
  },
  "advanced_config" : {
    "auto_search" : {
      "algo_configs" : [ {
        "name" : "bayes_opt_search",
        "params" : [ {
          "key" : "kind",
          "value" : "ucb",
          "type" : "String"
        }, {
          "key" : "kappa",
          "value" : "2.5",
          "type" : "Float"
        }, {
          "key" : "xi",
          "value" : "0.0",
          "type" : "Float"
        }, {
          "key" : "num_samples",
          "value" : "20",
          "type" : "Integer"
        }, {
          "key" : "seed",
          "value" : "1",
          "type" : "Integer"
        } ]
      } ],
      "reward_attrs" : [ {
        "name" : "max_search",
        "mode" : "max",
        "regex" : "10.0"
      } ],
      "search_params" : [ {
        "name" : "test_search",
        "lower_bound" : "1",
        "upper_bound" : "10"
      } ]
    }
  },
  "job_config" : {
    "code_dir" : "/algo-test/pytorch/work1/code/",
    "boot_file" : "/algo-test/pytorch/work1/code/test-pytorch.py",
    "parameters" : [ {
      "name" : "test-parameter",
      "value" : "10",
      "constraint" : {
        "type" : "String",
        "editable" : true,
        "required" : false,
        "sensitive" : false,
        "valid_type" : "None",
        "valid_range" : [ ]
      }
    } ],
    "parameters_customization" : true,
    "inputs" : [ {
      "name" : "data_url",
      "description" : "data source."
    } ],
    "outputs" : [ {
      "name" : "train_url",
      "description" : "model output."
    } ],
    "engine" : {
      "engine_name" : "PyTorch",
      "engine_version" : "PyTorch-1.3.0-python3.6"
    }
  }
}

响应示例

状态码：201

{
  "metadata" : {
    "id" : "2e5451fe-913f-4492-821a-2981031382f7",
    "name" : "TestModelArtsalgorithm",
    "description" : "This is a ModelArts algorithm",
    "create_time" : 1636600721742,
    "workspace_id" : "0",
    "ai_project" : "default-ai-project",
    "user_name" : "",
    "domain_id" : "xxxxxxxxxxxxxxxxxxxxxxxxxx",
    "source" : "custom",
    "api_version" : "",
    "is_valid" : true,
    "state" : "",
    "size" : 4791,
    "tags" : null,
    "attr_list" : null,
    "version_num" : 0,
    "update_time" : 0
  },
  "job_config" : {
    "code_dir" : "/algo-test/pytorch/work1/code/",
    "boot_file" : "/algo-test/pytorch/work1/code/test-pytorch.py",
    "command" : "",
    "parameters" : [ {
      "name" : "test-parameter",
      "description" : "",
      "i18n_description" : null,
      "value" : "10",
      "constraint" : {
        "type" : "String",
        "editable" : true,
        "required" : false,
        "sensitive" : false,
        "valid_type" : "None",
        "valid_range" : [ ]
      }
    } ],
    "parameters_customization" : true,
    "inputs" : [ {
      "name" : "data_url",
      "description" : "name to translate"
    } ],
    "outputs" : [ {
      "name" : "train_url",
      "description" : "name to translate"
    } ],
    "engine" : {
      "engine_id" : "pytorch-cp36-1.3.0",
      "engine_name" : "PyTorch",
      "engine_version" : "PyTorch-1.3.0-python3.6"
    },
    "code_tree" : {
      "name" : "code/",
      "children" : [ {
        "name" : "test-pytorch.py"
      } ]
    }
  },
  "resource_requirements" : null,
  "advanced_config" : { }
}