Hunyuan3D 2.0 완전 가이드: ComfyUI 네이티브 지원 및 ComfyUI-Huanyuan3DWrapper 포함

Hunyuan3D-2는 텐센트가 출시한 오픈소스 3D 생성 모델 시리즈입니다. 2025년 3월 기준 최신 버전은 2.0으로, 텍스트, 이미지 또는 스케치를 통해 고해상도 텍스처 맵이 포함된 고품질 3D 모델 생성을 지원합니다.

기술적 하이라이트

이 시스템은 기하학 생성 + 텍스처 합성의 분리된 프로세스를 채택했습니다:

• 기하학 생성(Hunyuan3D-DiT): 텍스처가 없는 3D 기하학 모델을 생성하는 플로우 확산 모델 기반으로, 2.6B 매개변수를 가지며 입력 이미지나 텍스트에서 기하학적 정보를 정확히 추출할 수 있습니다.
• 텍스처 합성(Hunyuan3D-Paint): 기하학 모델에 고해상도(4K) 텍스처를 추가하며, 1.3B 매개변수를 가지고, 사실적인 텍스처와 일관된 조명을 보장하기 위한 다중 뷰 확산 생성 기술을 지원합니다.

형태와 텍스처 생성을 분리함으로써 복잡성을 효과적으로 줄이고 생성 품질을 향상시킵니다.

성능 및 효율성 최적화

• 빠른 생성: 모델 생성을 최대 30초 만에 완료하며, 가속 버전(Hunyuan3D-DiT-v2-0-Fast)은 가이던스 증류 기술을 통해 추론 시간을 50% 단축합니다.
• 다중 모달 입력: 텍스트 설명, 이미지, 스케치 등 다양한 입력 방법을 지원하며, Blender 플러그인 및 Gradio 애플리케이션과 호환되어 사용 장벽을 낮춥니다.

오픈소스 모델 생태계 이 프로젝트는 6개의 모델(일부는 간소화 버전)을 오픈소스화했으며, 다양한 시나리오 요구를 충족합니다:

• Hunyuan3D-2mv: 다중 뷰 형태 생성 모델로, 복잡한 장면 모델링에 적합합니다.
• Hunyuan3D-Delight-v2-0: 이미지 조명 제거 모델로, 조명에 영향을 받지 않는 텍스처를 생성합니다. 기타 모델에는 경량 버전(2mini), 고품질 기하학 생성(DiT-v2-0) 등이 포함됩니다.

다음은 ComfyUI에 의존하지 않고 Hunyuan3D 2.0을 경험할 수 있는 온라인 플랫폼이나 구현입니다:

• Hunyuan3D-2mv 온라인 체험
• Hunyuan3D-2 온라인 체험
• Hunyuan3D 홈페이지
• Hunyuan3D-2-WinPortable

이제 ComfyUI에서 Hunyuan3D 2.0 모델 생성을 구현하는 접근 방식을 소개하겠습니다.

ComfyUI에서 Hunyuan3D 2.0 모델 생성 구현 접근 방식

다음은 이 가이드에서 다룰 주요 접근 방식입니다. 각각에 대해 완전한 워크플로우와 단계별 튜토리얼을 제공합니다.

ComfyUI-Hunyuan3DWrapper

Kijai가 개발한 이 플러그인은 현재 ComfyUI에서 가장 완전한 지원과 성능을 제공하며, 모델에서 텍스처까지 완전한 렌더링 출력을 구현할 수 있습니다. 그러나 텍스처 생성 부분은 별도 구성 요소의 컴파일이 필요하며, Python 가상 환경과 pip 명령에 대한 기본 지식이 필요합니다.

ComfyUI 네이티브 지원

ComfyUI는 현재 Hunyuan3D 2.0 및 2mv 시리즈 모델을 공식적으로 지원하여 모델 렌더링이 가능합니다. 그러나 아직 텍스처 렌더링은 지원하지 않으며, 자체적인 미적 매력을 가진 복셀 모델을 출력합니다. ComfyUI의 최신 버전으로 업데이트하기만 하면 사용할 수 있어 사용과 경험이 간단합니다.

ComfyUI 3D Pack

이 플러그인의 주요 문제는 의존성 환경이 최신 ComfyUI 의존성 환경과 다르기 때문에 설치가 매우 어렵다는 것입니다. 여러 번 시도했지만 성공하지 못했기 때문에 이 기사에서는 관련 부분과 관련 리소스에 대한 소개만 제공할 수 있습니다.

입력 이미지

