MiniMax H3 Spectrum

ComfyUI MiniMax H3 Spectrum

ComfyUI 中用于 MiniMax H3 采样的一种免训练特征预测方法。该节点对来自真实去噪步骤的最终隐藏状态观测值拟合一个正则化切比雪夫（Chebyshev）模型，然后利用其预测结果跳过选定的完整 DiT 前向计算。

这是针对 MiniMax H3 的特定集成实现。它不包含模型权重、ComfyUI、工作流或第三方注意力补丁。

许可证

本项目基于 GPL-3.0-or-later 许可。其 H3 前向路径集成衍生自 ComfyUI 的 MiniMax H3 实现，因此必须保持与 ComfyUI 的 GPLv3 许可兼容。

功能说明

在hidden 模式中，MiniMax H3 正常运行并产生最终隐藏特征。在 residual 模式下，节点存储最终隐藏值减去输入隐藏值的残差。给定所有保留的真实观测值后，它使用岭回归（ridge regression）在扩散时间坐标上拟合一个切比雪夫多项式。预测步骤会重新构建轻量级的 H3 输入嵌入，预测最终的隐藏状态，并仅运行最后的解码头（decode head）。采样器仍然执行其常规的隐空间更新。前者的计算开销较小，是对原论文的贴近实现，后者则是在原文上的优化

本实现受论文 Spectrum: Adaptive Spectral Feature Forecasting for Diffusion Sampling Acceleration 启发，但它是针对 H3 的工程适配实现，并非该论文的官方实现。

依赖要求

• 包含 comfy.ldm.minimax.model.MiniMaxH3Model 以及本节点所使用的 MiniMax H3 辅助 API 的 ComfyUI 构建版本。
• 由该 ComfyUI 安装提供的 PyTorch。不需要额外安装 pip 包。
• 一个 MiniMax H3 模型。

ps：如果安装出现问题，可以让你的Agent去分析依赖项的缺失:)

安装方法

将此仓库克隆到 ComfyUI 的 custom_nodes 目录中，然后重启 ComfyUI

工作流接线

在 MiniMax H3 的 MODEL 分支上，在模型级补丁之后、MiniMax H3 生成节点或下游采样器之前，插入 MiniMax H3 Spectrum Patch：

UNETLoader -> LoRA / 注意力补丁 -> MiniMax H3 Spectrum Patch -> MiniMax H3 生成器 将 steps 设置为下游 KSampler 的步数。对于双 H3 分支(如二采样方案)，对每个分支使用相同的调度器步数，分别应用一个 Spectrum 节点。

建议的初始配置

| 参数 | 值 | 含义 | | --- | ---: | --- | | steps | 下游 KSampler 步数 | 必须精确匹配。 | | forecasts_per_refresh | 1 | 预热后每执行一次真实 H3 步骤，交替执行一次预测步骤。 | | warmup_steps | 3 | 在进行任何预测之前收集三个真实观测值。 | | tail_actual_steps | 1 | 保留最后一步去噪为真实计算。 | | prediction_mode | residual | 预测最终隐藏值减去输入隐藏值的特征。 | | blend_w | 0.5 | 混合全局切比雪夫预测和局部一阶泰勒预测的占比，对于复杂场景可以稍微调高。 | | cheby_degree | 1 | 切比雪夫的阶数，对于多步数场景可以调高。 | | ridge_lambda | 0.05 | 切比雪夫拟合的正则化系数。 | | history_size | 0 | 保留所有真实观测值，即全局历史预测。 | | history_device | gpu | 仅当显存紧张时选择 cpu。 | | adaptive_guard | false | 在质量验证阶段开启，当探测误差过大时停止预测。 |

仅当固定种子的基线结果稳定后，再考虑增加速度。forecasts_per_refresh > 1 在复杂运动场景下更容易累积误差。

运行时日志

当 verbose=true 时，成功运行会同时打印真实步骤和预测步骤：

日志说明: [MiniMax H3 Spectrum] real step 1/8 (residual, t=..., sigma=...) [MiniMax H3 Spectrum] forecast step 4/8 (residual, t=..., sigma=...) [MiniMax H3 Spectrum] completed: real=5 forecast=3 total=8 ... 只有当完成行中的 forecast > 0 时，特征预测器才处于激活状态。比较固定种子的输出、总耗时、峰值显存和动作质量，仅仅看采样器的迭代速度是不够的。

兼容性说明

本节点复制了 H3 当前的内部前向行为以获取最终隐藏状态。ComfyUI MiniMax H3 API 的变动可能需要更新源代码。

one_sampler_only=true 可防止意外地在多个采样器之间复用同一个预测器状态。

形状、上下文、参考图像或关键帧的变更会重置预测器。

Spectrum 减少了完整模型前向的次数。它可以与每步前向加速（如 Sol 或 Sage Attention）叠加使用，但建议每次只调整一种近似方法。