huawei-cloud-modelarts-training-diagnosis

ModelArts 训练作业故障诊断

概述

此技能可自动诊断 Huawei Cloud ModelArts 训练作业故障。它通过 hcloud CLI 调用 ModelArts 日志和事件 API，收集运行时信息，分析训练作业失败、超时或卡住等问题，并输出诊断结论、修复建议和置信度。

架构

User Input
    ↓
Phase 1: Task Discovery (ListTrainingJobs)
    ↓
Phase 2: Status Assessment (ShowTrainingJobDetails)
    ↓
[Early Exit if traceback found in status.task_statuses[].message]
    ↓ (if no traceback)
Phase 3: Information Collection
    ├─ Main Path: ListTrainingJobEvents, ListTrainingJobStages
    └─ Extended Path: ShowTrainingJobLogsPreview, ShowObsUrlOfTrainingJobLogs
    ↓
Phase 4: Analysis (confidence-based inference)
    ↓
Phase 5: Output (diagnosis report + fix suggestions)

适用场景

• 训练作业失败（status.phase = "Failed"）
• 训练作业超时（status.phase = "Timeout"）
• 训练作业异常（status.phase = "Abnormal"）
• 训练作业卡住（长时间运行但没有进展）
• 资源不足导致训练失败

典型用例

• “我的训练作业失败了，帮我诊断一下”
• “训练作业卡住了，几小时没有进展”
• “训练作业超时了，出了什么问题？”
• “扫描我账号中所有失败的训练作业”
• “训练作业错误码 1.015 是什么意思？”

前提条件

安装 hcloud CLI

• 版本：7.2.2 或更高版本
• 验证：hcloud version 应返回不低于 7.2.2 的版本
• 安装指南：参见 references/cli-installation-guide.md

身份验证配置

• 在 ~/.hcloud/config.json 中配置 AK/SK
• 默认区域：cn-north-4
• 在配置文件中设置 project_id
• skipSecureVerify=true（适用于 WSL 环境）

验证命令：

hcloud configure list

IAM 权限

此技能需要 ModelArts 训练 API 的只读权限。

所需权限：参见 references/iam-policies.md

权限不足时的处理：

1. 如果任何 API 返回 403/401，请读取 references/iam-policies.md
2. 向用户展示所需权限列表和策略 JSON
3. 指引用户在 IAM 控制台中创建自定义策略
4. 暂停执行，直到用户确认已授予权限

KooCLI 命令格式规范

所有命令均遵循标准 hcloud 格式：

hcloud ModelArts <Operation> --param1=value1 --param2=value2 --cli-region=<region>

主要约定：

• 服务名称：ModelArts（PascalCase）
• 操作名称：PascalCase（例如 ShowTrainingJobDetails）
• 区域参数：--cli-region=<value>（默认值：cn-north-4）
• 输出格式：--cli-output=json（供 Agent 处理）
• JMESPath 筛选：--cli-query="<expression>"（用于减少输出）

示例：

hcloud ModelArts ShowTrainingJobDetails \
  --cli-region=cn-north-4 \
  --cli-output=json \
  --training_job_id="<TRAINING_JOB_ID>"

工作流

此技能采用 5 阶段诊断工作流：

阶段 1：任务发现

• 如果用户提供完整的作业 ID → 跳至阶段 2
• 如果用户提供名称 → 使用 ListTrainingJobs 查找 ID + status.phase
• 如果用户未提供信息 → 扫描所有异常作业（status.phase = "Failed"/"Timeout"/"Abnormal"）

阶段 2：状态评估

• 调用 ShowTrainingJobDetails 获取作业状态
• 检查 status.phase："Failed"/"Timeout"/"Abnormal" 表示真实故障，"Running"/"Success" 表示误报，"Initializing" 表示待观察
• 提取 status.task_statuses[].task_id，供后续日志 API 使用
• 提前退出：如果 status.task_statuses[].message 包含完整的 Python 回溯信息，则无需调用阶段 3 的 API，即可高置信度完成诊断

阶段 3：信息收集（适用提前退出条件时跳过）

主要路径（始终执行）：

1. ShowTrainingJobDetails → status.phase、status.task_statuses[].message、status.task_statuses[].task_id、status.failureAnalysisResult
2. ListTrainingJobEvents(level=Error) → 错误事件列表
3. ListTrainingJobStages → 检查卡住的阶段

