DSV4-Pro 双机 Pro6000D SGLang 硬件竞争归因：代码详解

1. 阅读导航

• 总体控制流
• 文件职责
• Phase 1 复用边界
• 预检与时钟
• 采集器实现
• Case 编排
• 时间窗对齐
• 结构化输出
• 函数行号索引

2. 总体控制流

main "$@"
  └─ ACTION=all → run_all
       ├─ validate_config
       ├─ preflight_node_tools + preflight_clock_sync
       ├─ start_service
       │    └─ 委托 Phase 1 的 start
       ├─ capture_static_snapshots before
       ├─ start_collectors
       │    └─ Head 与 Worker 各启动 9 类采集器
       ├─ idle baseline
       ├─ 固定诊断 Case
       │    └─ 每个 Case 委托 Phase 1 的 fixed
       ├─ 混合 Prefill/Decode A/B
       │    └─ 委托 Phase 1 的 mixed
       ├─ cooldown
       ├─ stop_collectors
       ├─ capture_static_snapshots after
       ├─ stop_service
       ├─ summarize_results
       │    └─ 按每个 Case 的 started_at/ended_at 切监控窗口
       └─ finish_manifest

Phase 2 不复制模型部署和 benchmark 生成代码。它新增的是诊断编排层： 在同一个服务生命周期中，让两节点的 GPU、CPU、NUMA、网络和 RDMA 时间序列包围 benchmark， 最后按 Case 时间切片。

3. 文件职责

3.1 Phase 2 与 Phase 1 的文件关系

用户
  └─ bash Phase2/run_hardware_contention_attribution.sh all
       ├─ source Phase2/config.env
       │    └─ PHASE1_ENTRY 指向 Phase1/run_quick_map.sh
       ├─ env ... bash "${PHASE1_ENTRY}" start/fixed/mixed/stop
       │    └─ Phase1/run_quick_map.sh
       │         ├─ source Phase1/config.env
       │         ├─ 读取 Phase1/quick_map_scenarios.tsv
       │         └─ 调用 Phase1/quick_map_results.py
       ├─ 自己启动两节点硬件采集器
       └─ 调用 Phase2/hardware_contention_attribution.py
            ├─ 读取 Phase1 生成的 bench/*/cases/*/meta.json
            ├─ 读取 Phase2 生成的 GPU/RDMA 时间序列
            └─ 按 Case 时间窗生成归因汇总

这里有两套 config.env，职责不同。Phase 2 的配置控制“测哪些 Case、如何监控”； Phase 1 的配置控制“模型如何部署、请求如何生成”。Phase 2 没有复制 MEM_FRACTION_STATIC，因此它最终仍从 Phase 1 的 config.env:L38 取得默认值。

3.1 config.env 分区

4. Phase 1 复用边界

4.1 委托函数

run_phase1_action 位于 run_hardware_contention_attribution.sh:L195-L214。它向 Phase 1 注入：

• 相同 RUN_ID 体系下的独立 benchmark 子目录。
• Phase 2 自己的 service/ 证据目录。
• 指定 CASE_IDS，使 Phase 1 只跑诊断 Case。
• CASE_COOLDOWN_S=0，由 Phase 2 统一控制 Case 间隔。
• DRY_RUN 原样传递，确保 Dry-run 不会偷偷启动模型。

run_phase1_action start
run_phase1_action fixed   # 通过 CASE_IDS 只跑一个 Case
run_phase1_action mixed
run_phase1_action stop

4.2 用户只运行哪个入口

正式执行只运行 Phase 2： bash run_hardware_contention_attribution.sh all。 start_service 和 stop_service 位于 L215-L229，是编排器内部调用，不需要手工先执行 Phase 1。

4.3 Phase 2 中如何查服务参数的实际值

例如 MEM_FRACTION_STATIC 的完整传递链是：

调用命令环境（可选覆盖）
  → Phase1/config.env:L38，默认 0.9
  → Phase1/run_quick_map.sh:L258
  → SGLang --mem-fraction-static 0.9
  → Phase2/results/<RUN_ID>/service/head_server_cmd.txt
  → Phase2/results/<RUN_ID>/bench/<sub-run>/run_manifest.json

