# 使用API创建训练作业 #### 场景说明 当您需要基于特定数据集和算法模型执行机器学习训练时，可以使用ModelArts API创建和配置训练作业。 训练作业创建成功后，平台将根据配置的资源规格自动启动训练作业，您可以通过作业ID监控训练进度和状态。 通过API创建训练作业特别适合以下场景，是生产环境中最推荐的训练作业创建方式： - **自动化生产流水线**：将训练作业集成到CI/CD流水线或MLOps系统，实现"数据更新→自动触发训练→评估→部署"的全自动闭环。 - **大规模并行超参搜索**：通过脚本循环调用API，同时下发数十个不同超参数的训练作业，利用算力池快速筛选最优模型。 - **二次开发集** **成**：ModelArts还提供多种编程语言的SDK供您使用，如果您需要将ModelArts集成到第三方系统进行二次开发，API是最佳接入方式。 - **资源精细化调度**：配合昇腾超节点的"训推共池"能力，在业务闲时通过API批量下发作业，提升算力性价比。 本章内容以使用**PyTorch**框架为例，介绍如何通过API创建训练作业。 #### 前提条件 - 已获取[IAM的EndPoint](https://developer.huaweicloud.com/endpoint?IAM)和[ModelArts的EndPoint](https://support.huaweicloud.com/api-modelarts/modelarts_03_0141.html)。 - 确认服务的部署区域，[获取项目ID和名称](https://support.huaweicloud.com/api-modelarts/modelarts_03_0147.html)、[获取账号名和ID](https://support.huaweicloud.com/api-modelarts/modelarts_03_0148.html)和[获取用户名和用户ID](https://support.huaweicloud.com/api-modelarts/modelarts_03_0006.html)。 - 已经将用于训练作业的数据上传至OBS目录。关于如何创建OBS桶和上传文件，请参见[OBS控制台快速入门](https://support.huaweicloud.com/qs-obs/obs_qs_0001.html)。 - 确保使用的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框架创建训练作业的流程如下： 1. 调用[认证鉴权](https://support.huaweicloud.com/api-modelarts/modelarts_03_0004.html)接口获取用户Token，在后续的请求中需要将Token放到请求消息头中作为认证。详情请参考[步骤一：调用鉴权API获取Token]。 2. 调用[创建训练作业](https://support.huaweicloud.com/api-modelarts/CreateTrainingJob.html)接口使用刚创建的算法返回的uuid创建一个训练作业，记录训练作业id。详情请参考[步骤二：创建训练作业]。 3. 调用[查询训练作业详情](https://support.huaweicloud.com/api-modelarts/ShowTrainingJobDetails.html)接口使用刚创建的训练作业返回的id查询训练作业状态。详情请参考[步骤三：查询训练作业]。 4. 调用[查询训练作业指定任务的日志（OBS链接）](https://support.huaweicloud.com/api-modelarts/ShowObsUrlOfTrainingJobLogs.html)接口获取训练作业日志的对应的obs路径。详情请参考[步骤四：获取训练作业日志]。 5. 调用[查询训练作业指定任务的运行指标](https://support.huaweicloud.com/api-modelarts/ShowTrainingJobMetrics.html)接口查看训练作业的运行指标详情。详情请参考[步骤五：查询训练作业运行指标]。 6. 当训练作业使用完成或不再需要时，调用[删除训练作业](https://support.huaweicloud.com/api-modelarts/DeleteTrainingJob.html)接口删除训练作业。详情请参考[步骤六：删除训练作业]。 #### 步骤一：调用鉴权API获取Token 调用IAM的[认证鉴权](https://support.huaweicloud.com/api-modelarts/modelarts_03_0004.html)接口获取用户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... ``` #### 步骤二：创建训练作业 调用[创建训练作业](https://support.huaweicloud.com/api-modelarts/CreateTrainingJob.html)接口使用刚创建的算法返回的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"表示训练作业正在创建中。 #### 步骤三：查询训练作业 调用[查询训练作业详情](https://support.huaweicloud.com/api-modelarts/ShowTrainingJobDetails.html)接口使用刚创建的训练作业返回的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链接）](https://support.huaweicloud.com/api-modelarts/ShowObsUrlOfTrainingJobLogs.html)接口获取训练作业日志的对应的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路径。复制至浏览器即可看到对应效果。 #### 步骤五：查询训练作业运行指标 调用[查询训练作业指定任务的运行指标](https://support.huaweicloud.com/api-modelarts/ShowTrainingJobMetrics.html)接口查看训练作业的运行指标详情。 **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"***为训练作业的任务名称，一般使用worker-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等相关的使用率指标。 #### 步骤六：删除训练作业 当训练作业使用完成或不再需要时，调用[删除训练作业](https://support.huaweicloud.com/api-modelarts/DeleteTrainingJob.html)接口删除训练作业。 **URI格式** ：DELETE https://***{ma_endpoint}*** /v2/***{project_id}*** /training-jobs/***{training_job_id}*** **请求消息头**： - X-Auth-Token: ***MIIZmgYJKoZIhvcNAQcCoIIZizCCGYcCAQExDTALBglghkgBZQMEAgEwgXXXXXX...*** 其中，加粗的斜体字段需要根据实际值填写： - ***"training_job_id"*** 为[步骤二：创建训练作业]记录的训练作业的任务ID。 **响应说明：**返回状态码"202 No Content"响应，则表示删除作业成功。