# 画质改进方案：为什么我们的视频比 ComfyUI 文档演示的差很多

**背景**：对照 https://docs.comfy.org/zh/tutorials/video/minimax/minimax-h3 （官方 ComfyUI
工作流文档）跟我们现在的 `api.py`/`t2va.py`/console 默认参数，找出的差距，按影响力排序。
都还没动手实测，需要真实 GPU，明天回服务器再做。

## 1. 分辨率——大概率是最大的差距

H3 原生分辨率是 1344×768（短边 768px）。我们线上默认 **832×480**，只有原生像素量的约 40%。
真实上限被 `api.py` 的 `ROWS_LIMIT=20000`（帧数×宽×高的显存安全线）卡死——这是 Turing 显卡
fp32-only（无高效 bf16/fp16 attention）导致的显存代价，不是随手设的参数。

**要做的实测**：在服务器上直接跑一次接近原生的分辨率（比如 1344×768，短时长/低帧数控制
rows 不超限），跟现在的 832×480 默认档同 prompt/seed 对比，看画质差距有多大、显存/耗时代价
多大。`ROWS_LIMIT` 支持 `H3_ROWS_LIMIT` 环境变量临时覆盖，不用改代码就能测。

## 2. Turbo 4 步 vs 关闭 Turbo 跑 20+ 步——现成的开关，从没系统测过

文档里 T2V/I2V 用的是 8 步蒸馏 LoRA，我们下载的两个 LoRA 文件名都写死是 `turbo_4step`
（`fl2va`/`ref2va` 各一个）。不用换文件就能验证的路径：console 早就支持关掉 Turbo、跑 20/50
步全精度（`turbo=false`），但**默认值是"Turbo 开/4步"**（为了速度），从没系统对比过画质。

**要做的实测**：同 prompt/seed，Turbo 开(4步) vs 关(20步) 各跑一条，对比帧间差异/音频响度/
肉眼观感。之前在纯文生视频上测过一次类似的（结论是步数越多帧间差异越小、音质越好，见
`CHANGELOG.md` 「15 秒时长实测」一节），但没有在现在的默认分辨率/R2V 场景下重新验证过。

## 3. CFG scale / negative prompt——完全没调过

pipeline 本身支持 `cfg_scale`（默认 1.0，等于没有 CFG 引导）和 `negative_prompt`（默认空
字符串），我们的 `api.py`/`t2va.py` 从来没传过这两个参数，一直骑着默认值裸跑。ComfyUI 文档
没有明确给出推荐值（蒸馏模型常见把 guidance 焙进 LoRA 里，不一定需要开 CFG），这是一个完全
没做过 A/B 的空白。

**要做的实测**：先确认默认值是不是真的最优——`cfg_scale` 调到 2-3 试试是否画质提升，同时看
是否会因为蒸馏 LoRA 的缘故反而变差（过度引导在蒸馏模型上有时会出伪影）。`negative_prompt`
可以先加几个常见负面词（模糊、抖动、变形）试试。

## 4. audio_flow_shift——同样裸跑默认值

`audio_flow_shift` 默认 3.0，从没被覆盖过，音频质量没调过。跟 `flow_shift`（视频的）性质
类似，值得跟着上面的实测一起做个粗调。

## 5. 8 步 Turbo LoRA——需要下载新文件，不是参数调整

文档里 T2V/I2V 用的是 8 步蒸馏 LoRA，我们只有 4 步版。如果第 2 项（关 Turbo 跑 20+ 步）验证
画质确实好很多、但耗时代价太高，可以考虑换一个 8 步版 LoRA 做折中——**这个需要先找到/下载
对应的模型文件，不是改个参数就行**，工作量和网络下载时间都要单独评估（服务器出口带宽约
5.9MB/s，见顶层 `CLAUDE.md`「硬件的三条硬限制」）。

## 建议的实测顺序

1 和 2 不需要下载任何新文件、不需要改代码，最快能出结果，优先做。3、4 需要小改 `api.py`
把这两个参数串上（目前完全没有入口）。5 最后再看要不要投入。