# 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**: | 组件 / Component | 来源 / Source | 作用 / Role | |---|---|---| | **Sol-Attn** | [Saganaki22/ComfyUI-sol-attn](https://github.com/Saganaki22/ComfyUI-sol-attn) | Triton 稀疏注意力，SM86-SM121（RTX 30/40/50 系）/
Triton sparse attention for SM86–SM121 (RTX 30/40/50) | | **FastH3 V1** | [Hao AI Lab (UCSD)](https://haoailab.com/blogs/fasth3-preview/) | 4 步蒸馏 adapter，约 11x 加速 /
4-step distilled adapter, ~11x speedup | | **Fused Modulation** | Sol-Attn 内置 / built-in | Triton 融合 AdaLN+门控残差，bit-exact | | **Chunk FeedForward** | Sol-Attn 内置 / built-in | MLP 显存峰值降低最多 1.9GB /
MLP VRAM peak reduced by up to 1.9GB | | **双采 Self-Lift** | 本插件 / this plugin | latent 直接放大+32px 对齐+CONST 重加噪，二采精修 /
latent upscale + 32px align + CONST re-noise for second-pass refinement | ### 亮点 / 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 | 配置 / Configuration | 5 秒 720p 视频 / 5s 720p video | 对比 / vs baseline | |---|---|---| | 原生 H3（50 步）/ Native H3 (50 steps) | ~30 分钟 / ~30 min | 基准 / baseline | | Sol-Attn（50 步）/ Sol-Attn (50 steps) | ~6.5 分钟 / ~6.5 min | ~4.5x 加速（RTX 5090）/ ~4.5x on RTX 5090 | | **FastH3 + Sol（4 步）/ 4-step** | **~2-3 分钟 / ~2-3 min** | **~11x 加速 / ~11x** | | NVIDIA 8xB300（4 步）/ server grade | 1.653 秒 / 1.653 s | 服务器级 / datacenter | > 实际速度取决于 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: | 节点 / Node | 作用 / Role | |---|---| | **BSAI Sol-H3 Loader (极速版)** | 一键加载 H3 模型 + FastH3 LoRA + Sol-Attn（全套精细参数），输出 `model / steps / cfg / sol_info`。/ One-click model + LoRA + Sol-Attn loader; outputs `model / steps / cfg / sol_info`. | | **BSAI Sol-H3 Latent 放大对齐 (双采)** | 双采核心节点：latent 直接放大（不经过 VAE）+ 像素 32 倍数对齐 + 可选 CONST 重加噪（音频默认锁定）。/ Core dual-sample node: latent upscale (no VAE round-trip) + 32px pixel alignment + optional CONST re-noise (audio locked by default). | | **BSAI Sol-H3 Info** | 显示 Loader 返回的优化状态信息（UI 文本）。/ Displays the optimization status string from the Loader. | --- ## 安装 / Installation ### 方式一：命令行 / Option 1: Command line ```bash 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 | # | 参数 / Parameter | 默认 / Default | 说明 / Description | |---|---|---|---| | 1 | model_name | - | H3 模型文件（`diffusion_models` 目录）
H3 model file in `diffusion_models` | | 2 | precision | int8 | 模型加载精度：int8 / default / fp8_e4m3fn | | 3 | sol_attn | ON | 是否安装 Sol-Attn 稀疏注意力补丁
Install Sol-Attn sparse attention patch | | 4 | tau_start | 0.5 | 渐变起始 tau（信息/兼容旧工作流）
Gradient start tau (informational) | | 5 | tau_end | 1.0 | 渐变结束 tau（信息/兼容旧工作流）
Gradient end tau (informational) | | 6 | sink_conditioning | exact_kv | 锚点策略：exact_kv / exact_kv_and_rows / off
Sink strategy | | 7 | int8_qk | ON | INT8 QK 量化 / INT8 QK quantization | | 8 | fused_modulation | ON | 融合调制优化 / Fused modulation | | 9 | chunk_ff | ON | FFN 分块显存优化 / Chunked FFN memory saving | | 10 | chunk_size | 2 | FFN 分块大小 1-8 / FFN chunk size | | 11 | fast_h3_steps | 4步 FastH3 极速 | 4步 FastH3 极速 / 8步 FastH3 增强 / 50步原生高质量
4-step Ultra / 8-step Enhanced / 50-step Native | | 12 | sampler | euler | 采样器：euler / dpmpp_2m / euler_ancestral | | 13 | cfg | 4.0 | 提示词引导强度 / CFG guidance | | 14 | shift | 8.0 | 视频流 flow matching 时间偏移（官方默认 12.0）
Video flow-matching shift (official default 12.0) | | 15 | **audio_shift** | 3.0 | 音频流独立时间偏移（官方默认 3.0；修音频怪异核心参数）
Audio shift — fixes weird audio | | 16 | **min_tokens** | 1024 | 序列长度阈值：低于此长度用 Dense（省显存/保质量）。**v2.9.1 起默认从 12288 下调到 1024**——H3 视频主注意力实测仅 ~6k~12k tokens（1344×768×24≈6167 / ×48≈12285），旧门槛会导致内核全部 Dense 回退、稀疏不生效；1024 让 tau 稀疏在短视频真实生效（内核实测比 Dense 快 2.4~3.8×）。
Below this token count, attention stays dense. v2.9.1 lowered default from 12288 → 1024 (H3 video main attention is only ~6k~12k tokens). | | 17 | **sol_tau** | 1.3 | Sol-Attn 稀疏强度（越大越稀疏、越省显存）
Sol-Attn sparsity strength | | 18 | **start_percent** | 0.2 | 稀疏生效起始采样比例（前 20% 步数 Dense 热身）
Sparse starts after 20% of steps (dense warmup) | | 19 | **end_percent** | 0.9 | 稀疏生效结束采样比例（最后 10% 步数 Dense 收尾）
Sparse ends at 90% (dense tail) | | 20 | **morton** | OFF | Morton 空间排序（提升稀疏命中率）
Morton space-filling ordering | | 21 | **morton_curve** | 2d_frame | 排序曲线：2d_frame / hilbert / z_order | | 22 | **centroid_tail** | ON | 质心尾块保留（提升长序列质量）
Keep centroid tail blocks | | 23 | **routed_cap_percent** | 0 | 路由容量上限百分比（0=不限制）
Routing capacity cap % (0 = unlimited) | | 24 | **reuse_qkv_memory** | OFF | 复用 QKV 中间缓冲（仅限已知安全模型）
Reuse QKV intermediate buffers | | 25 | **verbose** | OFF | Sol-Attn 详细日志 / Verbose logging | | 26 | **dense_blocks** | 空 | 强制全 Dense 的块索引，如 `0,1,2` / Force-dense block list | | 27 | **tau_profile** | 空 | 逐块 tau 覆盖，如 `0-4=2.0; 20-24=0.8`（分号/换行分隔）
Per-block tau overrides | | 28 | **spark_mode** | off | **v2.9 Spark-H3 契约**：off / rep_block / rabbit / full。
rep_block=SparkRepBlock（SLA 风格 top-k 分组路由，把精确预算花在注意力偏好相似的块上）；rabbit=SparkRabbit（尾部 token 质心加权精确修正，消除 pooled-summary 平均化偏差）；full=双机制叠加。默认 off=v2.8 行为。
**v2.9 Spark-H3 contract**: off / rep_block / rabbit / full. | | 29 | **spark_keep_percent** | 10.0 | rep_block/full 时保留的 key-block 比例（%）：**10% 密度契约 = 视频官方基准（注意力 2.33× / 整 it 1.73×，PSNR 23.30dB 比 Veda 高 ~3dB）**。
Key-block fraction kept (%), 10% = official Spark benchmark. | | 30 | **spark_token_aug** | 128 | rabbit/full 时尾部 token 增强数（64 的倍数，0-256，自动向下取整到 64）。
Tail-token augmentation (multiple of 64). | | 31 | **lora_name** | FastH3-4step-LoRA.safetensors | 主 LoRA（双采一采可改 8 步 LoRA 文件名，权重约 0.75）
Main LoRA (use an 8-step LoRA at ~0.75 for first pass) | | 32 | **lora_strength** | 1.0 | 主 LoRA 强度（0=禁用 LoRA）
LoRA strength (0 = disable) | > **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 | 参数 / Parameter | 默认 / Default | 说明 / Description | |---|---|---| | samples | LATENT | 一采输出的 latent（音视频 NestedTensor）| | scale | 2.0 | latent 放大倍率，双采推荐 1.5-2.0 | | align_to | 32 | 像素分辨率对齐步长（H3 官方 32px，避免边缘色条）| | method | bilinear | 放大方法：**必须 bilinear**（nearest-exact 会导致 latent 块化→二采鬼影）| | upscaler_model | (bilinear插值) | 可选 3D latent upscaler 模型做神经网络语义放大 | | add_noise | True | True=CONST 重加噪到 sigmas[0] 供二采；False=仅放大对齐 | | audio_denoise | 0.0 | 0=二采锁定一采音频（默认）；≥0.5=音频一起重噪重绘 | --- ## 示例工作流 / 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`. | | 原双采 Self-Lift / Classic Self-Lift | SolEngine 旁支 / SolEngine Branch | |---|---|---| | 二采模型 / Second-pass model | H3 自身 4步 LoRA | **LTX-2.5 22B 蒸馏**，3步 / LTX-2.5 22B distilled, 3 steps | | Handoff | latent 空间 bilinear 放大 / latent bilinear | **像素空间**裁剪+LTX VAE 重编码 / pixel-space crop + LTX VAE re-encode | | 精修起点 / Refine start | denoise=0.55 | sigma=0.909（official） | | 5090 耗时 / RTX 5090 time | 2-3 分钟 / 2-3 min | ~40 秒 / ~40 s | **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 26~34dB/SSIM 0.94~0.96），且 tau 稀疏比 Dense 内核快 2.4~3.8×（RTX 5090 Laptop 实测）。**Spark-H3 结论**：参数透传保留为可选能力（`spark_mode` 默认 off 不变），实测在本机 H3 视频序列（6k~12k 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

BSAI Sol-H3 Info

Inputs (1)

Outputs (0)