BSAI ComfyUI Sol-H3 ｜ BSAI ComfyUI Sol-H3

MiniMax H3 一键高速推理插件 — Sol-Attn 稀疏注意力 + FastH3 4 步蒸馏 + Fused Modulation + Chunk FeedForward + 双采 Self-Lift One-click high-speed inference for MiniMax H3 — Sol-Attn sparse attention + FastH3 4-step distillation + Fused Modulation + Chunk FeedForward + Dual-Sample Self-Lift

中文说明见下方；English documentation follows each section. 无需修改 ComfyUI 核心文件，clone 即用，开箱即得 4 步极速 + Sol-Attn 稀疏注意力。 No ComfyUI core file is modified — clone and run. 4-step ultra-fast + Sol-Attn out of the box.

---

插件介绍 / Introduction

BSAI Sol-H3 是一个为 MiniMax H3（文生视频+音频联合模型）打造的"一键高速推理"加载器插件。它把四套官方/社区优化整合到一个节点里，让用户不用自己拼装就能直接获得 4 步蒸馏 + 稀疏注意力的极速体验：

BSAI Sol-H3 is a one-click high-speed inference loader for the MiniMax H3 (text-to-video + audio joint model). It bundles four proven optimizations into a single node so you get 4-step distillation + sparse attention speed without assembling anything yourself:

亮点 / Highlights

• 一个节点替代多个优化节点：模型加载、LoRA 挂载、Sol-Attn 稀疏注意力安装（含 Morton hooks / block 索引 / sigma 换算）全部在 BSAI Sol-H3 Loader 内完成。
• 双采 Self-Lift 开箱即用：LatentUpscaleAlign 不经过 VAE 编解码直接放大 latent（无画质损失），按 H3 官方 32px 步进对齐（避免边缘色条），可选 CONST 重加噪，音频默认锁定，输出可直接接 SamplerCustomAdvanced + DisableNoise 精修。
• 音频问题根治：内置音频修复（audio_shift 独立缩放 + H3 AudioVAE 全量加载补丁，对应官方 PR #15371，含解码/编码兜底），5 秒音频解码从约 300+ 秒（0.39 DynamicVRAM 流式）降到约 1.6 秒，声音不再怪异。
• delta 权重（.diff/.diff_b）智能加载：v2.5.4 起自动识别 delta 格式 LoRA，自动匹配模型参数 key 并反量化应用，兼容标准 LoRA 与直连 delta 两种格式。
• 3D Latent Upscaler 支持：可选神经网络语义放大（比 bilinear 插值保留更多细节），模型文件自动搜索 models/latent_upscale_models/ 与 models/h3_latent_upscalers/。

---

性能 / Performance

实际速度取决于 GPU、分辨率与帧数。/ Actual speed depends on GPU, resolution and frame count.

---

节点 / Nodes

本插件提供 3 个节点，全部位于 BSAI/Sol-H3 分类下 / This plugin provides 3 nodes, all under the BSAI/Sol-H3 category:

---

安装 / Installation

方式一：命令行 / Option 1: Command line

cd ComfyUI/custom_nodes
git clone https://github.com/xm6018924/BSAI-ComfyUI-Sol-H3.git
cd BSAI-ComfyUI-Sol-H3
python install.py          # 自动检查 comfy_kitchen 并下载 FastH3 4步 LoRA（~300MB）
python -m pip install -r requirements.txt   # 如有依赖变更

方式二：ComfyUI Manager / Option 2: ComfyUI Manager

在 Manager 中搜索 BSAI-ComfyUI-Sol-H3 安装，重启 ComfyUI。/ Search BSAI-ComfyUI-Sol-H3 in Manager, install, restart ComfyUI.

首次安装自动做的事 / What install.py does

1. 检查 comfy_kitchen（Sol-Attn 内核，随 ComfyUI 提供）。
2. 自动下载 FastH3-4step-LoRA.safetensors（~300MB）到 models/loras/（ModelScope 国内直连优先，HF 兜底）。
3. 启动 ComfyUI 后，日志应出现 Sol-Attn已安装: ... (新API: sink_blocks/tail) 且无 kernel failed。

---

使用方法 / Usage

基本连接（文生视频+音频）/ Basic wiring (T2V + audio)

