huawei-cloud-cloudrobo-train

Windows / PowerShell： 示例使用 bash 语法。要在 Windows PowerShell 中运行：

• 将 \ 换行符合并为一行，或在行尾加上反引号。
• 使用 $env:NAME="value" 设置环境变量，而不是使用 export NAME="value"。
• 单引号括起来的 JSON '{"a":"b"}' 可以直接使用。

概述

管理 CloudRobo 模型训练任务和 SimRL 任务的完整生命周期。提供两种训练模式 （MODEL_TUNING / TRAIN_FROM_SCRATCH）和五种方法（FFT/SFT/LORA/QLORA/DEEPSPEED）。涵盖创建、 监控、诊断、草稿、统计、恢复和流水线编排。

两种任务类型（可通过 --sim-rl 切换）：

类型	API 前缀	CLI 开关	SDK 方法	恢复
常规训练	/v1/training/train-tasks	（默认）	19 个 train_*	是
SimRL	/v1/training/rl-tasks/simulation	--sim-rl	16 个 sim_rl_*	否

场景： 微调、预训练、仿真 RL、保存／重新提交草稿、监控（阶段／资源／事件）、失败诊断、统计。训练可能持续数小时／数天；请以 30–60 秒的间隔轮询。

Agent → CLI (`cloudrobo train <command> [--sim-rl]`) or SDK (`TrainClient`)
      → cloudrobo-service (REST API)

所有操作均针对 cloudrobo-service，且需要 workspace_id。模型／数据集发现操作通过 cloudrobo asset 调用 cloudrobo-asset-manager。

前置条件

有关 CLI 安装、AK/SK 身份验证和工作区配置，请参阅 references/cli-installation-guide.md。所有训练操作都需要有效的 workspace_id。

工作区自动解析：SDK 和 CLI 会按以下顺序自动解析 workspace_id：

1. 显式指定的 --workspace-id 参数（如果提供）
2. 已配置的默认工作区（通过 cloudrobo workspace use --workspace-id <id>）
3. 自动查询：如果未配置工作区，SDK 会查询 cloudrobo workspace list，选择第一个可用工作区，将其保存为默认工作区并使用

如果自动查询失败（未找到工作区），错误消息会引导用户创建工作区。 要手动设置默认工作区：cloudrobo workspace use --workspace-id <id>。

工作流

基于现有任务创建任务

场景：用户说“按照已有任务创建一个训练任务”“复制之前的任务”“create same task again”， 或提及某个现有任务名称。不要引导用户完成完整的任务创建工作流。 相反，直接复用现有任务的配置。

1. 查找现有任务 — 如果用户提供的是任务名称（而非 ID），使用 cloudrobo train list-tasks 按名称查找。如果用户提供了 task_id，则跳至第 2 步。
2. 查询现有任务配置 — cloudrobo train show-task --task-id <id> → 提取完整的 任务配置（train_mode、train_method、algorithm、input_models、datasets、spec、cluster_id、 worker_num、parameters、env、output_models）。
3. 确认需要修改的内容 — 只用一个问题询问用户要修改什么（通常只需修改任务 名称）。常见修改项：name、output_models[].model_name、parameters 的值。
4. 自动解决冲突 — 如果创建的任务使用了相同的输出模型名称，则追加后缀 （例如 -2、-3 或日期），以避免出现“输出模型已存在”错误。如有需要，通过 list-tasks 检查。
5. 构建新配置 — 复制现有配置并应用用户的修改。其他所有字段保持不变 （algorithm、datasets、spec、cluster_id 等）。
6. 提交 — cloudrobo train create-task --config '<new-json>'（优先使用 CLI）。 使用 --verbose/-v 时，先显示便于用户理解的摘要。
7. 轮询状态 — 每隔 30 秒轮询一次，直到任务进入终态。

核心原则：当用户提及现有任务时，Agent 必须先通过 show-task 查询该任务的配置并复用，而不是重新引导用户选择模型／数据集／方法。 用户已经做过这些决定；他们只是想用相同配置创建一个新任务。

任务创建工作流

快捷方式：如果用户引用了现有任务（“按照已有任务创建”、“复制之前的任务”、 “create same task again”），请跳过此工作流，改用基于现有任务创建任务。

此统一工作流用于创建 MODEL_TUNING 和 TRAIN_FROM_SCRATCH 任务。Agent 会协调在 cloudrobo-asset / cloudrobo-resource 中查找， 根据云端实际支持的内容筛选选项并展示，然后静默提交（在 CLI 调用中添加 --verbose/-v，即可先打印面向用户的摘要再提交，无需询问是否确认）。

步骤 1 — 默认任务名称

• 默认名称：Train-{YYYYMMDD-HHMMSS}（例如 Train-20260812-143000）
• Agent 提供默认名称；用户可以重命名。如果用户说“ok”，则使用默认名称。

步骤 2 — 选择训练方式

恰好询问一个问题（使用单次 AskUserQuestion 调用，绝不要重复询问）：

• A) 模型调优（MODEL_TUNING）——有基础模型，可通过 FFT/SFT/LORA/QLORA/DEEPSPEED 进行微调
• B) 无基模型训练（TRAIN_FROM_SCRATCH）——有三种子路径（见步骤 3b）

不重复规则：此工作流中的每个步骤最多询问用户一个问题。同一主题不得并行调用两次 AskUserQuestion。如果某一步需要多个输入（例如 model_name + model_type），请将它们合并到一个问题中，并提供默认选项。

步骤 3a — MODEL_TUNING 子流程

