# MiniMax H3（海螺 AI 3.0）加速部署调研与实测报告

> 主题：社区开发者 **dasiwa（大师娃，GitHub: darksidewalker）** 发布的 MiniMax H3 加速更新调研与 GPU 机（192.168.31.25）部署验证。
> 目标：把 0.4MP × 10s 的视频生成时间压缩到 2 分钟量级。
> 日期：2026-08-29 ｜ 状态：已部署并实测

---

## 一、背景与结论速览

- **MiniMax H3（Hailuo AI 3.0）** 是 MiniMax 开源的原生多模态 2K 视频生成大模型，支持 视频+同步音频 联合生成（T2VA / I2VA / Ref2VA），已在 ComfyUI 0.32+ 中**原生支持**（非独立插件）。
- **dasiwa（darksidewalker）** 发布的更新核心是三个 H3 加速/编排节点（并入 `ComfyUI-DaSiWa-Nodes` 节点包）：
  1. **MiniMax H3 Cache** —— 整块残差缓存（whole-block-stack residual cache），采样中相似特征步直接复用整条 transformer 块堆栈的残差，跳过块计算；社区实测 500s+ → 200s+。
  2. **Patch Comfy Kitchen Attention** —— 把该模型的注意力后端切换为 ComfyUI 内置 **INT8 注意力**。
  3. **MiniMax H3 Director** —— 时间轴式视频创作 UI（配合官方原生 H3 节点）。
- 本文档记录了：技术原理、所需模型文件、GPU 机部署过程、实测数据、以及后续使用建议。

---

## 二、技术材料来源（社区与官方）

| 来源 | 链接 | 说明 |
|---|---|---|
| dasiwa 节点包仓库 | https://github.com/darksidewalker/ComfyUI-DaSiWa-Nodes | H3 Cache / Kitchen Attention / Director |
| H3 Cache 文档 | https://github.com/darksidewalker/ComfyUI-DaSiWa-Nodes/blob/main/docs/minimax_h3_cache.md | 算法、参数、兼容性 |
| H3 Director 文档 | https://github.com/darksidewalker/ComfyUI-DaSiWa-Nodes/blob/main/docs/minimax_h3_director.md | UI 使用手册 |
| 缓存算法上游 | https://github.com/lihaoyun6/ComfyUI-MiniMaxH3-Cache | dasiwa 缓存算法来源（GPL-3.0） |
| 官方模型转制包 | https://huggingface.co/Comfy-Org/MiniMax-H3 | ComfyUI 各量化档模型 |
| 官方原始权重 | https://huggingface.co/MiniMaxAI/MiniMax-H3 | MiniMax 官方仓库 |
| 官方 ComfyUI 文档 | https://docs.comfy.org/tutorials/video/minimax/minimax-h3 | 官方教程 |
| 官方工作流模板 | https://github.com/Comfy-Org/workflow_templates | t2v / i2v / r2v |
| 社区整合包介绍 | https://www.zxcyw.com/ai-vloggers/walk-with-ai/17541.html | turbo LoRA 4/8/20 步 + 放大 |
| 社区视频演示 | https://www.bilibili.com/video/BV16mug6WEEs/ | “首个 H3 加速插件 500s+→200s+” |

---

## 三、加速原理

### 3.1 MiniMax H3 Cache（dasiwa / lihaoyun6 同源算法）
- 位置：`MODEL` 路径上、guider/sampler 之前。
- 机制：完整 H3 transformer 块堆栈的**残差缓存**。采样时对音视频 token 特征签名做**相对 L1 距离**采样；当签名变化足够小时，**直接复用整块堆栈的残差**，跳过该步全部块计算（包括注意力）。
- 关键参数（默认值）：
  - `reuse_threshold` 0.05 —— 允许的最大累计相对 L1 变化；越大跳过越多、越快，保真度略降。
  - `start_percent` / `end_percent` 0.15 / 0.90 —— sigma 调度中允许复用的区间。
  - `max_steps` 2 —— 连续命中缓存的上限（防止质量漂移）。
  - `device` auto —— 缓存残差存放设备（auto/cuda/cpu，显存不足自动落 CPU）。
