# 创建训练作业版本
#### 功能介绍
创建一个训练作业版本。
该接口为异步接口，作业状态请通过[查询训练作业列表](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/{job_id}/versions
参数说明如[表1]所示。
 表1参数说明 
| 参数         | 是否必选 | 参数类型   | 说明                                                                                               |
|:---|:---|:---|:---|
| project_id | 是    | String | 用户项目ID。获取方法请参见[获取项目ID和名称](https://support.huaweicloud.com/api-modelarts/modelarts_03_0147.html)。 |
| job_id     | 是    | Long   | 训练作业的ID。                                                                                         |
   
#### 请求消息
请求参数如[表2]所示。
 表2请求参数 
| 参数       | 是否必选 | 参数类型   | 说明                                                                        |
|:---|:---|:---|:---|
| job_desc | 否    | String | 对训练作业的描述，默认为"NULL"，字符串的长度限制为\[0, 256\]。                                   |
| config   | 是    | Object | 创建训练作业需要的参数。详情参见[表3]。 |
   
 表3config属性列表 
| 参数                 | 是否必选 | 参数类型            | 说明                                                                                                                                                                |
|:---|:---|:---|:---|
| worker_server_num  | 是    | Integer         | 训练作业worker的个数。最大值请从[查询作业资源规格](https://support.huaweicloud.com/api-modelarts/modelarts_03_0072.html)接口获取。                                                          |
| 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\<Object\> | 训练作业的运行参数，为"label-value"格式。该样例请参考请求示例；当为自定义镜像训练作业的时候，此参数为容器环境变量。[表5]                                           |
| 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        | 否    | JSON 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，默认为空，如："/bucket/trainUrl/"。                                                                                                                     |
| log_url            | 否    | String          | 训练作业的日志OBS输出路径URL，默认为空。如："/usr/train/"。                                                                                                                           |
| pre_version_id     | 是    | Long            | 训练作业前一版本的ID。 可通过[查询训练作业版本列表](https://support.huaweicloud.com/api-modelarts/modelarts_03_0049.html) 中查找"version_id"。                                               |
| 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}" 。                                  |
   
 表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同时出现。            |
   
 表5parameter属性列表 
| 参数    | 是否必选 | 参数类型   | 说明    |
|:---|:---|:---|:---|
| label | 否    | String | 参数名称。 |
| value | 否    | String | 参数值。  |
   
#### 响应消息
响应参数如[表6]所示。
 表6响应参数 
| 参数            | 参数类型    | 说明                                                                                                    |
|:---|:---|:---|
| 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     | 训练作业的运行状态，详细作业状态列表请参见[作业状态参考](https://support.huaweicloud.com/api-modelarts/modelarts_03_0074.html)。  |
| create_time   | Long    | 训练作业的创建时间，时间戳格式。                                                                                      |
| version_id    | Long    | 训练作业的版本ID。                                                                                            |
| version_name  | String  | 训练作业的版本名称。                                                                                            |
   
#### 请求示例
如下以创建"job_id"为10，"pre_version_id"为20的一个新版本作业为例。
```
POST    https://endpoint/v1/{project_id}/training-jobs/10/versions/
{
    "job_desc": "This is a ModelArts job",
    "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/",
        "pre_version_id": 20,
        "model_id": 1,
        "pool_id": "test-pool"
    }
}
```
#### 响应示例
- 成功响应示例
  ```
  {
      "is_success": true,
      "job_id": 10,
      "job_name": "TestModelArtsJob",
      "status": 1,
      "create_time": 1524189990635,
      "version_id": 10,
      "version_name":"V0001"
  }
  ```
  
- 失败响应示例
  ```
  {
      "is_success": false,
      "error_message": "Error string",
      "error_code": "ModelArts.0105"
  }
  ```
  
 
#### 状态码
状态码请参见[状态码](https://support.huaweicloud.com/api-modelarts/modelarts_03_0094.html)。