agentic-pd-hybrid/docs/H200_DRIVER570_SETUP_ZH.md

# H200 + Driver 570 上跑通本仓库的环境配置（含踩坑记录）

**适用范围**：4× H200 节点 + NVIDIA driver `570.86.15` + 本仓库 `kvc-debug-journey-v1-to-v4` 或后续分支。
**目标读者**：拿到一台新 H200 机器、需要快速跑通 sglang 0.5.10 vendor + mooncake RDMA + agentic-pd-hybrid 的下一个 SWE/research agent。
**作者状态**：本文档定稿于 `h200-cu130 @ 初始 commit`，smoke test 已 RDMA 跑通 16 reqs / 0 error。

---

## 0. TL;DR（5 行）

1. **`nvidia-smi` 的 "CUDA Version: 13.0" 是个陷阱**——它是 driver 能 forward-compat 跑的 runtime 上限，不是 driver 自己 API 版本。driver `570.86.15` 提供的 driver API 是 **cu12.8**。
2. vendor sglang 0.5.10 的 `jit_kernel/` 用 `tvm_ffi` + ninja + nvcc binary 在首次调用每个 kernel 时编译。系统唯一 nvcc 在 `/usr/local/cuda-13.0/bin/`，cu13 编译出的 .so 会 NEEDED `libcudart.so.13`，driver 570 拒绝运行 → `cudaErrorInsufficientDriver`。
3. 解法是**本地装一份 cu12.8 toolkit 到 `$HOME/cuda-12.8`**（不需要 root），让 tvm_ffi 走 cu12.8 nvcc，编译产物 NEEDED `libcudart.so.12`，driver 570 完美支持。
4. mooncake wheel (`mooncake-transfer-engine 0.3.10.post2`) 也是 cu12 build，需要 `libcudart.so.12`——已经由 `nvidia-cuda-runtime-cu12` 包提供，在 venv 里。
5. 每个 shell **必须 `source scripts/setup_env.sh`** 才能跑 SGLang。已封装好。

---

## 1. 一次性 setup（约 25min）

```bash
cd /path/to/agentic-pd-hybrid

# (1) Python 环境 (~3min)
uv sync

# (2) cu12.8 toolkit 本地装（~5GB 下载 + 5min 解压 = ~15-20min）
mkdir -p /tmp/cuda_dl && cd /tmp/cuda_dl
wget https://developer.download.nvidia.com/compute/cuda/12.8.1/local_installers/cuda_12.8.1_570.124.06_linux.run
sh cuda_12.8.1_570.124.06_linux.run \
  --silent --toolkit --override \
  --installpath=$HOME/cuda-12.8 \
  --tmpdir=$HOME/tmp \
  --no-drm --no-man-page

# (3) 验证
$HOME/cuda-12.8/bin/nvcc --version   # 应该看到 release 12.8, V12.8.93

# (4) 回到 repo 根目录,首次 source（每个 shell 都要做）
cd /path/to/agentic-pd-hybrid
source scripts/setup_env.sh
```

`source scripts/setup_env.sh` 输出应是：
```
agentic-pd-hybrid env ready:
  CUDA_HOME=/home/<user>/cuda-12.8 (12.8, V12.8.93)
  libcudart.so.12 at .../.venv/lib/python3.12/site-packages/nvidia/cuda_runtime/lib
  MC_TRANSFER_TIMEOUT=1800s
```

**`MC_TRANSFER_TIMEOUT=1800` (30 min) 替代 mooncake 默认 30s**——E2 forensic 发现 D 端 LRU eviction 会让 mooncake C++ control plane 被 starved 30+s，触发 `conn.py:1270` hair-trigger 永久 blacklist 整个 D 的 mooncake_session_id。1800s 给足缓冲，30 分钟还没回应才是真正"D 死了"。详见 `docs/E1_E2_RESULTS_ZH.md §5c`。`stack.py` 也对 worker subprocess 设了同名默认值。

---

## 2. Smoke test（验证整条链路）

把 16 个合成 request 喂给 1P3D 拓扑，启用真 RDMA，跑通后才能动 E1/E2 实验。