1. 模型来源：具身广场-模型（Gallery，PUBLIC_MODEL_ASSET）/ 空间资产-模型（Workspace，CUSTOM_MODEL_ASSET）

   • CLI：cloudrobo asset list-publication-assets --type model（Gallery）/ cloudrobo asset list-assets --type model（Workspace）
   • 列表输出必须显示：模型名称 + latest_version_id（用户从列表中选择）
   • 重要：列出 Workspace 模型时，必须先筛选出 status == "DRAFT" 的结果，再呈现给用户。只有 DRAFT 状态的模型才可用于训练。CREATING 状态的模型会导致 CREATE_FAILED，并报错 "输入模型未就绪"。如果没有 DRAFT 模型，请提醒用户并建议改用 Gallery 模型。Gallery 模型通常都已就绪。
   • Gallery 模型（默认流程）：适用下方步骤 2-5——算法来自模型的 actions 数组
   • Workspace 模型（自定义流程）：跳过步骤 2-5；算法配置只需 algorithm_asset_id 和 algorithm_version_id（2 字段格式）。后端会自动从算法资产解析引擎/命令。顶层 inputs/outputs 数组为必填项。请参阅下方的 Workspace 模型子流程。

2. 选择模型 → 从所选模型的列表条目中提取 asset_id + latest_version_id。 不要再次询问用户版本——自动使用 latest_version_id。只有用户明确要求使用非最新版本时才询问。

3. 查询模型版本详情 GET /v1/assets/{asset_id}/versions/{version_id} → 获取 actions 数组。每个 action：{action, algorithm:{asset_id, version_id}, status}

4. 仅显示可用的训练操作——筛选 actions 中 status == "ENABLE" 且属于训练相关操作的条目（例如 "FFT"、"SFT"、"LORA"、"QLORA"、"DEEPSPEED"）。排除 "ONLINE_DEPLOYMENT" 等非训练操作。action 字段的值将作为请求体中的 train_method。不要提供模型未声明的操作。

5. 用户选择方法 → 提取匹配 action 的 action 值（即 train_method）以及 algorithm.asset_id + algorithm.version_id。不要询问用户算法版本——版本直接来自 action。自动提取并继续。

6. 查询算法版本详情 GET /v1/assets/{algo_asset_id}/versions/{algo_version_id} → 获取 ext_metadata。从以下确切字段中提取：

   • 超参数：ext_metadata.hyperparams → [{name, default, constraint, description}]
   • 环境变量：ext_metadata.environment_variables → [{name, default, description}]
   • 资源约束：ext_metadata.resource → [{key, values, operator, constraints?}]
     • flavor_type.values：所需的 flavor 类型（例如 ["Ascend"]）——必须与资源池的 flavor 匹配
     • device_distributed_mode.constraints：{step, range:[min, max], default}——每个 worker 的 NPU 卡数范围；default 为建议卡数
     • host_distributed_mode.values："singular"（单机，worker_num=1）或 "multiple"
   • 注意：ext_metadata.env 可能存在，但已弃用；始终使用 environment_variables

7. 展示环境变量和超参数——提供两张表：

   • 超参数表：| 参数名 | 默认值 | 说明 | 约束 |
   • 环境变量表：| 变量名 | 默认值 | 说明 | 用户可以修改值。构建 parameters JSON 字符串：每项为 {key, desc, value, constraint}（传入所有超参数，无论是否必填）。根据 environment_variables 构建 env JSON 字符串（为空或缺失时默认为 "[]"）。

8. 选择数据集——有三种来源，各自所需字段不同：

   • Gallery（具身广场）：source_type: "PUBLIC_DATASET_ASSET" + dataset_asset_id + version_id + dataset_name
   • Workspace（空间资产）：source_type: "CUSTOM_DATASET_ASSET" + dataset_asset_id + version_id + dataset_name。筛选出 status == "DRAFT" 的数据集——与模型相同，只有 DRAFT 数据集才可使用。
   • OBS（对象存储）：source_type: "OBS" + 仅需 url_path（例如 "obs://bucket-name/dataset/"）。不需要 dataset_asset_id/version_id/dataset_name。

   关键：工作区数据集使用 CUSTOM_DATASET_ASSET（而不是 DATASET）。使用错误的 source_type 会导致 RUN_FAILED，并在不到 2 分钟内以 exitCode 1 退出。

9. 资源选择 — 选择资源池前，检查所有使用 Gallery source type 的输入资产（模型和数据集）的 data_read 权限（PUBLIC_MODEL_ASSET_OFFICIAL、PUBLIC_MODEL_ASSET_COMMUNITY、PUBLIC_DATASET_ASSET）：

   cloudrobo asset check-permission --asset-id <id> --version-id <ver> --permissions data_read
   

   • 如果任何资产返回 data_read: deny → 专属资源池将失败，并提示 "专属资源池需要输入资产的可读权限" → 必须使用共享资源池
   • 如果所有资产都返回 data_read: allow → 专属资源池和共享资源池均可使用
   • 工作区资产（CUSTOM_*）和 OBS 数据集无需进行此检查

   然后查询资源池：cloudrobo resource list-pools --resource-type MODELARTS （注意：在某些环境中，--usages MODEL_TRAINING 筛选条件可能导致 504 代理超时； 如果失败，请省略筛选条件，并手动选择 usages 数组中包含 MODEL_TRAINING 的资源池）。 对每个资源池，读取 config.flavor.ASCEND[] （规格字符串列表，例如 "1 * SNT9B2 | 24 vCPUs | 192 GiB"）。根据第 3a.6 步中的 ext_metadata.resource 约束筛选规格：

   • 从每个规格中解析 NPU 数量（* 前的数字，例如 "2 * SNT9B2..." → 2）
   • 仅显示 NPU 数量 >= device_distributed_mode.constraints.range[0]（最小值） 且 <= range[1]（最大值）的规格。例如，range: [2, 8] 会筛除 1 卡规格。
   • 默认选择：与 constraints.default 匹配的规格（例如，default: 2 → "2 * SNT9B2 | 48 vCPUs | 384 GiB"）。用户可以选择其他有效规格。
   • worker_num：如果 host_distributed_mode 为 "singular"，则设为 1；如果为 "multiple"，则询问用户。 → 选择资源池 → cluster_id（带 pool- 前缀）。规格：Ascend: <n> * <model> | <vCPUs> vCPUs | <GiB> GiB