Phase 2 的顶层 manifest.json 记录监控配置，不重复记录全部服务参数。 查“模型实际怎么起的”应看 service/head_server_cmd.txt 与 service/worker_server_cmd.txt；查结构化值应看任一 Phase 1 子 Run 的 run_manifest.json。

# 查看 Phase 1 默认值
grep '^MEM_FRACTION_STATIC=' \
  ../dsv4pro_pro6000d_2node_sglang_tp16_quick_map/config.env

# 查看某次 Phase 2 Run 的实际服务命令
grep -- '--mem-fraction-static' \
  results/<RUN_ID>/service/head_server_cmd.txt

# 从 Phase 1 子 Run Manifest 读取结构化值
python3 -c 'import glob,json; p=glob.glob(
  "results/<RUN_ID>/bench/*/run_manifest.json")[0];
print(json.load(open(p))["mem_fraction_static"])'

如果这样启动： MEM_FRACTION_STATIC=0.85 bash run_hardware_contention_attribution.sh all， 外部变量会由 Phase 2 进程继承给 Phase 1，Phase 1 的 ${MEM_FRACTION_STATIC:-0.9} 会保留 0.85。 因此只看默认配置不足以证明某次实验用了什么，必须查看 Run 证据。

5. 预检、Manifest 与时钟

5.1 配置和工具预检

validate_config 在 run_hardware_contention_attribution.sh:L66-L106 检查 Phase 1 入口、节点、Case 和关键数值。 preflight_node_tools 在 L107-L134 对两节点检查 Docker、NVIDIA、RDMA、sysstat、perf 与 NUMA 工具。

采集器可用性不能在运行半小时后才发现。预检默认 fail-closed； 只有显式允许部分采集器缺失时，才降级继续。

5.2 为什么检查两机时钟

preflight_clock_sync 位于 L135-L151。 Phase 2 用 wall clock 把 benchmark 的 started_at/ended_at 与两节点采样行对齐。如果两机时钟偏差超过配置容差，同一 Case 在 Worker 上会切到错误窗口。

5.3 运行元数据

Shell 的 write_manifest 位于 L152-L176， Python 的 create_manifest 位于 hardware_contention_attribution.py:L367-L390。 Manifest 记录 Git commit、是否 dirty、Phase 1 入口、节点、Case、采样周期、时钟容差和 Dry-run。

mark_event 位于 Shell L177-L194， Python 的 append_marker 位于 L338-L365。 每个 idle/case/cooldown 边界写入纳秒级 wall time，作为人工审计时间线。

6. 采集器实现

6.1 静态快照

capture_command、static_snapshot_command 和 capture_static_snapshots 位于 Shell L230-L283。 服务启动后和实验结束前分别采集：

• nvidia-smi 与 GPU topology。
• lscpu、numactl --hardware、numastat。
• ip、ethtool 的 eth0/eth3 状态与计数器。
• ibdev2netdev、ibstat、rdma 设备信息。
• 容器列表与 inspect。

前后快照回答“实验是否改变了设备状态”；时间序列回答“Case 运行期间发生了什么”。

6.2 通用采集器包装

start_stream_collector 位于 Shell L284-L318。每个采集器都具备：

1. 保存完整命令到 collector_commands/。
2. 用唯一 tag 标记远端进程，便于精准停止。
3. 受 COLLECTOR_TIMEOUT_S 限制，避免永久悬挂。
4. 保存 PID、日志与退出状态到 collector_status.csv。

6.3 GPU 采样

gpu_sampler_command 位于 Shell L319-L332， 每秒调用 nvidia-smi --query-gpu，采集利用率、显存利用率、显存占用、 功耗、温度、SM 时钟和显存时钟，并补上 wall_time_ns,node,gpu。

Python 的 summarize_gpu_rows 位于 hardware_contention_attribution.py:L101-L135。 它按 node + GPU 分组，对每个字段输出 mean、P95、max。

6.4 RDMA 采样

Shell 的 rdma_sampler_command 与 read_counter 位于 L333-L359，读取 mlx5_0/mlx5_3 的端口发送/接收数据、 包、错误、丢弃与恢复计数器。

Python 的 summarize_rdma_rows 位于 L148-L206。 它按 node + HCA 排序，使用最后值减第一值，并注意 IB port_xmit_data/port_rcv_data 的单位是 4 octets：

