Guide complet d’utilisation de Hunyuan3D 2.0, incluant le support natif ComfyUI et ComfyUI-Hunyuan3DWrapper

Hunyuan3D-2 est une série de modèles de génération 3D open source lancée par Tencent. À partir de mars 2025, la dernière version est la 2.0, qui prend en charge la génération de modèles 3D haute fidélité avec des cartes de texture haute résolution via du texte, des images ou des croquis.

Points forts techniques

Le système adopte un processus séparé de génération de géométrie + synthèse de texture :

• Génération de géométrie (Hunyuan3D-DiT) : Basé sur un modèle de diffusion de flux qui génère des modèles géométriques 3D sans texture, avec 2,6 milliards de paramètres, capable d’extraire avec précision les informations géométriques des images ou du texte d’entrée.
• Synthèse de texture (Hunyuan3D-Paint) : Ajoute des textures haute résolution (4K) aux modèles géométriques, avec 1,3 milliard de paramètres, prenant en charge la technologie de génération par diffusion multi-vues pour assurer des textures réalistes et un éclairage cohérent.

En découplant la génération de forme et de texture, il réduit efficacement la complexité et améliore la qualité de génération.

Optimisation des performances et de l’efficacité

• Génération rapide : Achève la génération du modèle en seulement 30 secondes, avec la version accélérée (Hunyuan3D-DiT-v2-0-Fast) réduisant le temps d’inférence de 50% grâce à des techniques de distillation guidée.
• Entrée multimodale : Prend en charge diverses méthodes d’entrée, y compris les descriptions textuelles, les images et les croquis, compatible avec les plugins Blender et les applications Gradio, abaissant le seuil d’utilisation.

Écosystème de modèles open source Le projet a mis en open source 6 modèles (certains en version simplifiée), couvrant différents besoins de scénarios :

• Hunyuan3D-2mv : Modèle de génération de formes multi-vues, adapté à la modélisation de scènes complexes.
• Hunyuan3D-Delight-v2-0 : Modèle de suppression d’éclairage d’image, générant des textures invariantes à l’éclairage. D’autres modèles incluent des versions légères (2mini), la génération de géométrie haute fidélité (DiT-v2-0), etc.

Voici quelques plateformes en ligne ou implémentations qui ne dépendent pas de ComfyUI pour expérimenter Hunyuan3D 2.0 :

• Expérience en ligne Hunyuan3D-2mv
• Expérience en ligne Hunyuan3D-2
• Page d’accueil Hunyuan3D
• Hunyuan3D-2-WinPortable

Nous allons maintenant présenter les approches pour implémenter la génération de modèles Hunyuan3D 2.0 dans ComfyUI.

Approches d’implémentation ComfyUI pour la génération de modèles Hunyuan3D 2.0

Voici les principales approches qui seront couvertes dans ce guide. Je fournirai des flux de travail complets et des tutoriels étape par étape pour chacune.

ComfyUI-Hunyuan3DWrapper

Développé par Kijai, il offre actuellement le support et les performances les plus complets dans ComfyUI, capable d’implémenter une sortie de rendu complète du modèle à la texture. Cependant, la partie génération de texture nécessite la compilation d’un composant séparé, ce qui requiert quelques connaissances de base des environnements virtuels Python et des commandes pip.

Support natif ComfyUI

ComfyUI prend désormais officiellement en charge les modèles des séries Hunyuan3D 2.0 et 2mv, capables de rendre des modèles. Cependant, il ne prend pas encore en charge le rendu de texture, produisant des modèles voxélisés qui ont néanmoins leur propre attrait esthétique. Vous n’avez qu’à mettre à jour vers la dernière version de ComfyUI pour l’utiliser, ce qui le rend simple à utiliser et à expérimenter.

ComfyUI 3D Pack

Le principal problème de ce plugin est que son environnement de dépendances diffère de l’environnement de dépendances de la dernière version de ComfyUI, ce qui rend l’installation très difficile. J’ai essayé plusieurs fois sans succès, donc je ne peux que fournir une introduction aux parties pertinentes dans cet article et aux ressources associées.