이 예제에서는 여러 워크플로우가 관련되어 있어 해당 입력 이미지를 제공합니다. 이 자료들은 모두 ComfyUI 공식 문서에서 사용된 샘플 이미지에서 가져온 것이지만, 자신의 이미지를 사용할 수도 있습니다.

ComfyUI-Hunyuan3DWrapper 플러그인은 ComfyUI-essentials 플러그인 노드를 사용하여 자동 배경 제거를 완료하지만, ComfyUI 네이티브 지원 워크플로우는 이 기능을 제공하지 않기 때문에 여기에서 제공되는 이미지는 이미 처리되었습니다. 자신의 이미지를 사용하려면 ComfyUI-Hunyuan3DWrapper 플러그인의 배경 제거 부분을 참조하세요.

ComfyUI-Hunyuan3DWrapper Hunyuan3D 2.0 워크플로우

이 섹션에서는 ComfyUI-Hunyuan3DWrapper 플러그인을 사용하여 Hunyuan3D 2.0 모델 생성을 구현합니다. 해당 워크플로우를 재구성하고 워크플로우 파일에 모델 다운로드 링크를 추가했습니다.

1. 관련 플러그인 설치

Kijai의 워크플로우는 다음 두 가지 플러그인에 의존합니다:

• ComfyUI-Hunyuan3DWrapper
• ComfyUI_essentials

ComfyUI Manager를 통해 이러한 플러그인을 설치할 수 있습니다.

1.1 기본 플러그인 의존성 설치

이 부분은 ComfyUI 플러그인 설치에 익숙한 독자들에게 친숙할 것입니다. ComfyUI Manager를 통해 플러그인을 설치한 경우 의존성이 자동으로 설치되어야 합니다.

수동으로 또는 git을 통해 설치한 경우, 해당 ComfyUI 가상 환경에서 의존성 설치 명령을 실행해야 합니다.

ComfyUI 플러그인 설치 가이드의 끝에 있는 의존성 설치 섹션을 참조하여 이를 완료하세요.

1.2 텍스처 생성 구성 요소 설치

ComfyUI-Hunyuan3DWrapper의 기본 의존성을 설치한 후, 텍스처 생성에 필요한 구성 요소를 컴파일하고 설치해야 합니다. 작성자는 특정 환경을 위한 사전 컴파일된 휠 파일을 제공했습니다.

작성자는 해당 디렉토리에 이러한 파일을 제공하고 플러그인의 Readme에서 사용 방법을 설명했습니다. ComfyUI Wiki 독자가 다국어 사용자임을 고려하여 이 내용 부분을 번역하고 정리했습니다.

1.2.1 사전 컴파일된 휠 파일 설치

다양한 환경에 대한 사전 컴파일된 휠 파일을 설치하는 지침은 다음과 같습니다. 시스템과 일치하는 버전이 없는 경우 자체 컴파일 설치 섹션을 참조하세요.

pip install wheels\custom_rasterizer-0.1-cp312-cp312-win_amd64.whl

python_embeded\python.exe -m pip install ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\wheels\custom_rasterizer-0.1-cp312-cp312-win_amd64.whl

python_embeded\python.exe -m pip install ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\wheels\custom_rasterizer-0.1.0+torch260.cuda126-cp312-cp312-win_amd64.whl

ComfyUI Desktop 버전의 경우, 해당 환경에서 설치를 완료하기 위해 다음 단계를 따를 수 있습니다:

Desktop 버전을 실행한 후, 아래 이미지와 같이 터미널을 열어야 합니다. Python 환경이 이미 활성화되어 있으므로 이 터미널에서 직접 설치 명령을 실행할 수 있습니다.

1. Desktop 버전을 실행한 후, 오른쪽 상단의 토글 버튼을 클릭하여 하단에 로그 패널을 엽니다
2. 하단 패널에서 terminal 탭을 선택하여 터미널을 엽니다
3. 터미널에서 설치 명령을 실행합니다:

pip install ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\wheels\custom_rasterizer-0.1-cp312-cp312-win_amd64.whl

일부 사용자는 이 방법으로 파일을 찾는 데 문제가 있다고 보고했으므로, cd 명령을 사용하여 적절한 폴더로 이동할 수도 있습니다:

cd custom_nodes\ComfyUI-Hunyuan3DWrapper\wheels

4. ls를 사용하여 wheels 폴더의 파일을 나열합니다
5. pip install을 사용하여 적절한 휠 파일을 설치합니다, 예를 들어:

pip install custom_rasterizer-0.1-cp312-cp312-win_amd64.whl

시스템에 따라 특정 버전을 선택하세요.

