Appearance
集群一键巡检工具教程
该章节为集群系统一键巡检工具的使用说明，巡检工具提供自动化查看集群状态及排查故障的功能，目标是扫描出上文中的所有配置的异常问题，解放人力，在多机环境或者集群使用前，可运行该工具来进行环境正常性判断，如出现异常需人工进行相应问题修复。
该章节使用教程适用于SDK release 2.29.0.5及以上的软件版本。
使用方式介绍
集群巡检工具脚本随maca sdk发布，目录为 /opt/maca/tools/mccl/inspector/
运行方式概述
cd到工具目录，直接执行mx-cmi（路径： /opt/maca/tools/mccl/inspector/mx-cmi ）
sdk master #20250529-508及之后的版本，mx-cci更名为mx-cmi
工具会自动根据配置，检测集群各节点状态，并在终端打印检测结果。 更详细的日志和信息存储在 ~/inspector_logs/ 目录.
运行效果如下图示：
使用前提及快速上手
环境依赖
集群所有机器节点需创建相同的用户账号/密码, 且具有sudo免密权限！
集群所有机器节点安装相同的软件，包括：ssh, scp, expect, ifconfig, ib驱动。
参考本指南上述章节，完成相应的软件安装，网络配置等。
如在docker内运行，请参考docker章节。
快速开始
单机测试：
修改config.ini中的账户密码，（路径： /opt/maca/tools/mccl/inspector/config.ini ）
mx-cmi运行
多机测试：
修改config.ini中的账户密码，
修改config.ini中hosts字段，指定检查目标IP
mx-cmi -R运行
使用教程
配置依赖
工具脚本的配置文件要求为ini格式（默认UTF-8编码）。
配置模式：
工具脚本支持一下三种指定配置文件方式：
| 1）自定义配置文件路径： | 工具支持命令行参数传入指定配置文件 mx-cmi -f config_path |
|---|---|
| 2）默认配置 | 参数未指定配置时，工具自动检测并使用mx-cmi所在目录的配置文件 |
基础配置：
基础配置字段为必填字段。 具体如下（默认配置路径： /opt/maca/tools/mccl/inspector/config.ini）：
除上述基础配置外， 其他配置字段为可选字段，工具提供默认值。 配置后自动覆盖默认配置。（默认配置路径： /opt/maca/tools/mccl/inspector/advanced_config.ini）
具体字段配置要求 请参见 本文 此章节。
只需在运行任务的节点运行工具时指定配置。 不需要手动在每个节点创建配置。
基础测试
基础测试 会对集群个节点进行基本信息获取，并进行状态检查。 基础测试为工具脚本默认执行环节，每次工具执行都会进行基础测试。
测试项：
GPU数量及速度是否正常，是否由掉卡掉速
用户是否正确配置 group、权限、集群免密()等。
是否已关闭ACS
网卡链路状态是否正常
RoCE网卡是否正确配置拥塞/优先级等
集群间GPU/网卡 的 驱动/固件/sdk等版本是否一致
......
测试命令：
/opt/maca/tools/mccl/inspector/mx-cmi
测试效果示例：
性能测试
注意： 性能测试项会和线上任务互相影响。 请确保运行测试时，没有其他GPU任务正在运行。
性能测试包括以下测试项 ：
| ping | RDMA 网卡连通性测试 |
|---|---|
| ib_write | RDMA 网卡带宽性能测试 |
| p2p | 单机内GPU, CPU间p2p带宽性能测试 |
| p2p_s | 多机间GPU两卡间p2p带宽性能测试 |
| mccl_perf | 集群内进行集合通信all_reduce_perf性能测试 |
执行方式：
方式1：运行所有性能测试项
/opt/maca/tools/mccl/inspector/mx-cmi -r
方式2：命令行指定测试列表。
/opt/maca/tools/mccl/inspector/mx-cmi -r "ping,ib_write"
效果示例：
- 正常效果示例：
- 异常效果示例：
性能测试前会自动进行基础测试， 基础测试失败则会停止运行测试。 需要用户先修复基础环境，通过基础测试后，才能继续性能测试。
无sudo权限降级模式
当用户无法获取sudo权限时， 工具通过降级运行方式 允许用户 进行验证。 需要注意，此时会跳过一些重要测试，如ACS开启状态、链路带宽、dmesg信息获取等。 因此不建议此模式。
工具脚本运行方式与之前相同，会在终端交互时自动询问用户是否降级执行。
运行效果示例：
查看工具产出系统拓扑信息
工具会在运行时， 抽取当前集群各个节点的GPU/NIC拓扑等基本信息。 可以通过命令行方式打印到终端，也可以查看运行后产出的信息文件（ ~/inspector_logs/detailed_info）
运行效果示例：
配置字段详细介绍
基础测试配置
基础配置
此部分配置为 必须 配置。
通用配置（环境检查）
本节配置 为基础测试检测配置。 工具跟检测系统信息后，与本配置中的字段进行比对校验， 判断是否符合预期。 如需调整基础检测行为，请按照下图字段描述进行调整。
RoCE配置（基础测试）
本节配置 用于 RoCE类型网卡基础测试校验。 工具会读取网卡拥塞配置等信息，并根据配置进行检查比对。
性能测试配置
ping 测试配置
本节配置 ping 测试行为。 一般无需修改
ib_write 测试配置
本节配置 ib_write 测试行为。
注意：
ib_limit 字段为0时，表示自动根据检测网卡带宽进行测试， 以理论带宽的70% 为正常标准。
如果需要自定义带宽要求，可以修改为期望值（支持单位:GB/s）
p2p 测试配置
本节配置 transferbench 的测试行为。
d2d_bw_limit 字段： 限定GPU间各级别链路带宽的下限。注意按照指定顺序配置。
p2p_s 测试配置
本节配置 transferbench 的测试行为。
d2d_bw_limit 字段： 限定GPU间各级别链路带宽的下限。注意按照指定顺序配置。
mccl_perf测试配置
本节配置 mccl_perf测试行为。
bw_limit： 集合通信all_reduce_perf 期望峰值带宽下限。
node_per_group 和 gpu_per_node: 这两个字段用于调整希望参与集合通信的机器节点和单机卡数。
常见检测结果及处理建议
工具运行失败
节点ssh登录失败
效果示例：
处理建议：
检查 控制网络连接。 检查ssh服务是否正常。检查.ssh目录权限是否正常。
基础检查异常
网卡基础状态检查异常
下图示例中的异常项包括：固件版本不一致，网卡拥塞配置异常。
处理建议：
请参考该章节重新安装驱动、配置网卡。
GPU基础状态异常
下图示例中，存在GPU掉卡， GPU vbios集群内不一致问题。
处理建议：
- 重新插拔或者更换GPU，重新更新驱动，并重启服务器。
服务器配置异常
下图示例中，服务器开启IOMMU。 该配置会开启PCIe ACS， 影响通信功能。
修复建议：
- 请参考该章节进行修改。
单项测试检查异常
ping 测试异常
示例：
处理建议：
请检查集群网络环境配置， 交换机配置等。
ib_write 测试异常
示例1： 带宽不符合预期
处理建议：
- 请检查网络配置、交换机配置。
示例2： 部分网络ib_write 不通
处理建议：
- 检查网络设置，是否存在spine层且配置异常。
p2p 带宽异常
效果示例：
处理建议：
请检查环境是否有其他任务同时执行。
请尝试插拔GPU，重启服务器。
mccl_perf带宽异常
效果示例：
处理建议：
请检查是否设置合理的环境变量。参考： 《MCCL环境变量指南.adoc》
请检查是否同时有其他用户在执行任务。
检查dmesg有错误信息
示例截图： 测试任务在执行时，会捕获测试执行期间的增量dmesg error。
处理建议：
请根据相关dmesg 错误信息，查看KMD wiki 资料。
插拔GPU并重启集群服务器。