closerAI-minimaxH3-Helper套件节点 使用手册

minimaxH3-套件节点。

20260823 更新至V2.0版本：：

minimaxH3-套件节点。20260823 V2.0版本

closerAI-minimaxH3-Helper 套件

项目定位

本项目是一个即插即用的 ComfyUI Helper 套件，围绕 MiniMax-H3 提供提示词结构化、参考图分析、音画规划、低显存运行、ClipProj 条件编码与实验性加速能力。所有功能均在 custom_nodes 插件目录内实现，不修改 ComfyUI 内部源码，因此不会阻碍 ComfyUI 后续升级。旧目录名和旧节点 ID 继续保留，已有工作流无需重建。

安装目录：

ComfyUI/custom_nodes/closerAI-minimaxH3-PromptHelper

更新节点后必须完全重启 ComfyUI。

节点总览

H3 音频修复

将 VAEDecodeAudio 的 AUDIO 输出接入 H3音频修复，再把修复后的音频接到视频合成或保存节点。默认值适合普通网络视频：目标 RMS -16 dBFS、峰值上限 -1 dBFS、压缩强度 0.30、噪声门 -55 dBFS、淡入淡出 15ms。

对白增强 会使用较明确的压缩，改善声音存在但过小、动态过大的对白。环境声增强 会减弱压缩并把噪声门降低到不高于 -70 dBFS，避免把雨声、风声和房间底噪误删。仅响度标准化 不执行噪声门和压缩，适合原始声音结构已经正确的结果。

报告中的响度是 RMS dBFS，不是严格的 BS.1770 LUFS。节点只能修复已经存在的波形，不能恢复模型没有生成的音效，也不能修复错误语言。非英语对白应先经过 音频策略分析；高风险任务优先使用原生 32B 编码器。

32B 与 4B 音频基准

使用相同提示词、首帧、seed、分辨率、帧数、模型、LoRA 和采样设置分别生成两次。将原生 32B 工作流的 VAEDecodeAudio 输出接到 参考音频_32B，将 4B ClipProj 工作流的输出接到 测试音频_4B，再执行 32B-4B音频基准。

节点报告时长、采样率、声道、RMS dBFS、峰值、峰均比、削波、静音占比、频谱重心、频谱带宽、85% 滚降频率、波形相关性和对数频谱距离，并输出可归档的 JSON。波形相关性只适用于时间对齐且内容相同的音频；使用不同 seed 时不能把它直接解释为质量分数。

当前节点不加载 ASR 或 CLAP，因此对白语言和环境声完整性会明确显示“未评估”。完整语义基准仍需要目标台词、声音事件标注和外部模型。RMS dBFS 也不能冒充 BS.1770 LUFS。

音频残差投影

可直接识别mmh3-*-ClipProj[-celeb][-mlp][-v3-mlp].safetensors。新版支持没有线性W路径的纯MLP v3矩阵、INT8视觉塔分页回退，并真正区分streaming整块加载与dynamic逐层分页。带-mlp的矩阵会自动启用文件内的通用残差网络并保持其保存精度；加载状态会显示MLP残差或纯MLP投影。-celeb与-mlp属于上游通用语义投影，下面的closerAI音频残差则是可选的额外音频专用校正，两者可以叠加，但必须分别完成同seed验证。

GPU流式编码后释放会先整块加载编码器、编码后整体释放；GPU动态分页编码后释放（INT8视觉可用）交给ComfyUI逐层分页，峰值更低但通常更慢。0.1.13已为INT8参考图视觉塔的位置嵌入增加安全回退，旧版仅文本可用、带图失败的问题不再需要强制常驻模式规避。

推理接线：

ClipProj优化加载器.CLIP
  -> 音频残差投影.CLIP
  -> MiniMaxH3ImageToVideo.clip / MiniMaxH3ReferenceToVideo.clip