- 兼容性：仅作用于克隆的 MiniMax H3 `MODEL`，不全局 patch；可与 Comfy Kitchen Attention、turbo LoRA 等链式组合。

### 3.2 Patch Comfy Kitchen Attention
- 把该模型的优化注意力后端切换为 ComfyUI 内置的 **INT8 注意力**（`comfy_kitchen_int8`），降低注意力计算量与显存；不可用时自动回退默认注意力。

### 3.3 组合拳（本机实测配置）
`UNETLoader(w4a8) → LoraLoaderModelOnly(turbo 8step) → MiniMaxH3Cache → PatchComfyKitchenAttention → Guider/Sampler`

---

## 四、模型文件清单（Comfy-Org/MiniMax-H3）

存放路径均为 `ComfyUI/models/` 下对应子目录。

| 文件 | 大小 | 说明 |
|---|---|---|
| `diffusion_models/minimax_h3_fl2va_pruned_w4a8_mixed.safetensors` | 12.5 GB | 主模型 FL2VA，w4a8 混合量化（本机选用，最省显存） |
| `diffusion_models/minimax_h3_fl2va_pruned_int8_convrot.safetensors` | 21.0 GB | 主模型 int8 档（官方推荐，需 cu130） |
| `diffusion_models/minimax_h3_ref2va_pruned_w4a8_mixed.safetensors` | 11.8 GB | Ref2VA 参考视频模式 w4a8 |
| `text_encoders/qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors` | 15.7 GB | 32B 文本编码器 nvfp4（不要求 Blackwell） |
| `text_encoders/qwen3vl_32b_minimax_h3_int8_convrot.safetensors` | 27.1 GB | 32B 文本编码器 int8 |
| `vae/minimax_h3_video_vae_int8_convrot.safetensors` | 3.2 GB | 视频 VAE int8 |
| `vae/minimax_h3_video_vae_fp16.safetensors` | 5.2 GB | 视频 VAE fp16 |
| `vae/minimax_h3_audio_vae_fp32.safetensors` | 0.6 GB | 音频 VAE |
| `loras/minimax/minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors` | 2.0 GB | turbo 8 步 LoRA（平衡档） |
| `loras/minimax_h3_fl2v_turbo_4step_v1.0_768p_comfyui_bf16.safetensors` | 2.0 GB | turbo 4 步 LoRA（最快档） |

> 注：GPU 机（192.168.31.25）上列模型文件**均已存在**（此前会话已下载），本次无需重复下载。

---

## 五、部署过程（GPU 机 192.168.31.25）

环境：ComfyUI **0.32.0**（git bd34f338）+ torch **2.11.0+cu130** + RTX 5060 Ti 16GB + 32GB RAM。

1. **安装 dasiwa 节点包**
   - 在 DSH 机经代理下载 `darksidewalker/ComfyUI-DaSiWa-Nodes` main 分支（1.9MB），scp 到 GPU 机 `custom_nodes/ComfyUI-DaSiWa-Nodes`。
   - 依赖（torch/av/Pillow/numpy/transformers/accelerate/huggingface_hub/psutil/imageio-ffmpeg）GPU 机均已具备；`nvidia-vfx` 为 RTX 节点可选项、惰性导入，缺失不影响加载。
2. **重启 ComfyUI**（v6 启动脚本，`kill` 旧进程后 `bash /home/zyw/start_comfyui_v6.sh`）
   - 日志确认：`[DaSiWa Nodes] Loaded 22 ... nodes`，`Import times: 0.1s: ComfyUI-DaSiWa-Nodes`
   - `/object_info` 确认注册：`MiniMaxH3Cache`、`PathchComfyKitchenAttentionDaSiWa`、`MiniMaxH3Director`、`MiniMaxH3DirectorGuide` 等。
3. **节点重名说明**：本机已有 `ComfyUI_MiniMaxH3_Director`（AiMixer 分支，注册 `MiniMaxH3Director`/`MiniMaxH3DirectorRefine` 等）。dasiwa 包同时注册 `MiniMaxH3Director`，仅此一名重名，ComfyUI 按加载序处理，未影响启动；Cache 与 Kitchen Attention 节点名唯一，正常使用。既有 Director 工作流不受影响。
4. **测试工作流**：`h3_t2v_cache_workflow.json`（已上传 GPU 机 `user/default/workflows/`）
   - 640×640（0.41 MP，32 对齐）× 243 帧（10.1s @24fps）T2V
   - 8 步 `simple`/`res_multistep` + turbo 8step LoRA + H3 Cache + Kitchen INT8 attention
   - API 提交：`POST /prompt`（prompt_id a13fa35e-…）

