Zenn
3️⃣

Macのgpuで Hunyuan-3DをComfyUI から動かした話

に公開
macOS
3DCG
生成 AI
ComfyUI
Hunyuan
tech

はじめに

Tencent Hunyuan-3D は複数枚の静止画から 3D メッシュを生成する先進モデルです。
Apple Silicon（M シリーズ）環境では MPS 制約や依存ライブラリ不足が障壁となりがちですが、本稿では Mac mini M2 Pro と MacBook Air M2 のローカル環境で実際に動作させた検証結果を整理し、「まず動かす」ための最短手順をまとめます。

Blenderの拡張プラグインとしてHunyuan-3Dを動かす方法もありますが、BlenderだとCPU機能のみが使われてしまう(Macだと)ので非常に生成が遅いです。
なのでComfyUIを経由すればApple SiliconのGPUを少し使ってくれるので若干生成が早くなります。

動作確認環境

項目 内容
macOS Sonoma 14.4.1 / 15.4.1
Mac Mac mini M2 ProとMacBook Air M2
Python 3.11（公式 .pkg 版）
PyTorch 2.2 〜 2.7（MPS ホイール）
ComfyUI v0.3.34-11（gbab836d8）以降
Hunyuan-3D Wrapper kijai/ComfyUI-Hunyuan3DWrapper v1.1.0

ポイント

  • Homebrew 版 Python は GUI 系依存が不足しやすい。公式 .pkg を推奨
  • Python 3.12 では MPS 対応ホイールが整備途中のため検証外

1. ComfyUI のインストール

git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI
python3.11 -m venv venv
source venv/bin/activate
pip install --upgrade pip wheel
pip install -r requirements.txt

⸻

2. Hunyuan-3D ラッパーの導入

cd custom_nodes
git clone -b v1.1.0 https://github.com/kijai/ComfyUI-Hunyuan3DWrapper.git

旧版 Hy3DLegacy フォルダが残っていると Import Error が発生します。存在する場合は削除してください。

⸻

3. 追加依存ライブラリを一括導入

pip install \
  transformers>=4.40 einops torchsde pydantic pymeshlab \
  opencv-python-headless trimesh open3d==0.18.0 shapely pyglet \
  safetensors pynanoinstantmeshes pyfqmr

OpenCV が競合する場合は opencv-python をアンインストールし、headless 版のみ残すと解決します。

⸻

4. MPS⇔CPU 混在エラー（device 不一致）の修正

comfy/ldm/modules/diffusionmodules/mmdit.py 内の
get_1d_sincos_pos_embed_from_grid_torch() が CPU デバイスを固定して呼び出すため

RuntimeError: Expected all tensors to be on the same device, but found mps:0 and cpu

が発生します。次のワンライナーでパッチを当てます。

python - <<'PY'
import pathlib, re, shutil
p = pathlib.Path("comfy/ldm/modules/diffusionmodules/mmdit.py")
bak = p.with_suffix(".bak_device")
if not bak.exists():
    shutil.copy(p, bak)
txt, out, patched = p.read_text().splitlines(), [], False
for line in txt:
    out.append(line)
    if line.strip().startswith("def get_1d_sincos_pos_embed_from_grid_torch"):
        indent = re.match(r"^(\s*)", line).group(1) + "    "
        out += [f"{indent}if device is None:",
                f"{indent}    device = pos.device"]
        patched = True
p.write_text("\n".join(out))
print("patch applied" if patched else "already patched")
PY

⸻

5. モデルファイルを配置

ComfyUI/models/diffusion_models/hunyuan3d-dit-v2-mv-turbo.safetensors
ComfyUI/models/vae/hunyuan3d-delight-v2-0.vae.safetensors

ComfyUI-Manager を利用している場合は GUI からダウンロードしても構いません。

⸻

6. ComfyUI を起動

source venv/bin/activate
PYTORCH_ENABLE_MPS_FALLBACK=1 python main.py --gpu-only

--gpu-only で CPU への自動転送を抑止し、MPS 内で処理を完結させます。

⸻

7. 最小ワークフロー（4面画像入力）

ImageOnlyCheckpointLoader で .safetensors を読み込む

LoadImage ×4（front / back / right / left）

各画像 → CLIPVisionEncode

4方向を Hunyuan3Dv2ConditioningMultiView に接続

EmptyLatentHunyuan3Dv2（resolution = 3072, batch = 1） Kサンプラーに繋いでください。

KSampler（steps = 20 など）

VAEDecodeHunyuan3D → VoxelToMesh → SaveGLB で .glb を出力

⸻

8. よくあるエラーと対処

エラー例・メッセージ 主因 対処
device 不一致 RuntimeError (mps:0 and cpu) CPU と MPS の混在 手順 4 のパッチを再適用
ModuleNotFoundError: pydantic 依存ライブラリ不足 pip install pydantic
OpenCV Import Error（競合） OpenCV 二重インストール pip uninstall opencv-python で GUI 版を削除し headless 版のみ残す
Cannot import ... Hy3DLegacy 旧ノードが残存 custom_nodes/Hy3DLegacy フォルダを削除

⸻

まとめ

以上の手順で、Apple Silicon 環境でも Hunyuan-3D を ComfyUI から安定稼働させることができます。
依存ライブラリの整備と MPS デバイスの一貫性確保が成否を分けるポイントです。
導入工数短縮の参考になれば幸いです。

Discussion