alibabacloud-pai-dlc-job-diagnostics

PAI-DLC 作业诊断与健康检查

针对 PAI-DLC 分布式训练作业进行只读诊断分析，涵盖以下三种场景：

• 排队卡住的根因分析 — 配额检查、节点调度诊断、超节点可用性
• 失败作业定位 — 失败分类、日志／事件证据链、根因识别
• 集群健康检查 — 训练吞吐量、卡死检测、SanityCheck、重启稳定性

架构：PAI-DLC 作业（只读查询）+ PAI Studio 资源诊断 API（排队场景）。

0. 依赖项

此技能仅执行只读诊断。所有写操作（创建／更新／停止作业、资源发现等）均由配套技能 alibabacloud-pai-dlc-job 负责。两个技能的职责互为补充，并共享通用字段约定。

前置技能	职责	何时切换到该技能
alibabacloud-pai-dlc-job	写操作（创建／更新／停止）+ AIWorkSpace 资源发现	创建／修改／停止作业，或发现 Image / Dataset / CodeSource
此技能	只读诊断（日志／事件／sanity-check／排队根因）	作业已存在 — 排查问题或检查健康状态

发现并安装前置技能：

# Discover available skills
npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-find-skills
# Install the alibabacloud-pai-dlc-job skill itself
npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-pai-dlc-job

**跨技能字段约定：**此技能使用的 --job-id / --pod-id 值由 alibabacloud-pai-dlc-job 通过 list-jobs / get-job --cli-query "Pods[0].PodId" 原样提供 — 无需转换。--region / --workspace-id 在两个技能中遵循相同的解析规则。

安装要求

预检查：需要 Aliyun CLI >= 3.3.1 运行 aliyun version 验证版本是否 >= 3.3.1。如果尚未安装或版本过低， 请参阅 references/cli-installation-guide.md。 然后[必须]运行 aliyun configure set --auto-plugin-install true。

**关于 --user-agent 的说明：**此技能中每条调用 API 的 aliyun 命令都必须 包含 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job-diagnostics。客户端侧辅助命令 （aliyun version、aliyun configure ...、aliyun plugin ...、 aliyun <product> --help）不会调用远程 API，因此无需添加此标志。

aliyun version
aliyun configure set --auto-plugin-install true
aliyun plugin update
aliyun pai-dlc --help
aliyun paistudio --help >/dev/null 2>&1 || aliyun plugin install --names aliyun-cli-paistudio

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job-diagnostics"
# After session: aliyun configure ai-mode disable

身份验证

预检查：需要 Alibaba Cloud 凭证

安全规则：

• 绝不读取、回显或打印 AK/SK 值
• 绝不要求用户直接输入 AK/SK
• 仅使用 aliyun configure list 检查凭证状态

aliyun configure list

检查输出中是否存在有效配置文件（AK、STS 或 OAuth 身份）。

如果不存在有效配置文件，请在此处停止。

1. 从 Alibaba Cloud 控制台 获取凭证
2. 在此会话之外配置凭证
3. 返回并在 aliyun configure list 显示有效配置文件后重新运行

RAM 权限

**[必须] 权限失败处理：**任何命令因权限错误而失败时：

1. 阅读 references/ram-policies.md，了解完整权限列表
2. 使用 ram-permission-diagnose 技能指导用户
3. 暂停操作，等待用户确认已授予权限

产品	权限	用途
pai-dlc	pai:GetJob、pai:GetPodLogs、pai:GetJobEvents、pai:GetPodEvents、pai:ListJobSanityCheckResults	作业信息收集
paistudio	paistudio:GetQuotaWorkloadDiagnosis	排队资源诊断

参数确认

重要：参数确认 — 执行任何命令之前，必须先与用户确认所有可由用户自定义的参数（RegionId、JobId 等）。

参数	必填	说明
region	是	作业运行所在的地域
job_id	是	DLC 作业 ID（例如：dlcXXX）

---

入口路由

收到诊断请求时，先调用 get-job 获取作业状态， 然后根据状态进行路由：

作业状态	路由到的场景
Queuing / Creating	→ 排队卡住根因分析
Failed	→ 失败作业定位
Running	→ 健康检查
Stopped	告知用户“作业已被主动停止”，不进行诊断
Succeeded	→ 历史回顾（遵循场景 3 的执行步骤）

边缘情况 — 作业曾在排队，但现在已停止/成功：如果用户描述作业“卡在队列中”，但 get-job 显示状态为 Stopped 或 Succeeded，仍然路由到场景 1（排队分析），但需要预期资源诊断 API 会返回 HTTP 400。遵循场景 1 中的“API 调用失败时的回退”流程。

用户也可以直接请求特定场景（例如，即使状态不是 Running，也要求“进行健康检查”）。

---

诊断工具箱

PAI-DLC 只读命令