扩展路径（按条件执行）： 4. ShowTrainingJobLogsPreview → 预览日志（查找回溯信息或错误行） 5. ShowObsUrlOfTrainingJobLogs → OBS 完整日志下载链接（有效期 5 分钟）

详细流程：参见 references/diagnosis-flow.md

核心命令

任务发现命令

ListTrainingJobs — 扫描所有异常训练作业

hcloud ModelArts ListTrainingJobs \
  --cli-region=cn-north-4 \
  --cli-output=json \
  --cli-query="items[?status.phase=='Failed' || status.phase=='Timeout' || status.phase=='Abnormal'].{job_id: metadata.id, name: metadata.name, phase: status.phase}"

状态检查命令

ShowTrainingJobDetails — 获取任务状态和错误信息

hcloud ModelArts ShowTrainingJobDetails \
  --cli-region=cn-north-4 \
  --cli-output=json \
  --training_job_id="<TRAINING_JOB_ID>"

关键响应字段：

• metadata.id、metadata.name — 任务标识符
• status.phase — 任务状态（“Failed”“Running”“Success”等）
• status.task_statuses[].message — 完整的 Python 回溯或错误消息（主要证据）
• status.task_statuses[].exit_code — 整数退出代码
• status.task_statuses[].task_id — 用于日志 API 的任务 ID
• status.failureAnalysisResult.analysis_results[] — 平台的自动诊断结果

信息收集命令

ListTrainingJobEvents — 获取错误事件

hcloud ModelArts ListTrainingJobEvents \
  --cli-region=cn-north-4 \
  --cli-output=json \
  --level=Error \
  --limit=100 \
  --training_job_id="<TRAINING_JOB_ID>"

ListTrainingJobStages — 检查阶段检查点

hcloud ModelArts ListTrainingJobStages \
  --cli-region=cn-north-4 \
  --cli-output=json \
  --training_job_id="<TRAINING_JOB_ID>"

ShowTrainingJobLogsPreview — 预览日志（查找回溯信息）

hcloud ModelArts ShowTrainingJobLogsPreview \
  --cli-region=cn-north-4 \
  --cli-output=json \
  --training_job_id="<TRAINING_JOB_ID>" \
  --task_id="<TASK_ID>"

ShowObsUrlOfTrainingJobLogs — 获取 OBS 完整日志下载链接（有效期 5 分钟）

hcloud ModelArts ShowObsUrlOfTrainingJobLogs \
  --cli-region=cn-north-4 \
  --cli-output=json \
  --training_job_id="<TRAINING_JOB_ID>" \
  --task_id="<TASK_ID>"

完整命令模板：参见 references/hcloud-command-templates.md

参数确认

训练诊断参数

参数	必填	类型	描述	默认值
training_job_id	是	字符串	训练任务 ID（例如，从 ListTrainingJobs 获取）	无
task_id	有条件必填	字符串	训练任务中的任务 ID（从 ShowTrainingJobDetails.status.task_statuses[].task_id 获取）	无
--cli-region	否	字符串	华为云区域	cn-north-4
--cli-output	否	字符串	输出格式（json/table/tsv）	json
--cli-query	否	字符串	用于筛选输出的 JMESPath 表达式	无

注意：

• 日志 API 需要 task_id，该 ID 可从 ShowTrainingJobDetails.status.task_statuses[].task_id 获取
• 可切换区域（例如，cn-north-9、cn-east-3），但必须为该区域配置 project_id
• 日志可能包含敏感信息；仅提取关键错误或回溯信息行，不要显示完整日志

输出格式

此技能以 Markdown 格式输出诊断报告。

输出模板

## 诊断结论

| 项目 | 值 |
|------|-----|
| 任务 | `<metadata.name>` (`<metadata.id>`) |
| 当前状态 | `<status.phase>` |
| 故障级别 | Fault / Abnormal / 疑似异常 / 正常 |

## 根因

<一句话描述什么导致了作业失败>（置信度：HIGH/MEDIUM/LOW）

## 修复建议

### 方案 1

1. <step 1>
2. <step 2>

> 注意：以上操作涉及 [只读查询 / 需要用户确认后手动执行的变更]

## 后续步骤

[信息不足时] 当前信息不足以确定根因，建议补充以下信息：
- 调用 `<API>` 获取 `<field>`
- 或手动检查 `<environment/configuration>`

严格限制：必须严格按照上述模板生成报告。分析推理应保留在内部，不要写入报告。

置信度级别