BSAI Sol-H3 Loader ──model──> KSampler ──LATENT──> VAEDecode ──IMAGE──> VHS_VideoCombine
CLIPLoader ──> CLIPTextEncode(正向) ─┘              └──> VAEDecodeAudio ──AUDIO──┘
             └─> CLIPTextEncode(负向)
EmptyHunyuanLatentVideo ──> KSampler(latent_image)
VAELoader(video VAE) ──> VAEDecode
VAELoader(audio VAE) ──> VAEDecodeAudio

也可将 Loader 输出的 steps（INT）接 EmptyHunyuanLatentVideo 的帧数无关（帧数由 latent 决定）；steps/cfg 可直接接入 KSampler 的 steps/cfg 输入端。

⚠️ 重要：勿叠加其他 attention 优化节点 / IMPORTANT: do NOT stack extra attention-optimization nodes

sol_attn=True 时 Loader 已内置 Sol-Attn 稀疏注意力补丁。同一条模型链上不要再挂：

• KJNodes MiniMaxH3MemoryEfficientSageAttentionPatch（int8/fp8 Sage，会在 Sol-Attn 内层重复量化，显存翻倍触发 OOM）
• 旧版单文件节点 SolAttnMiniMax（custom_nodes/sol_attn_minimax_v2.py 旧版残留，请删除该文件，插件 v2.2+ 始终使用内置副本）
• T8 MiniMaxLowVRAMAttention（另一套 attention override）

多套叠加会形成 Sol-Attn → kitchen → Sage int8/fp8 链式 patch，每层都分配中间张量，RTX 5090 Laptop 24GB 上主采样即 OOM。 When sol_attn=True, the Loader already installs the Sol-Attn sparse-attention patch. Do not add any of these on the same model path: KJNodes MiniMaxH3MemoryEfficientSageAttentionPatch (re-quantizes inside Sol-Attn, doubles VRAM → OOM), the legacy single-file SolAttnMiniMax node (delete the stale custom_nodes/sol_attn_minimax_v2.py; v2.2+ always loads the built-in copy), or T8 MiniMaxLowVRAMAttention. Stacking them chains Sol-Attn → kitchen → Sage int8/fp8, each layer allocating intermediate tensors, and OOMs the main pass even on a 24GB RTX 5090 Laptop.

保留 ModelAttentionBackend（comfy kitchen attention）不影响——它是底层 kernel 后端，Sol-Attn 正常工作依赖它。Keep ModelAttentionBackend (comfy kitchen attention) — it is the underlying kernel backend Sol-Attn relies on.

❗ 更正 / Correction：ModelAttentionBackend 必须删除/断开，不能保留。 该节点执行 set_model_optimized_attention，写入的正是 transformer_options["optimized_attention_override"]——与 Loader 内置 Sol-Attn 同一个槽位；节点图按依赖顺序执行，Loader 先装 Sol-Attn，ModelAttentionBackend 后执行会直接覆盖，Sol-Attn 稀疏注意力被禁用。int8 权重的 int8_linear 走 comfy_kitchen 的张量层（ops），不需要该节点。请删掉工作流中的 ModelAttentionBackend（302/264）节点，将 Loader → ChunkFF → SigmaShift 直接连到采样器。

Loader 参数说明 / Loader Parameters

delta 权重说明 / Delta weights: v2.5.4 起 lora_name 同时支持标准 LoRA（lora_A/lora_B）与直连 delta 权重（.diff/.diff_b 后缀，按模型 key 自动匹配反量化应用）。/ Since v2.5.4 both standard LoRA and raw delta weights (.diff/.diff_b) are auto-detected and applied.

LatentUpscaleAlign 参数 / LatentUpscaleAlign Parameters

---

示例工作流 / Example Workflows

仓库 workflows/ 目录提供 2 个可直接运行的示例（纯 ComfyUI 核心节点 + 本插件，不依赖任何第三方插件）。/ Two ready-to-run examples in workflows/ (pure ComfyUI core nodes + this plugin, no third-party dependency):

工作流 1：SolH3_Fast_4step.json — 基础 4 步极速（文生视频+音频）/ Basic 4-step Ultra (T2V + Audio)

节点链 / Node chain:

