想在 NVIDIA DGX Spark 上用 ComfyUI 跑 MiniMax H3，安裝方式要改成 Ubuntu 的 Python 虛擬環境。
網路上常教的 Windows Portable、python_embeded、.bat 啟動檔，以及檔名帶 win_amd64 的加速套件，都不能直接搬過來。這篇從環境檢查開始，依序安裝 CUDA 版 PyTorch、ComfyUI、Director、五個模型檔，再完成第一段有聲影片的驗收。
內容目錄
先看安裝路線與需要準備的東西
DGX Spark 的 GB10 搭配 Arm CPU 與 128 GB 統一記憶體，CPU、GPU 和其他程式共用這個記憶體池，硬體規格可對照 NVIDIA 硬體文件。
- 使用 Spark 原有的 DGX OS／Ubuntu 環境，本文以 Ubuntu 24.04、Python 3.12、Linux aarch64 為安裝目標。
- 準備可使用 sudo 的一般帳號與穩定網路，首次下載模型約 44.43 GB，建議 SSD 先留 150 GB，容納套件、編譯暫存與輸出影片。
- 從乾淨的專用資料夾開始，本文統一使用
~/AI/minimax-h3-spark，不與既有 ComfyUI 共用虛擬環境。 - 先用 PyTorch SDPA 跑通基本流程，再選擇是否編譯 SageAttention，第一輪不需要 xformers、FlashAttention 或 Windows 專用 Triton。
整體順序是：確認系統 → 建立虛擬環境 → 安裝 PyTorch → 安裝 ComfyUI → 安裝 Director → 下載與校驗模型 → 啟動與驗收 → 單段試跑 → 多段與加速。
若已在 Spark 跑 Ollama 本地模型的話，生成影片前先卸載閒置模型，替影音生成留出記憶體。
一、在 Spark 終端機檢查作業系統與 GPU
以下安裝指令都在 Spark 的 Ubuntu 終端機執行。你可以直接接螢幕，也可以先 SSH 登入 Spark。每個指令區塊跑完、沒有錯誤，再進下一步。
uname -m
cat /etc/os-release
python3 --version
nvidia-smi
free -h
df -h "$HOME"架構應顯示 aarch64，系統資訊應符合 Ubuntu 24.04，Python 應為 3.12.x，nvidia-smi 應能辨識 NVIDIA GPU。
若驅動無法載入，先用 DGX Spark 官方系統更新文件修復系統，再安裝 ComfyUI。不要先混裝桌機驅動或 Ubuntu 舊版 nvidia-cuda-toolkit。
本機環境紀錄（2026 年 10 月 26 日）：這台 DGX Spark 的 nvidia-smi 顯示 NVIDIA GB10、Driver Version 595.91.07、CUDA Version 13.2，但 nvcc --version 顯示 release 13.0, V13.0.88。這兩個數字代表不同層次，並不衝突。
- 驅動支援的 CUDA 版本：
nvidia-smi顯示 13.2，表示目前驅動最高支援到這個 CUDA 版本，不表示已安裝 CUDA 13.2 Toolkit。 - 實際的 CUDA Toolkit／編譯器：
nvcc --version顯示 13.0，SageAttention 等原始碼擴充的編譯應以這套工具為準。 - PyTorch 的 CUDA 建置版本：依本文安裝
torch==2.10.0+cu130後，torch.version.cuda應顯示 13.0。這是套件的 CUDA 建置版本，仍需在虛擬環境中實際確認。
依 NVIDIA 對 nvidia-smi 欄位的定義與驅動相容性說明，較新的驅動可以執行較舊 CUDA 版本建置的程式。因此，本機採用「595.91.07 驅動支援 CUDA 13.2、Toolkit 13.0、PyTorch cu130」這組配置，不需要只為了對齊數字改裝 Toolkit 或驅動。
Spark 的 Memory-Usage 顯示 Not Supported，也可能是整合式 GPU 的預期行為，可參考 NVIDIA 已知問題，不要只憑這個欄位判定 GPU 壞了。
二、安裝 Ubuntu 基本工具，建立獨立 Python 環境
sudo apt update
sudo apt install -y git curl ca-certificates python3.12-venv python3.12-dev build-essential pkg-config ffmpeg libgl1 libglib2.0-0
mkdir -p "$HOME/AI/minimax-h3-spark"
cd "$HOME/AI/minimax-h3-spark"
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel packaging ninja
python - <<'PY'
import sys
import platform
print(sys.executable)
print(sys.version)
print(platform.machine())
PY
ffmpeg -versionsys.executable 應指向 minimax-h3-spark/.venv/bin/python。之後安裝 Python 套件一律使用 python -m pip，不用 sudo pip。每次另開終端機，先重新啟用同一個環境：
cd "$HOME/AI/minimax-h3-spark"
source .venv/bin/activate三、在 CUDA 13.2 驅動環境安裝 cu130 PyTorch，實際跑一次 GPU 運算
本機的 nvcc 為 CUDA 13.0，因此保留 Spark ComfyUI playbook採用的 cu130 安裝來源，固定 PyTorch 2.10.0、TorchVision 0.25.0、TorchAudio 2.10.0。這組套件可搭配前述支援 CUDA 13.2 的 595.91.07 驅動，也讓後續 SageAttention 編譯使用的 Toolkit 與 PyTorch CUDA 建置版本同為 13.0。官方索引可找到三者對應 Python 3.12／manylinux aarch64 的 wheel，這是一組可重現的起點。
python -m pip install torch==2.10.0 torchvision==0.25.0 torchaudio==2.10.0 --index-url https://download.pytorch.org/whl/cu130
cat > torch-constraints.txt <<'EOF'
torch==2.10.0+cu130
torchvision==0.25.0+cu130
torchaudio==2.10.0+cu130
EOF
python -m pip checkconstraints 檔會在後續安裝時保護這組 PyTorch，避免第三方節點換掉 CUDA 版本，若安裝失敗，先讀錯誤訊息，不要換成 win_amd64 或 x86_64 wheel。可用 torch 索引與 torchvision 索引核對架構。
pip check 出現 cuSPARSELt 不支援平台，先核對 SBSA 標記
Spark 安裝後出現 nvidia-cusparselt-cu13 0.8.0 is not supported on this platform。
核對 NVIDIA 官方 0.8.0 ARM64 wheel發現，檔名使用 manylinux2014_aarch64，但內部 WHEEL 寫成 Tag: py3-none-manylinux2014_sbsa。pip 的平台檢查會比對這個內部標記，因此可能產生上述訊息。
這個訊息本身不能用來判定 CUDA 13.2 驅動與 Toolkit 13.0 不相容本文的 torch 2.10.0 明確依賴 cuSPARSELt 0.8.0，先保留版本，核對實際安裝的標記、AArch64 函式庫與 CUDA 運算，不要為了消除這行訊息直接升級、移除套件或修改 WHEEL。
在 ~/AI/minimax-h3-spark、同一個 .venv 中執行下列區塊，建立唯讀檢查工具。只有 pip check 的完整輸出恰好是這一行，而且版本、SBSA 標記、ELF 架構與函式庫載入均通過，才把它記錄為已確認的平台標記例外。任何其他錯誤仍會中止檢查。
cat > check-environment.py <<'PYFILE'
"""Read-only validation for one known NVIDIA ARM64 wheel-tag defect."""
import ctypes
import importlib.metadata as metadata
import platform
import subprocess
import sys
check = subprocess.run(
[sys.executable, '-m', 'pip', 'check'],
text=True, capture_output=True,
)
message = (check.stdout + check.stderr).strip()
print(message)
if check.returncode:
expected = 'nvidia-cusparselt-cu13 0.8.0 is not supported on this platform'
assert message == expected, '另有依賴錯誤，停止並逐項排查'
assert sys.platform == 'linux' and platform.machine() == 'aarch64'
dist = metadata.distribution('nvidia-cusparselt-cu13')
assert dist.version == '0.8.0'
wheel = dist.read_text('WHEEL') or ''
tags = [line for line in wheel.splitlines() if line.startswith('Tag:')]
print('WHEEL tags:', tags)
assert tags == ['Tag: py3-none-manylinux2014_sbsa'], '不是已核對的 SBSA 標記問題'
libraries = [
dist.locate_file(item) for item in (dist.files or [])
if str(item).endswith('/libcusparseLt.so.0')
]
assert len(libraries) == 1, '未找到唯一的 cuSPARSELt 函式庫'
library = libraries[0]
with library.open('rb') as stream:
header = stream.read(20)
assert header[:4] == b'\x7fELF' and header[4:6] == b'\x02\x01'
assert int.from_bytes(header[18:20], 'little') == 183, '函式庫不是 AArch64 ELF'
ctypes.CDLL(str(library))
print('PASS: AArch64 cuSPARSELt library load')
print('WARNING: pip check 仍有已確認的 SBSA 標記警告，未修改套件檔案')
import torch
import torch.nn.functional as F
print('torch:', torch.__version__, 'CUDA build:', torch.version.cuda)
assert torch.cuda.is_available(), 'CUDA 無法使用'
print('GPU:', torch.cuda.get_device_name(0))
x = torch.randn((256, 256), device='cuda', dtype=torch.bfloat16)
y = x @ x
q = torch.randn((1, 4, 128, 64), device='cuda', dtype=torch.bfloat16)
z = F.scaled_dot_product_attention(q, q, q)
torch.cuda.synchronize()
assert torch.isfinite(y).all().item() and torch.isfinite(z).all().item()
print('PASS: CUDA matmul + SDPA，仍需繼續驗收 H3 模型與影音輸出')
PYFILE
python check-environment.py若最後看到 PASS: CUDA matmul + SDPA，可繼續下一個 GPU 測試及 ComfyUI 安裝步驟。這代表基礎函式庫載入與運算通過，尚不代表 H3 的所有核心已驗收。原本的 pip check 仍可能回傳非零值，不要將它記成完全沒有警告。後續安裝完節點、再次遇到相同單一訊息時，可重新執行下列指令核對。
cd "$HOME/AI/minimax-h3-spark"
source .venv/bin/activate
python check-environment.py若輸出包含其他套件錯誤、cuSPARSELt 版本不同、函式庫載入失敗或 CUDA 運算失敗，先停止並依完整錯誤排查，不適用這個例外。
python - <<'PY'
import platform
import torch
import torchvision
import torchaudio
import torch.nn.functional as F
print("arch:", platform.machine())
print("torch:", torch.__version__)
print("torchvision:", torchvision.__version__)
print("torchaudio:", torchaudio.__version__)
print("torch CUDA:", torch.version.cuda)
assert torch.version.cuda == "13.0", "本文使用 cu130，請確認目前虛擬環境的 PyTorch 安裝來源"
print("CUDA available:", torch.cuda.is_available())
assert torch.cuda.is_available(), "CUDA 無法使用，先停止安裝並檢查驅動與 wheel"
print("GPU:", torch.cuda.get_device_name(0))
print("capability:", torch.cuda.get_device_capability(0))
x = torch.randn((256, 256), device="cuda", dtype=torch.bfloat16)
y = x @ x
q = torch.randn((1, 4, 128, 64), device="cuda", dtype=torch.bfloat16)
z = F.scaled_dot_product_attention(q, q, q)
torch.cuda.synchronize()
assert torch.isfinite(y).all().item()
assert torch.isfinite(z).all().item()
print("PASS: CUDA matmul + SDPA")
PY在 GB10 上應能辨識 Blackwell GPU，compute capability 通常為 (12, 1)，最後要看到 PASS，才能確認基礎 CUDA 運算能執行，單純 import torch 成功，或 torch.cuda.is_available() 為 True，都還不夠。這個小測試也不代表 H3 全部核心已驗收。
四、安裝支援 MiniMax H3 的 ComfyUI
Director 文件要求 ComfyUI 至少 v0.30.0。核對時，NVIDIA playbook 的部分範例仍固定 v0.28.2，因此這裡改用 2026 年 10 月 26 日核對的 ComfyUI 原始碼快照。固定 commit 能避免日後 master 更新，讓同一篇教學變成不同環境。
cd "$HOME/AI/minimax-h3-spark"
source .venv/bin/activate
git clone https://github.com/Comfy-Org/ComfyUI.git
cd ComfyUI
git checkout fe298e4e20f1ff26d30e8639267bbd0b57811390
python -m pip install -r requirements.txt -c ../torch-constraints.txt
python -m pip install huggingface_hub -c ../torch-constraints.txt
python -m pip check
git rev-parse HEAD之後如何更新 ComfyUI？
上面的 git checkout 是把 ComfyUI 固定在本文核對的 commit，這時 HEAD 不在分支上。之後要更新到最新開發版本，先在執行 ComfyUI 的終端機按 Ctrl+C 停止服務，再依下列步驟備份、切回 master 並更新。第一次安裝可以先沿用固定版本，跑通基準影片後再更新。
以下依官方手動安裝更新流程調整，加入本機的虛擬環境、版本備份與 cu130 限制，整段可以一次貼上，任一步驟失敗就會停止這個更新區塊，若 Git 顯示有本機修改，先保留並處理修改，再重新執行。
(
set -euo pipefail
cd "$HOME/AI/minimax-h3-spark"
source .venv/bin/activate
cd ComfyUI
if [ -n "$(git status --porcelain)" ]
then
git status --short
echo "有本機修改或未追蹤檔案，請先備份並處理，再執行更新"
exit 1
fi
COMFY_BACKUP_DIR="$HOME/AI/minimax-h3-spark/update-backups/$(date +%Y%m%d-%H%M%S)"
mkdir -p "$COMFY_BACKUP_DIR"
git rev-parse HEAD > "$COMFY_BACKUP_DIR/comfyui-commit.txt"
python -m pip freeze > "$COMFY_BACKUP_DIR/requirements-before.txt"
cp ../torch-constraints.txt "$COMFY_BACKUP_DIR/torch-constraints.txt"
echo "$COMFY_BACKUP_DIR" > ../last-comfyui-update-backup.txt
echo "更新前備份：$COMFY_BACKUP_DIR"
git fetch origin --tags
git switch master
git pull --ff-only origin master
python -m pip install -r requirements.txt -c ../torch-constraints.txt
python -m pip install huggingface_hub -c ../torch-constraints.txt
python ../check-environment.py
git rev-parse HEAD
)git switch master 會離開先前固定的 commit，git pull --ff-only 只在能直接向前更新時進行，不會自動建立合併。更新程式後仍要安裝 requirements，前端、工作流範本與核心套件才會一起跟上。這裡只更新 ComfyUI 核心，Director 等 Custom Nodes 需要依各自專案另外更新。
第三節的 check-environment.py 會確認依賴與基礎 GPU 運算，並針對已確認的 cuSPARSELt 平台標記作狹義檢查。如果還沒建立這個檔案，先完成第三節。若新版 requirements 與 torch-constraints.txt 衝突，停止並核對新版對 ARM64、CUDA 與 PyTorch 的需求，再決定是否升級整組套件，不要直接移除版本限制。
更新成功後，依第八節的啟動檔重啟 ComfyUI。下列終端機會持續執行服務，保持開啟，再重新整理瀏覽器，先跑一次原本已成功的單段 H3 Workflow。
cd "$HOME/AI/minimax-h3-spark"
./start-comfyui.sh後續更新也可以重複使用同一個更新區塊，每次都會留下更新前的 commit 與套件版本。最新開發版可能改變節點或依賴，這些版本尚未包含在本文最初的相容性核對結果內，仍要重新驗收。
更新後出問題，如何切回更新前的版本？
先按 Ctrl+C 停止 ComfyUI。以下會讀取剛才保存的備份位置，切回更新前的 commit，並嘗試還原原有 Python 套件版本。先確認備份路徑是你要回復的那一份。
(
set -euo pipefail
cd "$HOME/AI/minimax-h3-spark"
source .venv/bin/activate
COMFY_BACKUP_DIR="$(cat last-comfyui-update-backup.txt)"
echo "將使用這份備份：$COMFY_BACKUP_DIR"
test -d "$COMFY_BACKUP_DIR"
cd ComfyUI
git checkout "$(cat "$COMFY_BACKUP_DIR/comfyui-commit.txt")"
cp "$COMFY_BACKUP_DIR/torch-constraints.txt" ../torch-constraints.txt
python -m pip install -r "$COMFY_BACKUP_DIR/requirements-before.txt" -c ../torch-constraints.txt
python -m pip install -r requirements.txt -c ../torch-constraints.txt
python ../check-environment.py
git rev-parse HEAD
)回復完成後，再執行 ~/AI/minimax-h3-spark/start-comfyui.sh。這份備份記錄核心 commit 與套件版本，不是整個虛擬環境、模型與工作流的快照，更新時新增的套件也不會自動移除。如果仍有依賴衝突，應依備份版本重建獨立環境後再驗收。
正常時 pip check 應顯示 No broken requirements found.。若只有第三節已說明的 cuSPARSELt 0.8.0 平台訊息，執行 python ../check-environment.py 逐項核對，記錄標記警告與實際運算結果。若有其他依賴衝突，先停下來查明原因，不要直接跳過。相依性解析、套件內部標記與實機 CUDA 驗收是不同檢查，三者都要記錄。
Manager 是選用介面，本文以手動安裝 Director 為主。需要 Manager 時，再於 ComfyUI 目錄執行下列指令，啟動時加上 –enable-manager。這個套件與啟動方式可對照 ComfyUI Manager 文件。
python -m pip install -r manager_requirements.txt -c ../torch-constraints.txt五、安裝 MiniMax H3 Director 與 FFmpeg 設定
MiniMax H3 是生成模型，Director 則是整理多段時間軸、參考素材與輸出的第三方節點。本文使用 AIMixer 的 Director 專案，固定已核對的版本。
cd "$HOME/AI/minimax-h3-spark/ComfyUI/custom_nodes"
git clone https://github.com/AIMixer/ComfyUI_MiniMaxH3_Director.git
git -C ComfyUI_MiniMaxH3_Director checkout 4c6245e518dd8a494f3afc4f3cccd53f22d82d10
cd "$HOME/AI/minimax-h3-spark/ComfyUI"
python -m pip install -r custom_nodes/ComfyUI_MiniMaxH3_Director/requirements.txt -c ../torch-constraints.txt
export IMAGEIO_FFMPEG_EXE=/usr/bin/ffmpeg
python -m pip check
python - <<'PY'
import av
import cv2
import imageio_ffmpeg
import scenedetect
print("PyAV:", av.__version__)
print("OpenCV:", cv2.__version__)
print("FFmpeg:", imageio_ffmpeg.get_ffmpeg_exe())
print("SceneDetect:", scenedetect.__version__)
PYIMAGEIO_FFMPEG_EXE 指定使用 Ubuntu 已安裝的 FFmpeg，讓影片匯出工具使用明確路徑。
目前 Director requirements 也包含 ultralytics，供選用的 FaceRefine 使用，第一輪先不用 FaceRefine、Refine、VSR 或 Semantic Bridge，避免增加模型與擴充功能的變數。
六、下載五個模型檔，放進正確資料夾
參考圖生有聲影片使用 Ref2VA 主模型，還需要 Qwen3-VL 文字編碼器、Video VAE 與 Audio VAE。Turbo LoRA 是加速選項，先下載備用，第一輪可以不接。依 Comfy-Org 模型庫與 LightX2V LoRA 檔案清單核對，這五個檔案合計約 44.43 GB，以下容量採十進位 GB，並非執行時記憶體需求。
| 用途 | 完整檔名 | ComfyUI/models 下的目錄 | 約略容量 |
|---|---|---|---|
| R2V 主模型 | minimax_h3_ref2va_pruned_int8_convrot.safetensors | diffusion_models | 20.97 GB |
| 文字編碼器 | qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors | text_encoders | 15.69 GB |
| Video VAE | minimax_h3_video_vae_fp16.safetensors | vae | 5.21 GB |
| Audio VAE | minimax_h3_audio_vae_fp32.safetensors | vae | 0.61 GB |
| R2V 8 步 LoRA | minimax_h3_ref2v_turbo_8step_v1.0_768p_comfyui_bf16.safetensors | loras | 1.96 GB |
以下指令固定模型庫的 revision，只下載需要的檔案。注意 Linux 檔名大小寫有別，主模型放 diffusion_models，不能放 checkpoints。
cd "$HOME/AI/minimax-h3-spark/ComfyUI"
mkdir -p models/diffusion_models models/text_encoders models/vae models/loras
export H3_REV=e5eb578a89295337b8ff433a035929ce0279e0b6
export H3_TURBO_REV=30f485ed874aa44c8183348ad361c5eabad318da
hf download Comfy-Org/MiniMax-H3 diffusion_models/minimax_h3_ref2va_pruned_int8_convrot.safetensors --revision "$H3_REV" --local-dir models
hf download Comfy-Org/MiniMax-H3 text_encoders/qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors --revision "$H3_REV" --local-dir models
hf download Comfy-Org/MiniMax-H3 vae/minimax_h3_video_vae_fp16.safetensors --revision "$H3_REV" --local-dir models
hf download Comfy-Org/MiniMax-H3 vae/minimax_h3_audio_vae_fp32.safetensors --revision "$H3_REV" --local-dir models
hf download lightx2v/Minimax-h3-Turbo minimax_h3_ref2v_turbo_8step_v1.0_768p_comfyui_bf16.safetensors --revision "$H3_TURBO_REV" --local-dir models/loras中斷時可重新執行同一個下載指令。若遇到 401／403，先到模型頁面確認存取權限，需要時在終端機執行 hf auth login。下載工具的使用方式可對照 Hugging Face CLI 文件。模型權重的授權另依各模型庫條款確認。
七、用 SHA-256 驗證下載完整性
檔名對了，不表示檔案一定完整。下面的 SHA-256 來自前述固定 revision 的 Hugging Face LFS 檔案資訊。建立校驗清單後，在 models 目錄執行檢查，五項都應顯示 OK。這會讀取約 44 GB 資料，需要一些時間。
cd "$HOME/AI/minimax-h3-spark/ComfyUI/models"
cat > minimax-h3.sha256 <<'EOF'
9255f52b6677845ad238f20dfaafa94727053694127ab7f255c048f0f9365779 diffusion_models/minimax_h3_ref2va_pruned_int8_convrot.safetensors
35a88d51044231fe332301d7a62aa81e3f2cba62febeb446e2c1e3e0ef76f2c6 text_encoders/qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors
8e505d95dd1561d47abd43d4238fd40d9bb1ae9e147ed0a4cba778d76ae4db48 vae/minimax_h3_audio_vae_fp32.safetensors
7c1f131492e7eddacaac9069a61b81bdd39de5cc96561e677c5eab1cdce5e522 vae/minimax_h3_video_vae_fp16.safetensors
6a56f41ab4229c9dd845b9501bbd475ee57e112d846cf2e819d534a1ae928c5a loras/minimax_h3_ref2v_turbo_8step_v1.0_768p_comfyui_bf16.safetensors
EOF
sha256sum -c minimax-h3.sha256若有 FAILED，先重新下載對應檔案並再次校驗。本文核對的是遠端檔案資訊，這裡的指令才會驗證你實際下載到 Spark 的本地檔案。
八、啟動 ComfyUI，確認節點真的載入
先做一個固定路徑的啟動檔，之後重新開機也可以直接使用。基準配置使用 PyTorch SDPA，不先啟用 SageAttention。
cd "$HOME/AI/minimax-h3-spark"
cat > start-comfyui.sh <<'SH'
#!/usr/bin/env bash
set -euo pipefail
cd "$HOME/AI/minimax-h3-spark"
source .venv/bin/activate
export IMAGEIO_FFMPEG_EXE=/usr/bin/ffmpeg
cd ComfyUI
exec python main.py --listen 127.0.0.1 --port 8188 --use-pytorch-cross-attention
SH
chmod +x start-comfyui.sh
./start-comfyui.sh這個終端機會持續顯示伺服器日誌，先保持開啟。看到 http://127.0.0.1:8188 後，在 Spark 本機瀏覽器開啟這個網址。如果你是在自己的 Mac 或 Windows 電腦操作，另開自己電腦的終端機，將帳號與 Spark IP 換成實際值：
ssh -N -L 8188:127.0.0.1:8188 你的帳號@SPARK_IPSSH 連線保持開啟，再用自己電腦的瀏覽器開啟 http://127.0.0.1:8188。
如果本機 8188 已被其他 ComfyUI 使用，可改成 ssh -N -L 8189:127.0.0.1:8188 你的帳號@SPARK_IP，瀏覽器改開 8189。這裡的轉送指令不在 Spark 裡執行。
回到 Spark 的第二個終端機檢查 HTTP 與節點。HTTP 成功只代表網頁服務啟動，還要確認 H3 與 Director 的類別存在。
cd "$HOME/AI/minimax-h3-spark"
source .venv/bin/activate
curl -fsS http://127.0.0.1:8188/ > /dev/null
curl -fsS http://127.0.0.1:8188/object_info -o /tmp/minimax-h3-object-info.json
python - <<'PY'
import json
with open("/tmp/minimax-h3-object-info.json") as f:
info = json.load(f)
required = ["MiniMaxH3ReferenceToVideo", "MiniMaxH3ImageToVideo", "MiniMaxH3Director"]
missing = [name for name in required if name not in info]
print("Missing:", missing)
assert not missing, "節點未載入，請查看啟動日誌的 IMPORT FAILED 或 traceback"
print("PASS: H3 + Director nodes")
PY九、載入 R2V Workflow，先生成一個短鏡頭
從已安裝的 Director 直接複製範例 JSON，不需要另外尋找來路不明的整合包。Workflow 是節點接線與參數，不包含模型或你的參考圖片。
cd "$HOME/AI/minimax-h3-spark/ComfyUI"
mkdir -p user/default/workflows
cp custom_nodes/ComfyUI_MiniMaxH3_Director/example_workflows/minimax_h3_director_r2v.json user/default/workflows/minimax-h3-spark-r2v.json
cp custom_nodes/ComfyUI_MiniMaxH3_Director/example_workflows/minimax_h3_director_fl2v.json user/default/workflows/minimax-h3-spark-fl2v.json- 在 ComfyUI 左側 Workflow 清單開啟
minimax-h3-spark-r2v.json，或用 Workflow → Open 開啟 JSON。 - 逐一核對 UNET、CLIP、Video VAE、Audio VAE。主模型選 Ref2VA INT8，文字編碼器選上述 NVFP4 檔，CLIP Loader 的 type 必須是 minimax。
- 在 Director 的 R2V 素材群組上傳一張自己的參考圖。移除範例裡未提供的影音參照，先只保留一個群組、單一鏡頭，Ref image size 用 match。
- 第一輪先用未接 Turbo LoRA 的基準配置：864×480、24 FPS、約 5 秒、124 frames、25 steps、CFG 1.0、res_multistep、simple、video shift 12、audio shift 3。這些是專案的起始配置，尚非 Spark 性能實測。
- 停用段落延續、Refine、SelfLift、FaceRefine 與其他進階處理，確認圖片及聲音輸出都有接到 CreateVideo／SaveVideo。
- 輸入下方提示詞，再按 Run。初次讀取模型可能較久，是否成功要以最後輸出與日誌判斷。
Use <Picture 1> as the character reference. Keep the same face and clothing.
A person stands in a bright studio and slowly turns toward the camera.
Medium shot, fixed camera, natural movement, soft daylight.
The person says in Mandarin Chinese:「你好，這是我的本機影片測試。」
Quiet room tone. No subtitles, no text, no logos.角色情緒、鏡頭、動作與聲音都先保持單純。通過第一輪後，再調整多圖參考與較複雜的鏡頭，想先理解 H3 的本地使用概念，可以搭配站內的 MiniMax H3 本地部署整理閱讀，該文的其他平台指令仍須依本文 ARM64 環境調整。
十、驗收影片與聲音，保存可重現的環境
ComfyUI 顯示執行完成後，先到 output 找出剛生成的影片，並檢查是否同時包含視訊與音訊。把下方路徑替換成實際輸出檔名。
cd "$HOME/AI/minimax-h3-spark/ComfyUI"
find output -type f -name '*.mp4' -mmin -60
ffprobe -v error -show_entries stream=codec_type,codec_name,width,height,r_frame_rate,sample_rate,channels -show_entries format=duration -of json "output/video/請替換成實際輸出檔名.mp4"- ffprobe 應列出 video 與 audio 串流，並確認解析度、影格率與時長符合設定。124 frames 在 24 FPS 下約為 5.17 秒，介面顯示約 5 秒是正常的。
- 實際播放：確認畫面沒有全黑或異常色塊，聲音聽得到，中文內容與嘴型是否可用。有音軌不代表內容一定正確。
- 將已跑通的 Workflow 另存新檔，記錄 seed、主模型、LoRA、參考圖、解析度、frames、steps 與日誌耗時。
- GPU 運算、節點載入、模型校驗與影音輸出全部通過，才把這台機器標記為安裝驗收完成。
cd "$HOME/AI/minimax-h3-spark"
source .venv/bin/activate
python -m pip freeze > requirements-working.txt
git -C ComfyUI rev-parse HEAD > comfyui-commit.txt
git -C ComfyUI/custom_nodes/ComfyUI_MiniMaxH3_Director rev-parse HEAD > director-commit.txt
python -m pip check十一、加上 Turbo LoRA，或改跑首尾幀影片
R2V 基準流程通過後，可在 UNETLoader 與 Director 的 model 輸入之間插入 LoraLoaderModelOnly。選擇本文下載的 Ref2V Turbo 8-step v1.0 768p ComfyUI LoRA，strength_model 設為 1.0，Director steps 改為 8。Sampler、scheduler 與 shift 先保持前述配置。這個 768p LoRA 的最終使用效果應再以其目標解析度試跑確認，低解析度只用來檢查流程。
LoRA 是模型的蒸餾加速權重，與 SageAttention 的運算加速屬於不同層次。先只改 LoRA 與 steps，用相同 seed 比較，再決定品質是否符合需求。8 步並不代表整體耗時一定是 25 步的固定比例。
要做指定首幀與尾幀的 FL2V，主模型和 LoRA 必須一起換成 FL2VA／FL2V 版本。文字編碼器和兩顆 VAE 可以共用。以下下載約再增加 22.93 GB。
cd "$HOME/AI/minimax-h3-spark/ComfyUI"
hf download Comfy-Org/MiniMax-H3 diffusion_models/minimax_h3_fl2va_pruned_int8_convrot.safetensors --revision e5eb578a89295337b8ff433a035929ce0279e0b6 --local-dir models
hf download lightx2v/Minimax-h3-Turbo minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors --revision 30f485ed874aa44c8183348ad361c5eabad318da --local-dir models/loras開啟 minimax-h3-spark-fl2v.json，指定 FL2VA 主模型，上傳首幀與尾幀。若要加速，接 FL2V 專用 LoRA。不要把 Ref2V LoRA 接在 FL2VA 上。官方 MiniMax H3 工作流教學也提供原生節點範例，可用來與 Director 流程交叉排查。
十二、Triton 與 SageAttention：在 ARM64 上怎麼裝？
影片示範的 triton-windows 與 Windows SageAttention wheel，適用於 Windows，不能用在 Spark。本文選定的 torch 2.10.0 Linux cu130 wheel 依賴 triton==3.6.0，先檢查它是否已隨 PyTorch 安裝，不要另行升級到其他主版本。
cd "$HOME/AI/minimax-h3-spark"
source .venv/bin/activate
python - <<'PY'
import torch
import triton
print("torch:", torch.__version__)
print("Triton:", triton.__version__)
print("GPU:", torch.cuda.get_device_name(0))
print("capability:", torch.cuda.get_device_capability(0))
PYSageAttention 是選用的原始碼編譯流程。此次核對的 SageAttention setup.py明列 compute capability 12.1 與 sm_121a 編譯目標，但這仍不保證特定 H3 工作流在 Spark 上必然成功或更快。以下使用 SageAttention 2 系列的 sageattention 介面，與 ComfyUI 的 –use-sage-attention 對應，不混用套件介面不同的 SageAttention3。
本機 nvcc --version 已回報 release 13.0, V13.0.88，後續 SageAttention 應使用這套 CUDA 13.0 Toolkit。先找出 nvcc 的實際位置，避免把 nvidia-smi 的 13.2 誤當成 Toolkit 路徑。PyTorch wheel 帶有執行時函式庫，並不等於附帶完整編譯工具。
command -v nvcc
readlink -f "$(command -v nvcc)"
nvcc --version下面會由 nvcc 的實際路徑推導 CUDA_HOME，並檢查該目錄的編譯器及標頭檔。若 nvcc 位於 /usr/local/cuda-13.0/bin/nvcc，CUDA_HOME 就應是 /usr/local/cuda-13.0。若指向包裝腳本或目錄檢查失敗，先改成實際 Toolkit 根目錄，再執行。此配置應同時看到 nvcc release 13.0 與 torch.version.cuda == "13.0"，不要將路徑直接改成 cuda-13.2。
cd "$HOME/AI/minimax-h3-spark"
source .venv/bin/activate
export CUDA_HOME="$(dirname "$(dirname "$(readlink -f "$(command -v nvcc)")")")"
export PATH="$CUDA_HOME/bin:$PATH"
if python - <<'PY'
import os
import pathlib
import re
import subprocess
import torch
cuda_root = pathlib.Path(os.environ["CUDA_HOME"])
nvcc = cuda_root / "bin" / "nvcc"
assert nvcc.is_file(), "CUDA_HOME 沒有 bin/nvcc，請改成實際 Toolkit 根目錄"
assert (cuda_root / "include" / "cuda.h").is_file(), "CUDA_HOME 缺少 include/cuda.h，請核對 Toolkit 根目錄"
version_text = subprocess.check_output([str(nvcc), "--version"], text=True)
print("CUDA_HOME:", cuda_root)
print(version_text)
assert re.search(r"release 13\.0(?:,|\s)", version_text), "此配置需使用已確認的 CUDA 13.0 Toolkit"
assert torch.version.cuda == "13.0", "此配置需使用 cu130 PyTorch"
print("PASS: Toolkit 13.0 + PyTorch cu130")
PY
then
export TORCH_CUDA_ARCH_LIST="12.1"
export MAX_JOBS=4
export EXT_PARALLEL=2
git clone https://github.com/thu-ml/SageAttention.git
git -C SageAttention checkout d1a57a546c3d395b1ffcbeecc66d81db76f3b4b5
python -m pip install --no-build-isolation --no-deps ./SageAttention
python -m pip check
else
echo "版本或路徑檢查未通過，已跳過 SageAttention 編譯"
fi這裡的 –no-deps 只用於已具備 torch、Triton、packaging、ninja 的選用編譯步驟，避免編譯時替換已跑通的 PyTorch。MAX_JOBS 與 EXT_PARALLEL 是保守的編譯並行設定，編譯過程仍可能需要較長時間。失敗時保留錯誤訊息，基本 SDPA 流程仍可使用。
python - <<'PY'
import torch
from sageattention import sageattn
q = torch.randn((1, 4, 128, 64), device="cuda", dtype=torch.bfloat16)
out = sageattn(q, q, q, tensor_layout="HND", is_causal=False)
torch.cuda.synchronize()
assert out.shape == q.shape
assert torch.isfinite(out).all().item()
print("PASS: SageAttention CUDA kernel smoke test")
PY小測試通過後，先在原本跑伺服器的終端機按 Ctrl+C 停止，再改用下列指令啟動。一次只啟用一種注意力後端，不要同時加 –use-pytorch-cross-attention。
cd "$HOME/AI/minimax-h3-spark"
source .venv/bin/activate
export IMAGEIO_FFMPEG_EXE=/usr/bin/ffmpeg
cd ComfyUI
python main.py --listen 127.0.0.1 --port 8188 --use-sage-attention再用同一份單段 Workflow 驗收。若出現 unsupported architecture、no kernel image、CUDA 編譯錯誤、異常畫面或聲音，停止伺服器後重新執行 ~/AI/minimax-h3-spark/start-comfyui.sh 切回 SDPA。安裝成功不等於模型全流程加速成功，import 成功也不能取代 CUDA kernel 小測試。
十三、多段接續與統一記憶體的實際取捨
MiniMax H3 的官方開放權重流程以單段 4–15 秒、24 FPS 的有聲影片為主。長影片通常是多段生成後接續，而非解除單次長度限制。Director 可用上一段尾端的上下文協助下一段延續，人物、聲音或鏡頭仍可能在切點改變。
- 先完成單段，再增加到兩段。需要連續動作時開啟 Segment continuity，先採 Director 建議的 22 context frames。FL2V 有 From prev 等控制，實際依工作模式確認。
- 先用相同角色參考、服裝、場景與鏡頭語言，再逐段調整動作。每次只改一個主要變數。
- 生成時另開 Spark 終端機觀察
watch -n 2 free -h，搭配nvidia-smi與伺服器日誌，不只看傳統顯存欄位。 - 第一輪保留 ComfyUI 的記憶體預設，不照搬 RTX 5070 的 reserve-vram 數值，也不先加 –highvram、–gpu-only 或大幅修改系統 swap。
- 記憶體不足時先減少段落、解析度、參考素材與額外處理，再調整 offload。統一記憶體能容納較大的模型，不能推論生成速度等同桌機高階顯卡。
影片生成的時間取決於權重、精度、解析度、frames、參考素材、注意力核心、取樣步數與解碼。其他顯卡或雲端平台的時間不能直接當 Spark 成績。若你是在評估其他本地影音模型，也可參考 LTX 2.3 的本地部署流程，比較時應固定相近的輸出條件。
十四、常見錯誤與排查順序
| 現象 | 先檢查什麼 | 處理方式 |
|---|---|---|
| externally-managed-environment | 是否啟用 .venv | 重新 source 虛擬環境，再用 python -m pip 安裝。 |
| pip check：cuSPARSELt 0.8.0 is not supported on this platform | WHEEL 的 SBSA 標記、ELF 架構、函式庫與 CUDA 測試 | 依第三節 check-environment.py 核對單一標記例外，其他錯誤仍停止排查。 |
| not a supported wheel on this platform | wheel 的作業系統、CPU 架構與 Python ABI | Spark 需 Linux aarch64，不能使用 Windows 或 x86_64 wheel。 |
| CUDA available 是 False | nvidia-smi、torch.version.cuda、Python 路徑 | 確認驅動與 venv，使用第三節 cu130 指令安裝。 |
| H3 節點缺失 | ComfyUI 版本或 commit | 確認不是舊版 v0.28.2，重新核對第四節快照與 dependencies。 |
| Director IMPORT FAILED | 啟動日誌的第一個 traceback | 在相同 venv 重裝 Director requirements，重啟後再查 object_info。 |
| 找不到模型 | models 子目錄與檔名大小寫 | 核對第六節，重新整理模型清單或重啟 ComfyUI。 |
| 無法使用 NVFP4 核心 | comfy-kitchen、GPU 架構與完整錯誤訊息 | 先以以下 INT8 文字編碼器替換，再確認基本流程。 |
| 有影片但無聲 | Audio VAE、Director audio、CreateVideo 接線 | 確認音訊沒有設為 mute，用 ffprobe 檢查 audio stream。 |
| CUDA OOM 或整台變慢 | free -h、其他模型服務、解析度和 frames | 釋放閒置模型，先縮小單段測試，再逐步調高。 |
| SageAttention 編譯失敗 | nvcc 路徑、CUDA 13、sm_121a 支援 | 切回 start-comfyui.sh 的 SDPA 基準，保留編譯日誌排查。 |
若 NVFP4 文字編碼器遇到不相容，Comfy-Org 也提供 INT8 ConvRot 版本。這不是保證能修好所有核心問題，但能分離 NVFP4 特有的運算路徑。它約 27.14 GB，比 NVFP4 多約 11.45 GB，下載後只更換 CLIP Loader 檔案，type 仍為 minimax。
cd "$HOME/AI/minimax-h3-spark/ComfyUI"
hf download Comfy-Org/MiniMax-H3 text_encoders/qwen3vl_32b_minimax_h3_int8_convrot.safetensors --revision e5eb578a89295337b8ff433a035929ce0279e0b6 --local-dir models若要排除 Director 的影響，改用 官方 R2V Workflow測試。官方範例可能預選不同 Video VAE 與 4-step LoRA，載入後務必改成已下載的模型，未下載的 LoRA 要停用對應加速分支，並換掉範例參考圖片。不能只換 JSON，就假設模型與節點完全相同。
常見問題 FAQ
128 GB 統一記憶體可以保證 MiniMax H3 不會 OOM 嗎？
不能。CPU、GPU 與其他程式共用記憶體，模型之外還有中間張量與解碼需求，應先用單段短片驗收，再增加解析度與長度。
Triton、xformers 與 SageAttention 都一定要裝嗎？
不用。本文先使用 PyTorch SDPA，Triton 由選定的 Linux PyTorch 套件依賴帶入，SageAttention 是另外編譯與驗收的選用加速項目。
nvidia-smi 顯示 CUDA 13.2，為什麼安裝指令仍用 cu130？
nvidia-smi 的 13.2 是驅動支援版本，本機 nvcc 實際為 CUDA Toolkit 13.0。本文保留 cu130 PyTorch，搭配 Toolkit 13.0 編譯 SageAttention，這組配置可在目前較新的驅動上執行。安裝後仍需完成 CUDA 運算與影片輸出驗收。
怎麼確認 MiniMax H3 在 Spark 安裝成功？
依序確認 CUDA matmul 與 SDPA 通過、H3 和 Director 節點載入、模型 SHA-256 正確，再生成短片並驗收 video、audio 串流和實際播放結果。