• HIGH：status.task_statuses[].message 包含可识别根本原因的完整 Python 回溯，或 status.failureAnalysisResult.analysis_results[].description 提供明确的错误描述，或事件中包含明确错误
• MEDIUM：多个间接线索指向同一根本原因，或 status.task_statuses[].exit_code 非零，但 message 为空或含糊
• LOW：信息不足；必须输出“信息不足”，并列出所需的其他信息

置信度规则详情：参见 references/confidence-rules.md

验证方法

此技能采用三级验证方法：

安装验证

hcloud version

成功标准：返回的版本不低于 7.2.2

配置验证

hcloud configure list

成功标准：显示有效的 AK/SK 配置，且 region=cn-north-4

功能验证

hcloud ModelArts ListTrainingJobs --cli-region=cn-north-4

成功标准：返回 HTTP 200 和训练任务列表

验证步骤详情：参见 references/verification-method.md

最佳实践

尽早退出原则

• 如果 ShowTrainingJobDetails 在 status.task_statuses[].message 中返回完整的 Python 回溯，则跳过第 3 阶段 API（ListTrainingJobEvents、ListTrainingJobStages、ShowTrainingJobLogsPreview、ShowObsUrlOfTrainingJobLogs）
• 如果根本原因已明确，这样可以减少 API 调用并加快诊断

渐进式诊断

• 从最少信息开始（仅提供任务 ID）
• 首先执行第 2 阶段（ShowTrainingJobDetails）
• 仅当第 2 阶段结果不足（message 中没有回溯信息）时，才执行第 3 阶段 API
• 避免一次运行所有 API；请遵循五阶段工作流

基于证据的分析

• 每项推断都必须指向 API 响应中的具体字段
• 一项证据支持一项推断；通过多项证据交叉验证可提高置信度
• 当返回信息含糊或未包含明确错误时，输出“根据当前信息无法确定根本原因”
• 严格禁止：在没有证据的情况下猜测根本原因

日志处理

• 日志可能包含敏感信息（IP 地址、令牌、凭据）
• 诊断时仅提取关键错误／回溯行
• 不要在输出中显示完整日志
• 如需获取完整日志，请使用 ShowObsUrlOfTrainingJobLogs 并提示用户下载（链接有效期为 5 分钟）

切换区域

• 默认区域为 cn-north-4
• 切换区域时，请确保已为该区域配置 project_id
• 如果区域配置文件中缺少 project_id，请使用 hcloud configure init 或显式传入 --project_id

参考文档

文档	文件	说明
API 目录	references/api-catalog.md	6 个训练诊断 API、状态阶段、响应结构、事件级别
诊断流程	references/diagnosis-flow.md	详细介绍包含提前退出原则的 5 阶段诊断工作流
命令模板	references/hcloud-command-templates.md	各 API 的完整 hcloud 命令模板
置信度规则	references/confidence-rules.md	置信度级别定义、证据映射、输出约定
CLI 安装指南	references/cli-installation-guide.md	hcloud CLI 安装、配置和验证
IAM 策略	references/iam-policies.md	所需的 IAM 权限和策略 JSON
验证方法	references/verification-method.md	3 级验证步骤
验收标准	references/acceptance-criteria.md	技能测试的通过／失败标准

注意事项

安全约束

1. 始终只读：仅调用 GET API（ListTrainingJobs 除外，它使用 POST 执行只读列表查询）；绝不调用 Create/Update/Delete/Stop
2. 不得泄露凭据：绝不打印 AK/SK
3. 必须获得用户确认：如果修复建议涉及更改（重启、修改规格），必须明确提示“需要用户确认后才能手动执行”；绝不自动执行
4. 敏感信息脱敏：日志可能包含敏感信息；输出前应对敏感字段进行脱敏（例如，对 IP 地址脱敏，不打印完整令牌）

范围限制

• 仅诊断训练作业：不诊断 Notebook、推理服务或其他场景
• 不修改代码：不修改任何业务代码或资源
• 不捏造信息：绝不在没有证据的情况下捏造根本原因；必须依据 API 返回字段
• 不访问私有数据：不直接读取用户代码仓库中的私有数据

已知限制

• 部分 API 可能存在速率限制；如果触发限流，请等待后重试
• 日志预览可能会被截断；完整日志请使用 OBS 链接
• 已从技能中移除指标 API（可显示状态，但无法诊断根本原因）
• 对于某些失败，status.task_statuses[].message 可能为空；在这种情况下，需要使用第 3 阶段 API