---

## 六、实测结果（RTX 5060 Ti 16GB / 32GB RAM）

测试条件：T2V 640×640（0.41 MP，32 对齐）× 243 帧（10.13s @24fps）＋ 原生音频，
w4a8 主模型 + nvfp4 文本编码器 + int8 视频 VAE + fp32 音频 VAE + turbo LoRA，
ComfyUI 0.32.0（torch 2.11.0+cu130，v6 启动参数），API 提交。

| # | 配置 | 步数 | 缓存命中 | 端到端耗时 | 说明 |
|---|---|---|---|---|---|
| 1 | 默认缓存 + 冷启动 | 8 | 2/8（1.33x） | 237.6 s | 含 ~50s 模型冷加载 |
| 2 | **基线（无缓存）** | 8 | — | **182.3 s** | 对照基准 |
| 3 | 激进缓存(阈值0.10) | 8 | 0/8 | 182.3 s | 命中率与种子/轨迹相关，非越高越好 |
| 4 | **默认缓存(0.05)** | 8 | 2/8（1.33x） | **146.1 s（~2.4 分钟）** | 相比基线省 ~36s |
| 5 | **4步 turbo + 默认缓存** | 4 | 1/4（1.33x） | **88.8 s（~1.5 分钟）✅** | **达成 ≤2 分钟目标** |

### 结论
- **dasiwa 缓存节点真实有效**：命中时每跳一步省约 20s 采样（整块块堆栈完全跳过），
  8 步默认缓存（146s）比无缓存基线（182s）快约 20%，采样部分快约 25%。
- **命中率有波动**：与随机种子/去噪轨迹相关，本机实测 8 步下命中 2/8 或 0/8 不等；
  `reuse_threshold` 调高（0.10）并不保证更多命中（第 3 轮 0 命中），建议保持默认 0.05 并多做种子对比。
- **达成“2 分钟”的关键组合 = 4 步 turbo LoRA + dasiwa 缓存**：88.8s（~1.5 分钟）。
  若追求画质，8 步默认缓存为 146s，同样接近 2 分钟。
- **冷启动是主要固定开销**：模型加载约 20~50s（ComfyUI `--cache-lru 20` 会把模型驻留 RAM，
  warm 后加载约 20s）；连续生成时基本可忽略。
- **踩坑提醒**：同一种子、仅改缓存参数重跑时，ComfyUI 执行缓存会复用采样结果（实测 2.88s“假完成”）。
  每轮对比请更换随机种子（或重启 ComfyUI），否则结果无效。

### 运行日志关键行（实测摘录）
```
[DaSiWa Patch Comfy Kitchen Attention] Using Comfy Kitchen INT8 attention.
[INFO] Model MiniMaxH3 prepared ... 11956MB Staged. 208 patches attached.
[DaSiWa MiniMax H3 Cache] step 2: reuse block-stack residual.
[DaSiWa MiniMax H3 Cache] skipped 2/8 block-stack runs (1.33x theoretical speedup).
[INFO] Prompt executed in 146.12 seconds
[INFO] Prompt executed in 88.77 seconds
```

---

## 七、使用建议

- **档位选择**（速度 → 画质）：
  - 最快：turbo 4step LoRA（768p 版）+ 8~10 步 → 适合验证提示词；
  - 均衡（推荐日常）：turbo 8step LoRA + 8 步；
  - 极致：不用 LoRA，原生 20 步。
