九章智算云
Pod常用命令与故障排查

Alaya NeW的计算加速资源实例默认使用Ubuntu 22.04 LTS。本页面向已经具备基本Linux使用经验的用户,整理SSH登录Pod后常用的命令,重点覆盖文件管理、日志查看、数据传输、进程排查和资源监控。

使用说明

配套文档

本文中的/data、/data/checkpoints等路径均为示例,请根据实例实际挂载目录调整。命令是否可用还取决于当前用户权限、容器配置及已安装的软件。


文件与目录

切换目录:cd

cd /                       # 切换到根目录
cd ~                       # 切换到当前用户的主目录
cd -                       # 返回上一次所在的目录
cd ..                      # 切换到上一级目录
cd /data/checkpoints       # 切换到指定目录

输入路径时可以按Tab自动补全,减少手动输入长路径时的错误。

查看目录内容:ls

ls                         # 查看当前目录
ls -a                      # 包括隐藏文件
ls -lh                     # 以易读格式显示文件大小
ls -lhS                    # 按文件大小降序排列
ls -lt                     # 按修改时间降序排列
ls -lah                    # 查看包括隐藏文件在内的详细信息

常见用途:

  • 排查配置文件、隐藏目录及缓存目录是否存在。
  • 使用ls -lhS快速定位大文件。
  • 使用ls -lt查看最近生成的日志或checkpoint。

创建、复制、移动和删除

mkdir -p /data/runs/exp-001/logs   # 创建目录及缺失的父目录
touch a.txt                         # 创建空文件;文件存在时更新修改时间
cp config.yaml config.yaml.bak      # 复制文件并保留原文件
cp -r src/ dst/                     # 递归复制目录
mv old.pt new.pt                    # 重命名文件
mv model.pt /data/checkpoints/      # 移动文件
rm a.txt                            # 删除文件
rmdir empty_dir                     # 删除空目录

删除非空目录时可以使用rm -r,但应先确认目标路径。

注意

谨慎使用递归删除,rm -rf会递归删除目标且不进行交互式确认,通常无法通过常规方式恢复。执行前应检查变量和目标路径:

echo "TMP=${TMP}"
printf 'Target: %s\n' "$TMP"
test -n "$TMP" && test -d "$TMP" && echo "Path verified"

