# 创建训练作业 #### 功能介绍 创建一个训练作业。 该接口为异步接口，作业状态请通过[查询训练作业列表](https://support.huaweicloud.com/api-modelarts/modelarts_03_0046.html)和[查询训练作业版本详情](https://support.huaweicloud.com/api-modelarts/modelarts_03_0047.html)接口获取。 #### URI POST /v1/{project_id}/training-jobs 参数说明如[表1]所示。 表1参数说明 | 参数 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | project_id | 是 | String | 用户项目ID。获取方法请参见[获取项目ID和名称](https://support.huaweicloud.com/api-modelarts/modelarts_03_0147.html)。 | #### 请求消息 请求参数如[表2]所示。 表2请求参数 | 参数 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | job_name | 是 | String | 训练作业名称。限制为1-64位只含数字、字母、下划线和中划线的名称。 | | job_desc | 否 | String | 对训练作业的描述，默认为"NULL"，字符串的长度限制为\[0, 256\]。 | | config | 是 | Object | 创建训练作业需要的参数。详情请参见[表3]。 | | workspace_id | 否 | String | 指定作业所处的工作空间，默认值为"0"。 | 表3config属性列表 | 参数 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | worker_server_num | 是 | Integer | 训练作业worker的个数。最大值请从[查询作业资源规格](https://support.huaweicloud.com/api-modelarts/modelarts_03_0072.html)接口返回的"max_num"值获取。 | | app_url | 是 | String | 训练作业的代码目录。如："/usr/app/"。应与boot_file_url一同出现，若填入model_id则app_url/boot_file_url和engine_id无需填写。 | | boot_file_url | 是 | String | 训练作业的代码启动文件，需要在代码目录下。如："/usr/app/boot.py"。应与app_url一同出现，若填入model_id则app_url/boot_file_url和engine_id无需填写。 | | parameter | 否 | Array\ | 训练作业的运行参数，为"label-value"格式。取值可以为自定义的任何值，其中label为参数名称，value为参数值，该样例请参考请求示例；当为自定义镜像训练作业的时候，此参数为容器环境变量。详细请参见[表8]。 | | data_url | 否 | String | 训练作业需要的数据集OBS路径URL，默认为空。如："/usr/data/"。不可与data_source或者dataset_id/dataset_version_id同时出现，但必须有其一。 | | dataset_id | 否 | String | 训练作业的数据集ID。应与dataset_version_id同时出现，但不可与data_url或data_source同时出现。 | | dataset_version_id | 否 | String | 训练作业的数据集版本ID。应与dataset_id同时出现，但不可与data_url或data_source同时出现。 | | data_source | 否 | Array\ | 训练作业使用的数据集。不可与data_url或dataset_id/dataset_version_id同时使用。请查看[表4] | | spec_id | 是 | Long | 训练作业选择的资源规格ID。请从[查询作业资源规格](https://support.huaweicloud.com/api-modelarts/modelarts_03_0072.html)接口获取资源ID。创建公共池作业时，spec_id必选，且不能与pool_id同时出现。 | | pool_id | 是 | String | 专属资源池ID。可在ModelArts管理控制台，单击左侧"专属资源池"，在专属资源池列表中查看资源池ID。创建专属池作业时，pool_id必选，且不能与spec_id同时出现。 | | engine_id | 是 | Long | 训练作业选择的引擎规格ID，默认为"1"。填入model_id后app_url/boot_file_url和engine_id无需填写。请从[查询作业引擎规格](https://support.huaweicloud.com/api-modelarts/modelarts_03_0073.html)接口获取引擎规格ID。 | | model_id | 是 | Long | 训练作业的内置模型ID。请通过[查询预置算法](https://support.huaweicloud.com/api-modelarts/modelarts_03_0056.html)接口获取model_id。填入model_id后app_url/boot_file_url和engine_id无需填写。 | | train_url | 否 | String | 训练作业的输出文件OBS路径URL，默认为空，如："/usr/train/"。 | | log_url | 否 | String | 训练作业的日志OBS输出路径URL，默认为空。如："/usr/log/"。 | | user_image_url | 否 | String | 自定义镜像训练作业的自定义镜像的SWR-URL。如："100.125.5.235:20202/jobmng/custom-cpu-base:1.0"。 | | user_command | 否 | String | 自定义镜像训练作业的自定义镜像的容器的启动命令。形式为： "bash /home/work/run_train.sh python /home/work/user-job-dir/app/train.py {python_file_parameter}" 。 | | create_version | 否 | Boolean | 创建训练作业的同时是否创建版本。 - true：默认值，创建训练作业的同时创建版本。 - false：仅创建训练作业，不创建版本。 | | volumes | 否 | JSON Array | 训练作业可使用的存储卷。具体说明请参见[表5]。 | 表4data_source属性列表 | 参数 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | dataset_id | 否 | String | 训练作业的数据集ID。应与dataset_version_id同时出现，但不可与data_url同时出现。 | | dataset_version | 否 | String | 训练作业的数据集版本ID。应与dataset_id同时出现，但不可与data_url同时出现。 | | type | 否 | String | 数据集类型。可选值："obs"、"dataset"。obs与dataset不可同时出现。 | | data_url | 否 | String | OBS的桶路径，不可与dataset_id/dataset_version同时出现。 | 表5volumes属性列表 | 参数 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | nfs | 否 | Object | 共享文件系统类型的存储卷。仅支持运行于已联通共享文件系统网络的资源池的训练作业。具体说明请参见[表6]。 | | host_path | 否 | Object | 主机文件系统类型的存储卷。仅支持运行于专属资源池中的训练作业。具体说明请参见[表7]。 | 表6nfs属性列表 | 参数 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | id | 是 | String | SFS Turbo 文件系统 ID。 | | src_path | 是 | String | SFS Turbo 文件系统地址。 | | dest_path | 是 | String | 训练作业的本地路径。 | | read_only | 否 | Boolean | dest_path 是否为只读权限，默认为读写权限。 - true：只读权限 - false：默认值，读写权限 | 表7host_path属性列表 | 参数 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | src_path | 是 | String | 宿主机的本地路径。 | | dest_path | 是 | String | 训练作业的本地路径。 | | read_only | 否 | Boolean | dest_path 是否为只读权限，默认为读写权限。 - true：只读权限 - false：默认值，读写权限 | 表8parameter属性列表 | 参数 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | label | 否 | String | 参数名称。 | | value | 否 | String | 参数值。 | #### 响应消息 响应参数如[表9]所示。 表9响应参数 | 参数 | 参数类型 | 说明 | |:---|:---|:---| | is_success | Boolean | 请求是否成功。 | | error_message | String | 调用失败时的错误信息。 调用成功时无此字段。 | | error_code | String | 调用失败时的错误码，具体请参见[错误码](https://support.huaweicloud.com/api-modelarts/modelarts_03_0095.html)。 调用成功时无此字段。 | | job_id | Long | 训练作业的ID。 | | job_name | String | 训练作业的名称 | | status | Int | 训练作业的运行状态，详细作业状态列表请查看作业状态参考。 | | create_time | Long | 训练作业的创建时间，时间戳格式。 | | version_id | Long | 训练作业的版本ID。 | | resource_id | String | 训练作业的计费资源ID。 | | version_name | String | 训练作业的版本名称。 | #### 请求示例 - 如下以创建名为"TestModelArtsJob"，描述为"This is a ModelArts job"为例。 ``` POST https://endpoint/v1/{project_id}/training-jobs { "job_name": "TestModelArtsJob", "job_desc": "This is a ModelArts job", "workspace_id": "af261af2218841ec960b01ab3cf1a5fa", "config": { "worker_server_num": 1, "app_url": "/usr/app/", "boot_file_url": "/usr/app/boot.py", "parameter": [ { "label": "learning_rate", "value": "0.01" }, { "label": "batch_size", "value": "32" } ], "dataset_id": "38277e62-9e59-48f4-8d89-c8cf41622c24", "dataset_version_id": "2ff0d6ba-c480-45ae-be41-09a8369bfc90", "spec_id": 1, "engine_id": 1, "train_url": "/usr/train/", "log_url": "/usr/log/", "model_id": 1, "pool_id": "testpool" } } ``` - 如下以创建名为"TestModelArtsJob2"，创建自定义镜像训练。 ``` POST https://endpoint/v1/{project_id}/training-jobs { "job_name": "TestModelArtsJob2", "job_desc": "This is a ModelArts job", "workspace_id": "af261af2218841ec960b01ab3cf1a5fa", "config": { "worker_server_num": 1, "data_url": "/usr/data/", "app_url": "/usr/app/", "boot_file_url": "/usr/app/boot.py", "parameter": [ { "label": "CUSTOM_PARAM1", "value": "1" } ], "spec_id": 1, "user_command": "bash -x /home/work/run_train.sh python /home/work/user-job-dir/app/mnist/mnist_softmax.py --data_url /home/work/user-job-dir/app/mnist_data", "user_image_url": "100.125.5.235:20202/jobmng/custom-cpu-base:1.0", "train_url": "/usr/train/", "log_url": "/usr/log/", "model_id": 1, "pool_id": "testpool", "engine_id": 1 } } ``` - 如下以创建名为"TestModelArtsJob3"，创建使用存储卷的训练。 ``` POST https://endpoint/v1/{project_id}/training-jobs { "job_name": "TestModelArtsJob3", "job_desc": "This is a ModelArts job", "workspace_id": "af261af2218841ec960b01ab3cf1a5fa", "config": { "worker_server_num": 1, "app_url": "/usr/app/", "boot_file_url": "/usr/app/boot.py", "parameter": [ { "label": "learning_rate", "value": "0.01" }, { "label": "batch_size", "value": "32" } ], "dataset_id": "38277e62-9e59-48f4-8d89-c8cf41622c24", "dataset_version_id": "2ff0d6ba-c480-45ae-be41-09a8369bfc90", "spec_id": 1, "engine_id": 1, "train_url": "/usr/train/", "log_url": "/usr/log/", "model_id": 1, "pool_id": "testpool", "volumes": [ { "nfs": { "id": "43b37236-9afa-4855-8174-32254b9562e7", "src_path": "192.168.8.150:/", "dest_path": "/home/work/nas", "read_only": false } }, { "host_path": { "src_path": "/root/work", "dest_path": "/home/mind", "read_only": false } } ] } } ``` #### 响应示例 - 成功响应示例 ``` { "is_success": true, "job_id": "10", "job_name": "TestModelArtsJob", "status": "1", "create_time": "1524189990635", "version_id": "10", "version_name": "V0001", "resource_id": "jobafd08896" } ``` - 失败响应示例 ``` { "is_success": false, "error_message": "Job name:TestModelArtsJob is existed", "error_code": "ModelArts.0103" } ``` #### 状态码 状态码请参见[状态码](https://support.huaweicloud.com/api-modelarts/modelarts_03_0094.html)。