huawei-cloud-modelarts-training-management

Huawei Cloud ModelArts 训练管理

通过 hcloud CLI 全生命周期管理 ModelArts 训练作业及相关资源——涵盖 8 个功能领域中的 52 个 API 接口。

---

概述

此技能支持用户通过 hcloud CLI 管理 Huawei Cloud ModelArts 训练作业及相关资源。涵盖完整的训练生命周期，包括训练作业的增删查改、算法管理、训练实验、自动搜索（超参数调优）、模型导入和训练镜像保存。

架构

User Request → Agent → hcloud ModelArts <Operation> --cli-region={region} [--params] → Huawei Cloud ModelArts API

适用场景

• 训练作业管理：创建、列出、查看、停止和删除训练作业；查询日志、指标、引擎、规格和配额
• 算法管理：创建、列出、查看、更新和删除训练算法；发布到图库
• 训练作业标签：为训练作业创建、查看和删除标签
• 训练实验：创建、列出、查看、更新和删除训练实验，以及检查训练实验
• 训练作业事件：查询作业事件、阶段和任务；列出系统事件和定时事件
• 模型导入：导入、列出、查看和删除 AI 模型；创建 ModelArts 委托
• 自动搜索：查询超参数搜索试验、参数分析和 yaml 模板
• 训练镜像保存：创建和查询训练作业镜像保存任务

---

前提条件

1. 已安装并完成身份验证的 hcloud CLI — 参考：https://support.huaweicloud.com/qs-hcli/hcli_02_003.html
2. 已通过 hcloud 配置 Huawei Cloud AK/SK（见下文“安全与凭证检查”）
3. 已在目标区域启用 ModelArts 服务
4. IAM 权限 — 参见 references/iam-policies.md

安全与凭证检查

⚠️ 严重：本节定义了 Agent 的安全边界。必须严格遵守。

🔒 安全规则（强制）

• 🚫 绝不要读取、回显或打印 AK/SK 值（例如，禁止执行 cat ~/.hcloud/config.json、echo $HW_ACCESS_KEY）
• 🚫 绝不要读取或使用 cat 查看凭证文件，例如 ~/.hcloud/config.json 或任何可能包含机密信息的文件
• 🚫 绝不要要求用户在对话或命令行中直接输入 AK/SK
• 🚫 绝不要执行 hcloud configure set --cli-access-key=... --cli-secret-key=...——凭证配置由用户负责，必须在 Agent 会话之外完成
• 🚫 绝不要在每次 API 调用中传递 --cli-access-key/--cli-secret-key——在整个请求期间，这些值都会暴露在进程列表（ps aux）中
• ✅ 始终使用 hcloud configure list 检查凭证状态（仅检查是否存在，不检查具体值）
• ✅ 如果不存在有效配置文件，请停止并告知用户在本次会话之外配置凭证
• ✅ 建议使用权限最小化的 IAM 用户，而非主账号

✅ Agent 凭证检查（唯一可接受的检查方式）

# Step 1: Check credential status — presence only, not values
hcloud configure list

• ✅ 预期结果：显示包含 mode: AKSK 的有效配置文件

• ❌ 如果为空或无效 → 按以下 3 个步骤指导用户：

  分步指南（可复制粘贴给用户）：

  “未找到有效凭证。请在终端中按以下 3 个步骤操作：”

  ① 获取 AK/SK 登录 Huawei Cloud Console → IAM → Access Keys。如果还没有 AK/SK，请点击“Create Access Key”并妥善保存。

  ② 在终端中执行以下命令（一次性设置）：

  hcloud configure set --cli-access-key=<YOUR_AK> --cli-secret-key=<YOUR_SK>
  

  （将 <YOUR_AK> 和 <YOUR_SK> 替换为步骤 ① 中获取的值）

  ③ 返回并告诉我“已配置”，我会验证是否配置成功。

  注意：configure set 命令会将凭证存储在 ~/.hcloud/config.json 中。之后，所有 hcloud 命令都会自动使用这些凭证，无需再次传递 AK/SK。

  Agent：不要自行执行任何 configure set 命令。

🔧 用户职责（用于文档说明，不用于 Agent 执行）

用户在 Agent 会话之外（在自己的终端中）配置凭证：

# One-time setup — run this in your terminal, NOT in the agent chat
HISTCONTROL=ignorespace
 hcloud configure set --cli-access-key=<YOUR_AK> --cli-secret-key=<YOUR_SK>

⚠️ 注意：hcloud CLI 不会读取 HW_ACCESS_KEY/HW_SECRET_KEY 环境变量（这些变量仅供 Python SDK 使用）。hcloud configure set 是唯一受支持的凭证配置方式。

