Luisacaotica/ComfyUI-MiniMaxH3Mod

ComfyUI‑MiniMaxH3Mod – ComfyUI 中 MiniMax H3 的参考模块支持

它是什么

• 一个用于可视化编程界面 ComfyUI 的 自定义节点包，添加了一组用于 创建、加载、检查和应用 “RefMods” 的节点——这些是 MiniMax H3 模型（图像、视频和音频参考）的可复用参考包。
• 这些节点 不会训练 MiniMax H3 或替换其扩散核心；它们只是使用模型的 VAE 对视觉/音频数据进行编码，将潜在张量存储在 .safetensors 文件中，并在生成过程中将这些潜在变量反馈给模型。

关键概念

概念	含义
RefMod	一个包含视觉、视频或音频潜在变量以及元数据（token 数量、形状等）的 .safetensors 文件。
创建 H3 RefMod	将单个图像/视频/音频编码为 RefMod。
创建 H3 RefMod Master	将视觉 和 音频一起编码，生成一个包文件（或两个单独的文件）。
应用 H3 RefMod	将一个或多个加载的 RefMod 与生成提示结合，将存储的潜在变量作为条件提供。
加载 H3 RefMods / 加载 H3 RefMod Axis	浏览已注册的 refmods 文件夹并输出所选包的 UI 小部件。
Bundle	一个包含多种模态（视觉 + 音频）的版本 5 格式的 .safetensors 文件。

主要功能（截至 v0.2.6）

• 独立创建器 – 创建 H3 RefMod 和 创建 H3 RefMod Master 可以在没有下游节点的情况下运行；它们返回一个 details 字符串，并可选择写入文件。
• 掩码列表处理 – 收集 H3 RefMod 掩码 允许您将掩码列表（每个掩码保持其原始分辨率）提供给创建节点。
• 全参考视频采样 – 您可以在采样前指定因果帧数，避免旧的 16 帧硬限制。
• 紧凑的加法加载器 – 加载器节点从一个可见插槽开始；点击 + 添加 RefMod 可显示最多八个插槽，每个插槽都有自己的 全部 / 视觉 / 音频 选择器和强度控制。
• 单文件视觉 + 音频包 – 使用 save_layout=bundle，Master 节点会写入一个包含视觉和音频参考的 .safetensors 文件。
• 库和检查器 UI – 搜索/过滤存储的 RefMods，预览第一帧或完整视频，收听短音频预览，并查看 token 预算信息。
• 预算策略 – truncate（默认）自动削减多余的 token；error 在超出 token 预算时中止。视觉有单独的 max_tokens，音频有 audio_max_tokens，以及总体的 max_total_tokens 限制。
• 刷新 RefMods – 从文件系统更新下拉列表，无需重置整个 ComfyUI 模型列表。
• 跨平台支持 – 已在 Windows 和 Apple Silicon（M5 Ultra，macOS 27，PyTorch 2.14）上测试。可选的视频后端（opencv-python，imageio）。

安装

# 1️⃣ 克隆到 ComfyUI 的 custom_nodes 文件夹
 git clone https://github.com/Luisacaotica/ComfyUI-MiniMaxH3Mod \
    custom_nodes/ComfyUI-MiniMaxH3Mod
# 2️⃣ 重启 ComfyUI（或重新加载自定义节点）
# 3️⃣ 依赖项由 ComfyUI‑Manager 自动安装，或运行：
pip install -r custom_nodes/ComfyUI-MiniMaxH3Mod/requirements.txt

该包需要一个 已经支持 MiniMax H3 的正常工作的 ComfyUI 安装（即原生 H3 VAE 和条件节点）。不捆绑额外的 MiniMax‑H3 代码；该模块仅与现有 VAE 交互。

典型工作流程

1. 创建参考 – 将图像、短视频或音频片段拖入 创建 H3 RefMod（或 Master）节点。调整 max_tokens、budget_policy、mask/mask_list 等。按 运行；一个 .safetensors 文件出现在已注册的 refmods 文件夹中。
2. 加载参考 – 使用 加载 H3 RefMods（或 Axis 变体）选择保存的文件。您可以一次加载多个插槽并设置每个插槽的强度。
3. 在生成期间应用 – 将加载器输出连接到 应用 H3 RefMod，然后将生成的条件输入正常的 MiniMax H3 生成流程（例如，采样器节点）。模型将连同文本提示一起关注存储的潜在变量。
4. 检查 / 调整 – 打开 检查 H3 RefMod 查看 token 数量，预览存储的视觉/音频，并在重新运行前调整强度。

限制和已知问题

• 语音克隆不可用 – 音频提取有效，但当前实现无法可靠地转移说话者的身份。
• 无训练 – “训练”视觉模式（training / Compressed Reference）只是一个潜在池化 + 可选细化步骤；它 不会 训练 LoRA 或任何其他模型。
• Token 预算是硬性的 – 超出 max_tokens（视觉）或 audio_max_tokens 会中止，除非您选择 truncate。预算不保证质量；它只限制注意力成本。
• 音视频同步不保证 – 包分别存储视觉和音频潜在变量；它们不会在时间上对齐，除非源文件本身提供。
• 仅文件系统持久化 – RefMods 作为 .safetensors 保存在磁盘上；它们不受节点包的版本控制。
• 平台怪癖 – 主要在 Windows 上测试；Apple Silicon 支持存在，但可能无法覆盖所有工作流程。

从哪里开始

• 该存储库附带一个演示包：mods/vanellope_example.safetensors。安装后，它会在加载器下拉菜单中显示为 vanellope_example。将其以强度 1.0 插入 应用 H3 RefMod，并尝试类似 “a candy racer in a karting scene” 的提示。

进一步阅读

• 完整变更日志：CHANGELOG.md
• 验证和已知限制：REVIEW_FOLLOWUP.md
• 包文件格式详情：BUNDLE_FORMAT.md

---

ComfyUI‑MiniMaxH3Mod 是一个 专注于存储和条件 的 MiniMax H3 扩展。它让艺术家可以一次捕获视觉/音频参考，并在后续生成中高效复用，而无需重新训练模型。