文档首页/ 魔坊（ModelArts）模型训推平台/ 模型训练/ 创建训练作业/ 使用API创建训练作业

更新时间：2026-07-15 GMT+08:00

使用API创建训练作业

场景说明

当您需要基于特定数据集和算法模型执行机器学习训练时，可以使用ModelArts API创建和配置训练作业。训练作业创建成功后，平台将根据配置的资源规格自动启动训练作业，您可以通过作业ID监控训练进度和状态。

通过API创建训练作业特别适合以下场景，是生产环境中最推荐的训练作业创建方式：

自动化生产流水线：将训练作业集成到CI/CD流水线或MLOps系统，实现"数据更新→自动触发训练→评估→部署"的全自动闭环。
大规模并行超参搜索：通过脚本循环调用API，同时下发数十个不同超参数的训练作业，利用算力池快速筛选最优模型。
二次开发集：ModelArts还提供多种编程语言的SDK供您使用，如果您需要将ModelArts集成到第三方系统进行二次开发，API是最佳接入方式。
资源精细化调度：配合昇腾超节点的“训推共池”能力，在业务闲时通过API批量下发作业，提升算力性价比。

本章内容以使用PyTorch框架为例，介绍如何通过API创建训练作业。

前提条件

已获取IAM的EndPoint和ModelArts的EndPoint。
确认服务的部署区域，获取项目ID和名称、获取账号名和ID和获取用户名和用户ID。

已经将用于训练作业的数据上传至OBS目录。关于如何创建OBS桶和上传文件，请参见OBS控制台快速入门。
确保使用的OBS目录与ModelArts在同一区域。

已准备好训练代码，例如使用PyTorch框架，将启动文件“test-pytorch.py”存放在OBS的“obs://cnnorth4-job-test-v2/pytorch/fast_example/code/cpu”目录下。
已创建用于输出训练作业模型的路径，例如obs://cnnorth4-job-test-v2/pytorch/fast_example/outputs。
已经创建好训练作业的日志输出位置，例如“obs://cnnorth4-job-test-v2/pytorch/fast_example/log”。

API调用流程

使用PyTorch框架创建训练作业的流程如下：

调用认证鉴权接口获取用户Token，在后续的请求中需要将Token放到请求消息头中作为认证。详情请参考步骤一：调用鉴权API获取Token。
调用创建训练作业接口使用刚创建的算法返回的uuid创建一个训练作业，记录训练作业id。详情请参考步骤二：创建训练作业。
调用查询训练作业详情接口使用刚创建的训练作业返回的id查询训练作业状态。详情请参考步骤三：查询训练作业。
调用查询训练作业指定任务的日志（OBS链接）接口获取训练作业日志的对应的obs路径。详情请参考步骤四：获取训练作业日志。
调用查询训练作业指定任务的运行指标接口查看训练作业的运行指标详情。详情请参考步骤五：查询训练作业运行指标。
当训练作业使用完成或不再需要时，调用删除训练作业接口删除训练作业。详情请参考步骤六：删除训练作业。

步骤一：调用鉴权API获取Token

调用IAM的认证鉴权接口获取用户Token，作为后续所有请求头X-Auth-Token的值。请求体示例（scope设置为project，表示该Token仅在指定项目下的资源生效）。

URI格式：POST https://{iam_endpoint}/v3/auth/tokens

请求消息头：Content-Type: application/json

请求body：

{
  "auth": {
    "identity": {
      "methods": ["password"],
      "password": {
        "user": {
          "name": "您的IAM用户名",
          "password": "您的密码",
          "domain": { "name": "您的账号名" }
        }
      }
    },
    "scope": {
      "project": { "name": "cn-north-1"  }
    }
  }
}

预期结果： 返回 201 Created，响应Header中X-Subject-Token即为Token值。

后续所有请求Header中需携带：

