HyperFlow H3 Flash 本地文生视频部署 · 使用指南

# 1a. 芯片与内存（需 Apple Silicon，建议 ≥ 32 GB 统一内存）
sysctl -n machdep.cpu.brand_string
sysctl -n hw.memsize   # 期望 ≥ 34359738368 (32 GB)

# 1b. 系统与工具
sw_vers
python3 --version      # 期望 ≥ 3.10
git --version
curl --version | head -1
export PATH=/opt/homebrew/bin:$PATH
ffmpeg -version 2>/dev/null | head -1 || echo "ffmpeg 未装（仅验收需要，可后补）"

# 1c. 磁盘空间（模型 33 GB + 运行峰值，建议 ≥ 80 GB 可用）
df -h .

export ROOT=~/hyperflow          # ← 改成你的目标目录
mkdir -p "$ROOT/models" && cd "$ROOT"

python3 -m venv venv
./venv/bin/pip install --upgrade pip

# PyTorch（macOS 原生 MPS 构建）与核心依赖
./venv/bin/pip install torch==2.15.0 torchvision==0.29.2
./venv/bin/pip install gguf==0.19.0 safetensors==0.8.0 einops==0.8.2 \
    numpy==2.5.4 pillow==13.0.0 scipy==1.18.1 sentencepiece==0.2.3 transformers==5.22.2

cd "$ROOT"

git clone https://github.com/Comfy-Org/ComfyUI.git
cd ComfyUI
git checkout c1eece6            # 实测可用版本（v0.45 代）
../venv/bin/pip install -r requirements.txt
cd ..

git clone https://github.com/city96/ComfyUI-GGUF.git \
    ComfyUI/custom_nodes/ComfyUI-GGUF
git clone https://github.com/Video-Rebirth/ComfyUI-HyperFlow-Flash.git \
    ComfyUI/custom_nodes/ComfyUI-HyperFlow-Flash

cd "$ROOT/models"

curl -fL -C - -o minimax_h3_fl2va_hyperflow_flash_14b-Q4_K_M.gguf \
  "https://modelscope.cn/api/v1/models/VideoRebirthAI/hyperflow-h3-flash/repo?FilePath=fl2va_gguf/minimax_h3_fl2va_hyperflow_flash_14b-Q4_K_M.gguf"

curl -fL -C - -o qwen3vl_32b_minimax_h3-Q4_K_M.gguf \
  "https://modelscope.cn/api/v1/models/unsloth/MiniMax-H3-GGUF/repo?FilePath=qwen3vl_32b_minimax_h3-Q4_K_M.gguf"

curl -fL -C - -o minimax_h3_video_vae_fp16.safetensors \
  "https://modelscope.cn/api/v1/models/Comfy-Org/MiniMax-H3/repo?FilePath=vae/minimax_h3_video_vae_fp16.safetensors"

curl -fL -C - -o minimax_h3_audio_vae_fp32.safetensors \
  "https://modelscope.cn/api/v1/models/Comfy-Org/MiniMax-H3/repo?FilePath=vae/minimax_h3_audio_vae_fp32.safetensors"

import importlib.util
import torch
import gguf

def _load(name, path):
    spec = importlib.util.spec_from_file_location(name, path)
    mod = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(mod)
    return mod

dequant = _load("gguf_dequant", "ComfyUI/custom_nodes/ComfyUI-GGUF/dequant.py")

SRC = "models/qwen3vl_32b_minimax_h3-Q4_K_M.gguf"
DST = "models/qwen3vl_32b_minimax_h3-Q4_K_M.patched.gguf"
TARGET = "visual.patch_embed.proj.weight"

r = gguf.GGUFReader(SRC)
w = gguf.GGUFWriter(path=None, arch="qwen3vl")
w.add_name("qwen3vl_32b_minimax_h3")
w.add_quantization_version(gguf.GGML_QUANT_VERSION)

for i, t in enumerate(r.tensors):
    if t.name == TARGET:
        # dequantize, reshape conv layout [out*in, kt, kh, kw] -> [out, in, kt, kh, kw]
        raw = torch.from_numpy(t.data)
        raw.tensor_type = t.tensor_type
        raw.tensor_shape = torch.Size((3456, 2, 16, 16))
        q = dequant.dequantize_tensor(raw, dtype=torch.float32)
        q = q.reshape(1152, 3, 2, 16, 16).to(torch.float16).contiguous()
        w.add_tensor(t.name, q.numpy())
        print("reshaped patch_embed:", tuple(q.shape), flush=True)
    else:
        w.add_tensor(t.name, t.data, raw_dtype=t.tensor_type)
    if i % 200 == 0:
        print(f"{i}/{len(r.tensors)}", flush=True)

