使用 atlctl 进行原地调试

AIStudio 任务功能提供 atlctl 命令行调试工具，您可以从 Web Terminal 登录任意的任务 Worker，执行停止任务、统一下发测试命令等调试工作。

了解调试状态

atlctl 命令行调试工具可手动控制任务的生命周期。运行中的任务在生命周期中的部分状态下，可被手动设置为调试（Debug）状态。在调试状态下，允许用户对所有任务 Worker 统一发起检测，或下发测试命令等。调试结束后，可恢复任务执行。

进入调试状态

必须从网页端登录任务 Worker。打开 Web Terminal 后，可直接使用 atlctl 工具。

Worker 登录入口在任务详情页 Worker 信息中，点击登录后可打开 Web Terminal。

alt text

注意

仅在任务运行中时可登录 Worker。

使用流程

以下提供三个使用流程范例：

执行 atlctl 工具内置检测
执行用户自定义检测脚本
执行 GPU 和通信烧机测试

执行内置检测脚本

atlctl 工具内置了 GPU 与通信检测脚本，默认可对任务中的全部 Worker 进行检测 GPU 和通讯检测。支持通过添加参数检测具体项目和自定义的临时环境变量。

登录任务的任意一个 Worker，按下方步骤操作：

查看训练任务状态。如果输出 Job status 为 command，表示当前仍在执行任务中的用户代码。
shell
```
root@jo-daxbirgzm6e727pd-worker-0:~# atlctl status
Job status:  command
```

为了执行检测，需要先停止当前训练任务，将任务置于 Debug 状态。

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl stop
Stopping task in all workers...
Stop job task success.

建议检查当前任务是否有 python 进程残留，如有则清理。

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl run "ps -ef |grep python |grep -v grep |grep -v tini |awk '{print \$2}'|xargs kill -9"
Send command to all workers success.

每次执行 atlctl run 后，必须执行 atlctl stop，否则无法再次下发其他 atlctl 命令。

shell

atlctl stop

执行 atlctl 工具内置检测脚本。

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl check
All workers will be checked.
Check finished.
Check Quit.

检查结束，未发现问题，可终止检测。

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl stop
Stopping task in all workers...
Stop job task success.

如需恢复任务运行，请先查看训练任务是否处于 debugStop 状态。
shell
```
root@jo-daxbirgzm6e727pd-worker-0:~# atlctl status
Job status:  debugStop
```

如果任务状态已处于 debugStop 状态，可恢复训练任务：

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl status
Job status:  debugStop
root@jo-daxbirgzm6e727pd-worker-0:~# atlctl recover
Task recovering...
Task recover success.

执行自定义调试命令

自定义的流程与执行内置检测主流程类似，区别仅在于使用 atlctl run 下发自定义检测命令。

登录任务的任意一个 Worker，按下方步骤操作：

查看训练任务状态。
shell
```
root@jo-daxbirgzm6e727pd-worker-0:~# atlctl status
Job status:  command
```
输出 Job status 为 command 表示正在执行任务中的启动命令。

停止当前训练任务，将任务置于 Debug 状态。

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl stop
Stopping task in all workers...
Stop job task success.

建议检查当前任务是否有 python 进程残留，如有则清理。

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl run "ps -ef |grep python |grep -v grep |grep -v tini |awk '{print \$2}'|xargs kill -9"
Send command to all workers success.

每次执行 atlctl run 后，必须执行 atlctl stop，否则无法再次下发其他 atlctl 命令。

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl stop
Stopping task in all workers...
Stop job task success.

执行自定义测试命令。如有多个命令需要连续运行，建议封装为 Shell 脚本。

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl run "/mnt/public/debug/test-comms.sh"

调试结束，终止测试任务：

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl stop
Stopping task in all workers...
Stop job task success.

如需恢复任务运行，请先查看训练任务是否处于 debugStop 状态。
shell
```
root@jo-daxbirgzm6e727pd-worker-0:~# atlctl status
Job status:  debugStop
```

如果任务状态已处于 debugStop 状态，可恢复训练任务：

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl status
Job status:  debugStop
root@jo-daxbirgzm6e727pd-worker-0:~# atlctl recover
Task recovering...
Task recover success.

执行 GPU 和通信烧机测试

当需要对任务中的 Worker 进行性能压力测试时，可以使用 atlctl burn 命令。烧机测试可以帮助发现硬件问题、评估性能表现或验证系统稳定性。