BSAI Sol-H3 Loader ──model──> KSampler ──LATENT──> VAEDecode ──IMAGE──> VHS_VideoCombine
CLIPLoader ──> 2×CLIPTextEncode (正/负)                └──> VAEDecodeAudio ──AUDIO──┘
EmptyHunyuanLatentVideo (1344×768×24) ──> KSampler
VAELoader×2 (video VAE + audio VAE)

使用步骤 / How to use:

1. 把 workflows/SolH3_Fast_4step.json 拖入 ComfyUI 画布。
2. Loader 节点：确认 model_name 指向你本机的 H3 模型文件；fast_h3_steps 保持「4步 FastH3 极速」；精度 int8（显存紧张）或 default。
3. CLIPLoader：选择你的 H3 CLIP 文本模型（如 qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors）。
4. EmptyHunyuanLatentVideo：width/height/length 默认 1344×768×24（5 秒 @24fps），可改 672×384 快速测试。
5. 两个 VAELoader：分别选视频 VAE（minimax_h3_video_vae_fp16.safetensors）与音频 VAE（minimax_h3_audio_vae_fp32.safetensors）。
6. CLIPTextEncode：正向框写你的提示词（含画面+音效描述，如示例的雨夜霓虹小巷）；负向框保持默认负面词。
7. 点「运行」→ 视频+音频输出到 ComfyUI/output/。

参数建议 / Tips: 先用 672×384×16 测试；确认无问题再上 1344×768×24。shift=8.0（视频）、audio_shift=3.0（音频）为推荐默认值。

工作流 2：SolH3_Self-Lift_DualSample.json — 双采 Self-Lift 精修 / Dual-Sample Self-Lift Refinement

流程 / Pipeline:

一采 First pass:
  Loader(8步LoRA ~0.75) ──> KSampler(8步 euler/simple, 672×384×24)
        └──> LatentUpscaleAlign(scale=2.0 → 1344×768, bilinear, CONST重噪, 音频锁定)
二采 Second pass:
  LoraLoaderModelOnly(FastH3-4step-LoRA 0.7) ──> BasicGuider
  BasicScheduler(beta, 4步, denoise 0.55) ──> SamplerCustomAdvanced + DisableNoise
        └──> VAEDecode + VAEDecodeAudio ──> VHS_VideoCombine

为什么要双采 / Why dual-sample: 一采低分辨率快速出草稿（省显存/快），LatentUpscaleAlign 把 latent 直接放大到 2x 并 32px 对齐（无 VAE 编解码损失），二采用 4 步 LoRA + Beta 调度在原 latent 上精修细节，得到高清成片——比一次直接生成高分辨率更快、更省显存，且音频全程锁定一采结果不受影响。

使用步骤 / How to use:

1. 拖入 SolH3_Self-Lift_DualSample.json。
2. Loader：lora_name 指向你的 8 步 LoRA（一采保底），lora_strength≈0.75；fast_h3_steps 选「8步 FastH3 增强」（一采 8 步；>3 步画面更稳）。
3. LoraLoaderModelOnly：选 FastH3-4step-LoRA.safetensors，强度 0.7（二采收敛快、边缘清晰）。
4. LatentUpscaleAlign：scale=2.0（672×384→1344×768）、method=bilinear（不要改）、add_noise=True、audio_denoise=0.0（锁定一采音频）；如装有 3D upscaler 模型可选 upscaler_model。
5. BasicScheduler：scheduler=beta、steps=4、denoise=0.55（二采精修强度）。
6. 提示词与 CLIP/VAE 设置同工作流 1。运行即可。

经验参数（社区验证 + v2.4.2 实测） / Proven settings:

• 一采步数 ≤3 步快速预览更省抽卡成本（>3 步易画面异常）。
• 放大倍数 1.3–2（显存峰值=放大后分辨率那次，不能超单采预算）。
• 放大方法必须 bilinear（nearest-exact 会导致 latent 块化→二采鬼影/重影）。
• 二采 denoise 0.5–0.6（0.35 太低修不干净块化会留鬼影）。
• 显存紧张时 precision=int8 + chunk_ff=ON 可显著降低峰值。

---

常见问题 / FAQ & Troubleshooting

Q1: 报错 sol_attn() got an unexpected keyword argument 'max_blocks'？

