Hunyuan3D-2: ferramenta de geração de modelos 3D de alta resolução de código aberto da Tencent

Introdução geral

O Hunyuan3D-2 é um projeto de código aberto desenvolvido pela Tencent, com o objetivo de gerar modelos 3D de alta resolução a partir de textos ou imagens. Ele consiste em dois componentes principais: modelo de geração de forma (Hunyuan3D-DiT) e modelo de geração de textura (Hunyuan3D-Paint). Os usuários podem inserir descrições de texto ou fazer upload de imagens para gerar ativos digitais em 3D com texturas detalhadas. A ferramenta está disponível gratuitamente no GitHub com código e modelos pré-treinados, e a versão mais recente foi atualizada em 18 de março de 2025. Ela é compatível com vários modelos, incluindo uma versão rápida e uma versão mini para diferentes dispositivos. O Hunyuan3D-2 é amplamente utilizado no desenvolvimento de jogos, arte digital e pesquisa.

Lista de funções

• Suporte para geração de modelos 3D a partir de texto, os usuários podem inserir uma descrição para gerar a geometria correspondente.
• Suporte para geração de modelos 3D a partir de imagens e geração de ativos 3D com texturas após o upload de imagens.
• Fornece saída de alta resolução com detalhes nítidos do modelo e cores vibrantes da textura.
• Contém o modelo de geração de formas (Hunyuan3D-DiT), que é responsável por gerar a geometria subjacente.
• Inclui modelo de geração de textura (Hunyuan3D-Paint) para adicionar textura de alta resolução ao modelo.
• Suporte à geração de múltiplas visualizações (Hunyuan3D-2mv) para otimizar o modelo a partir de várias perspectivas.
• Uma versão mini do modelo (Hunyuan3D-2mini) é fornecida, com apenas 0,6 bilhão de parâmetros e operação mais rápida.
• Oferece suporte a uma versão rápida do modelo (Fast), que reduz pela metade o tempo de inferência e o torna mais eficiente.
• O Blender pode ser integrado para gerar e editar modelos 3D diretamente por meio do plug-in.
• Código-fonte aberto e modelos que os usuários podem baixar e modificar livremente.

Usando a Ajuda

O Hunyuan3D-2 é uma ferramenta avançada que requer algumas noções básicas de hardware e programação. A seguir, um guia detalhado de instalação e uso para ajudar os usuários a começar rapidamente.

Processo de instalação

1. Preparação de ambientes de hardware e software
   • Requer GPU NVIDIA com suporte a CUDA e pelo menos 6 GB (Mini) ou 12 GB (Padrão) de memória de vídeo.
   • Instale o Python 3.9 ou posterior.
   • Instale o Git para fazer download do código.
2. Download de códigos e modelos
   • É executado no terminal:

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

   • Baixe o modelo pré-treinado do Hugging Face:

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

3. Instalação de dependências
   • Instale as dependências básicas:

     pip install -r requirements.txt
     

   • Instala módulos adicionais para geração de textura:

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

   • A aceleração opcional do Flash Attention pode ser instalada:

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

4. Verificar a instalação
   • Execute o código de amostra:

     python minimal_demo.py
     

   • Se o modelo for exportado com sucesso, a instalação estará concluída.

Funções principais

1. geração de modelos 3D a partir de imagens

• mover::
  • Prepare uma imagem (por exemplo demo.png), colocado no assets Pasta.
  • Gerar a forma da base:

    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')
    

  • Adicione textura:

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

• no finalGerar um modelo 3D com texturas, salvar como .glb Documentação.

2. geração de modelos 3D a partir de texto

• mover::
  • Instale o módulo de conversão de texto em imagem (HunyuanDiT):

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

  • Execute o código:

    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')
    

• no finalGeração de modelos 3D a partir de texto.

3. usando a interface do Gradio

• mover::
  • Execute o aplicativo Gradio:

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

  • Abra seu navegador e acesse o endereço local solicitado.
  • Faça upload de uma imagem ou insira um texto e clique em Generate (Gerar).
• no finalGeração de modelos por meio de uma interface da Web sem escrever código.

4. uso de serviços de API

• mover::
  • Inicie o servidor de API:

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

  • Enviar uma solicitação para gerar um modelo:

    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
    

• no finalGeração de modelos 3D via API.

5. uso do plug-in do Blender

• montagem::
  • download blender_addon.py Documentação.
  • Abra o Blender, instale-o e ative-o em Edit > Preferences > Plugins.
• equipamento::
  • Inicie o servidor de API (veja acima).
  • Localize "Hunyuan3D-2" na barra lateral do Blender.
  • Digite o texto ou carregue uma imagem e clique em Generate (Gerar).
• no finalGeração e edição de modelos diretamente no Blender.

Operação da função em destaque

Geração de múltiplas visualizações (Hunyuan3D-2mv)

• Use o comando:

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')

• Ideal para cenas que exigem modelagem precisa de vários ângulos.

Geração rápida (Hunyuan3D-2mini)

• Use o comando:

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')

• Rápido e adequado para dispositivos de baixa configuração.

advertência

• Certifique-se de que o driver da GPU seja compatível com a versão CUDA para evitar erros de tempo de execução.
• adaptar num_inference_steps Os parâmetros podem ser otimizados para a qualidade da geração.
• Se você tiver problemas, peça ajuda no GitHub Issues ou no Discord (https://discord.gg/dNBrdrGGMa).

cenário do aplicativo

1. desenvolvimento de jogos
   Os desenvolvedores podem usá-lo para gerar rapidamente modelos de personagens ou adereços no jogo, reduzindo o tempo de modelagem manual.
2. arte digital
   Os artistas geram obras de arte em 3D a partir de texto ou imagens para produção criativa ou NFT.
3. design de produtos
   Os designers fazem upload de imagens de produtos para gerar modelos 3D para exibição ou teste de protótipos.
4. Pesquisa educacional
   Estudantes e pesquisadores o utilizam para explorar técnicas de 3D geradas por IA e para validar modelos de difusão.

QA

1. Quais são os requisitos mínimos de hardware?
   O Mini requer 6 GB de memória de vídeo e o Standard requer 12 GB, com uma GPU NVIDIA recomendada.
2. Ele está disponível comercialmente?
   A versão de código aberto é apenas para uso não comercial. Para uso comercial, entre em contato com para obter autorização.
3. Quanto tempo leva para gerar um modelo?
   Cerca de 30 segundos para a versão rápida e de 1 a 2 minutos para a versão padrão, dependendo do hardware e das configurações.