- **分辨率**：先小后大。0.4MP 级验证速度，定稿再升 0.7MP / 2K（放大）。
- **显存**：16GB 卡建议 w4a8 主模型 + nvfp4 文本编码器 + int8 视频 VAE（均已在机）。
- **缓存参数**：`reuse_threshold` 默认 0.05；追求速度可微调至 0.1，注意音频连续性与动作稳定性比对。
- **离线网络**：GPU 机无法直连 HuggingFace，模型下载走 `hf-mirror.com`（已验证 200），GitHub 走 ghfast.top 镜像。
- **GPU 掉总线坑**：勿用 `--disable-pinned-memory`（v5 已废弃，见运维记录），使用 v6 启动脚本。

---

## 附：相关文件
- 本报告：`~/Downloads/dl-hub/19-MiniMaxH3-dasiwa加速/`
- 测试工作流：GPU 机 `~/ComfyUI/user/default/workflows/h3_t2v_cache_workflow.json`
- 节点包：GPU 机 `~/ComfyUI/custom_nodes/ComfyUI-DaSiWa-Nodes`

---

## 八、T8mars TwoPass 二阶段工作流部署（2026-08-29 追加）

应需求"0.4MP 出片保存 latent → 核验 → 二采"，安装社区 **T8mars/comfyui-minimax-h3-audio-T8**（学习型 latent 放大 + 二阶段生成）。

### 已部署
- **节点包**：GPU 机 `~/ComfyUI/custom_nodes/ComfyUI-MinimaxH3AudioT8`（零额外 pip 依赖，ComfyUI 0.32 加载 0.5s，核心节点已注册）
- **工作流 6 个**（`~/ComfyUI/user/default/workflows/`，已修正 UNET 为机上 pruned int8、LoRA 为 alpha8）：
  - `2026-08-21_H3_Learned_Latent_TwoPass_I2VA_Standard_Advanced_EXP.json`（标准 I2VA 二采，4+4 步）
  - `2026-08-21_H3_Learned_Latent_TwoPass_I2VA_Native_Speech_Advanced_EXP.json`（无源音频基线）
  - `2026-08-21_H3_Learned_Latent_TwoPass_Hybrid_Lock_Source_Advanced_EXP.json`（锁源清晰语音）
  - `2026-08-21_H3_Learned_Latent_TwoPass_Hybrid_Remix_Source_020_Advanced_EXP.json`（源节奏重混 0.20）
  - `2026-08-21_H3_Learned_Latent_TwoPass_Hybrid_Reference_Only_Advanced_EXP.json`（源音频仅作参考）
  - `2026-08-16_H3_Latent_Upscale_By32.json`（普通 32 整除 latent 放大辅助）
- **模型**（hf-mirror 下载中/已就绪）：
  - `models/latent_upscale_models/minimax_h3_latent_upscaler_3d_fp16.safetensors`（0.69GB，SHA-256 固定 `043E5A48…`）
  - `models/loras/minimax_h3_fl2v_turbo_4step_v0.1_comfyui_alpha8.safetensors`（1.96GB，PEFT alpha 修正版）
- **节点改名适配**：工作流中 `MiniMaxH3DualClockSamplerT8Advanced` 已对应新版注册名 `MiniMaxH3DualClockSamplerT8`（无需改动，现名已注册）。

### 二采机制（作者说明）
- 第一阶段：低分辨率（如 736×416）4 步出干净联合 AV latent（第一采样器必须用 `denoised_output` 接放大节点）；
- 学习型 3D 放大：只放大视频 latent，音频 latent 保持 H3 原值（`minimax_h3_latent_upscaler_3d_fp16`，最大 4x）；
- 第二阶段：高分辨率画布 4 步继续联合音画去噪（shift 12/3，高分 sigma 0.9035/0.8/0.6316/0.3158/0），输出 1472×832 等。
- 16GB 实测参考：作者 RTX 4060 Ti 16GB 全程约 1572s（DynamicVRAM 换页为主）；本机 RTX 5060 Ti 16GB 预计同量级。
- ⚠️ 注意：量化底模须配 alpha8 LoRA（普通 `_comfyui` 文件会把 LoRA 更新放大 ~16 倍导致画面融化）。

---

## 九、MythicAlchemy 为什么 500s + 加速方案（2026-08-29 实测补充）

### 现象
用户在 GPU 机跑 dasiwa 官方 MythicAlchemy C-MMH3-16（5 秒素材）实测 **521 秒**，感觉"没有速度改善"。