10. 输出模型 — 询问一次 save_mode：

    • NEW_MODEL：在一个问题中询问 model_name 和 model_type；自动生成 version_name，值为 "0.0.1"（用户可以修改）。不要逐项单独询问。 字段：save_mode + model_name + version_name + model_type + strict:false
    • NEW_VERSION：在一个问题中询问要使用的现有模型和 version_name。列出已有模型及其最新版本； 用户选择模型并提供新的 version_name。 字段：save_mode + model_asset_id + model_name + version_id + version_name + model_type
    • NOT_SAVE：跳过其余输出模型字段。 字段：仅 save_mode — {"save_mode": "NOT_SAVE"}
    • 克隆/复制任务警告：如果用户要求“基于现有任务”创建任务、“复制之前的任务”或“再次创建相同任务”， 输出模型名称必须不同于原任务。提交前，通过 list-tasks 或 show-task 检查已有的输出模型名称。如果发现冲突，请提示用户提供新名称。 冲突时的错误信息："输出模型已存在，请更换模型名称"（输出模型已存在，请更换模型名称）。

11. 提交 — cloudrobo train create-task --config '<json>'（CLI）或 client.create_train_task(req)（SDK）。 默认：静默提交（不输出内容）。使用 --verbose/-v 时，先显示面向用户的摘要。 **绝不要输出原始 JSON 或代码。**然后直接提交，不询问是否继续。

12. 轮询状态 — 每隔 30s 检查一次，在终态前报告状态变化

13. 完成后： FINISHED → 建议导出/部署；FAILED/RUN_FAILED/CREATE_FAILED → 提供日志/事件以便排查

步骤 3a-WS — 工作空间模型子流程（空间资产模型）

当用户在步骤 3a.1 中选择工作空间模型（CUSTOM_MODEL_ASSET）时，无法从模型的 actions 数组中解析算法。相反，必须根据工作空间模型的算法元数据完成配置。此子流程替代 Gallery 路径的步骤 2-5。 步骤 6-13（ext_metadata、超参数、数据集、资源、输出模型、提交、轮询）共用。

1. 选择工作空间模型 → 从列表项中提取 asset_id + latest_version_id。 不要再次询问用户版本。

   重要：工作空间模型的 status 必须为 "DRAFT"。状态为 CREATING 的模型不能用作输入，并会导致 CREATE_FAILED，错误为 "输入模型未就绪"。 如果工作空间中没有 DRAFT 模型，请告知用户，并建议改用 Gallery 模型。

2. 查询模型版本详情 → 获取算法配置的 ext_metadata（engine、image、code_dir、 command 等）。工作空间模型的算法信息嵌入在模型自身中，而不是单独算法资产的 actions 数组中。

3. 构建算法配置 — 只需要 2 个字段。后端会自动从 算法资产解析 engine/command。不要包含 algorithm_source_type、engine、code_dir、command、 image_asset_id 或 image_version_id：

   {
     "algorithm_asset_id": "<algo-asset-id>",
     "algorithm_version_id": "<algo-version-id>"
   }
   

4. 构建 input_models — 使用 source_type: "CUSTOM_MODEL_ASSET"（而非 PUBLIC_MODEL_ASSET）：

   [{"source_type": "CUSTOM_MODEL_ASSET", "model_asset_id": "...", "version_id": "...", ...}]
   

5. 构建 inputs/outputs 数组 — 工作空间模型需要顶层的 inputs 和 outputs：

   inputs 格式（各项字段取决于 source_type）：

   "inputs": [{
     "name": "<display-name>",
     "url_path": "obs://bucket/path/",
     "source_type": "CUSTOM_MODEL_ASSET",
     "access_method": "env",
     "local_dir": "<name>=/home/ma-user/cloudrobo/inputs/<name>_0"
   }]
   

   • access_method："env"（环境变量）或 "parameter"（超参）
   • local_dir：env 模式 → "<name>=<container-path>"，parameter 模式 → "--<name>=<container-path>"

   outputs 格式（更简单 — 无 source_type，始终为 OBS 路径）：

   "outputs": [{
     "name": "<output-name>",
     "url_path": "obs://bucket/output-path/",
     "access_method": "parameter",
     "local_dir": "--<name>=/home/ma-user/cloudrobo/outputs/<name>_0"
   }]
   

6. 继续 Gallery 路径的步骤 6-13（ext_metadata 超参数、环境变量、资源约束、 数据集选择、资源选择、输出模型、提交、轮询）。对于 MODEL_TUNING，log_path 是可选的。

与 Gallery 模型的主要区别：工作空间模型使用 CUSTOM_MODEL_ASSET source_type、 2 字段算法格式（与 Gallery 相同），并且需要顶层的 inputs/outputs 数组。 Gallery 模型使用 PUBLIC_MODEL_ASSET，且不需要 inputs/outputs 数组。

步骤 3b — TRAIN_FROM_SCRATCH 子流程

询问选择哪条子路径：

• A) 预制算法（Gallery 算法）
• B) 空间资产-算法（Workspace 算法）
• C) 现配置算法（自定义配置，无预置算法）

通用步骤（适用于所有子路径）：

• 数据集选择（与步骤 3a.8 相同）
• 资源选择（与步骤 3a.9 相同，使用 ext_metadata.resource 约束；对于 Custom：无约束，显示所有规格）
• 超参数（与步骤 3a.7 相同；对于 Custom：从头开始，无默认值；如果没有则构建 "[]"）
• 输出模型（与步骤 3a.10 相同；NEW_MODEL 只需 4 个字段：save_mode、model_name、version_name、model_type）
• 构建请求体：name（唯一，追加时间戳）、train_mode: "TRAIN_FROM_SCRATCH"、datasets、spec、worker_num、cluster_id、parameters、env（默认为 "[]"）、output_models、log_path（可选）、enable_jupyter（可选，仅限 DEDICATED）
• 提交（cloudrobo train create-task --config '<json>'，使用 --verbose 显示摘要），每隔 30 秒轮询，直到进入终止状态

算法配置差异：