Images d’entrée

Puisque plusieurs flux de travail sont impliqués dans cet exemple, nous fournissons des images d’entrée correspondantes. Ces matériaux proviennent tous des images d’exemple utilisées dans la documentation officielle de ComfyUI, mais vous pouvez également utiliser vos propres images.

Comme le plugin ComfyUI-Hunyuan3DWrapper utilise des nœuds du plugin ComfyUI-essentials pour accomplir la suppression automatique de l’arrière-plan, tandis que le flux de travail du support natif ComfyUI ne fournit pas cette fonctionnalité, les images fournies ici ont déjà été traitées. Si vous souhaitez utiliser vos propres images, vous pouvez vous référer à la partie de suppression d’arrière-plan du plugin ComfyUI-Hunyuan3DWrapper.

Flux de travail Hunyuan3D 2.0 avec ComfyUI-Hunyuan3DWrapper

Dans cette section, nous utiliserons le plugin ComfyUI-Hunyuan3DWrapper pour implémenter la génération de modèles Hunyuan3D 2.0. J’ai réorganisé les flux de travail correspondants et ajouté des liens de téléchargement de modèles aux fichiers de flux de travail.

1. Installation des plugins associés

Le flux de travail de Kijai dépend des deux plugins suivants :

• ComfyUI-Hunyuan3DWrapper
• ComfyUI_essentials

Vous pouvez installer ces plugins via ComfyUI Manager.

1.1 Installation des dépendances de base du plugin

Cette partie devrait être familière aux lecteurs habitués à l’installation de plugins ComfyUI. Si vous avez installé les plugins via ComfyUI Manager, les dépendances devraient être installées automatiquement.

Si vous avez effectué l’installation manuellement ou via git, vous devrez exécuter les commandes d’installation de dépendances dans l’environnement virtuel ComfyUI correspondant.

Consultez la section d’installation des dépendances à la fin du Guide d’installation des plugins ComfyUI pour compléter cette opération.

1.2 Installation du composant de génération de texture

Après avoir installé les dépendances de base pour ComfyUI-Hunyuan3DWrapper, les composants nécessaires pour la génération de texture doivent être compilés et installés. L’auteur a fourni des fichiers wheel précompilés pour des environnements spécifiques.

L’auteur a fourni ces fichiers dans le répertoire correspondant et a expliqué comment les utiliser dans le Readme du plugin. Considérant que les lecteurs du ComfyUI Wiki sont des utilisateurs multilingues, j’ai traduit et organisé cette partie du contenu.

1.2.1 Installation des fichiers wheel précompilés

Voici les instructions pour installer les fichiers wheel précompilés pour différents environnements. S’il n’y a pas de version correspondant à votre environnement, veuillez vous référer à la section d’installation par auto-compilation.

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

Pour la version Desktop de ComfyUI, vous pouvez suivre ces étapes pour compléter l’installation dans l’environnement correspondant :

Après avoir lancé la version Desktop, vous devez ouvrir le terminal comme montré dans l’image ci-dessous. L’environnement Python est déjà activé, vous pouvez donc exécuter directement les commandes d’installation dans ce terminal.

1. Après avoir lancé la version Desktop, cliquez sur le bouton à bascule dans le coin supérieur droit pour ouvrir le panneau de journalisation en bas
2. Sélectionnez l’onglet terminal dans le panneau inférieur pour ouvrir le terminal
3. Exécutez la commande d’installation dans le terminal :

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

Certains utilisateurs ont signalé des problèmes pour trouver le fichier avec cette méthode, vous pouvez donc également utiliser la commande cd pour naviguer vers le dossier approprié :

cd custom_nodes\ComfyUI-Hunyuan3DWrapper\wheels

4. Utilisez ls pour lister les fichiers dans le dossier wheels
5. Utilisez pip install pour installer le fichier wheel approprié, tel que :

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

Choisissez la version spécifique en fonction de votre système.