登录任务的任意一个 Worker，按下方步骤操作：

查看训练任务状态。

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl status
Job status:  command

停止当前训练任务，将任务置于 Debug 状态。

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl stop
Stopping task in all workers...
Stop job task success.

执行 GPU 烧机测试。例如，运行 GPU Gemm 计算测试 5 分钟：
shell
```
root@jo-daxbirgzm6e727pd-worker-0:~# atlctl burn -t gemm -d 5m
```

或者执行通信烧机测试，测试 allreduce 性能：

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl burn -t global -d 3m -e NCCL_DEBUG=WARN

烧机测试完成后，停止测试任务：

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl stop
Stopping task in all workers...
Stop job task success.

确认任务状态并恢复训练任务：

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl status
Job status:  debugStop
root@jo-daxbirgzm6e727pd-worker-0:~# atlctl recover
Task recovering...
Task recover success.

手动强制删除掉卡节点

当节点出现掉卡（GPU异常、硬件故障等）导致任务卡住时，任务可能长时间无法自动退出。此时可通过以下步骤手动强制删除异常节点，加快任务重启或释放资源。

登录任务的任意一个 Worker，按下方步骤操作：

首先查看任务当前状态，确认任务是否处于异常或挂起状态：
shell
```
root@jo-daxbirgzm6e727pd-worker-0:~# atlctl status
Job status:  command
```
若任务仍在执行用户代码（如 Job status: command），建议先将任务切换到调试（Debug）状态，避免消耗用户任务的容错次数：
shell
```
root@jo-daxbirgzm6e727pd-worker-0:~# atlctl stop
Stopping task in all workers...
Stop job task success.
```

执行强制删除命令，直接清理所有的 pod 节点：

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl delete -p all
Send delete worker pod command to specified workers successfully.

删除后任务会自动重启，可通过任务详情页面监控重启进度。

此流程适用于节点掉卡、任务长时间卡住无法自动退出等场景，可有效加快故障恢复和资源释放。

命令说明

atlctl 工具提供以下命令。

burn

atlctl burn 提供通信和 GPU 烧机测试功能。该命令可以对任务中的 Worker 进行各种类型的性能压力测试，包括 GPU 计算、内存传输和网络通信测试。

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl burn

选项：

-t, --burnType <type>：指定执行的烧机测试类型。默认为 gemm。选项：
- gemm: 执行 GPU Gemm 烧机测试
- transfer: 执行 GPU 设备到主机和主机到设备的传输烧机测试
- local: 执行本地 allreduce 烧机测试
- global: 执行全局 allreduce 烧机测试
- batch: 执行批量 allreduce 烧机测试（必须设置 worker 列表）
-d, --duration <duration>：指定测试持续时间。默认为 20s。选项：
- 20s: 20 秒
- 5m: 5 分钟
- 10min: 10 分钟
-e, --envs <envs>：指定测试的环境变量。格式：
- key1=value1: 设置单个环境变量
- "key1=value1,value1.1;key2=value2;...": 通过分号分隔的键值对列表设置多个环境变量
-w, --workerList <list>：指定参与测试的 worker 范围。默认为 all。选项：
- all: 测试所有可用的 worker
- jo-xxx-worker1,jo-xxx-worker2,...: 通过逗号分隔的 worker 名称列表测试特定的 worker

使用示例

shell

# 使用默认设置运行所有烧机测试
atlctl burn

# 运行特定类型的 GPU 烧机测试
atlctl burn -t gemm -d 45s
atlctl burn -t transfer -d 3m

# 运行 allreduce 测试
atlctl burn -t global -d 3m -e NCCL_DEBUG=WARN
atlctl burn -t local -d 3m -e "NCCL_DEBUG=WARN;NCCL_ALGO=ring"
atlctl burn -t batch -d 3m -w jo-xxx-worker1,jo-xxx-worker2

输出示例：

shell