子路径	算法格式	发现方式
Gallery（预制）	2 个字段：algorithm_asset_id + algorithm_version_id。后端会自动解析引擎/镜像。	list-publication-assets --type algorithm → 提取 algorithm_asset_id + latest_version_id。查询 ext_metadata 获取超参数/环境/资源。
Workspace（空间资产）	7 个字段：engine.image_url + image_asset_id + image_version_id + code_dir + command + algorithm_asset_id + algorithm_version_id。	list-assets --type algorithm → 提取 algorithm_asset_id + latest_version_id。查询 ext_metadata 获取引擎/命令/代码目录以及超参数/环境/资源。
Custom（现配置）	4 个字段：image_asset_id + image_version_id + command + algorithm_source_type: "TEMP_CONFIGURE_ALGORITHM"。不包含 algorithm_asset_id。	用户提供镜像资产、启动命令和本地代码目录。没有可用的 ext_metadata。

注意：

• Gallery/Workspace 不需要 algorithm_source_type（会根据 algorithm_asset_id 自动推断）；仅 Custom 需要此字段（没有 asset_id）。
• Workspace 算法还需要顶层的 inputs/outputs 数组（格式与步骤 3a-WS 相同）。
• Custom 配置需要 inputs/outputs 数组。inputs 支持 4 种 source_type 值：PUBLIC_DATASET_ASSET、CUSTOM_DATASET_ASSET、OBS、CUSTOM_MODEL_ASSET。格式参见步骤 3a-WS。
• 失败时（2 分钟内以 exitCode 1 进入 RUN_FAILED，且没有日志文件）：很可能是数据集格式不兼容。请检查 source_type 和算法兼容性。

SimRL 工作流（仿真强化学习）

SimRL 任务使用的配置架构与常规训练任务不同：使用 config_mode + task_set + simple_params/rl_config_content，而非 algorithm + parameters。SimRL 任务通过 --sim-rl 标志共用相同的 CLI 命令接口。SimRL 不支持 resume。

步骤 1 — 模型发现

询问模型来源：

• 具身广场模型（Gallery）：cloudrobo asset list-publication-assets --type model --action-status ENABLE --actions LIBERO_SPATIAL,LIBERO_OBJECT,LIBERO_GOAL,LIBERO_10 --actions-operator OR → 选择模型 → 提取 model_asset_id + latest_version_id。source_type: "PUBLIC_MODEL_ASSET"。 不要再次询问用户版本 — 自动使用 latest_version_id。 关键：--actions 和 --action-status 筛选条件是必需的 — 不加这些条件，查询会返回具身广场中的所有模型，而不只是兼容 SimRL 的模型。只有启用了 LIBERO_* 动作的模型才能用于 SimRL 任务。
• 空间资产模型（Workspace）：cloudrobo asset list-assets --type model → 选择模型 → 提取 model_asset_id + latest_version_id。source_type: "CUSTOM_MODEL_ASSET"。

查询模型版本详情 GET /v1/assets/{asset_id}/versions/{version_id} → 获取 actions 数组。每个动作代表一个任务集（例如 LIBERO_SPATIAL、LIBERO_GOAL）。

步骤 2 — 选择任务集

从 actions 数组中向用户展示可用的任务集。提取 action 字段的值 （例如 "LIBERO_SPATIAL"）→ 将其作为请求正文中的 task_set。

查询所选任务集详情（动作详情），以获取：

• ext_metadata.hyperparams → SIMPLE 模式的参数默认值
• ext_metadata.environment_variables → SIMPLE 模式的环境变量
• ext_metadata.yaml_config → ADVANCED 模式的完整 YAML 配置模板
• ext_metadata.resource → 资源限制（规格类型、NPU 卡数量）

步骤 3 — 选择配置模式

询问用户选择哪种参数配置模式：

• 快速配置（SIMPLE）：config_mode: "SIMPLE"，使用 simple_params（JSON 字符串数组）。 展示 ext_metadata.hyperparams 中的超参数表，用户可以修改值。 RL_ALGO 默认值为 ppo。

  "simple_params": "[{\"key\":\"RL_ALGO\",\"value\":\"ppo\",\"desc\":\"强化学习算法\"},{\"key\":\"MAX_EPOCHS\",\"value\":\"100\",\"desc\":\"训练轮数\"},...]"
  

  每个条目：{key, value, desc}。simple_params 接受 JSON 字符串或数组；SDK 会自动将数组序列化为 JSON 字符串。

• YAML 配置（ADVANCED）：config_mode: "ADVANCED"，使用 rl_config_content（完整 YAML 字符串）。 使用 ext_metadata.yaml_config 的内容预填，用户可以调整。

  "rl_config_content": "runner:\n  task_type: embodied\n  max_epochs: 100\n  ..."
  

步骤 4 — 选择资源池

权限检查（对具身广场资产要求 data_read）和资源池查询方式与步骤 3a.9相同。 根据 ext_metadata.resource 限制筛选规格。SimRL 专属规则：

• SHARED（公共）池：enable_jupyter 必须为 false（不支持 JupyterLab）
• DEDICATED（专属）池：enable_jupyter 可以为 true 或 false（由用户选择）
• spec 格式："ASCEND: <n> * <model> | <vCPUs> vCPUs | <GiB> GiB"（ASCEND 必须大写）

步骤 5 — 输出模型

询问 save_mode：

• NEW_MODEL（新模型）：7 个字段：

  {"save_mode": "NEW_MODEL", "model_name": "<name>", "version_name": "0.0.1", "model_type": "vla",
   "model_asset_id": null, "version_id": null, "strict": false, "skills": []}
  

• NEW_VERSION（已有模型新版本）：8 个或更多字段：

  {"save_mode": "NEW_VERSION", "model_name": "<existing-model-name>", "version_name": "<new-version>",
   "model_type": "vla", "model_asset_id": "<existing-model-asset-id>", "version_id": "",
   "strict": false, "skills": [{"name": "<skill-name>", "prompt": "<skill-prompt>"}]}
  

  version_id 为空字符串 ""（而不是 null）。skills 数组可以包含技能定义。

步骤 6 — 构建 SimRL 配置

构造 JSON，包含：