1.2.2 Installation par auto-compilation (si les fichiers précompilés ne fonctionnent pas pour votre système)

Si les fichiers wheel précompilés ne fonctionnent pas pour votre système, vous devrez les compiler vous-même :

Compiler et installer Rasterizer :

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

cd hy3dgen/texgen/custom_rasterizer
python setup.py install

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 .

Après une installation réussie, vous devriez voir des fichiers custom_rasterizer_kernel*.pyd et un dossier custom_rasterizer dans le dossier site-packages de votre environnement Python.

Compiler l’extension 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

Ce fichier devrait exister dans ce dossier. Il est uniquement utilisé pour la fixation des sommets ; si ce fichier n’existe pas, une solution de repli s’exécutera sur le CPU, ce qui sera beaucoup plus lent. La fixation des sommets est sur un nœud séparé, donc dans le pire des cas, elle peut être contournée, avec l’inconvénient d’un remplissage de texture moins bon.

1.3 Installation optionnelle : BPT (Boundary Preserving Transform)

Ce composant est complètement optionnel mais a des exigences d’installation élevées :

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

Téléchargez le fichier de poids : bpt-8-16-500m.pt

Copiez bpt-8-16-500m.pt dans le dossier ComfyUI-Hunyuan3DWrapper-main\hy3dgen\shapegen\bpt.

1.4 Réparation du programme de mise à niveau Xatlas pour les modèles haute polygo

Pour résoudre le problème de la texture UV des modèles haute polygo, vous pouvez mettre à niveau 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. Flux de travail à vue unique Hunyuan3D 2.0

Les modèles Hunyuan3D 2.0 ne sont pas des modèles multi-vues, donc lors de l’utilisation de ComfyUI-Hunyuan3DWrapper, il est nécessaire d’utiliser les modèles de la série Hunyuan3D-DiT-v2-0 plutôt que ceux de la série Hunyuan3D-DiT-v2-mv. Ce plugin prend en charge non seulement la génération de la géométrie des modèles, mais aussi la génération de textures, permettant de créer des modèles 3D complets.

2.1 Fichier de flux de travail

Téléchargez le fichier de flux de travail ci-dessous et faites-le glisser dans ComfyUI, cela vous invitera automatiquement à terminer le téléchargement des modèles associés.

2.2 Installation manuelle du modèle

Étant donné qu’au moment de la première publication de Hunyuan3D 2.0, aucun modèle au format safetensors n’était disponible, Kijai a fourni des versions converties. Cependant, Hunyuan3D 2.0 propose désormais des modèles au format safetensors. Vous pouvez télécharger l’un des modèles ci-dessous et le sauvegarder dans le répertoire ComfyUI/models/diffusion_models/.

• Kijai : hunyuan3d-dit-v2-0-fp16.safetensors
• Tencent : hunyuan3d-dit-v2-0/model.fp16.safetensors (renommez-le en hunyuan3d-dit-v2-0.safetensors après le téléchargement)

2.3 Exécution du flux de travail par image

1. Assurez-vous que le modèle hunyuan3d-dit-v2-0.safetensors est chargé dans Hy3DModelLoader.
2. Chargez l’image d’entrée dans le nœud Load Image pour la génération du modèle.
3. Cliquez sur le bouton Queue, ou utilisez le raccourci Ctrl(cmd) + Enter pour exécuter le flux de travail.

3. Flux de travail multi-vues Hunyuan3D 2.0

3.1 Fichier de flux de travail

Téléchargez le fichier de flux de travail ci-dessous et faites-le glisser dans ComfyUI, cela vous invitera automatiquement à terminer le téléchargement des modèles associés.

3.2 Installation manuelle du modèle

Le modèle multi-vues Hunyuan3D 2mv est similaire à la version précédente. Kijai a également fourni des versions converties plus tôt, et Tencent a depuis proposé des versions safetensors. Vous pouvez télécharger l’un des modèles ci-dessous et le sauvegarder dans le répertoire ComfyUI/models/diffusion_models/.

