はじめに
Windows環境で Hunyuan3D（ShapeGen + TexGen）を完全に動作させるまでの手順とトラブルシュートをまとめた。
PyTorch/CUDA/C++拡張の依存関係が非常にシビアだったため、同じ環境の人の参考になれば幸い。
生成した「demo.glb」をBlenderで読み込んだスクショ：
1. 検証環境
- Windows 11
- RTX GPU（compute capability 8.9）
- CUDA Toolkit 12.1
- Python 3.10
- Visual Studio Build Tools 2022 (v14.44)
- PyTorch 2.5.1 + cu121（最終的に安定した組み合わせ）
- transformers 4.39.3（ここ重要）
- CPU： Core i7-12700K
- M B： ASRock Z690 Steel Legend
- MEM： ArkARD4-U32G48HB-24R-D DDR4 64G
- GPU： GK-RTX4070Ti-E12GB/WHITE/TP
- M.2： KINGSTON SNV2S2000G 2TB
2. Hunyuan3D の問題点（2026/02 時点）
Hunyuan3D は、
- Diffusers / Transformers の最新版と互換しない
- custom_rasterizer が CUDA / C++ のビルドを要求
- PyTorch 2.6 以降必須という バグ報告に近い制限 がある
- Windows はビルド環境が1つでも欠けると即死
という「地雷原」状態。
3. 正しく動いたセットアップ手順
3.1 仮想環境作成
python -m venv venv
venv\Scripts\activate
3.2 CUDA 12.1 をインストール
PyTorch 2.5.1 + cu121 と一致させるため 12.1固定。
3.3 Visual Studio Build Tools を追加
必須：
- MSVC v142
- Windows 10 SDK
- C++ ATL/MFC（なくても動いたが入れておくと安全）
特に MSVC 14.44 が必要で、14.3x だと nvcc が失敗する。
3.4 PyTorch のインストール
pip uninstall -y torch torchvision torchaudio
pip install torch==2.5.1+cu121 torchvision==0.20.1+cu121 --index-url https://download.pytorch.org/whl/cu121
※2.6 系は Windows+CUDA では公式 whl がまだ無い → 使えない。
3.5 Transformers を 4.39.3 に固定
Hunyuan3D の Multiview モデルが 最新 transformers で torch.load の脆弱性チェックに引っかかるため。
pip install "transformers==4.39.3"
3.6 custom_rasterizer のビルド
Hunyuan3D の TexGen が使う CUDA カーネル拡張。
cd hy3dgen/texgen/custom_rasterizer
python setup.py install
ここが最大の難所。
- VS Build Tools
- CUDA
- PyTorch のバージョンが揃って初めてコンパイルが通る。
4. minimal_demo.py が通れば成功
python minimal_demo.py
成功すると、
demo.glb
が生成される。
5. 生成物を Blender で確認
GLB は 20〜30 MB と大きめだが、Blender 5.0 で問題なく読める。
6. よく発生したエラーと解決まとめ
✔ torch.load の脆弱性エラー
→ transformers 4.39.3 に固定
✔ custom_rasterizer_kernel の DLL load failed
→ PyTorch と CUDA の ABI 不一致。 torch 2.5.1 + cu121 に戻すと解決。
✔ nvcc / MSVC の C2872 あいまいシンボル
→ MSVC 14.44 以上を必ず入れる。
✔ compile_89 / sm_89 のビルド失敗
→ Windows SDK 未インストール or 不完全 → SDK 10.0.26100 を入れ直す。
7. まとめ：Windowsで動いた構成（再現可能）
| コンポーネント | バージョン |
|---|---|
| Python | 3.10 |
| CUDA Toolkit | 12.1 |
| PyTorch | 2.5.1 + cu121 |
| Visual Studio Build Tools | MSVC 14.44 |
| transformers | 4.39.3 |
| Windows SDK | 10.0.26100 |
この構成で Hunyuan3D（ShapeGen + TexGen）両方が完全動作した。
8. 次の記事案（モデル生成編）
続編として以下を書くと流れが綺麗：
- 好きなプロンプトで 3D モデル生成する方法
- TexGen で任意 OBJ に PBR テクスチャを与える
- 生成モデルを Babylon.js / Three.js に最適化して持ち込む
- VR（Quest 2 / WebXR）で表示する手順
特にあなたは Babylon.js の記事シリーズを持っているので “生成された GLB → Babylon.js シーンに配置” は高相性。
💬 コメント