```bash
# 假设已 source scripts/setup_env.sh
mkdir -p outputs/smoke_rdma

uv run --no-sync python -m agentic_pd_hybrid.cli make-small-append-trace \
  --output outputs/smoke_rdma/mini_trace.jsonl \
  --session-count 4 --turns-per-session 4 \
  --initial-input-length 1024 --append-input-length 200 --output-length 50 \
  --inter-turn-gap-s 2 --session-stagger-s 1

uv run --no-sync python -m agentic_pd_hybrid.cli benchmark-live \
  --trace outputs/smoke_rdma/mini_trace.jsonl \
  --output-root outputs/smoke_rdma \
  --mechanism pd-disaggregation --policy default \
  --model-path /mnt/models/Qwen/Qwen3-30B-A3B-Instruct-2507 \
  --prefill-workers 1 --decode-workers 3 \
  --prefill-tp-size 1 --decode-tp-size 1 \
  --prefill-gpu-ids 0 --decode-gpu-ids 1,2,3 \
  --transfer-backend mooncake \
  --force-rdma --ib-device mlx5_60 \
  --gpu-budget 4 --time-scale 1 \
  --concurrency-limit 4 --timeout-s 1800 --request-timeout-s 300 \
  --session-sample-rate 1.0 --min-turns 1 --target-duration-s 600
```

**首次跑会慢 8-15min**（model load 196s + 5-10 个 JIT kernel 各编译 ~10-30s + warmup）。后续跑只 ~3-5min。

**期望结果**：`request_count=16, error=0, abort=0, failure=0, execution_modes={'pd-disaggregation-router': 16}`。

每个 worker 的日志应有 `installTransport, type=rdma`，表示 mooncake 真的走 RDMA 而不是 TCP loopback。

---

## 3. GPU ↔ RDMA HCA 映射（本机实测）

8 块 ConnectX HCA，全部 ACTIVE / 400 Gb/s NDR / RoCE v2 (link_layer=Ethernet, GID Index 3)。Mooncake 按 NUMA / PCIe affinity 自动选 preferred：

| GPU | preferred HCA | NUMA |
|---|---|---|
| cuda:0 | mlx5_60 | 0 |
| cuda:1 | mlx5_88 | 0 |
| cuda:2 | mlx5_98 | 1 |
| cuda:3 | mlx5_42 | 1 |

CLI 的 `--ib-device <name>` 只接单个设备名，给所有 worker 全局 override。Smoke test 默认填 `mlx5_60`（P worker 在 cuda:0 上 NUMA-local；D worker 在其它 GPU 上是 cross-NUMA 但能跑）。E1/E2 实验如果想最优，可以分 P/D worker 独立设环境变量，但目前 stack.py 不支持 per-worker `MOONCAKE_DEVICE`，要么所有 worker 同一个，要么走 mooncake auto（需把 `MC_MS_AUTO_DISC=0` 改回 1）。

完整 8 块 HCA：`mlx5_22, _27, _42, _60, _88, _98, _126, _135`（NUMA 0/1/0/0/0/1/0/1 混杂）。

---

## 4. 踩过的坑（按时间线）

### 坑 1：`nvidia-smi` 的 "CUDA Version: 13.0" 是误导

`nvidia-smi` header 显示 `Driver Version: 570.86.15 / CUDA Version: 13.0` 让人以为机器支持 cu13。**这是 driver 能 forward-compat 跑的 CUDA runtime 上限**，不是 driver 自己 API 的版本。driver 570 的 driver API 上限是 cu12.8（参见 NVIDIA "CUDA Compatibility" 矩阵）。

**正确判断方法**：跑 `torch.cuda.is_available()`，如果装了 cu13 build 的 torch 会报 `The NVIDIA driver on your system is too old (found version 12080)`。返回 `12080` 才是 driver 自己 API 版本（cu12.8）。

### 坑 2：vendor sglang vs pip sglang 的 patch 差异

仓库的 `third_party/sglang/python/` 是带项目自有 patches 的 SGLang 0.5.10 fork。**pip 上的 `sglang==0.5.10` 不包含核心 patches**——具体差异：

| 文件 | pip 版 | vendor 版 |
|---|---|---|
| `srt/managers/scheduler.py` | 3621 行 | 3938 行 |
| `admit_direct_append` 出现次数 | 2 | **11** |
| `DirectAppendAdmissionReqInput/Output` | 没有 | **有**（核心 RPC） |
| `_should_allow_local_prefill_on_decode` | 没有 | 有 |
| `maybe_trim_decode_session_cache` | 没有 | 有 |
| `decode_direct_waiting_queue` | 没有 | 有 |

→ **必须用 vendor 版**。本分支已把 `pyproject.toml` 的 `sglang==0.5.10` 改成 `sglang` + `[tool.uv.sources] sglang = { path = "third_party/sglang/python", editable = true }`，`uv sync` 后会自动 editable 安装 vendor 版。

历史上有些 sweep 脚本用 `PYTHONPATH=src:third_party/sglang/python` 在运行时切换，但用 `uv.sources` 把它装进 venv 更彻底，不会被 pip 的 sglang 偷偷 shadow。

### 坑 3：cu13 切换是死路

发现 driver 570 不兼容时第一个想到的路径是「装 cu13 PyTorch」。试过：