将 closerai_h3_audio_residual_v1 safetensors 放入 ComfyUI/models/clip_projections/，重启或刷新节点后选择该权重。残差强度=1.0 是训练标定值；建议以同 seed 从 0.5、0.75、1.0 做 A/B。选择 关闭 或强度 0 时，输出与基础 ClipProj 一致。

普通投影、LoRA 或未知 safetensors 不会出现在残差下拉框。节点还会验证 2560 -> 5120 等实际维度，不匹配时停止执行。

ClipProj 优化加载器

推荐连线：

closerAI ClipProj优化加载器.CLIP
    -> MiniMaxH3ImageToVideo.clip
    -> positive / latent
    -> guider / sampler

Ref2VA 时将同一个 CLIP 输出接到 MiniMaxH3ReferenceToVideo.clip。编码器只负责生成 Conditioning，不参与后续扩散采样。

8GB GPU编码后释放 的执行顺序为：GPU 加载 4B 编码器、生成 Conditioning、将 Conditioning 保存到 CPU、清空投影缓存、卸载编码器，随后原生 H3 节点才进行 VAE 编码与 DiT 采样。这一策略解决的是编码器与视频模型同时占用显存的问题；它不能消除 W4A8 主模型自身的采样临时张量峰值。

CPU最低显存 不占用编码阶段 GPU，但速度较慢。GPU流式编码后释放 适用于纯文本；部分 int8 视觉塔在流式图像编码时可能失败。GPU常驻（大显存） 不自动释放，只适合显存充足的用户。

当需要强制规定工作流执行顺序时，把已完成阶段的数据接入 ClipProj显存释放.执行顺序输入，再从 执行顺序输出 接到后续支持任意类型的节点。普通 I2V/Ref2VA 工作流使用优化加载器的自动释放即可，不必额外添加释放节点。

可视化素材编排器

closerAI-minimaxH3-MaterialCopilot 是嵌入式可视化节点：素材连接、@素材 想法编写、创作规格、服务配置、LLM 生成与中英文结果预览都直接显示在节点本体中，不再依赖普通参数控件或弹窗。素材卡片会显示每类已连接数量，点击 @Image1、@Video1、@Audio1 可插入到基础想法。

面板的“资产管理”区可将 PNG、JPG、WEBP、GIF 图片上传至指定 图像_N 槽位。上传动作只在当前工作流中创建标准 LoadImage 节点并自动连线，不修改 ComfyUI 内部文件；上传记录会显示在对应资产卡片中。视频帧、视频音轨和独立音频仍需要从画布中相应的加载节点接入，以保持与用户已安装的视频/音频节点兼容。

支持的输入容量与官方 MiniMaxH3ReferenceToVideo 对齐：

示例基础想法：

@Image1 的女孩与 @Image2 的面具女孩在咖啡馆发生争吵；
@Video1 提供快节奏追逐动作参考；@Audio1 作为环境音乐风格参考。

素材编排器复用 PromptHelper 的 运行模式、API 提供方、接口地址、模型名称、API 密钥 与代理配置。选择 直接调用 API 时，点击 使用第三方 API 处理 会直接请求本插件的本地 HTTP 路由，再由该路由调用所配置的 OpenAI 兼容 API 或 Google Gemini API；不进入 ComfyUI 队列，结果直接显示在面板的中英文预览区。API 密钥不会写入面板结果或返回给浏览器。

直接处理模式会传递基础想法、@素材 清单和素材角色说明。ComfyUI 尚未执行工作流时，后端无法安全读取任意上游节点的 IMAGE/AUDIO 张量，因此直接模式不会假装已分析连接图片；需要让视觉 LLM 对连接素材逐张分析时，请按常规方式执行该节点所在工作流。

选择 本地 LLM 指令 时，按钮会输出本地 LLM 指令而不发送任何 API 请求；将该输出接到本地视觉 LLM，再接 LocalResultParser。将 英文提示词 输出接到 MiniMaxH3ReferenceToVideo.prompt，再将相同素材按类型连接到原生 H3 节点的 ref_image_*、ref_video_*、ref_video_audio_*、ref_audio_* 输入。

