> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siflow.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 排查训练任务问题

> 在人工智能平台中排查训练任务排队、启动失败、运行失败、卡住、被抢占或资源利用异常等问题。

训练任务可能因为资源不足、镜像问题、启动命令错误、数据路径错误、节点异常、通信挂起或资源抢占而失败。排查时先从任务详情页的状态、事件、日志和监控入手，确认问题发生在调度、环境准备、程序运行还是恢复阶段，再选择 Debug 重提、自动容错或 Bisect Diagnose。

## 排查任务问题

1. 进入 **训练任务 > 任务管理**，找到目标任务。
2. 单击任务名称，进入详情页。
3. 查看生命周期时间线，确认任务卡在提交、排队、环境准备、运行还是结束阶段。
4. 查看 **状态详情**，确认任务整体状态、Pod 状态、节点、退出码和状态说明。
5. 查看 **事件**，确认是否存在资源不足、镜像拉取失败、Volume 挂载失败、调度受阻或容错相关事件。
6. 查看 **日志**，定位训练脚本报错、依赖缺失、数据路径错误或运行时异常。
7. 查看 **监控**，判断 GPU、显存、CPU、内存和网络是否存在瓶颈或异常波动。

## 根据现象处理

| 问题现象                                               | 可能原因                                          | 处理建议                                                                                                                                                      |
| -------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 长时间排队                                              | 资源池配额不足、优先级较低、资源保障要求不匹配或节点调度策略过窄。             | 查看事件和资源池配额，调整资源规格、资源池、优先级、资源保障或节点调度策略。                                                                                                                    |
| 提示 `quota check failed due to node blacklist: XXX` | 任务命中节点屏蔽策略，导致可调度节点不足。                         | 检查当前用户或租户范围内是否存在命中的节点调度策略，按需调整或移除屏蔽策略。                                                                                                                    |
| 启动失败                                               | 镜像不可用、命令错误、挂载路径覆盖系统目录、依赖缺失或 Volume / 数据集挂载失败。 | 查看事件和日志，检查镜像、启动命令、挂载路径、环境变量和输入数据路径。                                                                                                                       |
| 运行失败                                               | 训练代码异常、数据路径错误、内存或显存不足。                        | 查看用户日志和监控，调整代码、数据路径、batch size 或实例规格。                                                                                                                     |
| 任务被抢占                                              | 使用 Spot、闲时资源或未开启资源保障。                         | 使用 checkpoint 恢复，或改用更稳定的资源类型和资源保障配置。如果状态信息包含 `was preempted by another task`，通常表示任务被其他任务抢占。                                                               |
| 多机训练卡住                                             | 通信挂起、节点异常、网络异常或慢节点。                           | 查看监控和日志。需要平台自动恢复时，可使用[自动容错](./recover-training-tasks-with-auto-fault-tolerance)；需要定位故障节点时，可使用[Bisect Diagnose](./diagnose-training-failures-with-bisect)。 |
| 已运行但训练没有进展                                         | 数据加载、分布式初始化、通信等待或训练程序停滞。                      | 对比各 Pod 状态和日志，查看 GPU、CPU、网络指标，确认训练步是否推进。                                                                                                                  |
| 任务中断后需要继续训练                                        | 任务被抢占、节点故障、主动停止或达到容错限制。                       | 找到最新尝试，确认 checkpoint 是否加载成功，再决定重提、克隆后修改配置，或重新创建任务。                                                                                                        |

## 使用 Debug 重提

Debug 重提适合保留原任务资源需求，但不立即执行原训练命令，而是进入可排查的现场环境。

在任务列表中找到目标任务，单击 **重提**，并在重提弹窗中选择 Debug 模式。提交前请确认需要保留的 checkpoint、日志或模型输出已经写入持久化 Volume。

| 适用情况            | 使用建议                                                              |
| --------------- | ----------------------------------------------------------------- |
| 任务失败原因不明确       | 使用 Debug 重提进入容器，检查环境、路径、依赖和启动命令。                                  |
| 希望尽量复用原任务调度位置   | Debug 重提通常保留原资源需求，但会以排查命令启动新任务，不直接执行原训练命令。                        |
| RayJob 需要排查集群现场 | RayJob 开启 Debug 后，Ray 集群可保留一段时间，默认通常为 600 秒，便于进入 Head Pod 查看集群状态。 |

对于 RayJob，如果 Submitter Pod 已完成但 Head / Worker 仍保留，任务可能处于 `DebugHolding` 状态，可进入 Head Pod 查看 Ray 集群状态。

## 相关文档

* [查看和管理训练任务](./view-and-manage-training-tasks)
* [使用自动容错恢复训练任务](./recover-training-tasks-with-auto-fault-tolerance)
* [使用 Bisect Diagnose 诊断训练故障节点](./diagnose-training-failures-with-bisect)