root@jo-da4js4klf6zknlwx-worker-0:~# atlctl burn -t global -d 45s
All workers will be checked.
Round 1: AllReduce Perf(GB/s): Size=512M, BusBW=1.34 GB/s, AlgBW=1.34 GB/s, MasterAddr=jo-da4js4klf6zknlwx-worker-0
Round 1: AllReduce Perf(GB/s): Size=1G, BusBW=1.35 GB/s, AlgBW=1.35 GB/s, MasterAddr=jo-da4js4klf6zknlwx-worker-0
Round 1: AllReduce Perf(GB/s): Size=2G, BusBW=1.35 GB/s, AlgBW=1.35 GB/s, MasterAddr=jo-da4js4klf6zknlwx-worker-0
Round 1: AllReduce Perf(GB/s): Size=4G, BusBW=1.34 GB/s, AlgBW=1.34 GB/s, MasterAddr=jo-da4js4klf6zknlwx-worker-0
Check finished.
root@jo-da4js4klf6zknlwx-worker-0:~# atlctl stop
Stopping task in all workers...
Stop job task success.
root@jo-da4js4klf6zknlwx-worker-0:~#

status

atlctl status 用于查看当前任务的生命周期的状态。仅当任务处于 debugStop 状态下才能执行其他调试命令。

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl status
Job status:  debugStop

stop

atlctl stop 停止执行训练任务代码，将任务置于 Debug 状态，可通过 atlctl status 确认执行结果。

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl stop
Stopping task in all workers...
Stop job task success.

重要

每次执行 atlctl run/atlctl check 命令后，也必须执行 atlctl stop 终止调试任务，否则无法再次下发检测命令。

check

atlctl run check 运行内置检测，作用于任务所有 Worker。内置检测脚本默认将对任务中的全部 Worker 进行检测 GPU 和通讯检测。

shell

root@jo-daxbirgzm6e727pd-worker-0:~# atlctl check
All workers will be checked.
Check finished.
Check Quit.

如需控制检测范围，可参考以下参数。

选项：

-t, --checkType string：自定义检测范围。默认全部检测（gpu/通讯）。选项：
- gpu: 执行与 GPU 相关的检查。
- allreduce: 执行与 allreduce 操作相关的检查。
- all: 执行所有可用的检查。（默认值："all"）
-e, --envs string：添加自定义环境变量。默认为空。输入格式如下：
- key1=value1：设置单个环境变量
- "key2=value2;key1=value1a,value1b;..."：键值对用 ; 分隔。一个键如果有多个值，用 , 分割。
shell
```
# 设置单个环境变量
atlctl check -t gpu -e tt123=123
# 设置多个环境变量
atlctl check -t gpu -e "tt123=123;tt456=456,457"
```
-h, --help：显示 check 命令的帮助信息。
-w, --workerList string：自定义参与检测的 worker 范围。默认为全部。选项：
- all: 检查所有可用的工作节点。
- jo-xxx-worker1,jo-xxx-worker2: 通过提供逗号分隔的工作节点名称列表来检查特定的工作节点。（默认值："all"）

run

atlctl run "<command>" 下发并运行自定义调试命令，该调试命令将在任务所有 Worker 上运行。由于 atlctl run 不支持连续执行，建议在 <command> 中拼接多个 Shell 命令。推荐使用 Shell 脚本封装复杂调试命令。例如：

shell

atlctl run "/mnt/public/debug/test-comms.sh"

recover

atlctl recover：在调试结束后，恢复执行训练任务的用户代码。

taint

atlctl taint 用于管理单个任务中的污点节点。可用于标记、清空和查看污点节点，便于调试和资源隔离。

注意

该功能需申请使用。申请通过后，可在任务详情页的规格信息表中查询节点名，作为 taint 命令输入值。
taint 结果仅影响当前任务。
任务因硬件问题重新调度后，执行 atlctl taint -a list 会看到平台标记的污点节点。
任务被「一键重跑」或「改配重跑」后，taint 结果不会保留和生效。

用法示例：

shell

# 查看当前所有污点节点，同时包含用户和平台添加的污点节点
atlctl taint -a list

# 标记 node1,node2 为污点节点
atlctl taint -a set -n node1,node2

# 清空所有污点节点
atlctl taint -a remove -n all

# 再次查看当前所有污点节点
atlctl taint -a list

选项说明：

-a <action>：操作类型，可选值有 list（查看）、set（标记）、remove（清空）。
-n <nodeList>：指定节点名称，多个节点用逗号分隔，仅在 set 操作时使用。

delete

atlctl delete 用于直接删除指定的 pod，可用于强制终止异常或不需要的 pod。删除成功后，任务重启。

注意

