# dasiwa V18 工作流使用问题记录

> 记录日期：2026-09-05 ｜ 来源：22s 对口型唱歌视频多轮实测（V3/V7/V8/V12）
> 工作流：`DasiwaMinimaxH3WorkflowsT2VA_cMMH3V18.json`（API 模板 `v18_api_template.json`，节点 2730 = `DaSiWaMiniMaxH3DirectorLegacy`）

---

## 一、横纹/带状伪影（最严重问题）

### 现象
V8（V18，480×864）脸部/眼睛/额头出现横纹、带状伪影，贯穿头部；用户明确反馈后确认。

### 根因
**V18 模板的视频 VAE 是 int8 量化版**：

```
MiniMaxH3/minimax_h3_video_vae_int8_convrot.safetensors   ← V18 默认（有横纹）
minimax_h3_video_vae_fp16.safetensors                      ← 换用后消失
```

int8 量化的 VAE 在低分辨率 + 暗部/高对比过渡区域产生量化误差 → 周期性横纹。眼睛、额头等明暗交界处最明显。

### 修复
在 `build_v18_prompt()` 返回的 API 里，把 VAELoader 节点的 `vae_name` 替换为 fp16：

```python
for nid, node in api.items():
    if node.get("class_type") == "VAELoader" and "video" in str(node.get("inputs", {}).get("vae_name", "")):
        node["inputs"]["vae_name"] = "minimax_h3_video_vae_fp16.safetensors"
```

**实测**：V12（体操服任务）替换 fp16 后，主体区域无横纹。⚠️ 但浅色大面积区域（如浅色体操服）在 t=1s 仍有轻微水纹感——浅色低纹理区域的固有表现，可把 8 步提到 10-12 步缓解。

### 注意事项
- fp16 VAE 文件已在 GPU 机：`/home/zyw/ComfyUI/models/vae/minimax_h3_video_vae_fp16.safetensors`
- 只换视频 VAE；音频 VAE 保持 `minimax_h3_audio_vae_fp32.safetensors`

---

## 二、分辨率必须 32 网格对齐

### 现象
早期用 480×848（848 不是 32 的倍数）叠加 int8 VAE → 横纹更明显。

### 规则
MiniMax H3 生成分辨率要求 **32 的倍数**（官方 gen_timeline 源码明确 "multiples of 32"）：

| 分辨率 | 校验 | 用途 |
|---|---|---|
| 736×1280 | 736/32=23 ✓ 1280/32=40 ✓ | V18 默认（约 0.94MP） |
| 544×960 | 544/32=17 ✓ 960/32=30 ✓ | **0.52MP 9:16 竖屏**（体操服任务用） |
| 480×864 | 480/32=15 ✓ 864/32=27 ✓ | 低分辨率快速测试（但偏低） |
| 480×848 ❌ | 848/32=26.5 ✗ | 不要用 |

---

## 三、输出时长与帧数对齐（17k+5 网格）

### 现象
设置 11s，V18 实际输出 **11.55s**（不是 11.0s）；12s 输出 12.25s。

### 原因（v18_pipeline 源码）
H3 的帧数必须对齐 `17k+5` 网格（frame_align.py: `minimax_align_frame_count`）：
- 11s × 24fps = 264 帧 → 对齐到 **277 帧 = 11.54s**
- 12s × 24fps = 288 帧 → 对齐到 **294 帧 = 12.25s**

### 影响
- 两段拼接时实际总长 ≠ 设定总长（如 11.55 + 11.55 = 23.1s，需 concat 后 `-t 22` 截断）
- 音频参考 trim 段与输出段时长有轻微错位（11.54s 视频 vs 11s 音频参考），对口型在段尾可能细微偏移

---

## 四、音频参考（media_mode=audio）注意事项

### 已确认可行
- V18 Director 的 timeline items 支持 `type:"video", media_mode:"audio"` —— 只提取内嵌音轨，画面帧不用，正是 audio-only 模式的实现
- trim_start/trim_end 切分参考音频段