视频素材会抽取中间代表帧供视觉 LLM 分析；音频不被伪装成已被 LLM 听取，需在 素材角色说明 中描述其情绪、节奏、音色或用途。节点会输出 素材清单，明确 @ImageN -> <Picture N>、@VideoN -> <Video N>、@AudioN -> <Audio N> 的对应关系。

提示词助手

在线 API 模式

运行模式=直接调用 API 时，节点输出：

• 英文提示词：接入 MiniMax-H3 的 prompt。
• 中文提示词：用于审阅、修改与归档。
• 本地LLM指令：在线模式下为空。

支持 OpenAI 兼容接口、Google Gemini 与 HTTP/Mixed 代理，例如 http://127.0.0.1:7890。不支持 SOCKS 端口。

API Key 建议使用环境变量，避免密钥被保存进工作流：

CLOSERAI_MINIMAXH3_API_KEY
GOOGLE_API_KEY

参考图可接入 1-9 张；使用 ReferenceImageBatch 时，将输出接到 PromptHelper 的参考图输入，并把 参与分析的图像数量 设置为实际连接数量。图像顺序对应 <Picture 1>、<Picture 2> 等。

本地 LLM 模式

运行模式=本地 LLM 指令 不发送网络请求。将 本地LLM指令 接到任意本地文本/视觉 LLM 节点；本地模型输出再接 LocalResultParser。

本地模型必须返回：

<EN>
English MiniMax-H3 prompt
</EN>
<ZH>
中文提示词
</ZH>

标准 H3 图生视频接线

Load Image -> ImageResize+ -> MiniMaxH3ImageToVideo.first_frame
PromptHelper.英文提示词 -> MiniMaxH3ImageToVideo.prompt
CLIPLoader(CPU) -> MiniMaxH3ImageToVideo.clip
Video VAE -> MiniMaxH3ImageToVideo.vae
MiniMaxH3ImageToVideo -> SamplerCustomAdvanced.latent_image

UNETLoader -> TurboLoRA-Pruned -> BasicGuider.model
                                  -> BasicScheduler.model
BasicScheduler(SIGMAS) -> SamplerCustomAdvanced.sigmas
TurboSampler(SAMPLER) -> SamplerCustomAdvanced.sampler
SamplerCustomAdvanced -> Video/Audio VAE Decode -> SaveVideo

Turbo 工作流必须使用：

BasicScheduler: scheduler = simple, steps = 4, denoise = 1
SamplerCustomAdvanced.sampler: closerAI-minimaxH3-TurboSampler

不要继续使用 KSamplerSelect=res_multistep 作为 4-step Turbo 采样器。H3 的视频和音频使用不同 flow schedule；TurboSampler 会分别按视频 shift=12 与音频 shift=3 推进。

在 ComfyUI 0.31 及以上版本中，原生 ModelSamplingAV 已负责音视频流的时间映射；TurboSampler 会自动切换到低显存 Euler 路径，避免重复变换音频。不要使用 sa_solver：它会保留多阶预测历史并增加采样临时显存，在 8GB、0.4MP、5 秒的 W4A8 工作流中可能在第一次 MLP 计算时 OOM。

8GB I2V 示例还会把 ClipProj显存释放 放在 MiniMaxH3ImageToVideo.LATENT 与 SamplerCustomAdvanced.latent_image 之间，并选择 仅 ClipProj 编码器。动态显存模式会自行管理 VAE 与 DiT；不要在每轮采样前强制卸载全部模型，否则 16GB 系统内存设备可能反复重建 10GB 以上的 staged 权重、触发大量 Pin error 和页面文件抖动，严重时导致 NVIDIA 驱动重置。

Turbo LoRA 与模型兼容性

原始 MiniMax-H3 Turbo LoRA 为非剪枝 H3 训练：其 AdaLN 输入为 2688 维。pruned_int8_convrot 模型的 AdaLN 输入为 8 维，两者不能直接合并。