aliyun pai-dlc get-job --region <r> --job-id <id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job-diagnostics
aliyun pai-dlc get-job-events --region <r> --job-id <id> --max-events-num 50 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job-diagnostics
aliyun pai-dlc get-pod-events --region <r> --job-id <id> --pod-id <pod> --max-events-num 20 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job-diagnostics
aliyun pai-dlc get-pod-logs --region <r> --job-id <id> --pod-id <pod> --max-lines 100 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job-diagnostics
aliyun pai-dlc list-job-sanity-check-results --region <r> --job-id <id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job-diagnostics
aliyun pai-dlc get-job-sanity-check-result --region <r> --job-id <id> --sanity-check-number 1 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job-diagnostics

PAI Studio 资源诊断（仅限排队场景）

aliyun paistudio GET /api/v1/quotas/{quota_id}/workloads/{job_id}/diagnosis \
  --region <r> --header "Content-Type=application/json" --force \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job-diagnostics

严格约束：quota_id 必须取自 get-job 的 ResourceId 字段。 如果 ResourceId 为空（按量付费的公共资源），则此 API 不可用。

完整 API 结构：参见 references/resource-diagnosis-api.md。

---

场景 1：排队卡住根因分析

触发条件：作业状态为 Queuing / Creating，且用户报告作业无法调度。

工具：get-job → paistudio resource diagnosis →（可选）get-job-events。

严格约束：

• ResourceId 为空 → 资源诊断不可用；从事件中挖掘线索
• ResourceId 非空 → 资源诊断 API 是主要诊断工具

关键：pai-dlc 与 paistudio 是两个不同的产品

产品	范围	命令
pai-dlc	作业/Pod 生命周期（GetJob、GetJobEvents、ListJobs、GetPodLogs）	aliyun pai-dlc get-job ...
paistudio	平台级服务，包括资源诊断	aliyun paistudio GET /api/v1/quotas/...

资源诊断 API 属于 paistudio，而非 pai-dlc。 不要调用 pai-dlc GetResourceQuota、pai-dlc ListResourceQuotas， 或任何 pai-dlc GET /api/v1/resourcequotas/... ——这些都是错误的 API， 调用后会失败。正确命令为：

aliyun paistudio GET /api/v1/quotas/{quota_id}/workloads/{job_id}/diagnosis ...

模式知识：资源诊断会返回 4 项检查 （self_quota / ancestor_quota / user_limit / queue_strategy），以及节点调度和超节点分析。常见模式： references/diagnostic-patterns.md §1。

Agent 自主判断：决定是否计算配额缺口、是否拉取事件进行佐证，以及报告的详略程度。

API 调用失败时的回退

当作业不再处于活动排队状态时（例如，已被用户设为 Stopped），PAI Studio 资源诊断 API 可能会返回 HTTP 400/404 并调用失败。在这种情况下：

1. 明确声明 API 调用失败： "Resource diagnosis API unavailable: HTTP {code} — {error message}"
2. 仅使用以下数据源进行定性分析：
   • get-job → ResourceRequest（每个 Pod 的 GPU/CPU/内存需求）
   • get-job → PodCount × 每个 Pod 的资源需求 = 总需求
   • get-job → EcsSpec（实例类型及其每个节点的容量）
   • get-job-events → 调度事件时间线和排队时长
3. 禁止使用的措辞：绝不能使用“可能”“也许”“或许”“可能不够”等模糊措辞。只陈述已确认的事实：
   • GPU 总需求 = PodCount × RequestGPU = {computed value}
   • 实例类型 = {EcsSpec}
   • 排队时长 = {computed hours/minutes}
   • 作业最终状态 = {Stopped/Succeeded/etc.}
4. API 不可用时的强制输出结构：

## Resource Diagnosis (API Unavailable — Configuration-Based Analysis)

- Diagnosis API: unavailable (HTTP {code}: {message})
- Resource demand: {PodCount} pods × {GPU/pod} GPU = {total} GPU cards
- Instance type: {EcsSpec}
- Queuing duration: {hours}h {minutes}m
- Quota ID: {ResourceId}
- Job final status: {status} ({ReasonCode})
- Conclusion: The job requested {total} GPU cards which could not be
  fulfilled within the queuing window before the job was {stopped/completed}.

---

场景 2：失败作业定位

触发条件：作业状态 = Failed。

工具：get-job →（按需）get-job-events / get-pod-events / get-pod-logs。

硬性约束：

• Stopped 不属于失败——不要诊断
• [输出限制——严禁提供建议] 如果失败属于以下任一类别，诊断报告必须严格省略任何“建议”/“修复建议”/“后续步骤”/“解决方案”部分，只输出根本原因和客观事实：
  • ResourceAllocateFailed（资源不足）
  • 作业被抢占 / 驱逐（ReasonMessage 包含 preempted 或 evicted）
  • Spot 实例回收
  • 报告必须以诊断结论结束。 输出中的任何句子都不得指示用户更改配置、申请更多配额、切换实例类型、添加重试逻辑或修改任何作业参数。
  • 反面示例（全部禁止）：
    • “建议使用按量付费实例”
    • “可以考虑申请更多配额”
    • “尝试切换到其他可用区”
    • “通过设置 EnablePreemptibleJob: false 禁用可抢占作业”
    • “实施检查点和重试逻辑”
    • “解决方案：使用保证配额，而不是超售配额”
  • 唯一允许面向用户提供的建议：“如需调整配额策略，请联系平台管理员。”