确认路径无误后,再执行针对明确目标的删除操作。不要直接执行rm -rf "$TMP"/*等依赖未经验证的环境变量的命令。

查找文件:find

find . -name "*.safetensors"              # 查找模型权重文件
find . -type f -size +1G                   # 查找大于 1 GiB 的文件
find . -type f -mtime -1                   # 查找最近 24 小时内修改的文件
find /data -type d -name "checkpoint-*"    # 查找 checkpoint 目录
find /data -type f -name "*.log"           # 查找日志文件

注意

-mtime -1按文件修改时间的时间间隔筛选,并不严格等价于自然日内修改。查找范围较大时,优先指定目录,避免遍历不必要的文件系统路径。

查看当前路径及文件真实位置

pwd                       # 查看当前工作目录
realpath ./model.bin      # 将路径解析为绝对路径
stat model.bin            # 查看文件大小、权限和时间信息

realpath适合检查相对路径及符号链接的解析结果。排查挂载目录时,还可以使用:

findmnt /data             # 查看 /data 所在的挂载信息
df -h /data               # 查看该路径所在文件系统的空间使用情况

查看文件与训练日志

常用查看命令

cat config.json           # 输出整个文件,适合小文件
less train.log            # 分页查看大文件
head -n 50 train.log      # 查看前 50 行
tail -n 50 train.log      # 查看最后 50 行
tail -f train.log         # 实时查看新增日志
tail -n 200 -f train.log  # 查看最近 200 行并持续跟踪

在less中:

操作说明
Space / b向下翻页 / 向上翻页
/loss搜索loss
n / N跳转到下一个 / 上一个匹配项
g / G跳转到文件开头 / 结尾
q退出

搜索日志中的错误

grep -n "ERROR" train.log                 # 搜索 ERROR 并显示行号
grep -niE "error|exception|traceback" train.log
grep -n "out of memory" train.log         # 搜索 OOM 相关信息
grep -nE "loss|step|epoch" train.log      # 搜索训练进度
tail -n 300 train.log | grep -i "error"  # 检查最近 300 行中的错误

如果需要持续查看日志,可以组合使用:

tail -f train.log | grep --line-buffered -iE "loss|error|warning"

注意

日志文件必须存在且当前用户具有读取权限。grep未匹配到内容不代表任务正常,应结合退出码、完整日志和进程状态判断。

tail -f是训练期间最常用的命令之一。建议与 Tmux终端复用 配合使用,避免SSH断开后失去终端会话。


Vim:完成基本编辑即可

打开配置文件:

vim config.yaml

常用操作如下。

目标操作
开始编辑按i进入插入模式
结束编辑模式按Esc
保存并退出输入:wq后回车
不保存退出输入:q!后回车
跳转到第100行输入:100后回车,或按100G
搜索关键字输入/loss后回车
查找下一个匹配项按n
删除当前行按dd
撤销操作按u

如果不熟悉Vim,可以使用 VS Code Remote-SSH,在本地IDE中直接编辑Pod内的文件。


文件权限:chmod

修改权限

chmod +x run.sh              # 为文件增加可执行权限
chmod 755 run.sh             # 设置拥有者 rwx、同组及其他用户 r-x
chmod 644 config.yaml        # 设置拥有者 rw-、其他用户 r--
chmod -R 755 /data/scripts   # 递归设置目录及其中所有文件的权限

chmod -R 755会使目录和普通文件都获得执行权限,通常不适合直接用于混合文件类型的目录。批量修改前应先确认目录内容及权限需求。

数字权限速记

Linux权限使用r、w、x表示读取、写入和执行,对应数值分别为4、2、1。

数字权限含义
7rwx读取、写入、执行
6rw-读取、写入
5r-x读取、执行
4r--只读
0---无权限

例如,chmod 755 run.sh中的三个数字依次对应文件拥有者、所属组和其他用户。

查看权限

ls -l run.sh

示例输出:

-rwxr-xr-x 1 user user 4096 May 3 12:00 run.sh
  • 第一个字符-表示普通文件,d表示目录,l表示符号链接。
  • 接下来的九个字符依次表示拥有者、所属组和其他用户的权限。
  • 对目录而言,x表示可以进入目录并访问其中已知名称的文件,但实际访问仍受目录及文件的其他权限约束。

如果遇到Permission denied,应先检查文件权限、目录权限和当前用户身份,再判断是否需要修改权限。不要默认通过chmod 777解决问题。


打包与解压

使用tar

tar -czf data.tar.gz data/          # 将 data 目录打包并使用 gzip 压缩
tar -xzf data.tar.gz                # 解压到当前目录
tar -xzf data.tar.gz -C /target/    # 解压到指定目录
tar -tf data.tar.gz | head          # 查看归档中的前几项

常用参数:

参数含义
c创建归档
x解包
z使用gzip压缩或解压
v显示处理过程
f指定归档文件名

如果不需要逐项显示文件名,可以省略v,减少大目录打包时的终端输出。

使用zip

zip -r weights.zip checkpoint-*/   # 将匹配的 checkpoint 目录打包
unzip weights.zip                  # 解压到当前目录
unzip -l weights.zip               # 查看压缩包清单
unzip weights.zip -d /data/weights/ # 解压到指定目录

打包前应确认目标文件及目录匹配结果。模型权重可能占用大量空间,压缩前请检查磁盘剩余容量;对已经压缩的权重文件,重新压缩通常不会显著减小体积。


文件传输:本地与Pod之间

以下以SSH连接地址user@example.alayanew.com、端口31029为例。请替换为实际连接信息,并在本地终端执行涉及本地路径的命令。

使用SCP传输

从本地上传到Pod:

# 上传单个文件
scp -P 31029 model.safetensors user@example.alayanew.com:/data/

# 上传整个目录
scp -r -P 31029 dataset/ user@example.alayanew.com:/data/

从Pod下载到本地:

# 下载单个 checkpoint
scp -P 31029 user@example.alayanew.com:/data/checkpoint-1000.pt ./

# 下载整个目录
scp -r -P 31029 user@example.alayanew.com:/data/runs/exp-001/ ./

注意

SCP使用大写-P指定SSH端口;SSH命令本身使用小写-p。

大文件与断点续传:rsync

传输大型数据集、模型权重或训练checkpoint时,可以优先考虑rsync。它支持进度显示、续传及增量同步,但并不意味着网络中断后所有场景都能无条件续传,也不保证传输速度一定更快。

# 从本地上传目录内容
rsync -avP -e "ssh -p 31029" \
  /data/dataset/ \
  user@example.alayanew.com:/data/dataset/

# 从 Pod 下载目录内容
rsync -avP -e "ssh -p 31029" \
  user@example.alayanew.com:/data/checkpoints/ \
  ./checkpoints/

参数说明:

  • -a:归档模式,递归同步并尽可能保留文件属性。
  • -v:显示同步信息。
  • -P:组合启用进度显示和部分文件保留,便于中断后继续传输。
  • -e:指定远程连接命令。

源路径末尾的/会影响目录同步行为。/data/dataset/表示同步该目录中的内容;如果不带末尾的/,通常会把目录本身也放到目标目录中。

传输前先确认目标路径