• name：唯一任务名称
• description：可选
• workspace_id：由 SDK 自动注入
• input_models：[{source_type, model_asset_id, model_name, version_id, version_name}] （具身广场使用 PUBLIC_MODEL_ASSET，Workspace 使用 CUSTOM_MODEL_ASSET）
• task_set：来自步骤 2（例如 "LIBERO_SPATIAL"）
• config_mode：来自步骤 3 的 "SIMPLE" 或 "ADVANCED"
• simple_params：JSON 字符串（仅 SIMPLE 模式）
• rl_config_content：YAML 字符串（仅 ADVANCED 模式）
• spec："ASCEND: <n> * <model> | <vCPUs> vCPUs | <GiB> GiB"
• cluster_id：带 pool- 前缀的资源池 ID
• worker_num：通常为 1
• output_models：来自步骤 5
• enable_jupyter：SHARED 池设为 false；DEDICATED 池可设为 true 或 false

注意：SimRL 不使用 algorithm、datasets、parameters、env 或 log_path 字段。

步骤 7 — 提交并监控

1. 创建 SimRL 任务 — train create-task --config '<json>' --sim-rl（或先用 save-draft --sim-rl 保存草稿）。SDK：client.create_sim_rl_task(req)。
2. 轮询状态 — train show-task --task-id <id> --sim-rl 或 train list-tasks --sim-rl
3. 监控 — get-resource-usage --metric ... --start ... --end ... --sim-rl、 get-events --start-time ... --end-time ... --sim-rl、get-logs --sim-rl、 get-signed-url --file-source ... --file-name ... --sim-rl
4. 生命周期 — stop-task --sim-rl、restart-task --sim-rl、clone-task、 delete-tasks --sim-rl（按 ID 执行 DELETE）、update-task --sim-rl
5. 统计信息 — train stats --workspace-id <id> --sim-rl

草稿工作流（保存并重新提交）

场景：用户想要保存任务配置，但暂不立即执行，之后再编辑并提交。

1. 准备任务配置 — 草稿仅需 name + workspace_id；algorithm/spec 可选
2. 保存草稿 — train save-draft --config '<draft-json>'（或使用 --sim-rl 保存 SimRL 草稿）→ 返回 task_id，任务状态 = DRAFT
3. 之后编辑配置并重新提交：
   • SDK（推荐用于提交草稿）：使用完整的 TrainTaskDto 请求体调用 restart_train_task(task_id, req) — 重启接口会编辑并重新提交任务
   • CLI：train restart-task --task-id <draft-id> 使用现有配置重新提交；如需传入编辑后的配置，请使用 SDK。对于 SimRL，使用 restart-task --sim-rl 重新提交
4. 重新提交后，任务离开 DRAFT 状态 → CREATING → WAITING → RUNNING → 终态

推理说明：save-draft（POST /train-tasks/draft）会返回处于 DRAFT 状态的 task_id；restart（POST /train-tasks/{id}/restart）接受完整的 TrainTaskDto 请求体，并会编辑/重新提交任务。

监控工作流（进行中的任务）

场景：任务处于 RUNNING 状态，跟踪进度和资源使用情况。

1. 轮询状态 — show-task --task-id <id>（间隔 30s）
2. 查询执行阶段 — get-stages --task-id <id> → 返回 SCHEDULING → PREPARING → RUNNING → END，以及子阶段和时间戳
3. 查询资源使用情况 — get-resource-usage --task-id <id> --metric <m> --start <ts> --end <ts> → CPU/GPU/NPU 利用率和采样点
4. 查询事件 — get-events --task-id <id> --start-time <ts> --end-time <ts> → 带时间戳的 INFO/WARNING/ERROR/DEBUG 事件
5. 向用户报告进度；出现 WARNING/ERROR 事件时，主动发出提醒

诊断工作流（故障诊断）

场景：任务 FAILED / RUN_FAILED / CREATE_FAILED → 自动分析、定位原因并建议修复方案。

1. 获取任务详情，确认失败状态、失败阶段和退出代码
2. 获取执行阶段，确定哪个阶段失败（SCHEDULING/PREPARING/RUNNING/END）
3. 获取事件，按 level=Error 筛选以查找错误事件
4. 获取日志 — 尝试多种方法（任务快速失败时可能没有日志）：
   • get-logs --task-id <id>（CLI）
   • SDK：list_observations(task_id)，列出可用的日志文件
   • SDK：get_log_signed_url(task_id, file_source, file_name)，获取下载 URL
   • 如果所有方法都返回空结果/500：任务可能在生成日志前就已失败
5. 分析关键错误模式：
   • CREATE_FAILED → 检查 spec 格式、cluster_id、资源可用性、输入模型状态
   • 输入模型未就绪 → 错误：“输入模型未就绪”（输入模型未就绪）。当 input_models[].source_type 为 CUSTOM_MODEL_ASSET，但模型 status 为 CREATING（而非 DRAFT）时会出现此问题。修复方法：等待模型达到 DRAFT 状态，或改用 Gallery 模型 （PUBLIC_MODEL_ASSET）。通过 cloudrobo asset show-asset --asset-id <id> 检查模型状态
   • 任务名称冲突 → 错误：“资源已存在”（409 Conflict）。修复方法：使用唯一的任务名称 （追加时间戳后缀，例如 Train-YYYYMMDD-HHMMSS）
   • 资源调度失败 → 检查 spec 和 worker_num、集群容量
   • 镜像拉取失败 → 检查 algorithm.image_url（针对 MODEL_TUNING）或算法资产配置（针对 TRAIN_FROM_SCRATCH）
   • 数据集访问被拒绝 → 检查 datasets[].dataset_asset_id 和工作区权限
   • 数据集格式不兼容 → RUN_FAILED，exitCode 为 1，且在 2 分钟内失败，没有日志文件。 当数据集格式与算法要求不匹配时（例如，LeRobot 算法需要特定的数据集格式），或 source_type 设置错误时（使用 DATASET 而非 CUSTOM_DATASET_ASSET），会出现此问题。修复方法：确认数据集的 source_type 正确 （工作区使用 CUSTOM_DATASET_ASSET，而非 DATASET）；尝试改用 Gallery 数据集 （PUBLIC_DATASET_ASSET）；查看算法文档，了解所需的数据集格式
   • OOM → 检查 spec 内存、worker_num，并减小参数中的 batch_size
   • 算法错误 → 检查 algorithm.command、boot_file、parameters
   • 输出模型已存在 → 错误：“输出模型已存在，请更换模型名称”。对于克隆/重启，SDK 会通过查询资产服务中的最新版本，自动递增 version_name。对于创建任务，请使用唯一的模型名称（追加后缀，例如 -2、-3 或时间戳）
   • 专属资源池资产权限 → 错误：“专属资源池需要输入资产的可读权限”。当使用 DEDICATED 池且资产权限不足时会出现此问题。修复方法：切换到 SHARED 池，或为所有相关资产（input_models、algorithm、datasets）授予读/写/使用权限
   • 日志不可用（API 返回 500 或空列表）：任务失败过快，未生成日志。 根据事件中的任务执行时间和退出代码进行检查。如果 exitCode 为 1 且运行时间少于 2 分钟，则可能是数据集格式或训练脚本错误。建议尝试其他数据集，或查看算法文档了解所需的数据集格式。
