Hunyuan3D-2: 텐센트 오픈 소스 고해상도 3D 모델 생성 툴

일반 소개

Hunyuan3D-2는 텍스트나 이미지에서 고해상도 3D 모델을 생성하는 것을 목표로 하는 텐센트에서 개발한 오픈 소스 프로젝트입니다. 형상 생성 모델(Hunyuan3D-DiT)과 텍스처 생성 모델(Hunyuan3D-Paint)이라는 두 가지 핵심 구성 요소로 이루어져 있습니다. 사용자는 텍스트 설명을 입력하거나 이미지를 업로드하여 상세한 텍스처가 포함된 3D 디지털 자산을 생성할 수 있습니다. 이 도구는 코드와 사전 학습된 모델과 함께 깃허브에서 무료로 사용할 수 있으며, 최신 버전은 2025년 3월 18일에 업데이트되었습니다. 고속 버전과 다양한 디바이스를 위한 미니 버전 등 여러 모델을 지원하며, Hunyuan3D-2는 게임 개발, 디지털 아트, 연구 분야에서 널리 사용되고 있습니다.

기능 목록

• 텍스트에서 3D 모델 생성을 지원하며, 사용자는 설명을 입력하여 해당 지오메트리를 생성할 수 있습니다.
• 이미지 업로드 후 이미지에서 3D 모델을 생성하고 텍스처가 포함된 3D 에셋을 생성하는 기능을 지원합니다.
• 선명한 모델 디테일과 생생한 텍스처 색상으로 고해상도 출력을 제공합니다.
• 기본 지오메트리 생성을 담당하는 형상 생성 모델(Hunyuan3D-DiT)이 포함되어 있습니다.
• 모델에 고해상도 텍스처를 추가할 수 있는 텍스처 생성 모델(Hunyuan3D-Paint)이 포함되어 있습니다.
• 여러 관점에서 모델을 최적화할 수 있도록 멀티뷰 생성(Hunyuan3D-2mv)을 지원합니다.
• 6억 개의 매개변수만 있고 작동 속도가 더 빠른 미니 버전(Hunyuan3D-2mini)이 제공됩니다.
• 추론 시간을 절반으로 줄이고 더 효율적으로 만드는 빠른 버전의 모델(Fast)을 지원합니다.
• 블렌더를 통합하여 플러그인을 통해 직접 3D 모델을 생성하고 편집할 수 있습니다.
• 사용자가 자유롭게 다운로드하고 수정할 수 있는 오픈 소스 코드 및 모델입니다.

도움말 사용

Hunyuan3D-2는 일부 하드웨어와 프로그래밍 기반이 필요한 강력한 도구입니다. 다음은 사용자가 빠르게 시작하는 데 도움이 되는 자세한 설치 및 사용 가이드입니다.

설치 프로세스

1. 하드웨어 및 소프트웨어 환경 준비
   • CUDA를 지원하는 NVIDIA GPU와 6GB(미니) 또는 12GB(표준) 이상의 비디오 메모리가 필요합니다.
   • Python 3.9 이상을 설치합니다.
   • 코드 다운로드를 위해 Git을 설치합니다.
2. 코드 및 모델 다운로드
   • 터미널에서 실행됩니다:

     git clone https://github.com/Tencent/Hunyuan3D-2.git
     cd Hunyuan3D-2
     

   • 허깅 페이스에서 사전 학습된 모델을 다운로드하세요:

     huggingface-cli download tencent/Hunyuan3D-2 --local-dir ./weights
     

3. 종속성 설치
   • 기본 종속성을 설치합니다:

     pip install -r requirements.txt
     

   • 텍스처 생성을 위한 추가 모듈을 설치합니다:

     cd hy3dgen/texgen/custom_rasterizer
     python3 setup.py install
     cd ../../..
     cd hy3dgen/texgen/differentiable_renderer
     python3 setup.py install
     

   • 플래시 어텐션 가속(옵션)을 설치할 수 있습니다:

     pip install ninja
     pip install git+https://github.com/Dao-AILab/flash-attention.git@v2.6.3
     

4. 설치 확인
   • 샘플 코드를 실행합니다:

     python minimal_demo.py
     

   • 모델을 성공적으로 내보내면 설치가 완료된 것입니다.

주요 기능

1. 이미지에서 3D 모델 생성

• 이동::
  • 사진 준비(예 demo.png)에 배치하고 assets 폴더.
  • 기본 모양을 생성합니다:

    from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline
    from PIL import Image
    pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')
    image = Image.open('assets/demo.png')
    mesh = pipeline(image=image, num_inference_steps=30)[0]
    mesh.export('output.glb')
    

  • 텍스처를 추가합니다:

    from hy3dgen.texgen import Hunyuan3DPaintPipeline
    pipeline = Hunyuan3DPaintPipeline.from_pretrained('tencent/Hunyuan3D-2')
    mesh = pipeline(mesh, image=image)
    mesh.export('textured.glb')
    