rsync默认不会删除目标端多余文件,但添加--delete后会删除目标端不在源端对应内容中的文件。使用该参数前应先检查同步方向和目标路径。

从公网下载文件

wget https://example.com/file.tar.gz           # 下载文件
wget -c https://example.com/file.tar.gz        # 尝试断点续传
wget -O model.bin https://example.com/model    # 指定保存文件名

curl -fL -O https://example.com/file.tar.gz    # 下载并跟随重定向
curl -fL -o model.bin https://example.com/model # 指定保存文件名

wget -c和curl -C -都可用于尝试续传,但是否能够成功取决于服务器是否支持相应的续传机制。

如果下载的是AI模型或代码资源,可以参考:


进程与系统资源监控

查看内存、磁盘和CPU

free -h                     # 查看内存和 Swap
df -h                       # 查看各文件系统的空间使用情况
df -h /data                 # 查看 /data 所在文件系统
du -sh /data                # 查看 /data 的总占用
du -h --max-depth=1 /data   # 查看 /data 下一级目录的占用
top                         # 实时查看进程和 CPU 使用情况

需要注意:

  • df -h查看文件系统的容量及可用空间。
  • du统计目录中的文件占用,两者结果可能因已删除但仍被进程打开的文件、文件系统特性或挂载方式而不同。
  • du遍历大量文件时可能较慢;请优先指定目标目录。
  • htop提供更直观的交互式界面,但不一定预装在Pod中。没有该命令时,可以使用top。

查找进程

ps -ef | grep '[p]ython'              # 查找 Python 进程
ps aux --sort=-%mem | head -n 10      # 按内存使用率查看前 10 项
ps -eo pid,ppid,stat,%cpu,%mem,cmd --sort=-%cpu | head

grep '[p]ython'可以避免将用于搜索的grep进程本身也匹配出来。

如果需要确认某个进程是否属于当前训练任务,可以检查完整命令行、父进程和启动时间:

ps -p 1234 -o pid,ppid,user,lstart,stat,cmd

将示例中的1234替换为实际PID。

结束进程

kill 1234       # 发送 SIGTERM,请求进程正常退出
kill -9 1234    # 发送 SIGKILL,强制终止进程

优先使用kill PID,让进程有机会完成清理工作。只有确认进程无法正常退出且确实需要终止时,才考虑使用kill -9。

也可以按命令行查找进程,但不建议未经确认直接执行pkill -f train.py:该命令可能匹配并终止多个同名任务。


资源专用速查:显存、利用率与占卡排查

查看资源状态

nvidia-smi

该命令通常用于查看计算资源型号、驱动版本、显存使用量、利用率、功耗和可见的计算进程。

示例输出仅用于说明字段含义,实际型号、数值和列布局以当前环境为准。

+-----------------------------------------------------------------------------+
| NVIDIA-SMI ...             Driver Version: ...       CUDA Version: ...      |
+-------------------------------+----------------------+----------------------+
| GPU  Name                     | Memory-Usage        | GPU-Util             |
| 0    NVIDIA H800A             | 78234MiB/81559MiB    | 98%                  |
+-------------------------------+----------------------+----------------------+
| Processes:                                                                  |
| GPU   PID    Process name                         GPU Memory                |
| 0     1234   python train.py                      ...                       |
+-----------------------------------------------------------------------------+

重点指标怎么读

指标含义排查方向
Memory-Usage已用显存与总显存显存接近上限时,检查模型、batch size、激活值、缓存及其他进程
GPU-Util采样周期内算力资源忙碌程度持续偏低时,检查数据加载、CPU、同步等待、通信及任务规模
Pwr:Usage/Cap当前功率与功率上限结合计算加速资源利用率、时钟、温度和功率限制综合判断
Processes当前可见的计算加速资源进程信息用PID进一步确认任务归属和运行状态

不要仅凭一个指标判断故障:

  • 显存接近上限不代表一定会OOM。 是否发生OOM还取决于后续显存分配、临时张量、碎片及其他任务。
  • 计算加速资源利用率低不一定是IO瓶颈。 模型较小、batch size较小、同步等待或通信开销都可能造成低利用率。
  • 功耗低不一定代表计算加速资源异常。 算力资源可能处于等待、低负载或受功率策略限制的状态。
  • 进程列表不完整不一定代表没有占卡。 容器隔离、权限、MIG或平台的资源管理方式都可能影响可见信息。

实时刷新计算加速资源指标

nvidia-smi -l 1

每秒刷新一次,按Ctrl+C退出。

只查看指定指标:

nvidia-smi \
  --query-gpu=index,name,memory.used,memory.total,utilization.gpu,power.draw \
  --format=csv \
  -l 1

如果只想检查当前显存与利用率,可以进一步精简查询字段:

