Hunyuan3D-2-WinPortable 簡易構築ガイド（CUDA toolkitとVisual Studio Build Tools備忘用）

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

この手順では、Hunyuan3D-2-WinPortableを構築し、テクスチャ生成機能を含む完全な機能を利用できるようにします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3619695/3d8f3eb4-1e30-4fd2-bf62-f196bfcb4dd4.png)

というのは建前で、初めて、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. 必要なソフトウェアのインストール

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

1. **CUDA Toolkit 12.8.1のインストール**
   - [CUDA Toolkit 12.8.1をダウンロード](https://developer.nvidia.com/cuda-12-8-1-download-archive)
   - カスタムインストールを選択し、以下のオプションを確実に選択してください：
     - 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
   ```

2. **Visual Studio Build Tools 2022のインストール**
   - [VS Build Toolsをダウンロード](https://visualstudio.microsoft.com/ja/visual-cpp-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 リンク オプション... ]
   ```

3. **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のセットアップ

1. **ダウンロードと解凍**
   - [Hunyuan3D2_WinPortable.7zをダウンロード](https://github.com/YanWenKun/Hunyuan3D-2-WinPortable/releases/download/v2/Hunyuan3D2_WinPortable.7z)
   - 任意の場所に解凍

2. **環境変数の設定**
   - 以下のコマンドを管理者権限のコマンドプロンプトで実行：

   ```
   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
   ```

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

4. **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
   ```

5. **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 |
   +-----------------------------------------+------------------------+----------------------+
   ```

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

### 3. Hunyuan3D-2の起動と使用

1. **アプリケーションの起動**
   - 解凍したフォルダで`3-start.bat`をダブルクリックして実行
   - コマンドウィンドウに`Uvicorn running on http://0.0.0.0:8080`と表示されるまで待つ

2. **ブラウザでアクセス**
   - ブラウザで[http://localhost:8080/](http://localhost:8080/)にアクセス
   - 「Gen Shape」タブでメッシュのみ生成、「Gen Textured Shape」タブでテクスチャ付きメッシュを生成できます

3. **出力ファイル**
   - 生成されたファイルは`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 === 診断完了 ===
```

## まとめ

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

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