因此 TurboLoRA-Pruned 的行为是：

• 注入普通注意力/MLP 等兼容投影层。
• 跳过 51 组不兼容 AdaLN 权重。
• 可改善部分普通 LoRA 行为，但不能宣称完整复现官方非剪枝 Turbo LoRA 的 4-step 效果。

同时支持 pruned 专用 LoRA，例如名称含 pruned_comfyui 的约 620MB 文件。这类文件本身不包含 AdaLN 权重，节点会直接注入其普通投影层，不再要求 51 组 AdaLN。

模型格式与 LoRA 训练架构必须一致：

TurboLoRA-Pruned 只接受 pruned 架构；不要把它接到非剪枝 GGUF。GGUF 是否可用取决于其转换来源的网络结构，不取决于 .gguf 扩展名。

完整官方 Turbo LoRA 应使用非剪枝 BF16 或完整 INT8 ConvRot 模型；这通常需要远大于 8GB 的显存。

TurboLoRA-Pruned 显存策略

8GB 推荐从以下设置开始：

低显存逐层加载：开启
LoRA加载策略：混合 GPU 缓存
混合GPU缓存上限（GB）：0.25

稳定后可依次测试 0.35、0.50。第一次 OOM 后回退到上一个稳定值。8GB 不应选择 全部 GPU 常驻。

中高显存用户可以关闭 低显存逐层加载，或将 LoRA加载策略 设为 全部 GPU 常驻。控制台出现下列日志表示相应策略已生效：

Low-VRAM streamed LoRA adapters enabled.
Hybrid GPU LoRA cache enabled: 0.25 GB.
GPU-resident LoRA adapters enabled.

8GB 显存建议

推荐起点：

分辨率：约 0.4MP，例如 480 x 864
时长：5 秒，约 124 帧
采样：simple / 4 steps
文本编码器：CPU
TurboLoRA：低显存逐层加载，或 0.25GB 混合缓存

ReservedVRAMSetter 应放在模型链路中并保证其输出实际接入后续模型节点。手动调参时一次只改变一个值：降低保留显存会提高 GPU 常驻比例，但更容易 OOM；增大保留显存更稳定但更慢。

不要在 8GB 上同时开启 Turbo LoRA、Speed、Spectrum 等多个模型运行策略。每次仅启用一种策略，并使用相同 seed 做 A/B 对比。

CLIPLoader 的 32B MiniMax H3 文本编码器应保持 CPU；将它移到 8GB GPU 会挤占 H3 采样所需显存。

常见问题

长视频导演与分段素材时间线

新增节点：

• closerAI-minimaxH3-LongVideoDirector：按用户选择的单一语言生成完整故事、分段提示词、素材变化和H3帧计划。
• closerAI-minimaxH3-SegmentSelector：手动读取指定段落的提示词与帧数。
• closerAI-minimaxH3-SegmentMaterialRouter：递归执行时只输出当前段真正使用的素材。
• closerAI-minimaxH3-ChainPlanAdapter：把导演计划编译成可断点恢复的递归计划。
• closerAI-minimaxH3-ChainLoopStart/Current/Context/Trim/SegmentCheckpoint/LoopEnd/Assemble：逐段采样、上下文续接、音画裁剪、检查点和最终拼接。
• closerAI-minimaxH3-ProgressPreview：只读查看已成功分段，可单段预览或顺序预览当前已完成部分。
• closerAI-minimaxH3-ContinuationPolicy：按显存档位选择连续上下文、视频交叉淡化和音频去点击参数，覆盖8GB~24GB设备。
• closerAI-minimaxH3-AutoHandover：在CPU上分析分段尾部冻结状态，给出安全尾部裁剪和Safe Tail Bridge建议。
• closerAI-minimaxH3-SeamlessAVJoin：对已解码的两段视频和音频执行帧级视频交叉淡化及毫秒级音频去点击拼接。

基本操作