6. 输出诊断结论和修复建议
7. 获得用户确认后，修复配置并执行 restart-task，或保存草稿后执行 create-task

长时间运行任务工作流

1. 训练任务可能运行数小时/数天；创建任务后，设置合理的轮询间隔（60 秒以上）
2. 每次轮询时，报告：当前状态、当前阶段、已用时间、最新事件
3. 超时后（由用户定义），输出当前状态并建议：继续 / 查看日志 / 查看 资源使用情况 / 停止

CLI 命令格式

cloudrobo train <command> [OPTIONS] [--sim-rl]

• 子命令：kebab-case（create-task、list-tasks、get-stages 等）
• --sim-rl 用于路由到 SimRL API；--workspace-id <id> 可覆盖 stats 中的工作区 ID
• 通过 --config '<json>' 传入 JSON 参数；也可通过 --config-file 从文件读取
• 输出：JSON 写入标准输出

CloudRobo CLI 是基于 Click 自行开发的工具（不是 hcloud/KooCLI）。SDK 提供 33 个方法 （12 个 train_* + 15 个 sim_rl_* + 6 个未加前缀的方法）；CLI 提供 20 个命令。list_observations 仅在 SDK 中提供；resume 和检查点方法仅用于训练。请参阅 references/task-config-catalog.md 了解覆盖范围矩阵。

核心命令

优先使用 CLI：始终优先使用 CLI 命令（cloudrobo train <command>），而不是直接调用 SDK。 仅在以下情况下使用 Python SDK（TrainClient）：（a）CLI 不支持所需操作（例如， list_observations 仅在 SDK 中提供）；（b）跨包查询（例如，通过资产服务查询资产版本详情）；或（c）CLI 无法处理动态 JSON 组装。完整的 SDK 模板见 SDK 快速入门。

自动解析 workspace_id：所有需要 workspace_id 的命令（create-task、 save-draft、restart-task、list-tasks、stats）都会自动从以下位置解析该值：（1）显式指定的 --workspace-id 参数；（2）已配置的默认工作区（cloudrobo workspace use）；或（3）自动查询。 无需在 --config JSON 请求体中包含 workspace_id——SDK 会自动注入该值。

SDK 级验证：SDK 方法（create_train_task、create_sim_rl_task、save_draft、 create_sim_rl_task_draft、restart_train_task、restart_sim_rl_task、copy_sim_rl_task、 register_train_checkpoint）会在发起 HTTP 调用前验证必填字段。缺少字段时会引发 ValueError。 CLI 会自动将这些错误转换为易于理解的 click.UsageError 消息。需要以编程方式处理错误时，请直接使用 SDK。

创建任务

训练模式（微调 MODEL_TUNING 或预训练 TRAIN_FROM_SCRATCH）、方法 （FFT/SFT/LORA/QLORA/DEEPSPEED）、基础模型、数据集和规格均通过 --config JSON 请求体指定——没有专门的 finetune/pretrain 子命令。

提交微调任务（MODEL_TUNING）

cloudrobo train create-task --config '<task-json>'

• SDK： client.create_train_task(req)——请求格式见 步骤 3a
• API： POST /v1/training/train-tasks

提交预训练任务（TRAIN_FROM_SCRATCH）

cloudrobo train create-task --config '<task-json>'

• SDK： client.create_train_task(req)——请求格式见 步骤 3b
• API： POST /v1/training/train-tasks
  • log_path：可选 OBS 路径——如果用户未指定日志路径，可省略
  • enable_jupyter：可选布尔值——设为 true 可在训练期间访问 JupyterLab
  • workspace_id：由 SDK 自动注入

通过完整 JSON 配置创建任务（训练或 SimRL）

cloudrobo train create-task --config '<task-json>' [--sim-rl]

• SDK： client.create_train_task(req) / client.create_sim_rl_task(req)
• API： POST /v1/training/train-tasks / POST /v1/training/rl-tasks/simulation

保存草稿任务（训练或 SimRL）

cloudrobo train save-draft --config '<draft-json>' [--sim-rl]

• SDK： client.save_draft(req) / client.create_sim_rl_task_draft(req)
• API： POST /v1/training/train-tasks/draft / POST /v1/training/rl-tasks/simulation/draft

任务管理

所有命令均接受 --sim-rl（resume-task、clone-task 除外，它们仅适用于 SimRL）。API 前缀： /v1/training/train-tasks（train）/ /v1/training/rl-tasks/simulation（SimRL）。

命令	CLI 语法	SDK 方法	API 后缀
列出任务	list-tasks [--train-mode] [--status] [--offset] [--limit]	list_train_tasks / list_sim_rl_tasks	GET /
查看任务	show-task --task-id <id>	show_train_task / show_sim_rl_task	GET /{task_id}
更新任务	update-task --task-id <id> --config '<json>'	update_train_task / update_sim_rl_task	PATCH /{task_id}
删除任务	delete-tasks --task-id <id> [--task-id <id>...]	batch_delete_train_tasks(execution_ids) / delete_sim_rl_task(task_id)	POST /batch-delete（train）/ DELETE /{task_id}（SimRL）