w.write_header_to_file(path=DST)
w.write_kv_data_to_file()
w.write_tensors_to_file(progress=False)
w.close()
print("patched OK")

cd "$ROOT" && ./venv/bin/python patch_gguf.py

cd "$ROOT/ComfyUI/models"

ln -sf "$ROOT/models/minimax_h3_fl2va_hyperflow_flash_14b-Q4_K_M.gguf" \
    diffusion_models/minimax_h3_fl2va_hyperflow_flash_14b-Q4_K_M.gguf

ln -sf "$ROOT/models/qwen3vl_32b_minimax_h3-Q4_K_M.patched.gguf" \
    text_encoders/qwen3vl_32b_minimax_h3-Q4_K_M.gguf

ln -sf "$ROOT/models/minimax_h3_video_vae_fp16.safetensors" \
    vae/minimax_h3_video_vae_fp16.safetensors

ln -sf "$ROOT/models/minimax_h3_audio_vae_fp32.safetensors" \
    vae/minimax_h3_audio_vae_fp32.safetensors

#!/bin/bash
# End-to-end generation runner: server boot -> submit t2v workflow -> poll -> save -> shutdown
cd "$(dirname "$0")/ComfyUI"
export PYTORCH_ENABLE_MPS_FALLBACK=1
WF="${1:-../workflow_t2v_mac.json}"

../venv/bin/python main.py --listen 127.0.0.1 --port 8188 > /tmp/comfy_run.log 2>&1 &
SRV=$!

# wait for server
READY=0
for i in $(seq 1 120); do
  if curl -s -o /dev/null --max-time 2 http://127.0.0.1:8188/system_stats; then READY=1; break; fi
  if ! kill -0 $SRV 2>/dev/null; then echo "SERVER DIED"; tail -30 /tmp/comfy_run.log; exit 1; fi
  sleep 5
done
[ "$READY" = 1 ] || { echo "SERVER TIMEOUT"; exit 1; }
echo "server ready, submitting workflow"

RESP=$(curl -s --max-time 60 http://127.0.0.1:8188/prompt -H "Content-Type: application/json" \
  -d "{\"prompt\": $(cat "$WF")}")
PID=$(echo "$RESP" | python3 -c "import sys,json; print(json.load(sys.stdin).get('prompt_id',''))" 2>/dev/null)
if [ -z "$PID" ]; then echo "SUBMIT FAILED: $RESP"; kill $SRV; exit 1; fi
echo "prompt_id=$PID"

# poll until done (up to 6h)
DONE=0
for i in $(seq 1 720); do
  H=$(curl -s --max-time 10 "http://127.0.0.1:8188/history/$PID")
  if echo "$H" | python3 -c "import sys,json; d=json.load(sys.stdin); sys.exit(0 if '$PID' in d else 1)" 2>/dev/null; then DONE=1; break; fi
  sleep 30
done

if [ "$DONE" = 1 ]; then
  echo "GENERATION DONE"
  echo "$H" > /tmp/gen_history.json
  echo "$H" | python3 -c "
import sys,json
d=json.load(sys.stdin)['$PID']
outs=d.get('outputs',{})
for nid,out in outs.items():
    if 'videos' in out:
        for v in out['videos']: print('VIDEO:', v.get('filename'), v.get('subfolder'))
    if 'images' in out:
        for im in out['images']: print('IMAGE:', im.get('filename'))
st=d.get('status',{})
print('status:', st.get('status_str'), 'messages:', len(st.get('messages',[])))
"
else
  echo "TIMEOUT waiting for generation"
fi

echo "=== last 40 log lines ==="
tail -40 /tmp/comfy_run.log
kill $SRV 2>/dev/null; sleep 2; kill -9 $SRV 2>/dev/null
echo "RUNNER EXIT"

cd "$ROOT"
chmod +x run_gen.sh
mkdir -p ComfyUI/output/hyperflow

