使用 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.

命令说明

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：在调试结束后，恢复执行训练任务的用户代码。

注意

以上命令不会占用任务的容错次数。

使用 atlctl 进行原地调试 ​

了解调试状态 ​

进入调试状态 ​

使用流程 ​

执行内置检测脚本 ​

执行自定义调试命令 ​

执行 GPU 和通信烧机测试 ​

命令说明 ​

burn ​

status ​

stop ​

check ​

run ​

recover ​

使用 atlctl 进行原地调试

了解调试状态

进入调试状态

使用流程

执行内置检测脚本

执行自定义调试命令

执行 GPU 和通信烧机测试

命令说明

burn

status

stop

check

run

recover