Hunyuan3D-2.1

一张图,秒出带PBR材质的3D模型,直接进生产管线

开源 🏷️完全免费 🔧 仅开源项目,无在线服务,需自行部署 数字人3D 🍴 复刻 659 🐛 待处理 160 👀 关注 38
访问官网 ↗ GitHub ↗
GitHub 星标 ★ 4483
维护状态 低维护
是否开源 开源
定价模式 🏷️完全免费 开源项目,本地部署,完全免费。

项目预览

Hunyuan3D-2.1 项目界面预览图
图片来源:项目官网

项目数据

分类数字人3D
开发团队Tencent-Hunyuan
定价模式🏷️完全免费
价格说明开源项目,本地部署,完全免费。
访问状态🔧 仅开源项目,无在线服务,需自行部署
是否开源是
开源协议NOASSERTION
主要语言Python
技术栈/模型3d,3d-aigc,3d-generation,hunyuan3d,image-to-3d,shape,shape-generation,text-to-3d,texture-genertaion
GitHub 星标★ 4483
上线时间2025-06-13 00:00:00
代码更新2025-10-17
仓库体积148.7 MB
本站数据更新2026-11-18
维护状态低维护
收录时间2026-08-09
浏览次数5

项目介绍

Hunyuan3D-2.1是腾讯开源的3D资产生成模型,能从单张图片生成高保真3D模型,并附带生产级PBR材质。它解决的是传统3D建模耗时费力、门槛高的问题,让设计师和开发者可以快速从概念图或照片直接获得可用的3D资产。核心能力包括:基于扩散模型的多视图生成、几何重建与纹理烘焙、PBR材质输出(粗糙度、金属度、法线等),支持多种输入格式和输出格式。相比前代版本,2.1在几何细节、材质真实感和生成速度上都有提升,特别适合游戏、影视、电商等需要批量3D内容的场景。项目提供Python接口和命令行工具,方便集成到现有工作流。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化,观测越久曲线越完整

数据来源:GitHub API 逐日快照 · 收录于 2026-08-09 · 当前星标 ★ 4483

使用教程

难度:进阶 约 40 分钟 部署方式:本地安装 7 步

环境要求

  • Python 3.10(README 实测版本)
  • PyTorch 2.5.1 + cu124(NVIDIA CUDA 环境)
  • 能执行 git clone / wget 的网络环境
  • 具备 C++ 编译环境(README 要求编译自定义光栅化与渲染扩展)

安装与启动步骤

  1. 1克隆项目代码

    把仓库拉到本地,后续所有相对路径命令都要在仓库根目录执行。

    git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1.git
    cd Hunyuan3D-2.1
  2. 2安装 PyTorch

    按 README 指定的 cu124 源安装 2.5.1 版本的 torch 系列,避免版本不匹配。

    pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu124
  3. 3安装项目依赖

    在仓库根目录安装 requirements.txt 中的 Python 依赖,建议先用虚拟环境隔离。

    pip install -r requirements.txt
  4. 4编译自定义光栅化

    进入 hy3dpaint/custom_rasterizer 以可编辑模式安装,完成后回到仓库根目录。

    cd hy3dpaint/custom_rasterizer
    pip install -e .
    cd ../..
  5. 5编译可微渲染器

    执行官方编译脚本 build_mesh_painter.sh,编译失败通常是缺少 C++/CUDA 编译工具。

    cd hy3dpaint/DifferentiableRenderer
    bash compile_mesh_painter.sh
    cd ../..
  6. 6下载超分权重

    下载 Real-ESRGAN 的 x4plus 权重到 hy3dpaint/ckpt 目录,供纹理阶段使用。

    wget https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth -P hy3dpaint/ckpt
  7. 7调用 Python API

    README 提供类 diffusers 的接口,需先把两个子目录加入 sys.path 再导入管线类。

    import sys
    sys.path.insert(0, './hy3dshape')
    sys.path.insert(0, './hy3dpaint')
    from textureGenPipeline import Hunyuan3DPaintPipeline, Hunyuan3DPaintConfig
    from hy3dshape.pipelines import Hunyuan3DDiTFlowMatchingPipeline