delete-tasks 的行为：对于常规训练任务，CLI 会在调用 batch-delete 前，通过 show-task 根据 提供的 task_id 自动获取 execution_id。用户可以直接传入任务 ID，无需手动查找 execution_id。 对于 SimRL，会直接使用 task_id。

| 停止任务 | stop-task --task-id <id> | stop_train_task / stop_sim_rl_task | POST /{task_id}/stop | | 重启任务 | restart-task --task-id <id> [--config '<json>'] [--config-file <path>] [--sim-rl] | restart_train_task(task_id, req=None) / restart_sim_rl_task(task_id, req=None, task_detail=None) | POST /{task_id}/restart | | 克隆任务 | clone-task --task-id <id> [--config '<json>'] [--config-file <path>]（仅适用于 SimRL） | copy_sim_rl_task(task_id, req=None, task_detail=None) | POST /rl-tasks/simulation/{task_id}/copy | | 恢复任务 | resume-task --task-id <id>（仅适用于 train） | resume_train_task | POST /{task_id}/resume | | 统计 | stats --workspace-id <id> [--user-id] | count_train_tasks_by_status / count_sim_rl_tasks_by_status | GET /stats |

重启 = 编辑并重新提交。CLI 支持使用 --config/--config-file 覆盖原任务的字段；SDK 的 req 参数也可执行相同操作。非 DRAFT 状态的 train 任务无法修改 name/train_mode/train_method；SimRL 重启要求任务处于 DRAFT 状态。SDK 的 task_detail 参数可跳过自动执行的 show 调用。 SDK 会自动清理 input_models/output_models（移除运行时字段）；当 save_mode=NEW_MODEL|NEW_VERSION 时，会自动递增 version_name（查询资产服务以获取最新版本）；并会自动将 simple_params/rl_config_content 从数组/字典序列化为 JSON 字符串。 克隆仅适用于 SimRL（train 的复制 API 已移除）。除非 req 提供了明确的 name，否则 SDK 会自动生成一个带 -copy-{4hex} 后缀的新名称（例如 my-task-copy-a1b2）。恢复仅适用于 train。

任务监控

命令	必需参数	SDK 方法	返回值
get-stages --task-id <id>	--task-id	list_train_stages	4 个阶段：SCHEDULING→PREPARING→RUNNING→END
get-resource-usage --task-id <id> --metric <m> --start <s> --end <e>	--metric --start（秒） --end（秒）	show_resource_usage / show_sim_rl_task_resource_usage	CPU/GPU/NPU 利用率
get-logs --task-id <id> [--file-name] [--log-name-pre]	--task-id	get_log_content / show_sim_rl_task_observations_content	日志内容（--file-name，而非 --file-path）
get-signed-url --task-id <id> --file-source <s> --file-name <n>	--file-source --file-name	get_log_signed_url / show_sim_rl_task_observations_signed_url	OBS 临时下载 URL
get-events --task-id <id> --start-time <ms> --end-time <ms>	--start-time（毫秒） --end-time（毫秒）	list_events / list_sim_rl_task_events	INFO/WARNING/ERROR/DEBUG 事件
（仅 SDK）list_observations	--task-id	list_observations / list_sim_rl_task_observations	文件列表（CLI get-logs 可获取内容）

所有命令都接受 --sim-rl。get-events 使用毫秒（13 位），get-resource-usage 使用秒（10 位）。

检查点管理（仅限 train，不使用 --sim-rl）

cloudrobo train list-checkpoints --task-id <id> [--status] [--name] [--offset] [--limit] [--order]
cloudrobo train register-checkpoint --task-id <id> --checkpoint-name <name> [--save-mode NEW_VERSION|NEW_MODEL] [--version-name] [--model-name]

命令	SDK 方法	API
list-checkpoints	list_train_checkpoints(task_id, **params)	GET /{task_id}/checkpoints
register-checkpoint	register_train_checkpoint(task_id, req)	POST /{task_id}/checkpoints/register

register-checkpoint：NEW_VERSION（默认）会添加到现有模型；NEW_MODEL 会创建新模型 （需要 --model-name）。返回 WAITING；之后异步处理。

算法发现

列出可用算法

cloudrobo asset list-publication-assets --type algorithm [--name <fuzzy-name>] [--limit 20]

• SDK（跨包）： asset_client.list_publication_assets(type="algorithm", limit=20)
• API： 跨包调用——调用资源服务，而非直接调用 train 服务。

每个算法都包含创建预训练任务所需的 ext_metadata，其中有 engine.image_url、command、boot_file。

查询资源版本详情（模型 / 算法 / 数据集）

• API： GET /v1/assets/{asset_id}/versions/{version_id}（cloudrobo-asset-manager 服务）
• 模型版本详情返回：actions 数组，每个 action 包含 {action, algorithm:{asset_id, version_id}, status}。action 字段（例如 FFT、LORA、ONLINE_DEPLOYMENT）会成为 train_method。筛选训练相关的 action，要求 status=="ENABLE"（排除 ONLINE_DEPLOYMENT 等）
• 算法版本详情返回：ext_metadata.hyperparams（默认超参数）、 ext_metadata.environment_variables（环境变量，格式为 [{name, default, description}]）、 ext_metadata.engine.image_url、ext_metadata.command、ext_metadata.inputs/outputs、 ext_metadata.resource（NPU 卡约束——参见步骤 3a.6）
• 用法：微调时，从模型 actions 中获取算法 → 查询算法版本详情以获取超参数；预训练时，直接查询算法资源版本详情以获取超参数和完整的 ext_metadata

提交行为与确认

默认静默提交。 创建命令（create-task/restart-task/ register-checkpoint/save-draft）无需提示即可提交。Agent 不得打印原始 JSON 或代码。使用 --verbose/-v 时，先以便于用户理解的分组摘要（表格/列表）呈现，然后直接提交——无需询问是否确认。

破坏性操作（stop-task/delete-tasks/resume-task）：Agent 执行前须确认 task_id。 restart-task：如果修改了配置，简要展示差异后提交；如果没有修改，则静默提交。 update-task：PATCH 前确认字段变更。

