ComfyUI H3 渲染核心 (H3 Render Core)

ComfyUI H3 渲染核心 (H3 物理渲染與調度工序)

工序定位：短劇物理生成核心工序。 核心原則：不寫死 ComfyUI 節點號，嚴防 Windows WDDM 驅動鎖死，強制執行單人發音鎖定與潛空間尺寸安全檢查。

---

1. 運行契約與輸入輸出

• 輸入：
  1. plan.json（含運鏡、對白、時序 175 幀）；
  2. 第 2 工序的定幀墊圖：segments/{seg_id}_keyframe.png；
  3. style_bible.json。
• 輸出：
  1. H3 原生生成視頻：segments/{seg_id}.mp4（帶原生音畫）；
  2. 顯存狀態監控日誌與渲染耗時臺賬。

---

2. 硬核 SOP：三大防翻車物理鐵律（帶數字特徵與報錯反例）

2.1 鐵律一：潛空間尺寸 32 整除定律（防 VAE 潛空間崩潰）

• 現象/報錯： RuntimeError: shape '[1, 24, 1, 1, 15, 2, 26, 2]' is invalid for input of size 38160
• 根因：MiniMax H3 的 3D Patch 尺寸要求寬度必須被 16 整除，且商必須為偶數（即 width % 32 == 0）。
• 判據與處置：
  • 嚴禁使用：848×480（848/16=53 為奇數，無法被 patch=2 整除，必崩！）；
  • 強制鎖定：標準寬屏一律鎖定 832×480（832/16=52 為偶數，52/2=26 完美整除！）。

2.2 鐵律二：Windows WDDM 驅動互斥鎖防禦（防暴慢 15 倍）

• 現象： 在 Windows 下啟用 cudaMallocAsync 或多流異步搬運（async-offload）後，單步採樣從 40 秒暴跌至 600 秒（單段耗時高達 70 分鐘）。
• 根因：Windows 的 WDDM 驅動模型在跨 CUDA Stream 搬運大權重時，會產生嚴重的內核互斥鎖爭搶（Mutex Lock Contention）。
• 處置（ComfyUI 黃金啟動參數）：

  python <COMFYUI_PATH>/main.py --disable-auto-launch --disable-mmap --disable-cuda-malloc --disable-async-offload --listen 127.0.0.1 --port 8188
  

  利用原生緩存與單流調度避開驅動鎖，單段生成耗時穩定保持在 350 秒（5.8 分鐘）。

2.3 鐵律三：單人發音與閉嘴抑制指令裝配（消滅全員動嘴）

在構建 [Subject 1] 與 [Action 1] 時，必須強制執行分離裝配：

• [Subject 1]：Primary speaker: [SpeakerName], alongside [ListenerName] (silent listener).
• [Action 1] 核心原語：

  Only [SpeakerName] is actively speaking with natural, synchronized Mandarin lip movement, [Action]. 
  Crucial requirement: [ListenerName] remains strictly silent with lips tightly sealed and mouth completely closed, neither speaking nor making any mouth motions, showing a tense glare. 
  In the final 1.2 seconds, all characters firmly close their mouths, ending on a tense silent glare.
  

---

3. 硬核 SOP：顯存防碎片與斷點續產保護

1. 分鏡間顯存回收： 每個分鏡渲染完畢後，必須調用 ComfyUI /free 端點：

   payload = {"unload_models": False, "free_memory": True}
   

   清空 PyTorch 中間 3D 潛空間張量緩存，防止長週期連續生產累積 OOM。
2. 斷點續產防重複渲染： 檢測 segments/{seg_id}.mp4，若檔案已存在且大小大於 100KB，直接打印 [復用] 跳過，支持秒級斷點續跑。

---

4. 專屬工具腳本

• H3 執行圖組裝與調度引擎：python scripts/h3_render_orchestrator.py --plan plan.json --server 127.0.0.1:8188