hongshuai.dong 6ea2acf2d6 feat: 新增 GPU 节点画像与 3D 拓扑工具
- 新增只读 GPU 节点采集器,以统一 JSON 描述系统、CPU/NUMA、GPU、NVLink、PCIe、RDMA、网络与功耗信息
- 统一 Bond、独立 RoCE 和 InfiniBand 端点模型,支持 GPU 到 RDMA 端点的全局最优唯一匹配
- 亲和关系严格记录 nvidia-smi topo -m 证据,未暴露的 IB 设备不推测 GPU 连线
- 新增原生 HTML 运维画像和 Canvas 3D CT,可按 NUMA、PCIe 分组及 Bond 逐层查看物理成员端口
- 展示 CPU 亲和、P-State、当前功耗与 Power Limit,并提供 RDMA、Bond、IB、管理网络及整机健康检查
- 排除 CNI/veth 等虚拟接口对管理网络画像的干扰,普通管理 Bond 不计入 RDMA Bond 验收
- 提供脱敏 B300 真机示例、离线自包含页面、使用文档及 17 项解析和渲染回归测试
- 修正生成物忽略规则,确保两个 HTML 源模板能够随工具提交
2026-07-25 13:47:36 +08:00

156 lines
7.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# GPU Node Profile
`gpu_node_profile.py` 通过只读命令采集 GPU、NVLink、PCIe/NUMA、RoCE
Bond、RDMA 和 InfiniBand 信息,生成通用结构化 JSON,并使用 `templates/`
中的两个独立 HTML 源模板,从同一份 JSON 渲染完全离线、无 Mermaid、
无 CDN 依赖的运维画像与 3D 拓扑 CT。
页面顶部按“系统与软件 / GPU / CPU与内存”展示整机概览;中部的
GPU-RDMA 拓扑支持“总览 / NUMA 分览”即时切换,并继续展示 InfiniBand、
OS 可见的带内管理网卡和可读取的 BMC 带外信息;最底部横向展示健康检查
与验证结论。
3D CT 页面使用原生 Canvas 对结构化 JSON 动态布局,包含 NUMA 半透明地域、
CPU Socket、PCIe Root Complex、PCIe Switch 分组、GPU、NVSwitch、RoCE、
InfiniBand 和管理网卡。NUMA 与 PCIe 均来自数据,不包含 B300 专用坐标,
因此同一渲染器也可用于 A800 等其他 GPU 服务器。
页面提供递归内部镜头,可按“整机 → NUMA → PCIe 分组 → Bond → 物理网卡”
逐层钻取。进入任一层后会隐藏外层与无关的同级设备,只保留当前壳体和后代
节点;顶部面包屑说明当前位置,“上一层”按原路径返回。双击壳体继续深入,
双击普通设备时也会沿该设备的父级路径每次深入一层,例如连续双击 GPU 会
依次进入整机、NUMA 和对应 PCIe 分组;到达最深层后才执行设备聚焦。
`Shift + 拖动`可平移,`Esc`返回整机外观。
Canvas 标签使用高对比浅色底与黑色粗体。每个 RoCE Bond 会作为透明聚合
容器展示,并在内部继续拆出物理成员网卡、速率和 BDF。NVLink/NVSwitch
连线在设备盒子上层高亮绘制,GPU 端点带编号;该 Fabric 只连接 GPU,
不会连接网卡。
网络模型同时支持两种形态:存在 Bond 时渲染
`GPU → RoCE Bond → 物理成员端口`;不存在 Bond 时根据
`nvidia-smi topo -m`、RDMA 名称和 PCIe 路径渲染
`GPU → 独立 RoCE/InfiniBand 端点`。多张 GPU 与多个等距端点会进行
全局最优、确定性的唯一分配,避免顺序贪心导致所有 GPU 错误指向同一张
网卡;端点少于 GPU 时才保留可共享的最近路径语义。亲和关系只接受
`nvidia-smi topo -m` 暴露的 `PIX/PXB/PHB/NODE/SYS` 证据;若独立 IB
未出现在矩阵中,会保留设备和 PCIe/NUMA 信息并标记 `not-exposed`,但不会
推测一条 GPU 连线。
JSON 中的 `network_endpoints` 是两张页面共用的标准网络模型:
```text
network_endpoints[]
id / type(bond|standalone) / protocol(RoCE|InfiniBand)
rdma / numa / bdf / state / topology_visibility
members[] # Bond 为多个物理口,直连端点为一个物理口
gpu_links[] # GPU、PIX/PXB/...、用途及证据来源
gpus[].primary_network_id # 指向主要计算 RDMA 端点
gpus[].network_links[] # 保留主要端点和额外最近端点
```
CPU 与内存概览、NUMA 标尺和每张 GPU 卡片会同时展示 `nvidia-smi topo -m`
解析出的推荐 CPU 范围及内存 NUMA。该信息描述硬件拓扑的近端路径,不表示
训练或推理进程已经通过 `taskset`、cgroup、Slurm 或 Kubernetes 完成实际绑核。
GPU 概览和单卡画像会展示采集时刻的 `power.draw`、当前 `power.limit` 与
P-State。Power Limit 表示当前生效的 GPU 功耗上限,不等于整机额定功耗;
P0 表示最高性能状态,也不单独等价于 GPU 持续满载。
## 在 GPU 节点执行
```bash
python3 gpu_node_profile.py \
--output gpu_node_profile.html \
--topology-output gpu_topology_3d.html \
--snapshot-out gpu_node_snapshot.json \
--expected-gpus 8 \
--expected-bonds 8 \
--expected-ib 4
```
脚本不会修改网卡、驱动、Bond 或系统配置。唯一写操作是生成用户指定的
HTML/JSON 文件。`--expected-bonds` 校验的是 RDMA/RoCE Bond;普通管理
Bond 会保留在原始网卡信息中,但不会计入加速网络端点数量。
三个产物的关系:
```text
只读采集 → gpu_node_snapshot.json
├─→ gpu_node_profile.html
└─→ gpu_topology_3d.html
```
源码与演示数据的关系:
```text
gpu_node_profile.py # 只读采集、校验和渲染入口
templates/gpu_node_profile.html # 运维画像源模板
templates/gpu_topology_3d.html # 3D CT 源模板
examples/b300_demo.json # 由真机快照脱敏得到的演示数据
examples/b300_profile_demo.html # demo.json 生成的自包含示例
examples/b300_topology_3d_demo.html
```
最终生成的两张 HTML 会把 JSON 嵌入页面,因此可以直接双击、复制到其他机器
或离线归档。它们不会在打开时读取旁边的 `demo.json`;修改或替换 JSON 后,
需要重新运行 Python 渲染:
```bash
python3 gpu_node_profile.py \
--snapshot-in examples/b300_demo.json \
--output examples/b300_profile_demo.html \
--topology-output examples/b300_topology_3d_demo.html \
--expected-gpus 8 \
--expected-bonds 8 \
--expected-ib 4
```
## 使用已有快照离线渲染
```bash
python3 gpu_node_profile.py \
--snapshot-in examples/b300_demo.json \
--output b300_profile_demo.html \
--topology-output b300_topology_3d_demo.html \
--expected-gpus 8 \
--expected-bonds 8 \
--expected-ib 4
```
只采集 JSON 并写到标准输出,适合通过 SSH 在远端只读采集、在本地渲染:
```bash
python3 gpu_node_profile.py --snapshot-stdout
```
## 测试
```bash
python3 -m unittest discover -s tests -v
```
## 采集边界
- `nvcc` 表示当前 PATH 指向的 CUDA Toolkit,不代表容器或应用实际加载的
CUDA Runtime。
- LACP Bond 展示的是成员链路聚合容量,不承诺单连接可达到聚合带宽。
- 虚拟机中的 PCIe/NUMA 数据表示 Guest 可见拓扑,不能代替宿主机物理布线
和交换机侧验证。
- `pci_fabric` 保存 Guest 可见的 PCIe 祖先路径、桥和端点。3D 页面中的空间
坐标由这些逻辑关系动态生成,不代表设备在机箱中的厘米级真实位置。
- `PIX/PXB/PHB/NODE/SYS` 表示拓扑距离。`PIX` 可作为 GPUDirect RDMA 的
良好候选路径,但只有完成驱动能力和实际 RDMA 传输验证后才能标记为
`GDR Verified`。
- CPU 亲和表示 NVIDIA 拓扑给出的推荐 CPU/内存范围,不是运行中进程的
`Cpus_allowed_list`。评估实际 H2D 性能还需结合进程绑核、内存落点、
pinned memory 和带宽实测。
- GPU 功耗为报告生成时的一次瞬时采样;周期性训练负载的平均功耗和峰值
需要连续采样。整机功耗还需结合 BMC/DCMI 或机柜 PDU,不能简单等同于
所有 GPU Power Limit 之和。
- 独立BMC口通常不进入宿主OS网络命名空间。脚本会尝试从常见LAN通道只读
执行 `ipmitool lan print`;读取不到时会在画像中明确标记“OS不可见”。
- 管理网络区域只渲染物理 PCI 网卡、Bond 或默认路由接口;CNI、veth 等
容器虚拟接口仍可保留在原始 JSON 的 `nics` 中,但不会污染整机画像。