X-Auth-Token: MIIZmgYJKoZIhvcNAQcCoIIZizCCGYcCAQExDTALBglghkgBZQMEAgEwgXXXXXX...

步骤二：创建训练作业

调用创建训练作业接口使用刚创建的算法返回的uuid创建一个训练作业，记录训练作业id。

URI格式：POST https://{ma_endpoint}/v2/{project_id}/training-jobs

请求消息头：

X-Auth-Token: MIIZmgYJKoZIhvcNAQcCoIIZizCCGYcCAQExDTALBglghkgBZQMEAgEwgXXXXXX...
Content-Type: application/json

请求body：

{
    "kind": "job",
    "metadata": {
        "name": "test-pytorch-cpu01",
        "description": "test pytorch work cpu"
    },
    "algorithm": {
        "code_dir": "/cnnorth4-job-test-v2/pytorch/fast_example/code/cpu/",
        "local_code_dir": "/home/ma-user/modelarts/user-job-dir",
        "engine": {
            "image_url": "atelier/pytorch_cuda:pytorch_2.7.0-cuda_12.8-py_3.11.10-ubuntu_22.04-x86_64-20251215163925-4e5422a"
        },
        "command": "python ${MA_JOB_DIR}/cpu/test-pytorch.py"
    },
    "spec": {
        "resource": {
            "node_count": 1,
            "pool_id": "pool-maostest-train-06024304be00d5092fbdc0013d201342"
        },
        "log_export_path": {
            "obs_url": "/cnnorth4-job-test-v2/pytorch/fast_example/log/"
        }
    }
}

参数说明：

“kind”填写训练作业的类型，默认为job。
“metadata”下的“name”和“description”填写训练作业的名称和描述。
“algorithm”下的“code_dir”和“local_code_dir”分别为代码目录和代码下载到作业内的本地目录。
“algorithm”下的“image_url”填写训练作业镜像的地址。
“algorithm”下的“command”填写训练作业启动命令。
“spec”字段下的“pool_id”表示训练作业所依赖的资源池ID。“node_count”表示训练是否需要多机训练（分布式训练），此处为单机情况使用默认值“1”。“log_export_path”用于指定用户需要上传日志的obs目录。

响应示例：返回状态码“201 Created”，表示训练作业创建成功。