### 原因（重要）
MythicAlchemy 是 dasiwa 的**满配质量参考流**，默认配置不包含任何加速手段：
- **25 步原生采样**（Settings 面板 Steps 默认 25，无 turbo LoRA → 每步 ~20s 全量前向）
- 未挂 **MiniMaxH3Cache** 残差缓存节点
- 未挂 **Patch Comfy Kitchen Attention**（INT8 注意力）
- 主模型为 int8（21GB，16GB 卡需 offload）

→ 25 步 × ~20s ≈ 500s，属正常预期，不是故障。

### 实测对比（本机 RTX 5060 Ti 16GB）
| 配置 | 素材 | 采样步数 | 采样耗时 | 端到端 |
|---|---|---|---|---|
| MythicAlchemy 原版（25 步原生） | 5s | 25 | ~450s | **521.4s** |
| **扁平加速流**（w4a8+8步turbo+Cache+INT8注意力） | 5s@0.41MP | 8 | **52s**（命中2/8） | **227.8s**（含67s模型冷加载） |
| 扁平加速流（历史实测） | 10s@0.41MP | 8 | ~120s（命中2/8） | 146.1s |
| 扁平加速流（历史实测，4步turbo） | 10s@0.41MP | 4 | ~60s | 88.8s |

### 加速版工作流
已生成 `DaSiWa MiniMaxH3 MythicAlchemy C-MMH3-16 加速版.json`（同 UI）：
- Settings 面板 Steps：25 → **8**
- Advanced LoRA Loader 槽位 0 挂 **turbo 8 步 LoRA**（`minimax/minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors`）
- 保持 Director UI 不变；缓存/注意力节点未动（避免破坏子图环路，如需要可另做）

### 提速建议（按收益排序）
1. **步数 25→8 + turbo 8 步 LoRA**：采样 450s→约 100-120s（加速版已配好）
2. **换 4 步 turbo LoRA + 4 步**：采样再减半（约 50-60s），验证提示词用
3. **开 MemCache / SageAttention**（Settings 面板开关）：模型驻留减少重复加载（本机实测冷加载 67s vs warm 20s）
4. 想更激进可自行在模型环路上插 `MiniMaxH3Cache` + `Patch Comfy Kitchen Attention`（参考本报告第六节实测）
5. 换 w4a8 主模型（12.5GB）比 int8（21GB）offload 更轻

### 结论
dasiwa 缓存节点有效但**命中率有限**（实测 8 步命中 2/8，理论 1.33x）；"2 分钟"目标的关键是 **turbo LoRA 少步数**（8→4 步），缓存与 INT8 注意力锦上添花。16GB 卡上 H3 的固定开销（模型加载+VAE 编解码）约 60-90s，素材越小占比越大。

---

## 十、DaSiWa Hybrid 8Turbo 融合模型部署（2026-08-30）

### 背景
社区/云镜像（compshare 260GB 镜像）主打的"DaSiWa MiniMax H3 融合模型"，原始出处是 **dasiwa 本人在 Civitai 发布的 DaSiWa MiniMax H3 Hybrid 系列**（Hybrid v1 / 8Turbo v1 / 4Turbo v1，536 条 Overwhelmingly Positive 评价）。本质 = REF2VA pruned 基础 + turbo LoRA 熔进单个 checkpoint，8 步直接跑、免挂 LoRA。

### 获取
- Civitai 官方下载需登录认证；HF 上仅两个不完整搬运（frauleinpiss 的 34GB bf16 基础版、t8star 的 0.79GB 4步兼容 LoRA）。
- 已用用户 Civitai API Token 获取官方 int8 8Turbo 直链（Cloudflare R2 签名 URL），GPU 机 8 路并行直连下载（单连接 ~0.6MB/s，并行后 ~3.6MB/s，19.53GB 约 1-1.5h）。
- 文件：`models/diffusion_models/DasiwaMinimaxH3_dasiwaHybrid8turboV1.safetensors`
- 校验：实测 SHA256 = `cf0ac7da9750f7e31af70e18f2c514a6bbf62bd0c34e8a98de5a868cf64a96f2`（19.53GiB，8 块并行拼接后校验）
- 身份确认：文件内部 `modelspec.title` = `..._8turbo_int8_row-wise_convrot_runtime_mixed`，`quantization.bits: BF16 merged`，日期 2026-08-28；Civitai API 文档 SHA（E0441D26）与实际交付不一致，属重新量化构建，已以文件内 modelspec 为准确认 8Turbo 身份

