在 ComfyUI 中執行 MiniMax H3 需要嚴格遵守空間與時間網格規則，以避免張量形狀錯誤、無聲 MP4 匯出或模型崩潰。MiniMax H3 透過在單次前向傳遞中合成 2K 影片與原生同步立體聲來解決這些瓶頸。
重點摘要：MiniMax H3 ComfyUI 工作流程
- 原生多模態傳遞： MiniMax H3 在單次 ComfyUI 擴散傳遞中直接合成 2K 影片與同步的 32 kHz 立體聲。
- 硬體門檻： 執行 INT8 量化至少需要 16 GB VRAM，建議 24 GB 以原生 2K 渲染。
- 空間網格規則： 畫布與關鍵影格解析度必須嚴格可被 32 整除，例如 1344×768，以避免空間 VAE 張量形狀錯誤。
- 時間網格公式： 片段長度必須符合「總影格數 = 17k + 5」方程式（24fps 下的 5、22、39、56、141 影格），以避免潛在截斷。
- 速度優化： 支援官方 8 步 Turbo LoRA，可將渲染時間降低約 60%，CFG 鎖定在 1.0。
文字轉影片（T2V）依賴純文字驅動的潛在初始化，而影像轉影片（I2V）則使用 first_frame、last_frame 或 MiniMaxH3AddGuide 條件節點來錨定運動軌跡。以下章節將詳細說明兩種管線的完整環境設定、節點接線圖與故障排除協定。
必要先決條件與模型目錄結構
將 32B 文字編碼器放入 models/checkpoints 而非 models/text_encoders，會導致 ComfyUI 在圖形編譯期間凍結，或出現難以理解的 KeyError 錯誤。大多數設定失敗的原因是檔案放錯子資料夾，或使用標準 Qwen 權重取代 MiniMax H3 所需的客製化視覺文字編碼器。
系統相容性需求
在下載模型權重之前，請確認您的安裝符合以下基本硬體與環境規格：
- ComfyUI 核心： 版本 v0.30.0 或更高。
- 自訂節點： ComfyUI-MiniMaxH3-Easy 或官方 Comfy-Org 套件。
- GPU VRAM： 16 GB（INT8 最低）/ 24 GB（2K 建議）。
- 軟體堆疊： Python 3.10+ 搭配 PyTorch 2.4+ 與 CUDA 12.1+。
模型目錄放置對照表
從 Hugging Face 模型庫下載官方 MiniMax H3 開源模型權重，並將每個檔案放入指定的目標子資料夾。
| 模型類別 | 確切檔案名稱 | 目標目錄 | 備註與精度 |
| 擴散模型（T2V/FL2V） | minimax_h3_fl2va_pruned_int8_convrot.safetensors | ComfyUI/models/diffusion_models/ | 核心 INT8 量化擴散模型 |
| 擴散模型（Ref2V） | minimax_h3_ref2va_pruned_int8_convrot.safetensors | ComfyUI/models/diffusion_models/ | 參考引導圖形所需 |
| 文字編碼器 | qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors | ComfyUI/models/text_encoders/ | 自訂 4 位元視覺語言權重 |
| 影片 VAE | minimax_h3_video_vae_fp16.safetensors | ComfyUI/models/vae/ | FP16 視覺空間解碼器 |
| 音訊 VAE | minimax_h3_audio_vae_fp32.safetensors | ComfyUI/models/vae/ | FP32 聲學解碼器（防止截波） |
| Turbo LoRA（選用） | minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors | ComfyUI/models/loras/ | 啟用 8 步快速推理 |
關鍵安裝說明
qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors 檔案是專為 MiniMax H3 提示條件微調的自訂 4 位元 AWQ 量化視覺文字編碼器（Qwen3-VL 架構）。請勿將其與 text_encoders 資料夾中的標準語言轉換器混用，因為通用語言模型缺少潛在影片生成所需的多模態視覺投影。
建置文字轉影片（T2V）ComfyUI 節點圖
在 ComfyUI 中建置乾淨的文字轉影片（T2V）節點圖，需要以嚴格的線性順序路由文字嵌入、空間解析度設定與潛在影格張量。
節點套件說明： 本工作流程指南中使用的節點名稱（如 MiniMaxH3TextToVideo 與 MiniMaxH3ImageToVideo）參考自 ComfyUI-MiniMaxH3-Easy 自訂套件。如果您使用官方 Comfy-Org 核心套件，這些操作會拆分為獨立的 MiniMaxH3Sampler 與 MiniMaxH3Conditioning 節點。
逐步 T2V 節點接線指南
設定 T2V 潛在生成需要在執行取樣器傳遞之前，先隔離文字條件與空間參數。
- 文字編碼器接線： 將文字提示節點路由到 Qwen3-VL 視覺文字編碼器載入器。將輸出張量直接傳入 MiniMaxH3TextToVideo 節點的正向提示條件埠。
- 空間維度計算： 將 ResolutionSelector 的輸出值導入 ImageScaleToTotalPixels。此步驟計算像素分配，同時強制空間維度保持可被 32 整除。
- 取樣器與潛在生成： 將模型權重、正向條件張量與解析度參數直接路由到 MiniMaxH3TextToVideo，以生成原始影片潛在。
- VAE 解碼與影片匯出： 將潛在張量傳送至 minimax_h3_video_vae_fp16 進行解碼，然後將渲染的影格批次直接導入 SaveVideo。
T2V 節點路由矩陣
若要建置此圖形而不產生中斷的依賴關係，請遵循以下確切的節點埠連接：
| 來源節點 | 輸出埠 | 目標節點 | 輸入埠 | 工作流程功能 |
|---|---|---|---|---|
| Qwen3-VL 編碼器 | CONDITIONING | MiniMaxH3TextToVideo | positive | 引導文字編碼器接線 |
| ResolutionSelector | WIDTH / HEIGHT | ImageScaleToTotalPixels | width / height | 設定寬高比邊界 |
| ImageScaleToTotalPixels | IMAGE_BOUNDS | MiniMaxH3TextToVideo | resolution | 修正 32 像素空間網格 |
| MiniMaxH3TextToVideo | LATENT | VAEDecode | samples | 控制 T2V 潛在生成 |
| VAEDecode | IMAGE | SaveVideo | pixels | 渲染最終 MP4 影片輸出 |
MiniMax H3 幾乎完全依賴由 Qwen3-VL 視覺語言模型解析的詳細正向提示，這意味著傳統的負向條件節點會增加不必要的計算負載，而不會改善輸出品質。將 SaveVideo 直接連接到影片 VAE 解碼節點，可確保以 24fps 正確渲染 MP4，而不會丟失尾端影格。
建構影像轉影片（I2V）與首/尾影格工作流程
嘗試將靜態肖像動畫化或橋接兩個關鍵影格，通常會導致主體劇烈扭曲，或當起始與結束影像相差幾個像素時立即出現張量形狀崩潰。將標準文字管線轉換為影像轉影片（I2V）工作流程，需要更換基礎取樣器節點，並在初始與最終影格之間建立精確的影像條件管線。
關鍵影格插值與節點配置
若要從 T2V 轉換為首尾影格（FL2V）影片生成，請將 MiniMaxH3TextToVideo 替換為 MiniMaxH3ImageToVideo。此節點暴露了專用的 first_frame 與 last_frame 輸入埠，讓您定義起始狀態、結束狀態或完整的形變過渡。
- 載入影像節點： 在畫布上放置兩個 LoadImage 節點，以容納初始與目標關鍵影格。
- 尺寸匹配： 將影像輸出路由至 GetImageSize 以提取原始寬高尺寸。這可防止張量在進入取樣器之前發生空間網格不匹配。
- 張量條件： 將處理後的像素張量連接到 first_frame 以進行標準單一影像動畫，或同時填入 first_frame 與 last_frame 以執行關鍵影格插值。
I2V 與 FL2V 節點連接矩陣
| 來源節點 | 輸出埠 | 目標節點 | 輸入埠 | 管線功能 |
|---|---|---|---|---|
| LoadImage（起始） | IMAGE | MiniMaxH3ImageToVideo | first_frame | 建立初始影像條件 |
| LoadImage（結束） | IMAGE | MiniMaxH3ImageToVideo | last_frame | 設定 FL2V 形變的終端影格 |
| GetImageSize | WIDTH / HEIGHT | ResolutionSelector | width / height | 將輸入寬高比鎖定為 32 的倍數 |
| Qwen3-VL 編碼器 | CONDITIONING | MiniMaxH3ImageToVideo | positive | 透過文字提示引導運動軌跡 |
| MiniMaxH3ImageToVideo | LATENT | VAEDecode | samples | 將 FL2V 潛在傳送至影片 VAE |
MiniMax H3 強制執行關鍵影格輸入之間的嚴格維度一致性。兩個關鍵影格必須具有完全相同的空間解析度。如果 first_frame 與 last_frame 尺寸不同，取樣將在潛在初始化期間停止。將兩個影像路由至同一個縮放節點，以確保相同的像素尺寸。
使用 MiniMaxH3AddGuide 進階參考引導
標準的影像轉影片圖形僅控制第一與最後影格，使得中間動作未錨定。MiniMaxH3AddGuide 節點透過在生成時間軸上的任何特定 frame_idx 處錨定參考影像、多影格影像批次或音訊軌道，解決了此問題。
MiniMaxH3AddGuide 的核心功能
| 參數輸入 | 錨定行為 | 約束規則 |
|---|---|---|
| frame_idx | 指定確切的目標影格索引 | 負值從影片結尾向前計數。 |
| 影像 / 多影格 | 鎖定角色一致性或場景佈局 | 少於 5 個影格的批次使用第一個影像；5 個影格以上的批次對齊 $17k + 5$ 片段長度（5、22、39）。 |
| 音訊軌道 | 在索引處對齊對話或音效 | 自動裁剪至剩餘的影片長度。 |
如何串聯錨點節點以進行參考影片生成
串聯多個 MiniMaxH3AddGuide 節點可實現完整的參考影片生成（R2V）：
- 主要角色錨點： 將正向條件連接到 frame_idx 設為 0 的 MiniMaxH3AddGuide，以鎖定開始時的角色身份。
- 中段動作關鍵影格： 串聯第二個 MiniMaxH3AddGuide 節點，在 frame_idx 60 處餵入關鍵影格影像，強制角色在場景中間達到特定姿勢。
- 音訊耦合： 將目標配樂連接到音訊輸入埠，並傳入您的 audio_vae，直接將聲音同步至該時間軸偏移處。
串聯這些條件引導可維持時間穩定性，而無需強制擴散取樣器重新初始化潛在。
透過雙 VAE 路由整合同步原生音訊
創作者通常花費數小時在影片編輯軟體中手動對齊外部語音軌道，卻仍面臨不自然的唇形漂移或不匹配的環境噪音。MiniMax H3 透過依賴真正的多模態生成，在單次前向傳遞中同時合成影片影格與 32 kHz 立體聲，消除了後製音訊對齊。
單次傳遞流的架構
與傳統的管線（在影片渲染後串聯獨立的文字轉語音模型）不同，MiniMax H3 將文字、影像與時間線索處理成統一的潛在空間。在去噪階段，SamplerCustomAdvanced 輸出包含視覺與聲學特徵圖的複合潛在負載。這種聯合合成保證了精確的對話同步與有機的音效生成，與畫面動作精確對齊。
雙 VAE 解碼與節點配置
要將原始潛在轉換為可播放的媒體，圖形在 MP4 多工之前將輸出分為兩個獨立的解碼路徑。
| 節點組件 | 模型資產 / 精度 | 功能 | 輸出目的地 |
|---|---|---|---|
| 影片 VAE 載入器 | minimax_h3_video_vae_fp16.safetensors | 將視覺潛在解碼為 RGB 影格序列 | VAEDecode -> CreateVideo（影片串流） |
| 音訊 VAE 載入器 | minimax_h3_audio_vae_fp32.safetensors | 將聲學潛在解碼為未壓縮音訊信號 | VAEDecodeAudio -> CreateVideo（音訊串流） |
| 影片儲存器 | SaveVideo | 多工影片與原生立體聲音訊串流 | 編碼後的 MP4 檔案 |
技術節點設定
- 載入雙 VAE： 在畫布上新增兩個不同的 VAELoader 節點。將第一個指向 minimax_h3_video_vae_fp16.safetensors，第二個指向 minimax_h3_audio_vae_fp32.safetensors。
- 執行雙 VAE 解碼： 將取樣器的視覺潛在輸出路由至 VAEDecode，將音訊潛在區塊路由至 VAEDecodeAudio。將 minimax_h3_audio_vae_fp32 維持在 FP32 精度可防止背景配樂中的截波偽影與頻率失真。
- 透過 SaveVideo 多工： 將解碼後的影像張量與未壓縮的音訊波形饋入 CreateVideo 或直接饋入 SaveVideo。該節點處理最終容器封裝，寫入帶有內嵌立體聲的完整 24fps MP4 檔案。
這個原生雙串流設定直接在 ComfyUI 內提供相位精確的音訊執行，無需外部唇形同步外掛程式。
解析度計算、寬高比限制與影格網格對齊
在 ComfyUI 中輸入標準的 1920x1080 解析度或將片段長度設為 60 影格，會立即導致渲染佇列因張量形狀錯誤而崩潰，或產生嚴重扭曲的邊緣接縫。MiniMax H3 對空間尺寸與片段持續時間強制執行嚴格的數學邊界，因為其 3D VAE 架構會跨特定空間區塊與時間步長壓縮影片潛在。
空間尺寸與寬高比預設
空間 VAE 會將輸入降採樣 32 倍。如果目標寬度或高度不是嚴格的 32 的倍數，擴散取樣器將在邊界張量分配期間失敗。該模型以 768px 原生短邊為目標，在視覺保真度與其目標百萬像素預算之間取得平衡。
| 寬高比 | 預設尺寸（像素） | 可整除性檢查 | 目標方向 |
|---|---|---|---|
| 16:09 | 1344 x 768 | 1344 / 32 = 42，768 / 32 = 24 | 寬螢幕橫向 |
| 9:16 | 768 x 1344 | 768 / 32 = 24，1344 / 32 = 42 | 垂直手機 / UGC |
| 1:01 | 1024 x 1024 | 1024 / 32 = 32，1024 / 32 = 32 | 方形影格 |
| 21:09 | 1536 x 672 | 1536 / 32 = 48，672 / 32 = 21 | 電影級超寬 |
使用非標準像素尺寸會強制 VAE 填充或拉伸特徵圖，從而降低精細紋理細節。
17k + 5 影格網格規則
時間維度對齊遵循同樣嚴格的公式。為了保持在 MiniMax H3 影片長度限制 內，該架構以 17 影格潛在區塊加上 5 影格尾部初始化來處理影片序列。為避免時間截斷或無聲的 VAE 解碼崩潰，每次渲染必須滿足 17k + 5 影格網格方程式，其中 k 代表整數步數計數器。
在標準 24fps 影格率下，此數學公式決定了確切的時間持續時間：
- k = 0（5 影格）： ~0.21 秒（微動作或靜態爆發）
- k = 1（22 影格）： ~0.91 秒（快速動作片段）
- k = 3（56 影格）： ~2.33 秒（短鏡頭序列）
- k = 8（141 影格）： ~5.87 秒（完整標準片段限制）
將目標計數設為 60 會強制 ComfyUI 丟棄 4 個影格至 56（k=3），在取樣期間浪費 VRAM 計算。在排入生成批次之前，始終將節點參數對齊至確切的 17k + 5 步長邊界。
速度優化：啟用 8 步 Turbo LoRA 執行
在消費級 GPU 上，等待單個 6 秒預覽影片渲染超過六分鐘，使得快速提示迭代幾乎不可能。標準取樣運行需要 20 到 30 步，在調整動作線索、測試相機移動或評估關鍵影格過渡時，會造成嚴重的操作瓶頸。
整合蒸餾權重
整合官方 minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16 權重檔案，可將取樣傳遞次數減少至 8 步推理工作流程。此蒸餾過程實現了顯著的生成速度優化，而不會犧牲整體視覺連貫性。
要在 ComfyUI 中配置此蒸餾設定：
- 放置模型權重： 將 minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors 移至您的 ComfyUI/models/loras/ 目錄。
- 接線 LoraLoader 節點： 在饋入取樣器之前，將主要擴散模型張量透過 LoraLoader 節點路由。將 turbo_model_strength 設為 1.0。
- 調整步數： 將 MiniMaxH3Sampler 節點中的 steps 參數從標準的 20 降低至恰好 8。
- 鎖定 CFG 尺度： 將無分類器引導尺度參數強制設為 1.0，以避免過飽和。
效能基準：標準與 Turbo 執行對比
| 參數 / 基準指標 | 標準取樣管線 | 8 步 Turbo LoRA 執行 |
|---|---|---|
| 推理步數 | 20 至 30 步 | 8 步 |
| 渲染時間 (RTX 4090, 2K) | ~380 秒 | ~145 秒 |
| CFG 引導尺度 | 3.5 至 6.0 | 固定為 1.0（蒸餾後） |
| 主要生產用途 | 最終主渲染 | 快速預視覺化與場景草稿 |
| 時間穩定性 | 完整重建 | 複雜粒子物理上出現輕微邊緣抖動 |
當執行 minimax_h3_fl2v_turbo_8step 時，將 CFG 設為高於 1.0 會強制進行不必要的雙重條件傳遞，導致高動態影格上出現極端顏色燒灼、對比過曝與空間撕裂。啟動 turbo_mode 並將 Turbo LoRA 強度固定為 1.0，讓創作者能在三分鐘內驗證複雜的相機移動，然後再投入完整的 20 步生產渲染。
常見 ComfyUI MiniMax H3 圖形錯誤疑難排解
MiniMax H3 圖形中的大多數操作失敗源於輕微的張量對齊不匹配、未連結的音訊解碼器，或在模型載入期間的 GPU 記憶體瓶頸。
診斷指南與快速修復
-
CUDA 記憶體不足（OOM）
- 主要原因： 在 16GB VRAM GPU 上同時載入 32B 文字編碼器與 int8 擴散權重，且未啟用記憶體卸載。
- 逐步修復： 在 ComfyUI 啟動腳本中添加 --lowvram 或 --medvram 啟動標誌。對於記憶體緊張的 GPU 設定，請考慮使用 GGUF 量化在 ComfyUI 中執行 MiniMax H3，以降低基本記憶體需求。確保 qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors 嚴格放置在 models/text_encoders/ 內，以便在文字解析與取樣傳遞之間進行 VRAM 卸載。
-
形狀不匹配錯誤
- 主要原因： 自訂寬度/高度值或輸入關鍵影格影像違反了所需的 32 像素空間可整除性網格。
- 逐步修復： 在取樣器之前插入 ResolutionSelector 或 ImageScaleToTotalPixels 節點，以強制所有畫布與影像尺寸對齊至最接近的 32 的倍數。
-
匯出時缺少音訊軌道
- 主要原因： 音訊 VAE 路徑在圖形執行期間未連結或繞過。
- 逐步修復： 將 minimax_h3_audio_vae_fp32 連接到 VAEDecodeAudio 節點，然後將解碼後的音訊潛在與影片串流一起導入 SaveVideo 節點的音訊埠。
-
GetImageSize 節點失敗
- 主要原因： 關鍵影格寬高比不匹配，或饋入 I2V 取樣器輸入的無效多影格影像批次。
- 逐步修復： 將初始與終端影像都透過統一的 ImageScaleToTotalPixels 節點運行，以在潛在初始化之前將關鍵影格鎖定為相同尺寸。
-
ComfyUI Manager 缺少節點警告
- 主要原因： 所需的 MiniMax H3 自訂節點套件未索引或本地環境中缺失。
- 逐步修復： 開啟 ComfyUI Manager，選擇「安裝缺少的自訂節點」，搜尋 ComfyUI-MiniMaxH3-Easy，點擊安裝，然後重新啟動 ComfyUI。
解決記憶體下降與節點註冊衝突
許多教學忽略了 ComfyUI 如何在連續生成之間管理 VRAM 分配。如果您在第二次或第三次渲染嘗試時突然遇到 CUDA 記憶體不足錯誤，儘管初始傳遞成功，表示 ComfyUI 將文字編碼器保留在 VRAM 中。在啟動腳本中設定明確的卸載標誌，可在取樣器步驟之間釋放已分配的記憶體。
開啟社群 JSON 檔案時，ComfyUI Manager 缺少節點警告通常表示節點註冊表過時。安裝 ComfyUI-MiniMaxH3-Easy 可直接修復這些缺少的依賴項。對於 I2V 管線，解決 GetImageSize 失敗或形狀不匹配錯誤，需要確保初始與終端關鍵影格影像符合目標像素邊界。