---

工作流

步骤 1：确定操作

根据用户的请求，确定所需的训练操作：

用户意图	操作类别
创建/列出/查看/停止/删除训练作业	训练作业管理
创建/列出/查看/更新/删除算法	算法管理
创建/查看/删除训练作业标签	训练作业标签
创建/列出/查看/更新/删除实验	训练实验
查询作业事件、阶段、任务	训练作业事件
导入/列出/查看/删除模型	模型导入
查询自动搜索试验、参数分析	自动搜索
保存训练作业镜像	训练镜像保存

步骤 2：执行 CLI 命令

hcloud ModelArts <Operation> --cli-region={region} [--key=value ...]

必须将 {region} 替换为实际区域，例如 cn-north-4。请勿将区域硬编码。

步骤 2.5：⚠️ 执行前检查（写入操作的强制要求）

执行任何写入操作之前（创建/更新/删除/停止/更改/修补/通知/接受），你必须：

1. 阅读 references/known-issues.md — 查阅与目标 API 相关的章节
2. 应用文档中记录的解决方法 — 特别是以下高风险操作：

操作	关键问题	所需操作
CreateTrainingJob	必须使用 v2 kind/metadata/spec/tasks 格式	使用 --cli-jsonInput 和 v2 JSON 结构
CreateTrainingJob（专用资源池）	专用资源池不接受 flavor_id	省略 flavor_id，改为指定 pool_id
CreateAlgorithm	JSON 必须使用嵌套的 metadata + job_config 结构	使用 --cli-jsonInput 并采用正确的嵌套结构（参见 known-issues #27）
CreateAlgorithm	OBS 代码目录必须存在且可访问	调用 API 前验证 OBS 路径
StopTrainingJob	只能停止处于 creating/waiting/running 状态的作业	先检查作业状态
CreateModel	source_location 格式必须为 obs://bucket/path/	验证 OBS 路径格式
CreateModel	model_type 必须是有效值	查看 known-issues #22 了解有效值
CreateSaveImageJob	作业必须处于 running 状态；必须提供 SWR 命名空间	验证作业状态和 SWR 配置
ChangeAlgorithm	必须包含 --metadata.name 参数	在请求中添加 metadata.name
NotifyTrainingJobInformation	参数名称与 API 文档不同	查看 known-issues #24
UpdateTrainingJob	不是有效的 CLI 操作	改用 ChangeTrainingJob

跳过此步骤会导致本可避免的失败。 表中的每个问题都是通过真实 API 测试发现的。

步骤 3：价格查询（适用于收费操作）

执行收费写入操作（针对公共资源池的 CreateTrainingJob、CreateTrainingExperiment）之前，执行 BSS 价格查询，并向用户展示预估费用。

📖 价格查询的详细流程，请阅读 references/pricing-inquiry.md

收费操作

操作	是否需要查询	条件
CreateTrainingJob	✅ 是	使用公共资源池时（未指定 pool_id）
CreateTrainingJob	❌ 否	使用专用资源池时（已指定 pool_id — 资源池已计费）
CreateTrainingExperiment	✅ 是	实验可能会启动产生计算费用的训练作业
所有其他操作	❌ 否	读取操作、删除、停止、标签等均不产生费用

查询流程

1. Detect chargeable operation (CreateTrainingJob without pool_id)
2. Extract flavor_id from spec.resource.flavor_id parameter
3. Get project ID via IAM KeystoneListAuthProjects
4. Call BSS ListOnDemandResourceRatings to query on-demand price
5. Calculate estimated cost: unit_price × node_count × estimated_duration
6. Display price table and cost estimate to user
7. Proceed to Step 4 (user confirmation) after showing pricing info

快速查询价格

使用辅助脚本快速查询价格：

# Query single flavor
bash scripts/query-pricing.sh --region cn-north-4 --flavor modelarts.bm.gpu.v100

# Query multiple flavors for comparison
bash scripts/query-pricing.sh --region cn-north-4 --flavor modelarts.bm.gpu.v100 --flavor modelarts.cpu.8u32g --flavor modelarts.bm.ascend910

BSS 查询参数（固定）

参数	值	说明
cloud_service_type	hws.service.type.modelarts	ModelArts 服务类型
resource_type	hws.resource.type.modelarts	ModelArts 资源类型
usage_measure_id	4	小时（计费单位）
size_measure_id	14	实例数量
BSS API 区域	cn-north-1	BSS API 始终使用 cn-north-1

第 4 步：处理写入操作