1. 改 `pyproject.toml` 加 `[[tool.uv.index]]` 指向 `https://download.pytorch.org/whl/cu130`
2. 同样改 vendor sglang 的 `pyproject.toml`（root 项目的 sources 不会传递给 transitive editable dep）
3. `uv sync` 成功装上 `torch==2.9.1+cu130` 和 `nvidia-{nccl,nvjitlink,nvshmem,cusparselt,nvtx}-cu13`
4. **但 driver 570 不支持 cu13 runtime**——`torch.cuda.is_available()=False`，CUDA init 报 `driver too old (12080)`

→ cu13 路径需要 **driver 580+**。我们没有 root + 别人在用机器，所以放弃。本分支已 rollback 到 cu12 stack（pyproject 干净）。

### 坑 4：`--disable-overlap-schedule` 不够

第一次 smoke 崩在 `resolve_future_token_ids.cuh:49`，路径是 `event_loop_overlap_disagg_prefill`，怀疑是 overlap 模式特定 JIT kernel 问题。

cli.py 给 PD worker 加了 `--disable-overlap-schedule` 后，event loop 切到 `event_loop_normal_disagg_prefill`，但**崩在另一个 kernel `fused_inplace_qknorm`**，错误码完全相同（`cudaErrorInsufficientDriver`）。

→ 不是 overlap-specific，是 **整体 vendor sglang `jit_kernel/` 模块和 driver 570 不兼容**，任何 JIT kernel 都会崩在 `runtime.cuh:21` 的 `cudaOccupancyMaxActiveBlocksPerMultiprocessor` 调用（CUDA runtime 初始化时 driver feature 版本检查失败）。

但 `--disable-overlap-schedule` 留着不会造成伤害，且能避免之后类似 overlap-path 特定问题。本分支保留它在 `cli.py:_topology_from_args`。

### 坑 5：pip sgl_kernel vs vendor sglang/jit_kernel/ 是两套系统

`pip install sglang-kernel` 提供 `.venv/lib/.../sgl_kernel/{flash_ops,flashmla_ops,spatial_ops}.abi3.so`——这是 AOT 预编译产物。

`third_party/sglang/python/sglang/jit_kernel/` 是 vendor SGLang 0.5.10 内置的 **另一套 JIT 模块**，运行时用 tvm_ffi 编译。Smoke 崩在 vendor 的 jit_kernel，**降级 pip sgl_kernel 没用**（实测 0.4.0 / 0.4.1 同样崩）。

### 坑 6：`nvidia-cuda-nvcc-cu12` PyPI 包没装 nvcc binary

发现 cu13 nvcc 是 root cause 后，第一反应是 PyPI 装 cu12 nvcc 包：

```bash
uv pip install nvidia-cuda-nvcc-cu12==12.8.93
```

装上以后 `find .venv -name nvcc` **返回空**——这个 PyPI 包只装 `ptxas` 和 `nvvm/`，**没有 nvcc binary**（NVIDIA 出于分发限制不把 nvcc 放 PyPI）。

→ 完整 nvcc 必须从 NVIDIA 官方 `.run` installer 或 apt 装。`.run` installer 可以装到 user-writable 路径不需要 root，本仓库选这条路。

### 坑 7：tvm_ffi 通过 ninja 调用 nvcc

vendor sglang 的 `jit_kernel/` 用 `tvm_ffi.cpp.extension`，源码在 `~/.local/lib/python3.12/site-packages/tvm_ffi/cpp/extension.py`。关键路径：

```python
def _find_cuda_home() -> str:
    cuda_home = os.environ.get("CUDA_HOME") or os.environ.get("CUDA_PATH")
    if cuda_home is None:
        nvcc_path = shutil.which("nvcc")
        if nvcc_path is not None:
            cuda_home = str(Path(nvcc_path).parent.parent)
    ...
```

然后构造 ninja file：
```
nvcc = {_find_cuda_home()}/bin/nvcc
```

→ **设 `CUDA_HOME=$HOME/cuda-12.8` 就能 hook 整条编译链**。`scripts/setup_env.sh` 已经设好。

JIT 编译产物缓存在 `~/.cache/tvm-ffi/sgl_kernel_jit_*/*.so`。如果之前用 cu13 nvcc 编过，要先 `rm -rf ~/.cache/tvm-ffi/sgl_kernel_jit_*` 再用 cu12.8 重编。

### 坑 8：mooncake import path 与 onboarding 文档不一致

`docs/ONBOARDING_NEXT_AGENT_ZH.md` §3.3 的环境验证写：
```python
from mooncake_transfer_engine import TransferEngine
```