如何确认成功

在仓库根目录执行上述 Python 导入语句,无 ModuleNotFoundError 或编译报错即表示环境安装完成。

常见问题

Q:必须用 Python 3.10 吗?

A:README 的实测环境为 Python 3.10 与 PyTorch 2.5.1+cu124,其他版本可能因依赖或扩展编译不兼容而失败。

Q:GPU 是必需的吗?

A:README 安装命令使用 cu124 版 PyTorch,面向 CUDA 环境;纯 CPU 环境未在文档中说明支持情况。

Q:custom_rasterizer 和 DifferentiableRenderer 安装失败怎么办?

A:这两步是编译自定义扩展,报错多为缺少 C++/CUDA 编译工具链,请先补齐编译环境后重新执行对应命令。

Q:RealESRGAN_x4plus.pth 是做什么的?

A:它是纹理生成阶段用到的超分权重,README 要求放到 hy3dpaint/ckpt 目录下。

注意事项

  • 安装步骤必须在克隆后的仓库根目录执行,因为命令使用相对路径切换子目录。
  • 建议在独立虚拟环境中安装,避免与已有 torch 版本冲突。
  • 项目同时提供官网 https://3d.hunyuan.tencent.com 与 HuggingFace Demo,可先在线体验再本地部署。

核心亮点

  • 单图生成高精度几何,细节还原度高,适合复杂物体
  • 直接输出PBR材质贴图,省去手动调材质的繁琐步骤
  • 开源且提供完整推理代码,支持自定义训练和二次开发

不足之处

  • 生成速度较慢,高分辨率输出需要较强GPU资源
  • 对复杂拓扑和透明/半透明物体支持有限
  • 文档/社区待观察

适用场景

  • 游戏开发中快速生成道具和场景资产
  • 电商产品展示图快速建模
  • 影视特效中的概念设计快速原型

替代项目

TripoSR、Stable Fast 3D、Zero123

上一篇:Wonder3D

下一篇:DreamCraft3D

同类项目推荐

ICCV2023-MCNET 开源

用一张照片生成身份一致的说话头视频

The official code of our ICCV2023 work: Implicit Identity Representation Conditioned···

★ 253 2026-08-09
ScrumSurvivor 开源

摄像头交给 AI 分身,开会走神也看不出破绽。

Survive mandatory camera-on meetings with a photorealistic AI avatar

★ 30 2026-08-09
DreamScene 开源

输入一句话,自动生成多物体 3D 场景,布局合理不打架

[ECCV2024] DreamScene: 3D Gaussian-based Text-to-3D Scene Generation via Formation P···

★ 232 2026-08-09
HunyuanWorld-1.0 开源

一句话或一张图,生成可探索交互的3D世界

Generating Immersive, Explorable, and Interactive 3D Worlds from Words or Pixels wit···

★ 2977 2026-08-09
3d-model-anything 开源

手机扫房间,浏览器里编辑三维模型

Capture iPhone LiDAR and photos, reconstruct editable Three.js rooms, and explore th···

★ 3059 2026-10-26
reality-engine 开源

用 AI 快速搭建会演变的虚拟世界和故事

Top Dynamic AI World Simulation & Storytelling Tools 2026

★ 132 2026-08-09
Hunyuan3D-1 开源

一句话或一张图,快速生成可用 3D 模型

Tencent Hunyuan3D-1.0: A Unified Framework for Text-to-3D and Image-to-3D Generation

★ 3508 2026-11-06
CVPR2022-DaGAN 开源

用深度信息让说话头视频生成更逼真、姿态更可控

Official code for CVPR2022 paper: Depth-Aware Generative Adversarial Network for Tal···

★ 998 2026-08-09
aafactory-prototype 开源

一键生成并管理你的 AI 虚拟形象

⚡ AI Avatar Factory is an interface for creating and managing AI avatars. ⚡

★ 65 2026-08-09