{
    "kind": "job",
    "metadata": {
        "id": "31318695-2011-4e48-9b90-9c9178c57951",
        "name": "test-pytorch-cpu01",
        "description": "test pytorch work cpu",
        "create_time": 1777545352008,
        "workspace_id": "0",
        "ai_project": "default-ai-project",
        "labels": {
            "training-job": "modelarts-os"
        },
        "user_name": "",
        "annotations": {
            "job_template": "Template DL",
            "key_task": "worker"
        },
        "training_experiment_reference": {},
        "tags": []
    },
    "status": {
        "phase": "Pending",
        "secondary_phase": "Creating",
        "pending_time": 1000,
        "duration": 0,
        "is_hanged": false,
        "retry_count": 0,
        "start_time": 0,
        "node_count_metrics": null,
        "tasks": [
            "worker-0"
        ],
        "metrics_statistics": {
            "cpu_usage": {
                "average": -1,
                "max": -1,
                "min": -1
            },
            "mem_usage": {
                "average": -1,
                "max": -1,
                "min": -1
            }
        }
    },
    "algorithm": {
        "code_dir": "/cnnorth4-job-test-v2/pytorch/fast_example/code/cpu/",
        "local_code_dir": "/home/ma-user/modelarts/user-job-dir",
        "command": "python ${MA_JOB_DIR}/cpu/test-pytorch.py",
        "engine": {
            "engine_id": "",
            "engine_name": "",
            "engine_version": "",
            "v1_compatible": false,
            "image_url": "atelier/pytorch_cuda:pytorch_2.7.0-cuda_12.8-py_3.11.10-ubuntu_22.04-x86_64-20251215163925-4e5422a",
            "non_swr_image": false,
            "run_user": "",
            "image_source": true,
            "image_repo_id": "",
            "image_id": ""
        }
    },
    "spec": {
        "resource": {
            "pool_id": "pool-maostest-train-06024304be00d5092fbdc0013d201342",
            "pool_resource_flavor": "",
            "node_count": 1,
            "pool_info": {
                "cpu_arch": "x86",
                "core_num": 5,
                "mem_size": 22,
                "cache_size": 0,
                "accelerator": "",
                "accelerator_num": 0,
                "accelerator_type": "",
                "accelerator_size": 0,
                "variant": "",
                "huge_pages": 0,
                "x_parameter_plane": "",
                "use_privileged": false,
                "use_host_network": false,
                "use_ib_network": false,
                "project_id": "",
                "pool_resource_flavor": "liumuqi-eni-test",
                "pool_id": "pool-maostest-train-06024304be00d5092fbdc0013d201342",
                "cluster_id": "",
                "maos_pool": true,
                "quota_id": "",
                "maos_migrated": false,
                "detect_all_in_int": false,
                "pool_type": "",
                "enable_cabinet": false,
                "enable_memarts": false,
                "enable_ems": false,
                "empty_dir_size": 0
            },
            "main_container_allocated_resources": {
                "cpu_arch": "x86",
                "cpu_core_num": 4,
                "mem_size": 20,
                "accelerator_num": 0,
                "accelerator_type": ""
            }
        },
        "log_export_path": {
            "obs_url": "/cnnorth4-job-test-v2/pytorch/fast_example/log/"
        },
        "is_hosted_log": true,
        "runtime_type": "production"
    },
    "ftjob_config": {
        "checkpoint_config": {
            "save_checkpoints_max": 0,
            "checkpoint_id": "",
            "skipped_steps": 0,
            "restore_training": 0
        },
        "task_env": {
            "envs": null
        }
    }
}

记录“metadata”下的“id”（训练作业的任务ID）字段的值便于后续步骤使用。
“Status”下的“phase”和“secondary_phase”为表示训练作业的状态和下一步状态。示例中“Creating”表示训练作业正在创建中。

步骤三：查询训练作业

调用查询训练作业详情接口使用刚创建的训练作业返回的uuid查询训练作业状态。

URI格式：GET https://{ma_endpoint}/v2/{project_id}/training-jobs/{training_job_id}

请求消息头：

X-Auth-Token: MIIZmgYJKoZIhvcNAQcCoIIZizCCGYcCAQExDTALBglghkgBZQMEAgEwgXXXXXX...

其中，加粗的斜体字段需要根据实际值填写：

“training_job_id”为步骤二：创建训练作业记录的训练作业的任务ID。

响应示例：返回状态码“200 OK”。