### 已知坑
1. **切分点必须落在乐句间隙，不能切在强音符上**：
   - 10s 处（RMS 能量 5618，强音符）切分 → 参考音频"唱到一半戛然而止" → 模型后半段自编音乐
   - 11s 处（RMS 1903，乐句间隙）切分 → 参考完整收尾 → 模型稳定跟随
   - 决定前先用能量分析（0.25s 窗口 RMS）确认切分点
2. **提示词音频语义**：`<Audio 1>: fully_copy` + "every syllable matched, no drift" 必须保留；official Director 的提示词与 V18 可共用

---

## 五、与官方 Director 的注册冲突（重要）

GPU 机同时装了两个包，**都注册 `MiniMaxH3Director`**：

| 包 | 注册名 | 指向实现 |
|---|---|---|
| `ComfyUI-DaSiWa-Nodes` | `MiniMaxH3Director` + `DaSiWaMiniMaxH3DirectorLegacy` | DaSiWa 227 行版（V18 用） |
| `ComfyUI_MiniMaxH3_Director` | `MiniMaxH3Director` + `ComfyMiniMaxH3Director` | 官方 291 行多段版 |

- 同名 `MiniMaxH3Director` 被后加载包覆盖；**V18 模板用 `DaSiWaMiniMaxH3DirectorLegacy` 显式锚定 DaSiWa 版**
- API 检索 Director 节点时用 `class_type == "DaSiWaMiniMaxH3DirectorLegacy"`（V18）或 `"MiniMaxH3Director"`（官方版），不要混用

---

## 六、表达式/表情锁控弱于官方版

### 现象
V12（V18，8 步）眼波流转忧伤时有时无（t=8s 达标，t=1/5/12/16s 退化平静微笑/惊讶）；V10/V11（官方版 25 步）表情更稳定。

### 原因
8 步加速（`STEPS=8`）比官方 25 步激进，表情细节保真度下降。

### 对策
- 表情是重点时：提到 10-12 步，或接受轻微退化
- 提示词强化表情动作（如 "eyes welling with unshed tears"），弱化形容词堆砌

---

## 七、脚本/调用层面的坑

1. **维数匹配**：调解 736×1280/544×960 时，`build_v18_prompt` 的 width/height 参数要同时影响 Director 节点与 RTX 放大节点（RTX 关闭时无影响）
2. **timeline items 顺序**：图片先行（slot 0,1…），video/audio 在后；`validate_reference_limits` 要求"有音频必须有图/视频伴随"
3. **timeline v1 vs v4 不通用**：V18 用 `{"version":1,"items":[...]}`，官方版用 v4（segments/refAudios/continuity）——**两者 timeline 格式完全不同，不能互换**；V9 曾因官方版改 global 模式导致 ref_audios=0（音频参考没加载）自编音乐
4. **上传后本地路径替换**：media items 必须先 `_upload_file_to_comfy` 拿到远程文件名再填 `value`，否则 KeyError（V12 踩过）

---

## 八、性能参考

| 工作流 | 11s 段耗时 | 22s（两段+拼接） |
|---|---|---|
| dasiwa V18（8 步，fp16 VAE） | ~5-10 分钟 | **~20 分钟** |
| 官方多段 Director（25 步） | ~30-40 分钟 | **~78-85 分钟** |

V18 快 4 倍以上，代价是表情/细节略弱；横纹问题用 fp16 VAE 后基本解决。

---

## 附：推荐调用配置（V12 验证通过）

```python
W, H = 544, 960          # 0.52MP 9:16（或 736×1280 V18 默认）
STEPS = 8                # 快；表情优先时 10-12
FP16_VAE = "minimax_h3_video_vae_fp16.safetensors"   # 必换，防横纹
# 音频参考：media_mode="audio"，trim 落在乐句间隙（如 0-11 / 11-22）
# 提示词：保留 <Audio 1>: fully_copy + LIPSYNC 强同步描述
# 拼接：concat 后 -t 22 截断（V18 每段 11.54s，总长会超 22s）
```