对于所有写入操作（创建/更新/删除/停止/变更/修补/通知/接受/批量），执行前须征求用户确认。对于计费操作，确认时还须查看第 3 步中的价格信息。

第 5 步：生成控制台 URL（CreateTrainingJob 之后）

成功创建训练作业后，生成并显示 ModelArts 控制台 URL，以便用户直接在 Web 控制台中访问作业详情。

URL 格式

训练作业详情页（CreateTrainingJob 之后）：

https://console.huaweicloud.com/modelarts/?region={region}#/training/detail/{job_id}

训练作业列表页（ListTrainingJobs 之后）：

https://console.huaweicloud.com/modelarts/?region={region}#/training

组成部分	说明	示例
{region}	创建作业所在的区域	cn-north-4
{job_id}	CreateTrainingJob 返回的训练作业 ID	39cefbeb-0d86-46cb-a55a-fe6a62f3529b

重要：详情页使用 #/training/detail/{job_id}，列表页使用 #/training（新版控制台路径）。请勿使用 #/trainingJobs/details/{job_id} 或 #/trainingJobs——这些是已弃用的旧控制台路径。

工作流

1. CreateTrainingJob returns job_id in the response
2. Construct console URL: https://console.huaweicloud.com/modelarts/?region={region}#/training/detail/{job_id}
3. Display the URL to the user with a summary of the created job

输出示例

✅ Training job created successfully!

  Job Name:    my-training-job
  Job ID:      39cefbeb-0d86-46cb-a55a-fe6a62f3529b
  Status:      creating
  Region:      cn-north-4

  🔗 Console URL:
  https://console.huaweicloud.com/modelarts/?region=cn-north-4#/training/detail/39cefbeb-0d86-46cb-a55a-fe6a62f3529b

注意：控制台 URL 使用哈希路由（#/training/detail/{job_id}）。请勿使用旧路径 #/trainingJobs/details/{job_id}——它会重定向到已弃用的控制台页面。只要训练作业存在，且用户拥有该区域的 ModelArts 访问权限，此 URL 就有效。

---

KooCLI 命令格式标准

hcloud ModelArts <Operation> --cli-region={region} [--key=value ...]

特性	说明	示例
服务名称	固定为 ModelArts	ModelArts
操作名称	PascalCase	ListTrainingJobs、CreateTrainingJob
区域参数	--cli-region={region}	--cli-region=cn-north-4
简单参数	--key=value	--training_job_id=xxx
索引参数	--key.1=value1	--tasks.1.role=worker
project_id	若省略则自动解析	使用已配置的项目 ID

注意：若省略 --project_id，系统会根据身份验证凭据自动解析。只有在指定特定项目时才需显式提供此参数。

复杂参数：对于复杂的嵌套参数（例如 config、spec），请使用 --cli-jsonInput=/path/to/file.json。JSON 文件必须将 body 包装在 {"body": {...}} 外层结构中。

---

核心命令

所有 8 个功能领域的 52 个 CLI 命令示例均记录在单独的参考文件中。

📖 如需详细的命令语法、参数和示例，请阅读 references/cli-command-examples.md

快速索引

#	领域	API	关键操作
1	训练作业管理	14	CreateTrainingJob、ListTrainingJobs、ShowTrainingJobDetails、StopTrainingJob、DeleteTrainingJob、ShowTrainingJobLogs/Metrics/Engines/Flavors/Quotas
2	算法管理	7	CreateAlgorithm、ListAlgorithms、ShowAlgorithmByUuid、ChangeAlgorithm、DeleteAlgorithm、ShowSearchAlgorithms、CreateAlgorithmVersionToGallery
3	训练作业标签	3	CreateTrainJobTags、ShowTrainJobTags、DeleteTrainJobTags
4	训练实验	6	CreateTrainingExperiment、List/Show/Delete/Change/Check 实验
5	训练作业事件	7	ListTrainingJobEvents/Stages/Tasks、ListEvents/Categories/ScheduledEvents、AcceptScheduledEvent
6	模型导入	6	CreateModel、ListModels、ShowModel、DeleteModel、ShowModelEngineAndRuntime、CreateModelArtsAgency
7	自动搜索	7	ShowAutoSearchTrials/PerTrial/ParamsAnalysis/YamlTemplates、ShowAutoSearchTrialEarlyStop
8	训练镜像保存	2	CreateSaveImageJob、ShowSaveImageJob

执行任何命令时，务必参考参考文件，确认准确的参数名称、必填/可选标记和用法。

---

能力边界

此技能仅涵盖 ModelArts 训练管理——覆盖 8 个功能领域中的 52 个 API（见上文“核心命令”）。以下 ModelArts 功能不受支持：

