# 画质改进方案：为什么我们的视频比 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）导致的显存代价，不是随手设的参数。

**2026-08-21 已实测**：ref2va 分区，同 prompt/seed=42，`0f22388f7847`（1344×768×64帧，
峰值显存 15.49GB）vs `06bb43196c46`（832×480×124帧，峰值显存 11.47GB，其余参数相同）——
**原生分辨率肉眼明显更好**。但不是没问题：三条对比测试（含下面第 2 项那条）肉眼看**都还有
瑕疵**——画面模糊/细节糊、运镜或动作的抖动/拖影、人物五官变形，原生分辨率只是相对最好。
判断是口头目测，没有做客观指标也没有逐帧截图定位具体哪几秒出问题。详见
`CHANGELOG.md` 2026-08-21（下午）一节。

**还没做的**：默认分辨率之外的中间档（比如 1024×576）没试过；原生分辨率因为
`ROWS_LIMIT` 只能压到 64 帧（2.7秒），跟 832×480 能跑到 124 帧（5.2秒）不是等时长对比，
时长本身对观感的影响还没拆开看。

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

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

**2026-08-21 已实测（结论跟之前的纯 T2V 结论相反）**：ref2va 分区，同 832×480×124帧/
prompt/seed=42，`06bb43196c46`（Turbo开/4步，峰值显存 11.47GB）vs `807e042dce0d`
（Turbo关/20步，峰值显存 9.56GB）——**Turbo开/4步肉眼反而更好**。之前在纯文生视频上测过
一次类似的（结论是步数越多帧间差异越小、音质越好，见 `CHANGELOG.md` 「15 秒时长实测」
一节）这次在 ref2va 场景下**没有复现**，说明这条不是通用结论，是分区相关的（T2V vs
ref2va，或者还有别的没控制住的变量），**每个分区要分别测，不能只测一次就定档**。

## 3. CFG scale / negative prompt——入口已经加上了，还没做过 A/B

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

**2026-08-20 已完成**：`api.py` 的 `GenReq` 加了 `cfg_scale`/`negative_prompt`（都是
`Optional`，留空=不覆盖，行为跟以前一样），console 三个 tab 都加了对应的"高级参数"输入框
（本地浏览器验证过渲染/交互没问题，没有真机测过生成效果）。**要做的实测**没变：先确认默认值
是不是真的最优——`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`「硬件的三条硬限制」）。

**2026-08-21 更新**：这一项的前提被第 2 项的实测推翻了——ref2va 场景下 Turbo开/4步肉眼
反而比关闭 Turbo 跑 20 步更好，且更快、显存更省。**没有理由再为了"画质换速度"去下载 8 步
LoRA**，除非以后测别的分区/场景发现关 Turbo 明显更好，才重新评估。暂时搁置。

## 建议的实测顺序

**2026-08-21 更新**：1、2 两项已在 ref2va 分区跑过一轮实测（结论见上面对应小节），但三条
测试肉眼看都还有瑕疵（模糊、抖动/拖影、五官变形），说明光调分辨率/Turbo 不够，**接下来
应该做 3**（cfg_scale/negative_prompt，入口已经加上，直接在 console 填参数测，看能不能
压住这些瑕疵）。4 需要小改 `api.py` 把 `audio_flow_shift` 串上（目前还没有入口）。5 已经
搁置（见上面）。另外 1、2 的实测目前只在 ref2va 一个分区做过，fl2va/纯 T2V 是否同样结论
还没验证，也没有拆开看是"分辨率"还是"帧数/时长"在起作用。