旧版根目录顶层文件污染。检查 ComfyUI/custom_nodes/sol_attn_minimax_v2.py 是否存在——若非本插件内置副本，请删除或覆盖为最新版（v2.2 起插件始终加载内置副本，不受影响）。/ Remove any stale top-level sol_attn_minimax_v2.py in custom_nodes/.

Q2: 报错 got an unexpected keyword argument 'sink_blocks'？

comfy_kitchen 过旧，请升级 ComfyUI / comfy_kitchen 到支持 sink_blocks/sink_q/tail 新 API 的版本。/ Upgrade comfy_kitchen.

Q3: 音频怪异或解码极慢？

检查 Loader 的 audio_shift 是否为默认 3.0。必须先重启 ComfyUI（补丁在插件加载时生效）；启动日志应有 [BSAI-Sol-H3] 音频/视频解码修复已就绪(PR #15371 语义, 含解码/编码兜底)，生成时音频 VAE 应打印 音频解码修复生效（构造时）或 音频解码兜底生效（解码时），并打印 H3 VAE 动态 patcher 已重建为传统ModelPatcher(全量加载)，且不再出现 prepared for dynamic VRAM loading. 576MB Staged 字样。若仍见 576MB Staged，说明进程加载的是旧版 nodes.py，请彻底重启（关闭所有 ComfyUI 窗口再启动）。/ Ensure audio_shift=3.0 and restart ComfyUI; the AudioVAE full-load patch (with decode/encode fallback) is applied on plugin load. The audio VAE must print 音频解码修复生效/音频解码兜底生效 + H3 VAE 动态 patcher 已重建为传统ModelPatcher(全量加载) and must NOT log prepared for dynamic VRAM loading. 576MB Staged.

v2.6 修复要点（2026-10-12）：0.39 + --enable-dynamic-vram 下，sd.py 的 VAE.__init__ 在读取 disable_offload 之前就按初始 False 创建了动态 patcher（CoreModelPatcher 被 main.py 重赋值为 ModelPatcherDynamic），旧补丁只在 __init__ 返回后置位 disable_offload=True，动态 patcher 并未被替换，导致音频解码仍走 DynamicVRAM 流式（5 秒音频实测 209~324 秒）。本次修复：构造时与解码兜底都以 patcher 实际类型为准——检测到 ModelPatcherDynamic 即重建为传统 ModelPatcher（全量加载），不再被 disable_offload 已为 True 短路；修复后音频解码回到约 1 秒级。/ v2.6 fix: with --enable-dynamic-vram the dynamic patcher was created before disable_offload was read, and the old patch only set the flag after __init__ returned — so the patcher stayed dynamic. Now the patcher is rebuilt to a traditional ModelPatcher by its actual type (constructor + decode fallback), restoring ~1s audio decode.

v2.6 统一补丁（其他 BSAI 插件）：同一修复逻辑已抽为公共模块 BSAI-ComfyUI-Sol-H3/bsai_h3_vae_full.py，供所有 BSAI H3 系插件统一引用（apply_global_patch(owner)，多插件共享一次全局包装、幂等）。已接入：BSAI-ComfyUI-H3-Film-Factory、BSAI-ComfyUI-FastH3、BSAI_ComfyUI_SolarWM_H3、BSAI-ComfyUI-MiniMax-H3-PDD-Acc、BSAI-ComfyUI-vdn-minimax-h3、BSAI-ComfyUI-VAERouter、BSAI-H3-MotionFix。各插件入口 try/except 容错，宿主（本插件）缺失时 no-op；任一插件触发后全局生效，启动日志出现 [BSAI-H3VAE] H3 VAE 全量加载统一补丁已生效。/ The same fix is also shipped as the shared module bsai_h3_vae_full.py consumed by all BSAI H3 plugins (idempotent, single global patch). Log line: [BSAI-H3VAE] H3 VAE 全量加载统一补丁已生效.

Q4: 双采出鬼影/重影？

放大方法改回 bilinear；二采 denoise 提到 0.5-0.6；一采步数 ≤8 且 LoRA 强度适当。/ Use bilinear upscale; raise second-pass denoise to 0.5-0.6.

Q5: 没有 workflows/ 目录？

从 GitHub 最新版获取（v2.5+ 已内置两个示例工作流）。/ Get the latest from GitHub — v2.5+ ships both example workflows.

Q6: Sol-Attn 未生效（速度慢、显存高）？

确认 Loader sol_attn=ON 且 sink_conditioning≠off；日志应出现 Sol-Attn已安装，且无 kernel failed。/ Verify sol_attn=ON, sink_conditioning≠off, and no kernel failed in logs.

Q7: 报错 ERROR lora diffusion_model.blocks.N.adaln_proj.linear.weight shape '[...]' is invalid for input of size ...（blocks.0~N 刷屏）？

这是 LoRA 与模型架构不匹配。H3 的 adaln_proj 有两种结构：标准模型（10Eros_Max_h3_TURBO-hybrid_beta4*、minimax_h3_fl2va/ref2va_int8_convrot、bf16 系列）该层输入是 2688 维（权重 [96768, 2688]）；curve 模型（minimax_h3_fastvideo_*4step*、*_pruned_*、hybrid_b25-49、Dasiwa*）是 8 维（权重 [96768, 8]）。LoRA 也分两派：H3电影质感V0.4 .safetensors（rank16，A=[16, 2688]）为标准架构训练；minimax_h3_lms_v1.0_r64-细节纹理增强lora.safetensors（部分版本文件名无连字符）的 A=[64, 8]，为 curve 架构训练。挂反了，官方 Lora Loader Stack (rgthree) 路径就会 reshape 失败逐 block 刷屏：

• 标准模型 + lms（8 维 LoRA）→ shape '[96768, 2688]' is invalid for input of size 774144（774144 = 96768×8，LoRA 元素数）
• curve 模型（fastvideo 4步极速等）+ 质感V0.4（2688 维 LoRA）→ shape '[96768, 8]' is invalid for input of size 260112384（260112384 = 96768×2688） 与电脑/磁盘无关：任何机器这样组合都会报错（"C 盘正常"只是因为该组合从未出现在 C 盘工作流里）。 解决（按需二选一）：① 把不匹配的 LoRA strength 改为 0 或从栈中移除；② 换模型使架构匹配——质感V0.4 配标准模型（10Eros_TURBO/fl2va/ref2va），lms 配 curve 模型（fastvideo 4步极速等）。FastH3-4step-LoRA 由 Sol-H3 Loader 内置转换加载（日志出现 [BSAI-Sol-H3] LoRA已加载: FastH3-4step-LoRA... 258/258 即为生效），不要再挂官方栈。 EN: This is a LoRA ↔ model architecture mismatch on adaln_proj. Standard H3 models (e.g. 10Eros_Max_h3_TURBO-hybrid_beta4*, minimax_h3_fl2va/ref2va_int8_convrot, bf16) use a 2688-dim input (weight [96768, 2688]); curve models (minimax_h3_fastvideo_*4step*, *_pruned_*, hybrid_b25-49, Dasiwa*) use an 8-dim input (weight [96768, 8]). LoRAs match one side: H3电影质感V0.4 .safetensors (rank16, A=[16, 2688]) was trained for standard models; minimax_h3_lms_v1.0_r64-细节纹理增强lora.safetensors (A=[64, 8]) for curve models. Putting the wrong pair into the official Lora Loader Stack (rgthree) makes reshape fail and spam per-block errors:
• Standard model + lms (8-dim LoRA) → shape '[96768, 2688]' ... size 774144 (96768×8)
• Curve model (fastvideo 4-step etc.) + 质感V0.4 (2688-dim LoRA) → shape '[96768, 8]' ... size 260112384 (96768×2688) This is machine-independent: any PC hits it with that combo ("C-drive works" only because the combo never appears in those workflows). Fix: set the mismatched LoRA's strength to 0 (or remove it), or swap the model so architectures match — 质感V0.4 ↔ standard (10Eros_TURBO/fl2va/ref2va), lms ↔ curve (fastvideo 4-step). Keep FastH3-4step-LoRA out of the official stack; the Sol-H3 Loader converts and loads it natively ([BSAI-Sol-H3] LoRA已加载: FastH3-4step-LoRA... 258/258).

Q8: 加了 ModelAttentionBackend（comfy kitchen attention）后 Sol-Attn 不生效 / 显存没降？

删掉这个节点（或断开它的 model 链）。它执行 set_model_optimized_attention，写入的 transformer_options["optimized_attention_override"] 与 Loader 内置 Sol-Attn 是同一个槽位；按节点执行顺序它在 Loader 之后运行，会直接覆盖 Sol-Attn，稀疏注意力失效。int8 权重的计算走 comfy_kitchen 张量层（ops），不依赖该节点。/ Remove it. It writes the same optimized_attention_override slot as the Loader's built-in Sol-Attn and overwrites it when executed later, disabling sparse attention. INT8 math runs in comfy_kitchen's tensor layer and does not need this node.

---

SolEngine 两级精修旁支 / SolEngine Two-Stage Refiner Branch (v2.7)

完全旁支，不影响原有三个节点。 你可以继续用原来的 H3 双采 Self-Lift，也可以走新的 NVIDIA Sol Engine 两级流水线。 Fully additive — the original three nodes are untouched. Use the classic H3 dual-sample Self-Lift or the new NVIDIA Sol Engine two-stage pipeline.

参考 NVIDIA Sol Engine / H3 Super Acceleration（2026-09 开源）：

Stage 1: H3 在 672x384 出草稿（4步 FastH3，原有 Loader 不变）
   ↓ VAEDecode -> IMAGE, VAEDecodeAudio -> AUDIO
Stage 2: BSAI SolEngine Refiner 节点内部自动完成：
   帧裁剪/resize (960x544 encode) -> LTX-2.5 VAE 编码 -> x2 latent 放大 (1920x1088)
   -> T8mars patch + official sigma=0.909 3步 euler 精修 -> LTX VAE 解码
   ↓ 输出精修 IMAGE + 裁剪后的 H3 原音频

社区 5090 实测：冷启动 ~40s，热启动 ~30s，5 秒 1344x768 带音频视频。 Community RTX 5090: cold start ~40s, warm start ~30s for 5s 1344×768 video with audio.

依赖（本机已全部就位）/ Dependencies (all present on this machine)：

• T8mars/comfyui-minimax-h3-audio-T8（SolEngine 核心 patch / core patch）
• LTX-2.5 transformer: ltx-2.5-22b-dev-transformer-comfy-int8-convrot.safetensors (~20GB)
• LTX-2.5 video VAE: ltx-2.5-video-vae-conv-bf16.safetensors (~1.4GB)
• LTX-2.5 text encoder: gemma4-12b-with-proj-ltx-2.5-comfy-int8-convrot.safetensors (~14.6GB)
• LTX-2.5 x2 spatial upscaler: ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors (~950MB)
• Distilled LoRA: ltx-2.5-22b-distilled-lora-450-bf16.safetensors (~8.5GB, strength=0.8)

使用 / Usage：H3 草稿跑完后，把 VAEDecode 的 IMAGE 和 VAEDecodeAudio 的 AUDIO 接到新节点 BSAI Sol-H3 SolEngine 两级精修 (LTX-2.5)，填 prompt + 目标分辨率，输出直接接 VHS_VideoCombine。 After H3 draft finishes, wire VAEDecode IMAGE + VAEDecodeAudio AUDIO into the new BSAI Sol-H3 SolEngine 两级精修 (LTX-2.5) node, fill in the prompt + target resolution, and output directly to VHS_VideoCombine.

关键参数 / Key Parameters:

• target_width/target_height: 默认 1920×1088（encode 自动降到 960×544 后 x2 放大）/ Default 1920×1088 (encode auto-downscaled to 960×544, then x2 upscaled)
• schedule_mode: 默认 official_0p909（NVIDIA 官方 3步 sigma: 0.909/0.725/0.421875）/ Default official_0p909 (NVIDIA official 3-step sigmas)
• refiner_lora_strength: 默认 0.8 / Default 0.8

示例工作流：workflows/SolH3_SolEngine_LTX25_Refine_V2.json。 Example workflow: workflows/SolH3_SolEngine_LTX25_Refine_V2.json.

VRAM 注意 / VRAM Note: LTX-2.5 22B int8 ≈ 18GB, 24GB VRAM 需 --lowvram --disable-dynamic-vram --reserve-vram 1.5 启动参数。采样时 ComfyUI 会自动 offload 部分 transformer 权重到 CPU，速度略慢但可跑通。/ LTX-2.5 22B int8 ≈ 18GB; on 24GB VRAM use --lowvram --disable-dynamic-vram --reserve-vram 1.5 launch flags. ComfyUI auto-offloads part of the transformer to CPU during sampling — slightly slower but fits.

---

硬件要求 / Requirements

• NVIDIA GPU: SM86 (RTX 30 系) / SM89 (RTX 40 系) / SM120 (RTX 50 系) / SM121 (DGX Spark)
• PyTorch + CUDA，bfloat16 支持 / bfloat16 support
• Triton 3.6.0+
• ComfyUI 0.30.0+

版本历史 / Changelog

• v2.9.1 (2026-10-08): 默认 min_tokens 12288 → 1024（实测驱动）—— 对 1344×768×24 H3 视频（主注意力仅 6167 tokens，×48 帧 12285 tokens）跑真实采样对比（off tau 路由 vs full Spark RepBlock 10%+Rabbit 128）发现：旧门槛下主注意力全部 Dense 回退（verbose 日志实证 dense (1,6167,56,128): seq 6167 < 12288），Spark 与 tau 稀疏均未生效（off/full 同种子输出逐像素一致 maxdiff=0.00）。下调到 1024 后稀疏真实生效（输出差异 PSNR 2634dB/SSIM 0.940.96），且 tau 稀疏比 Dense 内核快 2.43.8×（RTX 5090 Laptop 实测）。Spark-H3 结论：参数透传保留为可选能力（spark_mode 默认 off 不变），实测在本机 H3 视频序列（6k12k tokens）下 Spark full 相对 tau 稀疏无加速优势（48 帧反而慢 80%，内核级 topk+aug 比 tau 慢 1.8×）；官方 1.73× 提速基线是 dense/Veda，非 tau 稀疏。超长序列（数万 tokens）场景可对照实验。
• v2.9 (2026-10-08): Spark-H3 契约（B站《MiniMax-H3又能狂飙了！Spark-H3稀疏注意力让10秒768p视频提速1.73倍质量还更强》/ NVIDIA Sol-Attn Spark 发布）—— Loader 新增 spark_mode（off / rep_block / rabbit / full）+ spark_keep_percent + spark_token_aug 三参数：
  1. SparkRepBlock（spark_mode=rep_block）：映射内核 topk_ratio——SLA 风格每 query-block top-k 分组路由，把精确计算预算花在注意力偏好相似的块上（sink 与对角块仍恒精确）。10% 密度契约（spark_keep_percent=10）= 视频官方基准：注意力 2.33×、整 it 1.73× 提速，PSNR 23.30dB（比 Veda 高近 3dB），且不改权重、显存占用不变。
  2. SparkRabbit（spark_mode=rabbit）：映射内核 token_aug——尾部 token 按质心评分加权精确修正（每行额外精确关注高分未路由 token，其余尾部对质心精确而非按块池化），消除 pooled-summary 平均化偏差。
  3. full = 双机制叠加；off = v2.8 行为（tau 阈值），旧工作流零改动。内核已由 comfy_kitchen 0.2.37 生产级 CUDA 内核提供（sm_80+，RTX 50 系 sm_120 专属路径），无需改模型权重。新增参数均追加在输入列表末尾。
• v2.8 (2026-10-04): 对齐 NVIDIA Sol-H3 RSI 论文 (arXiv 2609.35110) + SoL-Refiner (arXiv 2609.37969) 四项升级 ——
  1. SolEngine Refiner Stage-2 稀疏注意力默认启用 (stage2_attention=sol_attn_sparse)：v2.7 写死 dense_reference，把内置 h3_t8 已实现的官方 Stage-2 Sol-Attn 路径（论文 §3.4：3 步精修逐步 tau 1.0/1.25/1.5 + 第 0 层 dense 保护）关掉了；现默认接通，内核缺失自动回退 dense 并如实上报。
  2. Stage-2 条件缓存 (stage2_cond_cache=ON)：论文 §4.2 prompt caching 的 ComfyUI 落地——按 (clip文件, prompt, fps) 进程内缓存精修条件，同提示词复跑直接跳过 14.6GB Gemma 的"卸载→加载→编码→卸载"整段。官方 RTX 5090 实测里该编码器每请求重建占端到端 34.1% 耗时（13.568s 中前向仅 0.518s），24GB 显存本机收益更大，同时显著压低 Windows 提交内存峰值（os error 1455 诱因）。
  3. 一步精修模式 (schedule_mode=one_step_sol)：复刻官方 Stage-2 首段 0.85→0 单步降噪，耗时≈3 步方案 1/3，定位 4K 快速预览。真·SoL-Refiner（HR持续训练+RL后训练+单步蒸馏，3840×2176）权重官方尚未公开，出正式 4K 建议 official_0p85(3步) + BSAI-H3-upscale-4K 超分。
  4. 4K tiled 解码 (decode_mode=auto)：输出面积 >1.6MP（高于 1080p 档）自动走核心 decode_tiled 分块解码（论文 §3.6 并行瓦片同路线，与全量最大偏差约 0.02 视觉不可见），24GB 显存可跑满 3840×2176；target_height 上限同步放开到 2176。
  5. Loader 官方安全轨 (sol_tau_ramp=ON + dense_first_blocks=2)：一采稀疏注意力按采样进度线性递增 tau（早期高噪声步保守保全局构图，后期激进提速），且前 2 个 block 强制 dense（论文原话：全局结构成形期引入的误差会持续到后续层）；与手动 dense_blocks 自动合并。新增参数均追加在输入列表末尾，旧工作流加载不受影响。
• v2.7 (2026-09-29): SolEngine 两级精修旁支 — 新增 BSAI_SolH3_SolEngine_Refiner 节点，封装 NVIDIA Sol Engine / H3 Super Acceleration Stage-2（H3 draft 像素 handoff → LTX-2.5 VAE encode → x2 latent 放大 → LTX-2.5 3步精修 → TAEHV 解码），保留 H3 原音频。原有三个节点完全不变，用户可选老路（H3 双采 Self-Lift）或新路（LTX-2.5 精修，5090 ~40s）。依赖 T8mars/comfyui-minimax-h3-audio-T8 + LTX-2.5 权重（本机已就位）。
• v2.6.1 (2026-09-12): docs(FAQ): Q7 扩展为双向 LoRA 兼容矩阵——新增反向案例（curve 模型如 fastvideo 4步极速 × 标准架构 LoRA 质感V0.4 → shape '[96768, 8]' ... size 260112384），修正原"质感V0.4 可任意挂官方栈"的误导；兼容性结论与电脑/磁盘无关。
• v2.6 (2026-09-12): FastVideo LoRA 真正生效 / FastVideo LoRA fully works — 内置 FastVideo→ComfyUI 结构转换（transformer_blocks.attn.to_q/to_k/to_v→blocks.attn.qkv_proj 块对角融合、ff.net.0.proj/2→mlp.fc1/fc2、.diff/.diff_b→量化感知 delta patch），并加形状过滤自动跳过 curve 版模型（adaln 8 维 / 无 time_embedder）不兼容的 patch；同时修复 FastVideo 导出 LoRA 文件 header 数据长度与实际文件不一致导致的 safetensors 0.8.0 严格校验失败（自动回退手动解析）。标准模型（adaln 全宽 2688）上 FastH3-4step-LoRA 258+85 全部生效；curve 版模型（如 10Eros TURBO-hybrid）主体 208+80 生效、不兼容部分自动跳过。
• v2.5.4 (2026-09-11): Loader 支持 delta 权重（.diff/.diff_b）智能加载（自动 key 匹配 + 反量化应用）；示例工作流恢复并更新至 29 参数结构。
• v2.5.3 (2026-09-11): 分离标准 LoRA 与 delta 格式；shape/cov 调试打印。
• v2.5.2: 示例工作流默认选 3D upscaler 模型（fp16）。
• v2.5.1: 自动注册 h3_latent_upscalers 目录为模型搜索路径。
• v2.5: LatentUpscaleAlign 支持 3D latent upscaler 模型语义放大。
• v2.4: 双采 Self-Lift：Loader 双 LoRA 可配（lora_name/lora_strength）+ 新增 LatentUpscaleAlign 节点。
• v2.3: 音频修复：audio_shift 独立缩放 + AudioVAE 全量加载补丁（PR #15371）。
• v2.2: Loader 改为内置副本优先，根治旧顶层文件污染。
• v2.1: Loader 并入 Sol-Attn 全套精细参数，_apply_patch 完整路径安装。

许可证 / License

MIT（本插件 / this plugin）｜Sol-Attn 内核：Apache 2.0 (NVIDIA)｜H3 权重：MiniMax Community License