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

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. 必要なソフトウェアのインストール

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

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
   

2. 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 リンク オプション... ]
   

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をダウンロード
   • 任意の場所に解凍

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/にアクセス
   • 「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をセットアップし、テクスチャ生成を含む完全な機能を利用できます。各ステップで環境確認コマンドを使用することで、問題を早期に発見し解決できます。