• Kijai : hunyuan3d-dit-v2-0-fp16.safetensors
• Tencent : hunyuan3d-dit-v2-mv/model.fp16.safetensors (renommez-le en hunyuan3d-dit-v2-mv-fp16.safetensors après le téléchargement)

3.3 Exécution du flux de travail par image

1. Assurez-vous que le modèle hunyuan3d-dit-v2-mv-fp16.safetensors est chargé dans Hy3DModelLoader.
2. Téléchargez des images d’entrée sous différents angles dans le nœud Load Image. Si vous n’avez pas d’images pour un angle donné, faites un clic droit sur le nœud correspondant et définissez le mode sur Never.
3. Cliquez sur le bouton Run, ou utilisez le raccourci Ctrl(cmd) + Enter pour exécuter le flux de travail.

Flux de travail natif Hunyuan3D 2.0 dans ComfyUI

Actuellement, ComfyUI prend en charge nativement les modèles de la série Hunyuan3D-2mv, permettant de générer directement des modèles géométriques 3D (les textures ne sont pas encore prises en charge). Il vous suffit de mettre à jour ComfyUI vers la dernière version pour en faire l’expérience. Étant donné que le Wiki de ComfyUI a commencé à collaborer avec l’équipe officielle de Comfy pour maintenir la documentation officielle de Comfy, nous avons déjà fourni des informations détaillées à ce sujet dans la documentation officielle de Comfy. Cependant, la documentation officielle ne prend en charge que le chinois et l’anglais. Pour faciliter la lecture des utilisateurs du Wiki de ComfyUI, nous avons réorganisé et édité le contenu initialement publié sur docs.comfy.org sur notre site.

Actuellement, ComfyUI propose trois flux de travail natifs, principalement pour le support des modèles Hunyuan3D 2.0 et Hunyuan3D-2mv.

• Flux de travail multi-vues Hunyuan3D-2mv
• Flux de travail accéléré multi-vues Hunyuan3D-2mv-turbo
• Flux de travail à vue unique Hunyuan3D-2

Ce flux de travail a été ajouté aux modèles de flux de travail de la dernière version de ComfyUI. Vous pouvez le trouver dans la barre de menu workflow -> workflow templates -> 3d.

1. Utilisation du flux de travail multi-vues Hunyuan3D-2mv

1.1 Exemple de flux de travail

Téléchargez l’image ci-dessous et faites-la glisser dans ComfyUI, cela vous invitera automatiquement à terminer le téléchargement des modèles associés.

1.2 Installation manuelle du modèle

Téléchargez hunyuan3d-dit-v2-mv.safetensors et sauvegardez-le dans le répertoire ComfyUI/models/checkpoints/, puis renommez-le en hunyuan3d-dit-v2-mv.safetensors.

1.3 Exécution du flux de travail étape par étape

1. Assurez-vous que le modèle hunyuan3d-dit-v2-mv.safetensors est chargé dans le nœud Image Only Checkpoint Loader(img2vid model).
2. Chargez les images correspondantes dans chaque nœud Load Image.
3. Exécutez le flux de travail pour générer le modèle 3D.

2. Utilisation du flux de travail accéléré Hunyuan3D-2mv-turbo

Hunyuan3D-2mv-turbo est une version distillée de Hunyuan3D-2mv, offrant une vitesse d’exécution plus rapide.

2.1 Exemple de flux de travail

Téléchargez l’image ci-dessous et faites-la glisser dans ComfyUI, cela vous invitera automatiquement à terminer le téléchargement des modèles associés.

2.2 Installation manuelle du modèle

Téléchargez hunyuan3d-dit-v2-mv-turbo.safetensors, renommez-le en hunyuan3d-dit-v2-mv-turbo.safetensors et sauvegardez-le dans le répertoire ComfyUI/models/checkpoints/.

2.3 Exécution du flux de travail étape par étape