但实际 PyPI `mooncake-transfer-engine 0.3.10.post2` wheel 的 import path 是：
```python
from mooncake.engine import TransferEngine
```

第一次 `from mooncake_transfer_engine` 会 `ModuleNotFoundError`。**ONBOARDING 文档应该更新**（本分支不动 onboarding，留给主 agent 决定）。

### 坑 9：mooncake.engine import 必须有 libcudart.so.12

`from mooncake.engine import TransferEngine` 在 fresh shell（未 source setup_env.sh）下报：
```
ImportError: libcudart.so.12: cannot open shared object file: No such file or directory
```

mooncake 的 `engine.so` 是 cu12 build，dynamic link `libcudart.so.12`。venv 里有但需要 LD_LIBRARY_PATH 暴露。`scripts/setup_env.sh` 已加。

### 坑 10：Inferact 数据集 schema 与 agentic-pd-hybrid 期望不匹配

`huggingface.co/datasets/Inferact/codex_swebenchpro_traces` 是 ShareGPT 格式（`{"from": "human/gpt", "value": "<text>"}`），不含 token 计数 / hash_ids / 时间戳。

`agentic-pd-hybrid` 期望 JSONL：`chat_id, parent_chat_id, timestamp, input_length, output_length, type, turn, hash_ids[]`。

→ 已写 `scripts/convert_inferact_to_trace.py`：tokenize（用 model 自带 tokenizer）+ 滚动 hash 切 24-token block + 伪造 timestamp。610 trials × 33 turns 处理约 37min，跑出 20,230 reqs（与 Inferact README 的 "20,230 total LLM calls" 完全一致）。

输出 `outputs/inferact_codex_swebenchpro.jsonl`（1.3GB，被 `.gitignore` 排除不进仓库）。

### 坑 11：sampling 默认 `--session-sample-rate 0.01`

`benchmark-live` 跑的时候内部会先做 sampling。默认 1%，意味着 50 sessions 才抽 1 个。Mini smoke trace 4 sessions × 1% = 0 → `ValueError: Sampling produced no requests`。

→ smoke test 命令显式加 `--session-sample-rate 1.0 --target-duration-s 600`。

---

## 5. 后续给下个 agent

跑 E1 / E2 sweep 之前**每个 shell 第一件事**：

```bash
cd /path/to/agentic-pd-hybrid
source scripts/setup_env.sh
```

然后用 ONBOARDING §3 的 sweep 脚本（参考 `scripts/sweep_ts1_migration_v2.sh` 作为底版）。注意几处针对本机的修改：

1. **MODEL 路径**改成 `/mnt/models/Qwen/Qwen3-30B-A3B-Instruct-2507`（onboarding 写的 `/mnt/kzlin/workflow/pd-hybrid/simm-swe-bench/models/...` 不存在）。
2. **TRACE 路径**：`outputs/qwen35-swebench-50sess.jsonl` 不存在；用 `outputs/inferact_codex_swebenchpro.jsonl` （converter 跑完后产生）。
3. **`--ib-device`** 选 `mlx5_60`（cuda:0 NUMA-local）或视实验需要自选；onboarding 写的 `mlx5_0` 在本机不存在。
4. **保留 cli.py 的 `--disable-overlap-schedule`** 不要删——理论上 cu12.8 toolchain 应该让 overlap 也能跑，但目前未验证 overlap path 没有别的潜在问题，留着是 zero-cost 保险。

---

## 附录 A：本分支的代码改动

- `pyproject.toml`：sglang dep 改用 `[tool.uv.sources]` path source 走 `third_party/sglang/python`（editable）。
- `src/agentic_pd_hybrid/cli.py:_topology_from_args`：给 prefill/decode worker 自动加 `--disable-overlap-schedule`。
- `scripts/setup_env.sh`：env wrapper，每个 shell `source` 一次。
- `scripts/convert_inferact_to_trace.py`：Inferact ShareGPT → agentic-pd-hybrid JSONL schema converter。
- `docs/H200_DRIVER570_SETUP_ZH.md`：本文档。

## 附录 B：被 `.gitignore` 排除的产物

- `outputs/inferact_codex_swebenchpro.jsonl`（1.3GB）——converter 输出，用 `scripts/convert_inferact_to_trace.py` 重新生成
- `outputs/smoke_rdma/`（含 mini trace + smoke run artifacts）
- `third_party/codex_swebenchpro_traces/`（209MB，HF dataset 下载）—— `hf download Inferact/codex_swebenchpro_traces --repo-type dataset --local-dir third_party/codex_swebenchpro_traces` 重下
- `~/cuda-12.8/`——cu12.8 toolkit，用 §1 步骤 (2) 重装
- `.venv/`——`uv sync` 重建