详细显示格式

按分组显示为表格/列表，绝不显示原始 JSON。包含以下部分：【基本信息】【算法配置】【基础模型】（仅限 MODEL_TUNING）【超参】（表格）【环境变量】（表格）【数据集】【资源配置】【训练产物】。不显示不适用的部分；环境变量为空时显示“（无）”。对于 restart-task --verbose：显示 task_id 和已更改的字段（差异格式）。

必填参数（无默认值）

命令	必填参数	备注
get-resource-usage	--metric --start --end	秒（10 位数字）
get-events	--start-time --end-time	毫秒（13 位数字）
get-signed-url	--file-source --file-name	file_source 来自 8 值枚举
stats	--workspace-id	—
finetune	--method	大写：FFT/SFT/LORA/QLORA/DEEPSPEED
pretrain/finetune	--spec	Ascend: N * Model | vCPUs vCPUs | GiB GiB

参考文档

• CLI 安装指南 — cloudrobo CLI 的安装与配置
• IAM 策略 — 最小权限凭证模型
• 验证方法 — 验证方法详情
• 数据流图 — Mermaid 数据流图
• 验收标准 — 验收标准
• 任务配置参考 — TrainTaskDto 字段、算法映射、spec 格式、状态枚举、阶段/事件结构、三层覆盖矩阵
• SDK 快速入门 — 完整的 Python SDK 调用模板：初始化、微调/预训练/SimRL 完整请求体示例、草稿工作流、轮询与监控、跨包查询
• API 路径 — 完整端点列表及 SDK 源代码行引用

边缘情况

场景	处理方式
缺少 workspace_id	所有命令都会从配置中自动解析或自动查询；运行 cloudrobo workspace use 设置默认值
任务处于非终止状态	每隔 30-60s 轮询一次；训练可能持续数小时或数天
spec 格式	字符串 Ascend: <n> * <model> | <vCPUs> vCPUs | <GiB> GiB，不是 JSON。根据 ext_metadata.resource 约束进行筛选
train_method / train_mode	大写枚举值：FFT/SFT/LORA/QLORA/DEEPSPEED；MODEL_TUNING/TRAIN_FROM_SCRATCH
CREATE_FAILED	检查 spec 格式、cluster_id、资源可用性、任务名称唯一性（409 Conflict）、输入模型状态（工作区模型必须为 DRAFT）
RUN_FAILED	检查日志/事件；常见原因：OOM、镜像拉取失败、数据集访问被拒、数据集格式不兼容（2 分钟内 exitCode 1，且没有日志）
资源调度失败	检查 spec、worker_num、集群容量，以及 ext_metadata.resource 的最小 NPU 约束
已停止的任务	使用 restart-task 重新提交；对于受支持的仅训练场景，使用 resume-task
SimRL 恢复	不支持；resume-task 不接受 --sim-rl
通过 CLI 提交草稿	restart-task 支持使用 --config/--config-file 在重新提交前编辑字段
缺少必填字段	SDK 会在 HTTP 调用前进行校验；CLI 会显示 click.UsageError，并列出缺少的字段
未设置 AK/SK	操作会在 HTTP 签名步骤失败；请设置 HUAWEI_CLOUD_AK/HUAWEI_CLOUD_SK
数组大小限制	datasets、input_models、output_models——每项最多 1 个
parameters 格式	JSON 字符串；每项包含 key+desc+value+constraint；传入所有超参数
env 格式	JSON 字符串；没有自定义环境变量时传入 "[]"
cluster_id	带 pool- 前缀的池 ID（例如 pool-6872b4ac-...）；池类型为 SHARED 或 DEDICATED。SHARED 池需要完整的 pool_id（以 pool- 开头）；DEDICATED 池直接使用 cluster_id。使用 DEDICATED 池需要资产读取权限
任务状态	status 有 10 个值：CREATING/RUNNING/FAILED/WAITING/DRAFT/FINISHED/STOPPING/DELETING/ABNORMAL；detail_status 有 15 个值（增加 CREATE_FAILED/RUN_FAILED/STOP_FAILED/NOT_EXIST/UNKNONW）；终止状态：FINISHED/FAILED/STOPPED/ABNORMAL
删除任务	不可撤销。CLI delete-tasks --task-id <id> 会根据 task_id 自动解析常规训练任务的 execution_id；无需手动查询
算法信息	从 ext_metadata 动态获取；不要对 asset_ids 进行硬编码
对象存储	必须使用 obs:// 协议；禁止使用 s3://
跨技能调用	不会调用其他技能；数据处理 → cloudrobo-dataset，部署 → cloudrobo-infer
--sim-rl 标志	用于 14 个命令；pretrain/finetune/resume-task/list-checkpoints/register-checkpoint 不支持
get-logs 文件选择	使用 --file-name（而非 --file-path）；--log-name-pre 按前缀匹配
克隆任务名称冲突	SDK 会自动生成 {original-name}-copy-{4hex} 名称；传入 --config '{"name":"custom-name"}' 可覆盖

验证与最佳实践

• 测试：bash scripts/test-cli-commands.sh（CLI/SDK/API）；完整覆盖范围请参阅 templates/test-vars.json
• 轮询：间隔 30-60s；报告状态和阶段变化。状态为 FINISHED 时 → 建议导出/部署；状态为 FAILED 时 → 提供日志/事件
• 草稿工作流：save-draft → 验证为 DRAFT → restart-task → 验证仍为 DRAFT → 轮询直到终态
• 监控：get-stages（4 阶段流程）、get-resource-usage（CPU/GPU/NPU）、get-events（使用 --level Error 筛选）
• SimRL：使用 --sim-rl 重复监控（不使用 get-stages——SimRL 没有阶段端点）；验证 resume-task 会拒绝 --sim-rl
• 试运行：此 CLI 不支持；提交 create-task 前，使用 save-draft + show-task 验证参数
• 草稿：使用 SDK 的 restart_train_task(task_id, req) 以编辑后的配置提交（CLI 不接受配置正文）
• 统计：使用 stats --workspace-id <id> 查看状态分布概览