{
    "kind": "job",
    "metadata": {
        "id": "31318695-2011-4e48-9b90-9c9178c57951",
        "name": "test-pytorch-cpu01",
        "description": "test pytorch work cpu",
        "create_time": 1777545352008,
        "workspace_id": "0",
        "ai_project": "default-ai-project",
        "labels": {
            "training-job": "modelarts-os"
        },
        "user_name": "modelarts_xxx",
        "annotations": {
            "job_template": "Template DL",
            "key_task": "worker"
        },
        "training_experiment_reference": {},
        "tags": []
    },
    "status": {
        "phase": "Running",
        "secondary_phase": "Running",
        "pending_time": 68992,
        "duration": 4000,
        "is_hanged": false,
        "retry_count": 0,
        "task_ips": [
            {
                "task": "worker-0",
                "ip": "172.16.0.31",
                "host_ip": "192.168.140.98",
                "schedule_count": 1
            }
        ],
        "start_time": 1777545421000,
        "node_count_metrics": [
            [
                1777545411000,
                0
            ],
            [
                1777545420000,
                0
            ],
            [
                1777545421000,
                1
            ],
            [
                1777545424000,
                1
            ],
            [
                1777545425000,
                1
            ]
        ],
        "tasks": [
            "worker-0"
        ],
        "metrics_statistics": {
            "cpu_usage": {
                "average": -1,
                "max": -1,
                "min": -1
            },
            "mem_usage": {
                "average": -1,
                "max": -1,
                "min": -1
            }
        },
        "running_records": [
            {
                "start_at": 1777545424,
                "start_type": "init_or_rescheduled"
            }
        ]
    },
    "algorithm": {
        "code_dir": "/cnnorth4-job-test-v2/pytorch/fast_example/code/cpu/",
        "local_code_dir": "/home/ma-user/modelarts/user-job-dir",
        "command": "python ${MA_JOB_DIR}/cpu/test-pytorch.py",
        "engine": {
            "engine_id": "",
            "engine_name": "",
            "engine_version": "",
            "v1_compatible": false,
            "image_url": "atelier/pytorch_cuda:pytorch_2.7.0-cuda_12.8-py_3.11.10-ubuntu_22.04-x86_64-20251215163925-4e5422a",
            "non_swr_image": false,
            "run_user": "",
            "image_source": true,
            "image_repo_id": "",
            "image_id": ""
        }
    },
    "spec": {
        "resource": {
            "pool_id": "pool-maostest-train-06024304be00d5092fbdc0013d201342",
            "pool_resource_flavor": "",
            "node_count": 1,
            "pool_info": {
                "cpu_arch": "x86",
                "core_num": 5,
                "mem_size": 22,
                "cache_size": 0,
                "accelerator": "",
                "accelerator_num": 0,
                "accelerator_type": "",
                "accelerator_size": 0,
                "variant": "",
                "huge_pages": 0,
                "x_parameter_plane": "",
                "use_privileged": false,
                "use_host_network": false,
                "use_ib_network": false,
                "project_id": "",
                "pool_resource_flavor": "liumuqi-eni-test",
                "pool_id": "pool-maostest-train-06024304be00d5092fbdc0013d201342",
                "cluster_id": "",
                "maos_pool": true,
                "quota_id": "",
                "maos_migrated": false,
                "detect_all_in_int": false,
                "pool_type": "",
                "enable_cabinet": false,
                "enable_memarts": false,
                "enable_ems": false,
                "empty_dir_size": 0
            },
            "main_container_allocated_resources": {
                "cpu_arch": "x86",
                "cpu_core_num": 4,
                "mem_size": 20,
                "accelerator_num": 0,
                "accelerator_type": ""
            }
        },
        "log_export_path": {
            "obs_url": "/cnnorth4-job-test-v2/pytorch/fast_example/log/"
        },
        "is_hosted_log": true,
        "runtime_type": "production"
    },
    "ftjob_config": {
        "checkpoint_config": {
            "save_checkpoints_max": 0,
            "checkpoint_id": "",
            "skipped_steps": 0,
            "restore_training": 0
        },
        "task_env": {
            "envs": null
        }
    }
}

根据响应可以了解训练作业的版本详情，其中“status”为“Running”表示训练作业正在运行。

步骤四：获取训练作业日志

调用查询训练作业指定任务的日志（OBS链接）接口获取训练作业日志的对应的obs路径。

URI格式：GET https://{ma_endpoint}/v2/{project_id}/training-jobs/{training_job_id}/tasks/{task_id}/logs/url

请求消息头：

X-Auth-Token: MIIZmgYJKoZIhvcNAQcCoIIZizCCGYcCAQExDTALBglghkgBZQMEAgEwgXXXXXX...
Content-Type→text/plain

其中，加粗的斜体字段需要根据实际值填写:

“training_job_id”为步骤二：创建训练作业记录的训练作业的任务ID。
“task_id”为训练作业的任务名称，一般使用worker-0。
Content-Type可以设置成不同方式。text/plain，返回OBS临时预览链接。application/octet-stream，返回OBS临时下载链接。