1.2.2 자체 컴파일 설치 (사전 컴파일된 파일이 시스템에 맞지 않는 경우)

사전 컴파일된 휠 파일이 시스템에 맞지 않는 경우, 직접 컴파일해야 합니다:

래스터라이저 컴파일 및 설치:

cd custom_nodes/ComfyUI-Hunyuan3DWrapper/hy3dgen/texgen/custom_rasterizer
python setup.py install

cd hy3dgen/texgen/custom_rasterizer
python setup.py install

python setup.py bdist_wheel

cd C:\ComfyUI_windows_portable\ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\hy3dgen\texgen\custom_rasterizer
C:\ComfyUI_windows_portable\python_embeded\python.exe -m pip install .

설치가 성공하면 Python 환경의 site-packages 폴더에 custom_rasterizer_kernel*.pyd 파일과 custom_rasterizer 폴더가 있어야 합니다.

mesh_processor 확장 컴파일:

cd custom_nodes/ComfyUI-Hunyuan3DWrapper/hy3dgen/texgen/differentiable_renderer
python setup.py build_ext --inplace

cd hy3dgen/texgen/differentiable_renderer
python setup.py build_ext --inplace

cd hy3dgen/texgen/differentiable_renderer
python_embeded\python.exe setup.py build_ext --inplace

이 파일은 해당 폴더에 존재해야 합니다. 정점 수정에만 사용되며, 이 파일이 없으면 CPU에서 실행되는 대체 방안이 실행되는데 이는 훨씬 느립니다. 정점 수정은 별도의 노드에 있으므로, 최악의 경우 우회할 수 있지만, 단점으로 텍스처 채우기가 더 나빠집니다.

1.3 선택적 설치: BPT (Boundary Preserving Transform)

이 구성 요소는 완전히 선택 사항이지만 설치 요구 사항이 높습니다:

cd custom_nodes/ComfyUI-Hunyuan3DWrapper/hy3dgen/shapegen/bpt
pip install -r requirements.txt

cd ComfyUI-Hunyuan3DWrapper\hy3dgen\shapegen\bpt
pip install -r requirements.txt

python_embeded\python.exe -m pip install -r ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\hy3dgen\shapegen\bpt\requirements.txt

가중치 파일 다운로드: bpt-8-16-500m.pt

bpt-8-16-500m.pt를 ComfyUI-Hunyuan3DWrapper-main\hy3dgen\shapegen\bpt 디렉토리에 복사합니다.

1.4 고폴리곤 모델의 UV 매핑 수정을 위한 Xatlas 업그레이드

고폴리곤 모델의 UV 매핑 문제를 해결하기 위해 Xatlas를 업그레이드할 수 있습니다:

python_embeded\python.exe -m pip uninstall xatlas

git clone --recursive https://github.com/mworchel/xatlas-python.git
cd .\xatlas-python\extern

git clone --recursive https://github.com/jpcy/xatlas

.\python_embeded\python.exe -m pip install .\xatlas-python\

2. Hunyuan3D 2.0 단일 뷰 워크플로우

Hunyuan3D 2.0 모델은, 다중 뷰 모델이 아니므로 ComfyUI-Hunyuan3DWrapper 사용 시 Hunyuan3D-DiT-v2-mv 시리즈가 아닌 Hunyuan3D-DiT-v2-0 시리즈 모델을 사용해야 합니다. 이 플러그인은 모델 기하학 생성뿐만 아니라 텍스처 생성도 지원하므로 완전한 3D 모델을 만들 수 있습니다.

2.1 워크플로우 파일

아래 워크플로우 파일을 다운로드하여 ComfyUI로 드래그하면, 관련 모델 다운로드를 자동으로 완료하도록 프롬프트됩니다.

2.2 수동 모델 설치

Hunyuan3D 2.0이 처음 출시되었을 때는 safetensors 형식의 모델을 제공하지 않았기 때문에 Kijai가 변환된 버전을 제공했습니다. 그러나 현재 Hunyuan3D 2.0은 safetensors 형식의 모델을 제공합니다. 아래 모델 중 하나를 다운로드하여 ComfyUI/models/diffusion_models/ 디렉토리에 저장할 수 있습니다.

• Kijai: hunyuan3d-dit-v2-0-fp16.safetensors
• Tencent: hunyuan3d-dit-v2-0/model.fp16.safetensors 다운로드 후 hunyuan3d-dit-v2-0.safetensors로 이름 변경

2.3 이미지로 워크플로우 실행