如果在执行用户命令阶段（Job status: command）直接执行 atlctl delete，导致任务重启，平台会自动计为一次为容错。如果容错次数（最大 10 次，可配置）耗尽，任务将直接失败。为避免消耗用户任务容错次数，建议先执行 atlctl debug 命令，将任务置为 debug 状态。

用法示例：

shell

# 直接删除某个 pod
atlctl delete -p pod

# 直接删除某几个 pod
atlctl delete -p pod1,pod2

# 删除所有 pod
atlctl delete -p all

选项说明：

-p <podList>：指定要删除的 pod 名称，多个 pod 用逗号分隔。

常见问题

atlctl 命令会消耗用户任务容错次数吗？

atlctl stop/run/recover 命令不会消耗用户任务容错次数。
先执行 atlctl debug 再执行 atlctl delete，也不会消耗用户任务容错次数。

为什么 `atlctl taint -a list` 输出了用户未标记的污点节点？

任务因硬件问题重新调度后，执行 atlctl taint -a list 会看到平台标记的污点节点。

为什么执行 `atlctl delete` 后，任务直接运行失败了？

如果在执行用户命令阶段（Job status: command）直接执行 atlctl delete，导致任务重启，平台会自动计为一次为容错。如果容错次数（最大 10 次，可配置）耗尽，任务将直接失败。

为避免消耗用户任务容错次数，建议先执行 atlctl debug 命令，将任务置为 debug 状态，然后再执行 atlctl delete 命令。

在调试过程中，如何在任务 Worker 容器中运行一个分布式脚本？

您可以在任务运行中，登入任意任务 Worker，使用 atlctl run "<command>" 下发并运行自定义调试脚本，该调试脚本将在任务所有 Worker 上运行。

为什么执行 `atlctl run` 后无法再次下发其他命令？

每次执行 atlctl run 或 atlctl check 等部分命令后，都必须执行 atlctl stop 来终止当前的调试任务。这是因为 atlctl 工具需要确保任务处于正确的调试状态才能接受新的命令。

如何查看烧机测试的详细输出结果？

执行 atlctl burn 命令时，测试结果会直接显示在终端输出中。对于通信测试，您可以通过设置环境变量 -e NCCL_DEBUG=WARN 来获取更详细的调试信息。

任务恢复后是否会从断点继续执行？

使用 atlctl recover 恢复的任务会重新开始执行用户代码，而不是从调试前的断点继续。因此建议在调试前确保训练代码具有合适的检查点保存机制。

可以在多个 Worker 上同时登录并执行 atlctl 命令吗？

不建议在多个 Worker 上同时执行 atlctl 命令，这可能导致冲突。建议只在一个 Worker 上执行 atlctl 命令，该命令会自动作用于所有相关的 Worker。

使用 atlctl 进行原地调试 ​

了解调试状态 ​

进入调试状态 ​

使用流程 ​

执行内置检测脚本 ​

执行自定义调试命令 ​

执行 GPU 和通信烧机测试 ​

手动强制删除掉卡节点 ​

命令说明 ​

burn ​

status ​

stop ​

check ​

run ​

recover ​

taint ​

delete ​

常见问题 ​

atlctl 命令会消耗用户任务容错次数吗？ ​

为什么 atlctl taint -a list 输出了用户未标记的污点节点？ ​

为什么执行 atlctl delete 后，任务直接运行失败了？ ​

在调试过程中，如何在任务 Worker 容器中运行一个分布式脚本？ ​

为什么执行 atlctl run 后无法再次下发其他命令？ ​

如何查看烧机测试的详细输出结果？ ​

任务恢复后是否会从断点继续执行？ ​

可以在多个 Worker 上同时登录并执行 atlctl 命令吗？ ​

使用 atlctl 进行原地调试

了解调试状态

进入调试状态

使用流程

执行内置检测脚本

执行自定义调试命令

执行 GPU 和通信烧机测试

手动强制删除掉卡节点

命令说明

burn

status

stop

check

run

recover

taint

delete

常见问题

atlctl 命令会消耗用户任务容错次数吗？

为什么 `atlctl taint -a list` 输出了用户未标记的污点节点？

为什么执行 `atlctl delete` 后，任务直接运行失败了？

在调试过程中，如何在任务 Worker 容器中运行一个分布式脚本？

为什么执行 `atlctl run` 后无法再次下发其他命令？

如何查看烧机测试的详细输出结果？

任务恢复后是否会从断点继续执行？

可以在多个 Worker 上同时登录并执行 atlctl 命令吗？