• 결국텍스처가 포함된 3D 모델을 생성하고 다른 이름으로 저장합니다. .glb 문서화.

2. 텍스트에서 3D 모델 생성

• 이동::
  • 텍스트-이미지 변환 모듈(HunyuanDiT)을 설치합니다:

    huggingface-cli download Tencent-Hunyuan/HunyuanDiT-v1.1-Diffusers-Distilled --local-dir ./weights/hunyuanDiT
    

  • 코드를 실행합니다:

    from hy3dgen.text2image import HunyuanDiTPipeline
    from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline
    t2i = HunyuanDiTPipeline('Tencent-Hunyuan/HunyuanDiT-v1.1-Diffusers-Distilled')
    i23d = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')
    image = t2i('a cute rabbit')
    mesh = i23d(image, num_inference_steps=30)[0]
    mesh.export('rabbit.glb')
    

• 결국텍스트에서 3D 모델을 생성합니다.

3. Gradio 인터페이스 사용

• 이동::
  • Gradio 애플리케이션을 실행합니다:

    python3 gradio_app.py --model_path tencent/Hunyuan3D-2 --subfolder hunyuan3d-dit-v2-0 --texgen_model_path tencent/Hunyuan3D-2
    

  • 브라우저를 열고 메시지가 표시되는 로컬 주소를 방문합니다.
  • 이미지를 업로드하거나 텍스트를 입력하고 생성을 클릭합니다.
• 결국코드 작성 없이 웹 인터페이스를 통해 모델을 생성합니다.

4. API 서비스 사용

• 이동::
  • API 서버를 시작합니다:

    python api_server.py --host 0.0.0.0 --port 8080
    

  • 모델 생성 요청을 보냅니다:

    img_b64_str=$(base64 -i assets/demo.png)
    curl -X POST "http://localhost:8080/generate" \
    -H "Content-Type: application/json" \
    -d '{"image": "'"$img_b64_str"'"}' \
    -o test.glb
    

• 결국API를 통해 3D 모델을 생성합니다.

5. 블렌더 플러그인 사용

• 마운팅::
  • 다운로드 blender_addon.py 문서화.
  • Blender를 열고 편집 > 환경설정 > 플러그인에서 설치 및 활성화합니다.
• rig::
  • API 서버를 시작합니다(위 참조).
  • Blender 사이드바에서 "Hunyuan3D-2"를 찾습니다.
  • 텍스트를 입력하거나 이미지를 업로드하고 생성을 클릭합니다.
• 결국블렌더에서 직접 모델을 생성하고 편집합니다.

주요 기능 작동

멀티뷰 생성(훈위안3D-2mv)

• 명령을 사용합니다:

pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2mv', subfolder='hunyuan3d-dit-v2-mv')
mesh = pipeline(image=Image.open('assets/demo.png'))[0]
mesh.export('mv_model.glb')

• 여러 각도에서 정확한 모델링이 필요한 장면에 이상적입니다.

빠른 생성(훈위안3D-2미니)

• 명령을 사용합니다:

pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2mini', subfolder='hunyuan3d-dit-v2-mini')
mesh = pipeline(image=Image.open('assets/demo.png'))[0]
mesh.export('mini_model.glb')

• 빠르고 구성이 적은 장치에 적합합니다.

주의

• 런타임 오류를 방지하기 위해 GPU 드라이버가 CUDA 버전과 호환되는지 확인하세요.
• 적응 num_inference_steps 생성 품질에 맞게 파라미터를 최적화할 수 있습니다.
• 문제가 있는 경우 GitHub 이슈 또는 Discord(https://discord.gg/dNBrdrGGMa)에서 도움을 요청하세요.

애플리케이션 시나리오

1. 게임 개발
   개발자는 이를 사용하여 게임 내 캐릭터 또는 소품 모델을 빠르게 생성하여 수동 모델링 시간을 단축할 수 있습니다.
2. 디지털 아트
   아티스트는 크리에이티브 또는 NFT 제작을 위해 텍스트나 이미지로 3D 아트워크를 생성합니다.
3. 제품 디자인
   디자이너는 제품 이미지를 업로드하여 프로토타입을 전시하거나 테스트할 수 있는 3D 모델을 생성합니다.
4. 교육 연구
   학생과 연구자들은 이를 사용하여 AI 생성 3D 기술을 탐색하고 확산 모델을 검증합니다.

QA

1. 최소 하드웨어 요구 사항은 무엇인가요?
   미니는 6GB, 스탠다드는 12GB의 비디오 메모리가 필요하며, NVIDIA GPU를 권장합니다.
2. 상업적으로 이용 가능한가요?
   오픈 소스 버전은 비상업적 용도로만 사용할 수 있습니다. 상업적 용도로 사용하려면 에 문의하여 허가를 받으세요.
3. 모델을 생성하는 데 시간이 얼마나 걸리나요?
   하드웨어 및 설정에 따라 빠른 버전의 경우 약 30초, 표준 버전의 경우 1~2분 정도 소요됩니다.