# 最小烟测工作流（448×256，seed 42；烟测用 4 步加速，标准生成用 6 步）
cat > workflow_t2v_smoke.json << 'EOF'
{
 "1": {
  "class_type": "HyperFlowLoader",
  "inputs": {
   "unet_name": "minimax_h3_fl2va_hyperflow_flash_14b-Q4_K_M.gguf",
   "weights_in": "auto"
  }
 },
 "2": {
  "class_type": "CLIPLoaderGGUF",
  "inputs": {
   "clip_name": "qwen3vl_32b_minimax_h3-Q4_K_M.gguf",
   "type": "minimax"
  }
 },
 "3": {
  "class_type": "VAELoader",
  "inputs": {
   "vae_name": "minimax_h3_video_vae_fp16.safetensors"
  }
 },
 "4": {
  "class_type": "VAELoader",
  "inputs": {
   "vae_name": "minimax_h3_audio_vae_fp32.safetensors"
  }
 },
 "5": {
  "class_type": "MiniMaxH3ImageToVideo",
  "inputs": {
   "clip": [
    "2",
    0
   ],
   "vae": [
    "3",
    0
   ],
   "prompt": "A street musician plays a weathered acoustic guitar on a cobblestone corner at golden hour. The camera slowly pushes in from a wide shot to a medium close-up as passers-by drift through the warm backlight. Soft strumming, distant chatter and a passing tram bell fill the soundtrack.",
   "width": 448,
   "height": 256,
   "length": 124
  }
 },
 "6": {
  "class_type": "HyperFlowSigmas",
  "inputs": {
   "model": [
    "1",
    0
   ],
   "steps": 4
  }
 },
 "7": {
  "class_type": "KSamplerSelect",
  "inputs": {
   "sampler_name": "euler"
  }
 },
 "8": {
  "class_type": "RandomNoise",
  "inputs": {
   "noise_seed": 42
  }
 },
 "9": {
  "class_type": "BasicGuider",
  "inputs": {
   "model": [
    "1",
    0
   ],
   "conditioning": [
    "5",
    0
   ]
  }
 },
 "10": {
  "class_type": "SamplerCustomAdvanced",
  "inputs": {
   "noise": [
    "8",
    0
   ],
   "guider": [
    "9",
    0
   ],
   "sampler": [
    "7",
    0
   ],
   "sigmas": [
    "6",
    0
   ],
   "latent_image": [
    "5",
    1
   ]
  }
 },
 "11": {
  "class_type": "VAEDecode",
  "inputs": {
   "samples": [
    "10",
    0
   ],
   "vae": [
    "3",
    0
   ]
  }
 },
 "12": {
  "class_type": "VAEDecodeAudio",
  "inputs": {
   "samples": [
    "10",
    0
   ],
   "vae": [
    "4",
    0
   ]
  }
 },
 "13": {
  "class_type": "CreateVideo",
  "inputs": {
   "images": [
    "11",
    0
   ],
   "audio": [
    "12",
    0
   ],
   "fps": 24
  }
 },
 "14": {
  "class_type": "SaveVideo",
  "inputs": {
   "video": [
    "13",
    0
   ],
   "filename_prefix": "hyperflow/t2v",
   "format": "mp4"
  }
 }
}
EOF

# 防系统休眠 + 不限时执行；首次运行需加载模型（约 50 s 热缓存 / 数分钟冷启动）
caffeinate -i bash run_gen.sh "$ROOT/workflow_t2v_smoke.json"

export PATH=/opt/homebrew/bin:$PATH
V="$ROOT/ComfyUI/output/hyperflow/t2v_00001_.mp4"

# 8a. 容器规格
ffprobe -v error -show_entries stream=codec_name,width,height,r_frame_rate:format=duration -of csv=p=0 "$V"
# 期望（448 烟测）：h264,448,256,24/1 / aac / 5.166688

# 8b. 抽 4 帧拼图，人工/视觉检查
ffmpeg -y -v error -i "$V" \
  -vf "select='eq(n\,8)+eq(n\,40)+eq(n\,75)+eq(n\,110)',tile=4x1" -frames:v 1 /tmp/tile.png

# 8c. 音轨波形（确认原生配乐存在）
ffmpeg -y -v error -i "$V" -filter_complex "showwavespic=s=800x160" -frames:v 1 /tmp/wave.png