可直接载入 example_workflows/closerAI-minimaxH3-20秒分段连续生成-8GB示例.json。示例已连接长视频导演、递归计划、当前段素材路由、两路独立图像引用、Motion Context、精确裁剪、检查点和最终拼接；运行前替换本机模型、LoRA、图片和音频文件。

1. 在长视频导演填写用户需求、总时长和每段目标时长。
   “视频需求”文本框可向下拖动增高；输入@会显示素材候选，方向键选择并按Enter/Tab即可插入。
2. 上传或从画布连接图片、视频帧和音频。
   点击面板生成时，当前有效的@ImageN会按编号排序并逐张独立识别，再把锁定的视觉事实交给导演LLM。控制台会输出标签、文件名、原始尺寸和短指纹，可据此核对@Image2实际发送的文件。断开连接或把上游图片节点设为忽略后，该素材不会发送；文件不可读取时会停止生成，不会跳过图片后继续造成编号错位。
3. 在每段卡片中点击素材标签，设置本段使用的素材。
4. 在“变化说明”中填写人物入场/离场、场景替换、服装变化或素材用途。
5. 先选择中文或英文，再点击“生成分段剧本”，在完整时间线检查该语言提示词。
6. 橙色标签表示计划使用但未连接；补齐素材后再执行工作流。
7. 已确认段落可锁定；重写本段会修复相邻连续状态，同时保持锁定段落不变。

LLM生成完成后，所选语言的提示词可以直接编辑。修改中的文本框会显示待保存状态；点击保存本段修改只提交当前段，点击底部保存全部修改提交所有段。保存会同步更新计划JSON、当前语言完整剧本和节点内部计划草稿。之后执行工作流时优先读取该草稿，不会再次请求LLM覆盖人工修改；只有点击重新生成完整计划或仅重写本段才会主动生成新内容。

执行提示词语言同时决定LLM输出Schema和递归采样语言：选择中文时只请求title_zh/opening_state_zh/closing_state_zh/transition_zh/prompt_zh，选择英文时只请求对应*_en字段。未选语言保持空值，不发送双语翻译请求，从而显著减少长计划Token。切换到计划中不存在的语言后必须重新生成；旧工作流未保存该字段时默认使用英文。

点击底部清空提示词会清空全部分段提示词和冻结计划，但保留用户需求、素材分配及生成参数。LLM生成完成或编辑保存后，分段卡片和提示词框显示绿色；未保存的编辑显示琥珀色。

节点标题区的“展开连接点”按钮用于显示完整的左右端口和标签；展开时节点会增加左右安全边距，方便检查或修改素材接线。再次点击“收起连接点”恢复紧凑的可视化面板。该状态随工作流保存。

高速动态清晰增强

示例：

• example_workflows/closerAI minimax_h3_Ref2VA动态清晰增强开关示例0815-8GB-Turbo版.json：低显存流程验证，二次分支使用Turbo LoRA。
• example_workflows/closerAI minimax_h3_Ref2VA动态清晰增强开关示例0815-质量版.json：移除Turbo LoRA，使用基础模型25步调度，适合16~24GB和最终保片。

生成进度预览

closerAI-minimaxH3-Helper / 长视频进度预览无需连接任何线路，也不会作为输出节点进入队列。顶部下拉框会列出output/h3_chains/下真实存在的生成批次；选择历史批次会固定预览该目录。点击“同步”会读取长视频递归计划的基础运行名称并开启“跟随最新”，面板每2秒只读检查对应的checkpoints/clip_*.json。

完整生成后分支重生成

新版工作流在长视频递归计划与连续生成开始之间加入closerAI-minimaxH3-PostRunBranch。该节点默认透传完整计划，不会改变正常生成。当前批次全部分段完成后，在进度预览中选择不满意的第N段，点击从本段分支重生成并确认：