1. Hy3DModelLoader 노드에서 hunyuan3d-dit-v2-0.safetensors가 로드되었는지 확인합니다
2. Load Image 노드에서 모델 생성을 위한 해당 입력 이미지를 로드합니다
3. Queue 버튼을 클릭하거나 단축키 Ctrl(cmd) + Enter를 사용하여 워크플로우를 실행합니다

3. Hunyuan3D 2.0 다중 뷰 워크플로우

3.1 워크플로우 파일

아래 워크플로우 파일을 다운로드하여 ComfyUI로 드래그하면, 관련 모델 다운로드를 자동으로 완료하도록 프롬프트됩니다.

3.2 수동 모델 설치

Hunyuan3D 2mv 다중 뷰 모델은 이전과 유사합니다. Kijai도 초기 변환 버전을 제공했고, 이후 Tencent에서 safetensors 버전을 제공했습니다. 아래 모델 중 하나를 다운로드하여 ComfyUI/models/diffusion_models/ 디렉토리에 저장할 수 있습니다.

• Kijai: hunyuan3d-dit-v2-0-fp16.safetensors
• Tencent: hunyuan3d-dit-v2-mv/model.fp16.safetensors 다운로드 후 hunyuan3d-dit-v2-mv-fp16.safetensors로 이름 변경

3.3 이미지로 워크플로우 실행

1. Hy3DModelLoader 노드에서 hunyuan3d-dit-v2-mv-fp16.safetensors가 로드되었는지 확인합니다
2. Load Image 노드에 다른 각도의 입력 이미지를 업로드합니다. 특정 각도의 이미지가 없는 경우, 해당 노드를 우클릭하고 모드를 Never로 설정합니다
3. Run 버튼을 클릭하거나 단축키 Ctrl(cmd) + Enter를 사용하여 워크플로우를 실행합니다

ComfyUI 네이티브 Hunyuan3D 2.0 워크플로우

ComfyUI는 현재 Hunyuan3D-2mv 시리즈 모델을 네이티브로 지원하며, 3D 기하학 모델을 직접 생성할 수 있습니다(현재 텍스처 재질 없음). ComfyUI를 최신 버전으로 업그레이드하기만 하면 이를 경험할 수 있습니다. ComfyUI Wiki는 Comfy 공식 문서를 유지하기 위해 Comfy 공식과 협력을 시작했으며, 이 내용 부분은 Comfy 공식 문서에 자세히 설명되어 있습니다. 그러나 공식 문서는 현재 중국어와 영어만 지원합니다. ComfyUI Wiki 독자의 편의를 위해, ComfyUI Wiki는 docs.comfy.org에 원래 게시된 내용을 우리 사이트에서 재구성하고 편집했습니다.

ComfyUI는 현재 세 가지 네이티브 워크플로우를 제공하며, 주로 Hunyuan3D 2.0 및 Hunyuan3D-2mv 시리즈 모델을 지원합니다:

• Hunyuan3D-2mv 다중 뷰 워크플로우
• Hunyuan3D-2mv-turbo 가속 다중 뷰 워크플로우
• Hunyuan3D-2 단일 뷰 워크플로우

이러한 워크플로우는 최신 버전의 ComfyUI 워크플로우 템플릿에 추가되었습니다. 메뉴 바 workflow -> workflow templates -> 3d에서 찾을 수 있습니다.

1. Hunyuan3D-2mv 다중 뷰 워크플로우 사용

1.1 워크플로우 예제

아래 이미지를 다운로드하여 ComfyUI로 드래그하면, 관련 모델 다운로드를 자동으로 완료하도록 프롬프트됩니다.

1.2 수동 모델 설치

hunyuan3d-dit-v2-mv.safetensors를 다운로드하고, hunyuan3d-dit-v2-mv.safetensors로 이름을 변경한 후, ComfyUI/models/checkpoints/ 디렉토리에 저장합니다.

1.3 단계별 워크플로우 실행

1. Image Only Checkpoint Loader(img2vid model) 노드에서 hunyuan3d-dit-v2-mv.safetensors 모델이 로드되었는지 확인합니다
2. 각 Load Image 노드에서 해당 각도의 이미지를 로드합니다
3. 워크플로우를 실행하여 3D 모델을 생성합니다

2. Hunyuan3D-2mv-turbo 가속 워크플로우 사용

Hunyuan3D-2mv-turbo는 Hunyuan3D-2mv의 증류 버전으로, 더 빠른 실행을 제공합니다.

2.1 워크플로우 예제

아래 이미지를 다운로드하여 ComfyUI로 드래그하면, 관련 모델 다운로드를 자동으로 완료하도록 프롬프트됩니다.