### 搭配工作流（官方原版，2026-08-30 修正）
按用户要求改用**模型提供方官方工作流**（不再自改 JSON）：
- **`DasiwaMinimaxH3WorkflowsT2VA_cMMH3V18.json`**（Civitai "DaSiWa MiniMax H3 Workflows" 模型页 v1.8，SHA256 `5ebbc15a…` 与档案一致）已放 workflow 目录 + 下载中心
- 官方 v1.8 默认配置即针对 8Turbo hybrid：**euler/simple、8 步、shift 12/3**，FL2VA 与 REF2VA 两个 UNET 槽位均指向 `MiniMaxH3/dasiwa_minimax_h3_ref2va_v1_pruned_hybrid_bf16_m_8turbo_int8_row-wise_convrot_runtime_mixed.safetensors`
- 文本编码器：`qwen3vl_32b_minimax_h3_int4_convrot.safetensors`（int4，Abiray/MiniMax-H3-GGUF，14.95GB，已下载）；视频 VAE int8 convrot + 音频 VAE fp32；latent upscaler bf16
- 模型路径适配：hybrid 已硬链接到 `models/diffusion_models/MiniMaxH3/` 官方名；int8 视频 VAE 硬链接进 `models/vae/MiniMaxH3/`
- AnimeSharp 放大节点官方默认 bypass；taeh3 预览（10MB）已下载
- 此前自制的 Hybrid8Turbo版/加速版变体已按用户要求移除

### 提示
- ⚠️ Civitai API Token 使用完毕后请到 civitai.com Account Settings → API Keys **Revoke**。
- hybrid 为 int8（19.5GB），显存画像与 ref2va int8 相同；REF2VA 高分辨率仍要注意 OOM（参考第九节：降时长/换 w4a8）。

### int4 文本编码器最终落地（2026-08-31 凌晨）
- 文件：`models/text_encoders/qwen3vl_32b_minimax_h3_int4_convrot.safetensors`（14,952,506,709 字节）
- **哈希三方一致**：官方 HF LFS = 迅雷源文件 = GPU 机最终文件 = `21fd2e2f06bc4fc422c6aa20893fe189edbbd9ab3068215f96e7a6cf2f6cb5bb`
- 传输路径：hf-mirror 直连被限流 → 迅雷多线程下到 DSH → 5G 信道 sshpass scp 直传 GPU 机（~16MB/s，全程约 18 分钟）
- ⚠️ 教训：**aria2c 16 线程 FTP 分片在 5G 不稳链路下会产生静默内容损坏**（大小对、哈希错），最后用单流 scp 一次成功；大文件跨机传输优先 scp/rsync 而非多线程分片
- 至此官方 v1.8 工作流全部依赖就绪：8Turbo hybrid（MiniMaxH3/ 子目录硬链接）+ int4 TE + int8/fp16 视频 VAE + fp32 音频 VAE + taeh3 + latent upscaler bf16

### 8Turbo 文件损坏实锤与重下（2026-08-31）
- **问题**：官方 v1.8 工作流加载 8Turbo hybrid 报 `ValueError: buffer length must be a multiple of element size (2)`——之前 R2 并行分块下载的文件**静默损坏**（哈希 cf0ac7da ≠ 官方 E0441D26，当时误判为"重新量化版"）
- **重下**：经迅雷（Web UI 手动任务）重新下载完整 21GB，**哈希 `e0441d26…` 与 Civitai API 文档完全一致** ✅（文件 20,967,642,441 字节）
- **传输**：5G 信道 sshpass scp 至 GPU 机（注意：5G IP 会随 DHCP 重签变化，绑定地址必须实时获取）
- **迅雷 API 研究**：认证已跑通（pan-auth JWT + Device-Space 空串），但 API 创建任务不被 CLI 认领（PENDING），仅 UI 创建生效——详见《09-迅雷下载/迅雷API下载任务排查说明.md》