不支持的领域	操作示例	建议
Notebook（开发环境）	CreateNotebook、ListNotebooks、ShowNotebook	使用 ModelArts 控制台或专用 Notebook 技能
推理服务（在线服务）	CreateService、ListServices、ShowService	使用 ModelArts 控制台或推理技能
资源池/集群	CreateResourcePool、ListResourcePools	使用 ModelArts 控制台
工作流编排	CreateWorkflow、ListWorkflows	使用 ModelArts 控制台
镜像管理（SWR）	ListImages、ShowImage	使用 SWR 控制台或直接使用 CLI
DevServer	CreateDevServer、ListDevServers	使用 ModelArts 控制台
工作空间管理	CreateWorkspace、ListWorkspaces	使用 ModelArts 控制台

收到上述不支持功能的请求时，请明确告知用户此技能不支持这些功能，并建议使用 ModelArts 控制台（https://console.huaweicloud.com/modelarts/）或相关专用技能。

---

参数确认

参数	必填	描述	示例
{region}	是	华为云区域	cn-north-4、cn-east-3
{training_job_id}	作业操作	训练作业 UUID	xxx-xxx-xxx
{algorithm_id}	算法操作	算法 UUID	xxx-xxx-xxx
{experiment_id}	实验操作	训练实验 UUID	xxx-xxx-xxx
{model_id}	模型操作	模型 UUID	xxx-xxx-xxx
{job_id}	SaveImage 操作	保存镜像作业 UUID	xxx-xxx-xxx
{project_id}	否（自动）	项目 ID；省略时自动解析	默认值可省略
{workspace_id}	否	工作空间 ID	默认工作空间可省略

---

SDK 回退

如果 CLI 操作因 CLI 缺陷而失败，请回退到 SDK：

from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkmodelarts.v2.modelarts_client import ModelArtsClient
from huaweicloudsdkmodelarts.v2.region.modelarts_region import ModelArtsRegion

credentials = BasicCredentials(ak="{AK}", sk="{SK}", project_id="{project_id}")
client = ModelArtsClient.new_builder() \
    .with_credentials(credentials) \
    .with_region(ModelArtsRegion.value_of("{region}")) \
    .build()

---

参考文档

文档	描述
references/cli-command-examples.md	所有 52 个 API 的 CLI 命令语法和示例详解
references/pricing-inquiry.md	训练作业的 BSS 按需价格查询（创建前的成本估算）
references/iam-policies.md	最小权限 IAM 策略
references/verification-method.md	验证和测试方法
references/dataflow-diagram.md	Mermaid 数据流图
references/acceptance-criteria.md	验收标准检查清单
references/api-paths.md	SDK 源代码中的 REST API 路径
references/cli-installation-guide.md	CLI 安装和身份验证指南
references/known-issues.md	已知问题和解决方法

---

已知问题摘要

• 复杂的嵌套参数：对于 CreateTrainingJob、CreateAlgorithm、CreateModel 等操作，请使用 --cli-jsonInput 和 JSON 文件。
• --cli-jsonInput 语法：直接使用文件路径（不加 @ 前缀），JSON 必须封装在 {"body": {...}} 中。
• 训练作业日志：ShowObsUrlOfTrainingJobLogs 返回临时 OBS URL（有效期为 5 分钟）。
• StopTrainingJob：只能停止处于 creating、waiting 或 running 状态的作业。
• 自动搜索：仅当试验处于运行状态时，才能提前停止试验。

完整详情请参阅 references/known-issues.md。

---

注意事项

• 所有写入操作（Create/Update/Delete/Stop/Change/Patch/Notify/Accept）都必须在执行前获得用户确认。
• 价格查询：CreateTrainingJob（公共资源池）和 CreateTrainingExperiment 会在执行前触发 BSS 价格查询 — 参阅 references/pricing-inquiry.md
• 专属资源池：使用专属资源池（指定 pool_id）的训练作业无需进行价格查询 — 该资源池已计费。
• 区域未硬编码 — 使用 {region} 占位符。
• 如果未指定 project_id，系统会自动解析。
• 所有文件中均未硬编码 AK/SK — 用户在 Agent 会话之外通过 hcloud configure set 配置凭证。
• Agent 只能使用 hcloud configure list 检查凭证是否存在 — 绝不可读取或回显 AK/SK 值。
• 如果未找到有效凭证，Agent 必须停止并引导用户完成 3 步配置流程（参见先决条件部分）。
• CLI 遇到 Bug 时可使用 SDK 作为后备方案。
• 复杂的嵌套参数请使用 --cli-jsonInput 和 JSON 文件。