# 评估：把 2080Ti 那套换成 ComfyUI + Raylight，试试能不能把 4×22G 当一个显存池用

## ⚠️ 2026-08-22 更新：已扶正为生产默认后端，部分成功——832×480×64帧能用，124帧OOM

这条todo从"评估要不要做"推进到了"已经做了、接管了h3-console"。详细结果、实测数据表、
warm-reuse实测（比预想的效果差很多）、已知限制，都写进了 `raylight/README.md` 和
`raylight/notes.md`（新建的顶层workload目录，按CLAUDE.md目录约定），过程记录在
`CHANGELOG.md` 对应日期条目里，这里不重复。旧的 `minimax-h3` 转为热备份，代码权重都保留，
`start-all.sh`能秒级回滚。下面原文保留作为调研过程的历史记录。

---

**背景**：用户想知道 2K 分辨率能不能跑（`quality-tuning-plan.md` 排查画质差距的同时，也有人在问
分辨率能不能往上提）。按 `api.py` 现成的 `_rows()` 公式外推：2K×15s 需要的 rows 是现在安全上限
（`ROWS_LIMIT=20000`）的十几倍，且从已实测数据看显存需求在 rows 越过约 2 万这个区间之后是**加速
增长**（不是线性）——根因是 Turing 没有高效 attention kernel，PyTorch 静默退化到 MATH 后端，
把完整的 N×N 注意力矩阵摊在显存里。粗略外推：2K 分辨率下这批卡大概只能撑 1-2 秒，不是能用的档位。
详细推导见跟用户的对话记录（还没搬进 CHANGELOG，这个文件先占个位）。

**这不是"缺显存"能一次性解决的问题**——4 张卡合计 88G，但现在的架构（DiffSynth-Studio 的
MiniMax-H3 pipeline）**不支持把一次生成拆到多张卡上算**，四卡只能是四个独立 worker 各跑各的
（`gateway.py` 做的路由/并发，不是显存池化）。查过 DiffSynth-Studio 最新文档，H3 pipeline 里
确认零序列并行/张量并行支持，这条路走不通，是架构级的，不是配置项。

## 调研到的方案：Raylight（ComfyUI 插件）

真正做**序列并行**（把一次生成的注意力计算拆到多卡上并行算，不是简单地把不同模块分到不同卡）。
查到的关键点，都对我们有利：

- **官方支持列表明确写了 Turing 架构**（"Volta and Turing: use latest Yunchang libs"）——
  不是没测过，是真的适配过老卡这一档。
- **不需要 NVLink，走 PCIe 就行**——benchmark 里专门提过消费级卡"P2P 走 SYS 路径（无 NVLink），
  带宽降低但能用"，说的就是我们这种没有 NVLink 桥的机器。
- **支持列表里明确写了 MiniMax-H3**（USP + FSDP，CFG 暂不支持）。
- 通信走 NCCL（`nvidia-nccl-cu12==2.28.9`），Ray 管 worker 进程。

对比之下，HuggingFace `diffusers` 库那个"多GPU"文档示例是假的——只是把文本编码器和 DiT
分别扔到不同卡（组件级放置），不解决 DiT 自己在高分辨率下显存超限的问题，而且这功能现在
还有 bug（CUDA 设备不匹配没修），官方示例还是照 2×80G A100 写的，跟我们的场景不是一回事，
排除。

## 代价：这是换引擎，不是装个包

Raylight 是 **ComfyUI 的插件**，不是能塞进现在这套 `api.py`/`gateway.py`/`h3-console` 架构里的
东西。真要用意味着：

1. 整套换成 ComfyUI 做推理引擎——现在这套 FastAPI 队列+轮询的服务（`api.py`/`gateway.py`/
   `console`）得重新对接 ComfyUI 的 API，或者两套并存一段时间
2. 新依赖一整套：PyTorch 2.8.1、NCCL 2.28.9……版本跟现在这个 venv 里为 Turing 精调过的
   torch/bitsandbytes 组合不是一回事，得单独起环境，不能直接装进现有 venv（会跟 NF4 那条线
   互相踩版本）
3. 工作流从现在的"prompt+参数"变成 ComfyUI 的节点图 workflow，console 前端这套三个 tab
   的表单得重新设计怎么对接
4. Flash Attention 2 官方标"可选但推荐"——Turing 没有 FA2 支持（这条本项目已经反复实测确认过，
   见 `README.md`/`turing-bf16-attention-dead` 记忆），Raylight 在 Turing 上到底是用 Yunchang
   的哪条 fallback 路径、还吃不吃得动 MATH 后端那套，**必须先小规模实测才能确认**，不能假设
   "支持 Turing"就等于"跟现在一样快甚至更快"。

