一、前提条件
| 条件 | 说明 |
| 已编译的 hyper-trace 二进制 | 已联系 在线客服 获取已编译的二进制工具。 |
| 操作系统 | Linux 内核 5.4+（推荐 5.15+）。 |
| 内核模块 | 启用 BTF 功能（检查是否存在虚拟文件/sys/kernel/btf/vmlinux）。 |
| GPU 训练进程正在运行 | NVIDIA CUDA 或 DCU 训练进程已启动（或即将启动）。 |
| root 权限 | 采集命令需要 sudo 运行。 |
二、步骤1：安装 HyperTrace 训练效能保障套件
HyperTrace 训练效能保障套件以二进制命令行工具形式提供，不依赖于操作系统发行版本。工具下载到训练环境后添加可执行权限即可使用，推荐放到 /usr/local/bin 目录下方便使用。
chmod +x hyper-tracemv hyper-trace /usr/local/bin/# 验证工具，查看帮助命令hyper-trace –help
三、步骤2：训练环境检测
·单节点场景下：支持 NVIDIA/DCU 的环境检测，训练前预检测 GPU 故障，发现环境问题提前告警。
# NVIDIA 平台hyper-trace gpu health# DCU 平台hyper-trace dcu health
·多节点/集群场景下：批量执行环境检测，需要节点间配置 SSH 免密。
# 集群节点信息提前配置到 hosts.txt 文件中echo "10.0.0.110.0.0.2" >> hosts.txt# 执行集群批量环境检测hyper-trace gpu health -f hosts.txt
四、步骤3：集群一致性检测
集群一致性检测支持批量执行，批量检测前需要节点间配置 SSH 免密。
# 集群节点信息提前配置到 hosts.txt 文件中echo "10.0.0.110.0.0.2" >> hosts.txt# 执行集群一致性检测hyper-trace collect -f hosts.txt
五、步骤4：接入训练任务
HyperTrace 训练效能保障套件支持以 preflight 方式提供训练任务的接入，并通过配置环境变量开启/关闭特定功能。执行后节点间会自动建连并识别拓扑，自动批量执行对应功能。
# master 节点hyper-trace torchrun –nproc_per_node=8 –nnodes=2 –node_rank=0 –master_addr=10.0.0.1 train.py# worker 节点hyper-trace torchrun –nproc_per_node=8 –nnodes=2 –node_rank=1 –master_addr=10.0.0.1 train.py
六、步骤5：采集训练性能数据
在另一个终端中执行，采集进行中的训练任务：
# 自动检测 GPU 进程，全部探针，采集 10 秒sudo hyper-trace run -t 10# 采集完成后自动生成 HTML 报告sudo hyper-trace run -t 10 –report
采集完成后，输出目录结构如下：
/tmp/ebpf-trace/<timestamp>/├── trace_output.json Chrome Trace 格式（可导入 Perfetto UI）├── trace_report.html 交互式 HTML 报告（ECharts 可视化）└── trace_output_gpu_stats.xlsx 算子性能数据明细清单