抢占 / 驱逐 / 资源不足类失败的必需输出模板：

## Diagnosis Conclusion

- Failure reason: {classification} ({ReasonCode}: {ReasonMessage})
- Affected pods: {pod list with SubStatus}
- Timeline: {key timestamps from events}
- Evidence: {quoted ReasonMessage or event details}

For quota policy or resource allocation adjustments, please contact your
platform administrator.

模式知识：失败分类优先级 （网络 > 镜像 > 运行时 > 资源 > 配置 > 系统）、退出代码含义、 关键词匹配规则。请参阅 references/diagnostic-patterns.md §2。

Agent 自主判断空间：当 ReasonCode 明确时，可能无需日志；当 日志已说明问题时，可能无需事件。根据现有信息是否充分，自行决定调查深度。

---

场景 3：健康检查

触发条件：作业状态 = Running，且用户请求检查 / 健康检查。

工具：get-job + get-job-events + get-pod-logs

• list-job-sanity-check-results。

执行步骤：

1. get-job → 获取状态、WorkspaceId、Pod 列表，以及是否设置了 EnableSanityCheck
2. get-job-events → 分析事件链（调度、重启等）
3. get-pod-logs → 优先查看主 Pod（rank=0）；如果存在结构化训练指标，则提取
4. list-job-sanity-check-results → 仅当作业设置中 EnableSanityCheck=true 时执行
5. 生成控制台链接（必需 — 必须始终输出两个链接）：
   • 作业概览：https://pai.console.aliyun.com/?regionId={region}&workspaceId={workspace_id}#/dlc/jobs/{job_id}/overview
   • 监控仪表板：https://pai.console.aliyun.com/?regionId={region}&workspaceId={workspace_id}#/dlc/jobs/{job_id}/monitor
   • 必需的结尾提示（在每份检查报告末尾原样附上）：

     > GPU/内存实时资源利用率指标需要通过上述监控仪表板查看。
     > 此技能的 CLI 命令不支持直接获取运行时利用率数据。
     

   无论作业状态如何（Running、Succeeded 或其他状态），此步骤均为必需。即使作业已完成，用户仍需要监控链接来查看历史资源利用率。

维度矩阵（必需与可选）：

维度	必需/可选	说明
训练吞吐量	可选	从主 Pod 日志中提取
卡死检测	仅 Running 状态	Succeeded 作业跳过
硬件健康状况	可选	需要 EnableSanityCheck=true
重启稳定性	必需	直接从 get-job 读取 RestartCount

关于资源利用率的说明：无法通过此技能的 CLI 命令获取 GPU/内存指标。每份检查报告都必须包含监控仪表板链接（步骤 5）及其结尾提示 — 不得省略。

各维度的判读规则：参见 references/healthcheck-dimensions.md。

Agent 自主判断：kilo-card 作业侧重检查卡死情况和 SanityCheck；小型作业则查看日志中的训练吞吐量。根据作业规模和用户意图决定检查深度及报告详略。

---

最佳实践

1. 先执行 get-job，再分流 — 切勿假定状态；先查询，再分流
2. 限制响应大小 — 使用 --max-lines 100 / --max-events-num 50，避免上下文过度膨胀
3. 找到问题 Pod — 在 get-job 返回的 Pod 中，重点关注 Status=Failed/Unknown 或包含 ReasonMessage 的 Pod
4. 读取日志末尾 — 错误通常出现在最后几十行；无需获取完整日志
5. 退出代码只是线索，并非结论 — exit 137 可能由 OOM 或外部终止导致；需结合上下文判断
6. 不要过度诊断 — 如果 ReasonCode 已说明原因，则跳过完整日志输出
7. 控制台链接 — 生成概览和监控链接，让用户可以进入控制台查看详情和资源利用率指标
8. 只读 — 此技能绝不得执行 stop / update / create
9. 报告摘要 — 在报告末尾提供按维度划分的评级表：

维度	评级	主要发现
训练吞吐量	✅/⚠️/❌/N/A	...
卡死检测	✅/⚠️/❌/N/A	...
硬件健康状况	✅/⚠️/❌/N/A	...
重启稳定性	✅/⚠️/❌	...

参考链接

文档	内容
references/resource-diagnosis-api.md	PAI Studio 资源诊断 API 完整参考
references/diagnostic-patterns.md	故障模式知识库（排队 / 失败 / 挂起 / 重启）
references/healthcheck-dimensions.md	健康检查维度和解读规则
references/ram-policies.md	RAM 权限策略
references/related-commands.md	CLI 命令快速参考
references/acceptance-criteria.md	验收标准
references/verification-method.md	验证方法
references/cli-installation-guide.md	CLI 安装指南