**这是一个要投入几天的独立迁移项目，不是明天顺手能试完的东西**——跟 `quality-tuning-plan.md`
里那几项（不用下载任何文件、改几个参数就能测）完全不是一个量级。

## 建议的顺序（不要跳过前面直接冲这个）

1. **先做 `quality-tuning-plan.md` 里的 1、2 两项**（分辨率提到接近原生 1344×768 但控制在
   `ROWS_LIMIT` 内、Turbo开关对比）——不用下载任何东西，不用改代码，最快出结果。如果画质问题
   主要是这两项导致的，可能根本不需要 Raylight 这条重路。
2. 参考 RTX PRO 6000 那边的 int8-convrot 实测结果（见 `h3-rtxpro6000-setup.md`）——如果换更高
   精度对画质有明显提升，说明量化精度也是真嫌疑，但那条路线（在 96GB 单卡上跑 int8）跟
   Raylight（多卡序列并行）解决的是两个不同问题（画质 vs 能跑多大分辨率/多长时长），不要混着评估。
3. 如果 1、2 都做完发现画质本来就没问题，纯粹是想要更高分辨率/更长时长——才轮到评估 Raylight。
   第一步只做**最小验证**：单独起一个隔离环境（不动现在生产用的 venv），装 ComfyUI + Raylight，
   用一个小 workflow 跑通 MiniMax-H3 最低配置（比如 448×256×8f）确认链路通，再谈要不要真迁移。

## 还没做的事

1. ~~明天到公司先确认服务器驱动/CUDA 版本~~ **2026-08-21 已确认，不挡路**：
   - 驱动 `580.173.02`，CUDA capability 到 13.0——比 NCCL 2.28.9（走 cu12 运行时）要求的
     高得多。生产 venv 里 `torch==2.9.0+cu128` 已经在这块驱动上稳定跑着，是现成的实测证据，
     不用另外验证驱动这层。RTX PRO 6000 那条线要求的驱动 ≥r580 这台也满足。
   - **新发现的风险点**：系统级 `nvcc --version` 是 **11.5**（apt 装的
     `nvidia-cuda-toolkit 11.5.1-1ubuntu1`），跟 pip 侧 torch 12.x 对不上。直接用 pip 装好的
     wheel（NCCL、torch 本身）没事，但 Raylight 依赖的 xDiT/xFuser、Yunchang（Turing 专门要
     "latest Yunchang libs"）、可选的 flash-attention 如果要现场编译 CUDA 扩展，系统这个
     11.5 会导致编译失败/ABI 不匹配。**解法**：隔离 venv 里另装 `nvidia-cuda-nvcc-cu12`
     （pip 包，12.x 版 nvcc），不要依赖系统工具链，跟 minimax-h3 venv 隔离生产环境的思路一致。
   - **新发现的风险点**：`/`（系统盘）只剩 **23G 可用**（90% 已用），`/data` 还有 243G。
     Raylight 隔离环境（torch 2.8.1 + xDiT + Yunchang 编译产物）大概率装不进 `/`，
     **必须指定装到 `/data`**。
2. 按上面「建议的顺序」，先把 `quality-tuning-plan.md` 的 1、2 两项测完再决定要不要往下推进。
3. 如果决定推进：在 `/data` 下找干净的验证环境（不要污染现在的生产 venv），装 ComfyUI +
   Raylight，pip 装 `nvidia-cuda-nvcc-cu12` 而不是用系统 nvcc，跑最小 workflow 验证链路。

## 2026-08-21（当天，续）—— 最小验证已跑通，**成功**，用户明确要求跳过前面排队直接做这项

用户当天明确表态跳过`quality-tuning-plan.md` 1、2 两项排队，直接做这个"几天量级"的验证，
所以下面是实测结果，不是推演。

**环境**：`/data/models/raylight-eval/`（隔离目录，没碰生产 venv）。`git clone` 用
`https://ghfast.top/<github地址>` 代理（这台机器直连 GitHub 不通，`ghfast.top` 实测约
5.4MB/s，贴近机器出口带宽上限）。`uv venv --python 3.11` 踩了个坑：系统 `python3.11` 实际是
**3.11.0rc1（预发布版）**，缺 `sys.get_int_max_str_digits`，torch 内部依赖这个属性，
ComfyUI 启动直接崩溃——改用 `uv python install 3.12` 让 uv 自己管理一份正式版 Python 解决。
全程没有触发任何 CUDA 扩展现场编译（跳过了可选的 FlashAttention 2），所以上面提到的系统
nvcc 11.5 版本不匹配问题这次没有真正卡住流程，但如果以后要装 FlashAttn/SageAttn 之类需要
编译的可选加速后端，那条风险仍然成立，没有被这次验证推翻。