xmit_bytes = (last_xmit_data - first_xmit_data) × 4
xmit_gbps = xmit_bytes × 8 / duration_s / 1e9

同时保留错误计数器 delta，因此“带宽低”可以与“链路错误增加”分开判断。

6.5 CPU、进程和 NUMA

start_node_collectors 位于 Shell L405-L457， 每个节点启动九类采集器：

container_pid_preamble 与 numastat_command 位于 L372-L404，先解析容器主 PID，再让 perf/numastat 对准实际服务进程。

6.6 停止与残留清理

check_collectors 和 stop_collectors 位于 Shell L469-L519。 除了等待已知 PID，还会按唯一 tag 清理远端残留采集器。 cleanup 在 L594-L602 由 trap 调用，先停监控再停模型服务。

7. Case 编排

7.1 固定 Case

run_fixed_case 位于 Shell L529-L556。 它为 Case 生成独立子 Run ID，写 case_start marker， 委托 Phase 1 的 fixed，再检查该子 Run 的 summary.csv， 最后写 case_end marker。

默认固定集合来自 config.env:L18，用于区分： 单请求长 Prefill、并发 Prefill、普通 Decode、持续长 Decode、长上下文 Decode。 Phase 2 不把所有 Phase 1 点再跑一遍，只保留对资源归因有辨识度的负载。

7.2 混合 Case

run_mixed_case 位于 Shell L557-L582。 它复用 Phase 1 已经保证真实时间重叠的 mixed A/B，并把整段监控留在同一采集窗口内。 Phase 2 自己不重新实现后台请求与注入逻辑。

7.3 run_all 的失败策略

run_all 位于 Shell L604-L668：

• 服务健康时，即使一个 Case 失败，也继续后续诊断 Case，并累计 failures。
• 每个固定 Case 后检查 /health；服务失活则中止剩余 Case。
• 服务已失活时跳过 mixed，避免无意义错误。
• 不论成功失败，最终尝试 cooldown、停止采集、后快照、停止服务和汇总。
• Run 状态区分 COMPLETED、COMPLETED_WITH_FAILURES、DRY_RUN。

8. 按真实 Case 时间窗归因

8.1 时间窗从哪里来

load_case_windows 位于 hardware_contention_attribution.py:L233-L260。 它读取 Phase 1 每个 meta.json 中的 started_at 与 ended_at，转换为纳秒时间戳。 这比用“Case marker 前后大概几秒”更精确，因为它对齐的是 benchmark 进程实际测量区间。

8.2 如何切 GPU/RDMA 数据

rows_in_window 位于 L263-L274， 只保留 started_ns ≤ wall_time_ns ≤ ended_ns 的采样行。 summarize_case_hardware 位于 L276-L319， 对每个 Case、每个节点分别切 GPU 与 RDMA，再复用全局汇总函数。

Case meta.started_at / ended_at
          │
          ├─ filter head/gpu_samples.csv
          ├─ filter worker/gpu_samples.csv
          ├─ filter head/rdma.csv
          └─ filter worker/rdma.csv
                 ↓
     case_gpu_summary.csv / case_rdma_summary.csv

9. 输出和归因边界

results/<RUN_ID>/
  manifest.json
  markers.csv
  collector_status.csv
  service/
  commands/
  bench/<phase1-sub-run>/
  head/
    gpu_samples.csv
    rdma.csv
    dcgm.log
    mpstat.log
    pidstat.log
    sar_network.log
    perf.log
    docker_top.log
    numastat.log
    collector_commands/
  worker/
    ...同上...
  gpu_summary.csv
  rdma_summary.csv
  bench_summary.csv
  case_windows.csv
  case_gpu_summary.csv
  case_rdma_summary.csv
  summary.json
  report.md

Python 的 summarize 位于 hardware_contention_attribution.py:L405-L504。 它汇总全局 GPU/RDMA、Phase 1 bench、Case 时间窗和 Case 级硬件数据， 同时统计采集器状态与文件大小。

自动报告只整理证据，不自动宣布“瓶颈就是 GPU/NCCL/CPU”。 L498-L499 明确要求最终结论结合 markers、原始 DCGM/sysstat 和 SGLang 日志。 这是有意的保守边界，避免单个指标被机械误判。

10. 函数行号索引

10.1 run_hardware_contention_attribution.sh

10.2 hardware_contention_attribution.py