2.2 수동 모델 설치

hunyuan3d-dit-v2-mv-turbo.safetensors를 다운로드하고, hunyuan3d-dit-v2-mv-turbo.safetensors로 이름을 변경한 후, ComfyUI/models/checkpoints/ 디렉토리에 저장합니다.

2.3 단계별 워크플로우 실행

1. Image Only Checkpoint Loader(img2vid model) 노드에서 hunyuan3d-dit-v2-mv-turbo.safetensors 모델이 로드되었는지 확인합니다
2. 각 Load Image 노드에서 해당 각도의 이미지를 로드합니다
3. 이 워크플로우에서는 cfg가 1.0으로 설정되어 있으며, 증류 cfg 생성을 제어하기 위한 flux guidance 노드가 추가되었음에 주목하세요
4. 워크플로우를 실행하여 3D 모델을 생성합니다

3. Hunyuan3D-2 단일 뷰 워크플로우 사용

Hunyuan3D-2 모델은 단일 뷰 입력에서 3D 모델 생성을 지원합니다.

3.1 워크플로우 예제

아래 이미지를 다운로드하여 ComfyUI로 드래그하면, 관련 모델 다운로드를 자동으로 완료하도록 프롬프트됩니다.

3.2 입력 이미지 예제

3.3 수동 모델 설치

hunyuan3d-dit-v2.safetensors를 다운로드하고, hunyuan3d-dit-v2.safetensors로 이름을 변경한 후, ComfyUI/models/checkpoints/ 디렉토리에 저장합니다.

3.4 단계별 워크플로우 실행

1. Image Only Checkpoint Loader(img2vid model) 노드에서 hunyuan3d-dit-v2.safetensors 모델이 로드되었는지 확인합니다
2. Load Image 노드에서 입력 이미지를 로드합니다
3. 이 워크플로우에서는 Hunyuan3Dv2ConditioningMultiView가 아닌 Hunyuan3Dv2Conditioning 노드를 사용함에 주목하세요
4. 워크플로우를 실행하여 3D 모델을 생성합니다

ComfyUI 3D Pack

ComfyUI 3D Pack 설치 시 주요 문제는 의존성 충돌입니다. 플러그인의 환경 요구 사항은 최신 ComfyUI 버전의 요구 사항과 다르며, 특히 PyTorch 및 CUDA 버전 지원과 관련하여 차이가 있습니다. 시도해 보고 싶다면, ComfyUI-3D-Pack 프로젝트의 설치 지침을 참조할 수 있습니다. 또한, 커뮤니티 사용자들이 통합 패키지를 제공했으며, Comfy3D-WinPortable | 통합 패키지를 시도해 볼 수 있습니다.

추가 콘텐츠

텍스트에서 모델을 생성하는 방법

위의 워크플로우에서는 입력 이미지를 사용했습니다. 이러한 워크플로우 전에 텍스트-이미지 워크플로우를 추가하여 해당 이미지 콘텐츠를 생성할 수 있습니다. 다중 뷰 입력이 필요한 경우, ComfyUI-MVAdapter 플러그인을 사용하여 해당 캐릭터의 다양한 각도 이미지를 생성해 볼 수 있습니다.

Hunyuan3D 2.0 오픈소스 모델 시리즈

Hunyuan3D 2.0은 완전한 3D 생성 프로세스를 포함하는 여러 모델을 오픈소스화했습니다. 자세한 내용은 Hunyuan3D-2를 방문하여 알아볼 수 있습니다.

Hunyuan3D-2mini 시리즈

Hunyuan3D-2mv 시리즈

Hunyuan3D-2 시리즈

Hunyuan 3D 2.0 관련 링크

• Hunyuan3D 홈페이지: https://3d.hunyuan.tencent.com
• Hunyuan3D-2 데모: https://huggingface.co/spaces/tencent/Hunyuan3D-2
• Hunyuan3D-2 모델: https://huggingface.co/Tencent/Hunyuan3D-2
• Hunyuan3D-2mv 모델: https://huggingface.co/tencent/Hunyuan3D-2mv
• Hunyuan3D-2mv 데모: https://huggingface.co/spaces/tencent/Hunyuan3D-2mv
• GitHub: https://github.com/Tencent/Hunyuan3D-2
• Discord: https://discord.gg/GuaWYwzKbX
• 보고서: https://github.com/Tencent/Hunyuan3D-2/blob/main/assets/report/Tencent_Hunyuan3D_2_0.pdf
• 공식 웹사이트: http://3d-models.hunyuan.tencent.com