1. Assurez-vous que le modèle hunyuan3d-dit-v2-mv-turbo.safetensors est chargé dans le nœud Image Only Checkpoint Loader(img2vid model).
2. Chargez les images correspondantes dans chaque nœud Load Image.
3. Dans ce flux de travail, assurez-vous que le paramètre cfg est réglé sur 1.0 et ajoutez le nœud flux guidance pour contrôler la génération de cfg distillé.
4. Exécutez le flux de travail pour générer le modèle 3D.

3. Utilisation du flux de travail à vue unique Hunyuan3D-2

Le modèle Hunyuan3D-2 prend en charge la génération de modèles 3D à partir d’entrées à vue unique.

3.1 Exemple de flux de travail

Téléchargez l’image ci-dessous et faites-la glisser dans ComfyUI, cela vous invitera automatiquement à terminer le téléchargement des modèles associés.

3.2 Exemple d’image d’entrée

3.3 Installation manuelle du modèle

Téléchargez hunyuan3d-dit-v2.safetensors, renommez-le en hunyuan3d-dit-v2.safetensors et sauvegardez-le dans le répertoire ComfyUI/models/checkpoints/.

3.4 Exécution du flux de travail étape par étape

1. Assurez-vous que le modèle hunyuan3d-dit-v2.safetensors est chargé dans le nœud Image Only Checkpoint Loader(img2vid model).
2. Chargez l’image d’entrée dans le nœud Load Image.
3. Notez que ce flux de travail utilise le nœud Hunyuan3Dv2Conditioning plutôt que Hunyuan3Dv2ConditioningMultiView.
4. Exécutez le flux de travail pour générer le modèle 3D.

Pack 3D ComfyUI

Lors de l’installation du Pack 3D ComfyUI, le principal problème que vous pourriez rencontrer est le conflit de dépendances. L’environnement requis par ce plugin diffère de celui de la dernière version de ComfyUI, en particulier en ce qui concerne la version de PyTorch et le support de la version CUDA. Si vous souhaitez essayer, vous pouvez consulter les instructions d’installation du projet ComfyUI-3D-Pack. De plus, des utilisateurs de la communauté ont fourni des packages intégrés, vous pouvez essayer Comfy3D-WinPortable | Package intégré pour l’expérience.

Autres informations complémentaires

Comment réaliser un modèle de génération de texte

Dans le flux de travail ci-dessus, nous utilisons des images d’entrée. Vous pouvez ajouter un flux de travail de génération d’images avant ce flux de travail pour compléter la génération de contenu correspondant à l’image. Si vous avez besoin d’entrées multi-vues, vous pouvez essayer d’utiliser les fonctionnalités du plugin ComfyUI-MVAdapter pour générer des images d’un personnage sous différents angles.

Série de modèles open source Hunyuan3D 2.0

Actuellement, Hunyuan3D 2.0 a ouvert plusieurs modèles, couvrant l’ensemble du processus de génération 3D. Vous pouvez visiter Hunyuan3D-2 pour en savoir plus.

Série Hunyuan3D-2mini

Série Hunyuan3D-2mv

Série Hunyuan3D-2

Liens connexes Hunyuan 3D 2.0

• Page d’accueil Hunyuan3D : https://3d.hunyuan.tencent.com
• Démonstration Hunyuan3D-2 : https://huggingface.co/spaces/tencent/Hunyuan3D-2
• Modèles Hunyuan3D-2 : https://huggingface.co/Tencent/Hunyuan3D-2
• Modèles Hunyuan3D-2mv : https://huggingface.co/tencent/Hunyuan3D-2mv
• Démonstration Hunyuan3D-2mv : https://huggingface.co/spaces/tencent/Hunyuan3D-2mv
• GitHub : https://github.com/Tencent/Hunyuan3D-2
• Discord : https://discord.gg/GuaWYwzKbX
• Rapport : https://github.com/Tencent/Hunyuan3D-2/blob/main/assets/report/Tencent_Hunyuan3D_2_0.pdf
• Site officiel : http://3d-models.hunyuan.tencent.com