响应示例：返回状态码“200 OK”。

{
    "obs_url": "https://modelarts-training-log-cn-north-4.obs.cn-north-4.myhuaweicloud.com:443/66ff6991-fd66-40b6-8101-0829a46d3731/worker-0/modelarts-job-66ff6991-fd66-40b6-8101-0829a46d3731-worker-0.log?AWSAccessKeyId=GFGTBKOZENDD83QEMZMV&Expires=1641896599&Signature=BedFZHEU1oCmqlI912UL9mXlhkg%3D"
}

返回字段表示日志的obs路径。复制至浏览器即可看到对应效果。

步骤五：查询训练作业运行指标

调用查询训练作业指定任务的运行指标接口查看训练作业的运行指标详情。

URI格式：GET https://{ma_endpoint}/v2/{project_id}/training-jobs/{training_job_id}/metrics/{task_id}

请求消息头：

X-Auth-Token: MIIZmgYJKoZIhvcNAQcCoIIZizCCGYcCAQExDTALBglghkgBZQMEAgEwgXXXXXX...

其中，加粗的斜体字段需要根据实际值填写：

“training_job_id”为步骤二：创建训练作业记录的训练作业的任务ID。
“task_id”为训练作业的任务名称，一般使用work-0。

响应示例：返回状态码“200 OK”。

{
    "metrics": [
        {
            "metric": "cpuUsage",
            "value": [
                -1,
                -1,
                28.622,
                35.053,
                39.988,
                40.069,
                40.082,
                40.094
            ]
        },
        {
            "metric": "memUsage",
            "value": [
                -1,
                -1,
                0.544,
                0.641,
                0.736,
                0.737,
                0.738,
                0.739
            ]
        },
        {
            "metric": "npuUtil",
            "value": [
                -1,
                -1,
                -1,
                -1,
                -1,
                -1,
                -1,
                -1
            ]
        },
        {
            "metric": "npuMemUsage",
            "value": [
                -1,
                -1,
                -1,
                -1,
                -1,
                -1,
                -1,
                -1
            ]
        },
        {
            "metric": "gpuUtil",
            "value": [
                -1,
                -1,
                -1,
                -1,
                -1,
                -1,
                -1,
                -1
            ]
        },
        {
            "metric": "gpuMemUsage",
            "value": [
                -1,
                -1,
                -1,
                -1,
                -1,
                -1,
                -1,
                -1
            ]
        }
    ]
}

可以看到CPU\NPU\GPU等相关的使用率指标。

步骤六：删除训练作业

当训练作业使用完成或不再需要时，调用删除训练作业接口删除训练作业。

URI格式：DELETE https://{ma_endpoint}/v2/{project_id}/training-jobs/{training_job_id}

请求消息头：

X-Auth-Token: MIIZmgYJKoZIhvcNAQcCoIIZizCCGYcCAQExDTALBglghkgBZQMEAgEwgXXXXXX...

其中，加粗的斜体字段需要根据实际值填写：

“training_job_id”为步骤二：创建训练作业记录的训练作业的任务ID。

响应说明：返回状态码“202 No Content”响应，则表示删除作业成功。

父主题： 创建训练作业

上一篇：创建模型精调作业

下一篇：优先级和调度策略

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！您可在我的云声建议查看反馈及问题处理状态。

系统繁忙，请稍后重试

如您有其它疑问，您也可以通过华为云社区问答频道来与我们联系探讨

云宝助手提问云社区提问

使用API创建训练作业

场景说明

前提条件

API调用流程

步骤一：调用鉴权API获取Token

步骤二：创建训练作业

步骤三：查询训练作业

步骤四：获取训练作业日志

步骤五：查询训练作业运行指标

步骤六：删除训练作业

相关文档

意见反馈

文档内容是否对您有帮助？