Hunyuan3D-2-WinPortable 簡易構築ガイド

この手順では、Hunyuan3D-2-WinPortableを構築し、テクスチャ生成機能を含む完全な機能を利用できるようにします。

というのは建前で、初めて、CUDA toolkitとVisual Studio Build Toolsの組み合わせｗ使えたので、備忘として残せるものを残しておく。

必要環境

GPU: NVIDIA GPU（最低6GB VRAM、テクスチャ生成には8GB以上推奨）
GPU Driver: バージョン550以上（2024年3月以降）
必要なソフトウェア:
- CUDA Toolkit 12.8
- Visual Studio Build Tools 2022

手順

1. 必要なソフトウェアのインストール

両方をインストールしてから次のステップに進みます。順番はどちらが先でも構いません。

CUDA Toolkit 12.8.1のインストール
- CUDA Toolkit 12.8.1をダウンロード
- カスタムインストールを選択し、以下のオプションを確実に選択してください：
  - CUDA ✓
  - Development ✓
  - Runtime ✓
  - Visual Studio Integration ✓
インストール確認コマンド:
```
nvcc --version
```
正常な出力例:
```
nvcc: NVIDIA (R) Cuda compiler driver
Copyright (c) 2005-2025 NVIDIA Corporation
Built on Fri_Feb_21_20:42:46_Pacific_Standard_Time_2025
Cuda compilation tools, release 12.8, V12.8.93
```

Visual Studio Build Tools 2022のインストール

VS Build Toolsをダウンロード
「C++によるデスクトップ開発」ワークロードを選択

インストール確認コマンド:

cl

正常な出力例:

Microsoft(R) C/C++ Optimizing Compiler Version 19.xx.xxxxx for x64
Copyright (C) Microsoft Corporation. All rights reserved.

使い方: cl [ オプション... ] ファイル名... [ /link リンク オプション... ]

CUDAファイル確認コマンド:

dir "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\include\cuda_runtime.h"

正常な出力例:

2025/02/21  20:42         107,125 cuda_runtime.h

dir "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\lib\x64\cudart*.lib"

正常な出力例:

2025/02/21  20:42       1,839,148 cudart.lib
2025/02/21  20:42       4,286,936 cudart_static.lib

2. Hunyuan3D-2-WinPortableのセットアップ

ダウンロードと解凍
- Hunyuan3D2_WinPortable.7zをダウンロード
- 任意の場所に解凍

環境変数の設定

以下のコマンドを管理者権限のコマンドプロンプトで実行：

setx CUDA_HOME "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8"
setx CUDA_PATH "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8"
setx PATH "%PATH%;C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\bin"

※ 新しいコマンドプロンプトを開いて環境変数確認コマンド:

echo %CUDA_HOME%

正常な出力例:

C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8

初期セットアップ
- 解凍したフォルダで0-initialize.batをダブルクリックして実行（完了まで待つ）
- 次に2-download-models.batをダブルクリックして実行（約19GBのダウンロードが完了するまで待つ）

CUDA対応のPyTorchをインストール

解凍フォルダ内のコマンドプロンプトで以下のコマンドを実行：

python_standalone\python.exe -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124 --force-reinstall

PyTorch CUDA確認コマンド:

python_standalone\python.exe -c "import torch; print(f'PyTorch: {torch.__version__}'); print(f'CUDA利用可能: {torch.cuda.is_available()}'); print(f'CUDA バージョン: {torch.version.cuda}');"

正常な出力例:

PyTorch: 2.7.0+cu124
CUDA利用可能: True
CUDA バージョン: 12.4

NVIDIAドライバー情報確認:

nvidia-smi

正常な出力例:

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 572.xx                Driver Version: 572.xx        CUDA Version: 12.8       |
|-----------------------------------------+------------------------+----------------------+
| GPU  Name            ...  | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  ...      |           Memory-Usage | GPU-Util  Compute M. |
|                           |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA GeForce ...   |   00000000:01:00.0  On |                  N/A |
|  xx%   xxC    P8    xx W  |    xxxx MiB /  xxxx MiB |      x%      Default |
|                           |                        |                  N/A |
+-----------------------------------------+------------------------+----------------------+

テクスチャ生成モジュールのインストール
- 解凍したフォルダで1-compile-install-texture-gen.batをダブルクリックして実行
- インストールが完了するまで待つ（時間がかかる場合があります）

3. Hunyuan3D-2の起動と使用

アプリケーションの起動
- 解凍したフォルダで3-start.batをダブルクリックして実行
- コマンドウィンドウにUvicorn running on http://0.0.0.0:8080と表示されるまで待つ
ブラウザでアクセス
- ブラウザでhttp://localhost:8080/にアクセス
- 「Gen Shape」タブでメッシュのみ生成、「Gen Textured Shape」タブでテクスチャ付きメッシュを生成できます
出力ファイル
- 生成されたファイルはHunyuan3D-2\gradio_cacheフォルダに保存されます

よくある問題と対処法

CUDA認識エラー: CUDAのパスやヘッダーファイルが見つからない場合:
1. CUDA Toolkitが正しくインストールされているか確認
2. 環境変数が正しく設定されているか確認
3. 必要に応じてCUDA Toolkitを再インストール
PyTorchがCUDAを認識しない: CUDA利用可能: Falseと表示される場合:
1. 正しいCUDAバージョン向けのPyTorchをインストールしているか確認
2. 環境変数が正しく設定されているか確認
3. PyTorchインストールコマンドを再実行
VRAMに応じた設定:
- VRAMが8GB未満の場合: run-very_low_vram.batを使用
- VRAMが24GB以上の場合: run-high_vram.batを使用してパフォーマンス向上

環境診断用総合確認コマンド

すべての環境設定が正しいか確認するためのまとめコマンド:

@echo off
echo === CUDA環境診断 ===
echo.
nvcc --version
echo.
echo === Visual Studio C++コンパイラ確認 ===
cl 2>&1 | findstr "Microsoft"
echo.
echo === CUDAヘッダーファイル存在確認 ===
dir "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\include\cuda_runtime.h"
echo.
echo === CUDAライブラリ存在確認 ===
dir "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\lib\x64\cudart*.lib"
echo.
echo === CUDA環境変数確認 ===
echo CUDA_HOME: %CUDA_HOME%
echo CUDA_PATH: %CUDA_PATH%
echo.
echo === PyTorch CUDA情報確認 ===
python_standalone\python.exe -c "import torch; print(f'PyTorch: {torch.__version__}'); print(f'CUDA利用可能: {torch.cuda.is_available()}'); print(f'CUDA バージョン: {torch.version.cuda}');"
echo.
echo === NVIDIAドライバー情報 ===
nvidia-smi
echo.
echo === 診断完了 ===

まとめ

必要なソフトウェア（CUDA & VS Build Tools）をインストール（環境確認コマンドで検証）
Hunyuan3D-2-WinPortableをダウンロード・解凍
環境変数を設定（環境変数確認コマンドで検証）
初期セットアップとモデルダウンロード
CUDA対応PyTorchのインストール（CUDA確認コマンドで検証）
テクスチャ生成モジュールのインストール
アプリケーションの起動と使用

この手順に従えば、最小限の手順でHunyuan3D-2-WinPortableをセットアップし、テクスチャ生成を含む完全な機能を利用できます。各ステップで環境確認コマンドを使用することで、問題を早期に発見し解決できます。