**驱动**：验证过程中，这台机器的驱动确实还是 570.153.02（CUDA 12.8），不是本文档前一节
写的 580——那一节的结论来自另一个并发进程/时间点的检查，跟这次验证不是同一次。580.173.02
是这次验证**当场升级上去的**（详见 `CHANGELOG.md` 对应条目），因为 Raylight 官方 FL2VA
example workflow 用的 DiT/文本编码器权重是 `int8-convrot` 量化，其 `comfy-kitchen` 加载后端
硬性要求 CUDA Runtime ≥13.0、驱动 ≥r580，12.8 装不上。用户当场拍板"可以直接升"，升级流程
（发现 dpkg 记录 535 但实际装的是 .run 装的 570，先 `nvidia-uninstall` 清理旧的再
`apt install nvidia-driver-580` 走正规包管理、锁定 grub 一次性启动当前内核避免误启动一个从
没跑过的新内核）见 `CHANGELOG.md`，minimax-h3 四卡生产服务全程正常拉回，未受影响。

**权重**：用的是 Raylight 官方 example workflow 原生搭配——`minimax_h3_fl2va_pruned_int8_convrot.safetensors`
（DiT，21GB）+ `qwen3vl_32b_minimax_h3_int8_convrot.safetensors`（文本编码器，27GB，注意
**不是** example 默认写的 `nvfp4_awq` 版——nvfp4 是 Blackwell 专属格式，Turing 没有对应
Tensor Core，换成 int8-convrot 版规避这个硬件门槛）+ video/audio vae（5.8GB）。合计约 54GB，
ModelScope + aria2c 16连接下载，实测约 5.7MB/s（等于跑满出口带宽），约 2.5 小时下完，
safetensors 头校验通过、大小跟 ModelScope 元数据完全吻合，没有损坏。

**官方 example workflow 本身有个 bug**：`RayBasicGuider` 节点的 `conditioning` 输入在官方发布
的 `Minimax_H3_I2V_Raylight.json` 里根本没接线（`MiniMaxH3ImageToVideo` 的 `positive` 输出
`links` 是空数组），直接跑会在校验阶段报 `required_input_missing`。手动把这条线接上
（`133.positive → 145.conditioning`）才能跑。另外 `RayInitializer` 的 `XFuser_attention`
默认值 `TORCH_FLASH` 依赖 FlashAttention（我们没装，可选步骤跳过了），改成
`TORCH_MATH`——这也是 Turing 已知没有高效 attention kernel、必然要落到的那条路径，跟
`turing-bf16-attention-dead` 记忆里的结论一致，不是退而求其次，是唯一现实选项。

**最小验证配置**：`GPU=4, ulysses_degree=4, ring_degree=1, cfg_degree=1, FSDP=True,
XFuser_attention=TORCH_MATH, use_mmap=True, skip_comm_test=False`（NCCL 通信测试特意没跳过，
这就是要测的东西），320×320、5 帧（协议允许的最小帧数，`round(duration*24)` 再调整到
`≡5 (mod 17)` 的边界值）。**四卡显存先临时清空**（minimax-h3 四个 worker + gateway 全停，
顺带发现 GPU0 上一直挂着 `m3e`/`sd-forge` 两个"本该停着"的服务，重启后又自动起来了——像是
开机自启，**没查是谁配的，留给下一次**）。

**结果**：`status_str: "success"`，总耗时 **10分40秒**（含首次 Ray/NCCL 集群起集群、FSDP
分片、USP 初始化，不是纯推理时间——这些是一次性开销，真要评估吞吐得看第二次及以后的调用）。
产出 `MiniMax_H3_00001_.mp4`（320×320、24fps、5帧、带音轨），人工看了帧画面，
**内容清晰连贯，跟 prompt 描述对得上**（男子扔长矛+金色传送门场景），不是黑屏/噪声/NaN。
**结论：Raylight + FSDP + 4×2080Ti（Turing，无 NVLink，SYS 跨 NUMA 拓扑）这条链路是真的能跑
通的**，`XFuser_attention=TORCH_MATH` 这个"最保守兜底"选项在真实分布式场景下没有崩，官方
"Volta/Turing 用最新 Yunchang 库"这条支持声明也验证是真的，不是文档虚标。

**没测的**：这次只验证了"链路通不通"，不是画质/速度基准。10分40秒里刨除模型加载和 NCCL
初始化的一次性开销后，真实每步推理耗时、多卡并行相对单卡是否真的提速、以及跟 2080Ti 现有
NF4 pipeline 画质的对比，都还没测——如果要往下推进到"值不值得真迁移"这个决策，这些是
下一步需要补的数据。测试用完的环境（`/data/models/raylight-eval/`）保留着，没清理，
下次可以直接复用。