nvidia-smi \
  --query-gpu=memory.used,memory.total,utilization.gpu \
  --format=csv

找出占卡进程

第一步,查看进程:

nvidia-smi

第二步,确认目标PID的归属和命令行:

ps -p 1234 -o pid,ppid,user,lstart,stat,cmd

第三步,检查进程是否属于当前训练任务,以及是否仍在运行。确认可以终止后,优先发送正常退出信号:

kill 1234

如果进程没有退出,再检查其状态和日志,确认确实需要强制结束后,才使用:

kill -9 1234

注意

不要把释放显存等同于杀掉所有计算加速资源进程,fuser -k /dev/nvidia*可能终止当前容器内使用匹配设备文件的多个进程,影响正在运行的其他任务;在共享Pod或多任务环境中尤其危险。排查占卡问题时,应先定位具体PID,确认进程归属,再决定是否终止。

训练慢或OOM:常见现象与排查方向

现象可能原因建议排查
资源利用率持续为0%,但显存仍被占用进程等待数据、同步阻塞、任务停滞或其他进程持有显存查看训练日志、进程状态及CPU、磁盘和网络活动
资源利用率在0% 与100% 之间反复波动数据加载、CPU预处理或同步操作可能导致计算加速资源间歇等待检查DataLoader、num_workers、pin_memory和数据读取耗时
资源利用率持续偏低batch size较小、模型计算量不足、通信或其他等待开销结合模型规模、吞吐量和训练阶段进行分析
显存接近上限并发生OOM激活值、临时张量、batch size或其他显存分配导致空间不足检查OOM日志,尝试降低batch size、启用gradient checkpointing或调整并行策略
资源利用率较高但训练吞吐偏低计算效率、显存带宽、通信、同步或内核执行可能存在瓶颈结合tokens/s、step time、通信耗时及性能分析工具判断

具体优化应以日志和性能数据为依据。num_workers、pin_memory、gradient checkpointing和ZeRO等配置并非对所有任务都有效,调整后应对比吞吐量、显存和稳定性。


命令历史与环境排查

查找和复用历史命令

history | tail -n 50      # 查看最近 50 条命令
history | grep python     # 查找包含 python 的历史命令

交互式快捷键:

快捷键用途
Ctrl+R反向搜索历史命令
Ctrl+C中断当前前台命令
Ctrl+Z向当前前台进程组发送挂起信号
Ctrl+D在空输入行时结束终端输入或退出Shell

Ctrl+Z并不是让任务可靠地在后台持续运行。需要长时间运行的训练任务,应优先使用Tmux;对于已挂起的作业,可通过jobs查看,再根据实际情况使用fg恢复前台运行。

Bash中的!!可展开上一条命令,!1234可展开历史编号为1234的命令。使用历史展开前应确认展开内容,尤其不要直接重放可能包含删除、覆盖或其他破坏性操作的命令。

检查Python和CUDA环境

which python              # 查看当前命中的 Python 可执行文件
python --version           # 查看 Python 版本
echo "$PATH"               # 查看命令搜索路径
env | grep -E 'CUDA|NVIDIA' # 查看相关环境变量
nvidia-smi                 # 查看驱动及资源状态

如果使用Conda或其他虚拟环境,还应确认当前环境是否正确激活,并检查实际使用的Python解释器及依赖版本。

注意

nvidia-smi显示的CUDA Version表示驱动支持的CUDA版本上限信息,不等同于当前Python环境实际安装的CUDA Toolkit或PyTorch CUDA运行时版本。


长时间训练:使用Tmux

训练通常持续数小时甚至数天。SSH连接中断不一定会导致进程退出,但直接在SSH终端启动的任务可能随会话结束而终止。建议在启动训练前使用Tmux管理终端会话。

创建和恢复会话

tmux new -s train       # 创建名为 train 的会话

在Tmux会话中启动训练任务:

python train.py

需要暂时离开时,按Ctrl+B,松开后再按D,即可脱离会话而不主动结束其中的任务。

tmux ls                 # 查看现有会话
tmux attach -t train    # 重新连接 train 会话

如果会话已被其他终端连接,可以根据实际情况使用tmux attach -d -t train将会话从其他客户端分离后重新连接。执行前应确认不会影响其他用户正在使用的终端。

使用建议

  • 启动长时间训练前,先创建Tmux会话。
  • 将训练日志写入文件,便于重新连接后查看进度和排查异常。
  • 通过tmux ls确认会话是否存在,但不要将会话存在等同于训练进程正常运行。
  • 如果需要在SSH断开后继续运行任务,应结合Tmux、进程状态和日志共同确认。

更多用法请参考 Tmux终端复用。


后续阅读

最后更新于

这篇文档对你有帮助吗?

目录