1. 原批次保持不变；系统创建带branch_sNN_时间后缀的新运行目录。
2. 新分支复制第1至N-1段的媒体和完整检查点，不重新采样这些已接受段落。
3. 新分支删除第N段及之后的旧产物，从第N-1段的上下文检查点恢复，再自动生成第N段到结尾。
4. 后续段会基于重生成结果继续，因此人物、运动和镜头上下文不会沿用已废弃的旧第N段。
5. 分支完成后会重新生成manifest并自动合成新的最终视频。

可使用22或39帧并按实际工作流验证。自动交接对FI2VA/FL2VA的冻结尾帧最有效，Ref2VA仍以递归上下文为主。

自动无缝拼接

closerAI-minimaxH3-SeamlessChainAssemble直接接收递归循环输出的H3_CHAIN_MANIFEST，不需要用户手动提供上一段和当前段媒体。每段检查点会保存自动交接分析；最终拼接时节点按顺序读取分段文件，在CPU/FFmpeg上处理冻结尾帧、视频交叉淡化和生成音频去点击，不增加H3采样显存。

• 自动冻结尾帧：优先改善接缝，可能因移除检测出的冻结尾帧而略短于原计划时长。
• 兼容硬拼接：调用原有拼接行为，保持旧工作流的精确帧数与结果特性。
• 原closerAI-minimaxH3-ChainAssemble不会被删除；旧工作流继续使用它。增强工作流才替换为自动无缝拼接节点。

自动交接分析元数据只在新生成的分段检查点中存在。使用旧检查点恢复时，增强拼接器会把缺失元数据当作0帧裁剪，保持可恢复性。

素材变化规则

• 场景在第3段更换：第2段结尾必须提前出现入口、光线或运动方向，第3段从同一动作进入新场景。
• 人物在第4段更换：第3段应让旧人物离场或完成交接，第4段独立定义新人物，并禁止面部、服装和道具融合。
• 未在本段素材列表中的参考不会被素材路由节点传给H3，降低身份污染和额外参考条件开销。
• 修改素材后计划会失效并要求重新生成，避免旧提示词与新素材静默错配。

递归工作流连接

长视频递归计划输出的宽高、当前分段输出的提示词/长度/步数/种子，应连接到原生H3 conditioning和采样主体。当前分段编号同时连接到素材路由。解码后的图像与音频必须先经过分段音画裁剪，再同时连接分段检查点和连续生成结束。最终manifest连接拼接长视频。

递归节点内置自检和共享补丁标记，不修改ComfyUI文件。不要同时安装多个旧版Motion Context分支；如果已有其他插件独占了H3 PackedLayout补丁，节点会拒绝叠加并给出错误，而不是静默生成错误结果。

0811 FI2VA / Ref2VA 长视频示例

• closerAI minimax_h3低显存FI2VA长视频分段连续生成工作流0811.json：使用本机实际模型文件minimax_h3_fl2va_pruned_w4a8_mixed.safetensors。官方文件名是FL2VA，该工作流以首帧和后续5帧运动上下文维持连续性。
• closerAI minimax_h3低显存Ref2VA全能参考长视频分段连续生成工作流0811.json：使用minimax_h3_ref2va_pruned_w4a8_mixed.safetensors，3个图像槽、2个视频槽、对应视频音轨及2个独立音频槽已经接入长视频导演。排队前必须为已连接的加载器选择有效文件；不使用的加载器应断开。
• 两份示例都启用套件内置的ClipProj 0.1.13加载器和编码后显存释放，不再旁路到普通CLIPLoader。
• Ref2VA版通过分段图像/视频/音频读取节点传递当前段素材。只需在导演面板的分段素材计划中增删@ImageN、@VideoN、@VideoAudioN、@AudioN，未启用素材不会进入该段Ref2VA条件。
• 8GB环境保持ref_image_size=match；max会显著增加参考编码与采样成本。参考素材没有段内时间范围，一旦在某段启用便影响该段全部帧。

主题授权提示：请在后台主题设置-主题授权-激活主题的正版授权，授权购买：RiTheme官网