TripoSR：单图快速3D重建部署指南

官方信息

项目背景

3D 建模一直是专业技能：一个角色模型可能需要建模师花几天甚至几周。如果能拍一张照片就自动生成 3D 模型，那对游戏开发、虚拟现实、电商展示、3D 打印都是革命性的。

TripoSR 由 VAST（Tripo3D 母公司）和 Stability AI 联合开发，基于 Large Reconstruction Model (LRM) 架构，采用前馈神经网络直接从单张图片预测 3D 场。最大亮点是速度极快：单张图片在 GPU 上只需 0.5 秒即可生成完整的带纹理 3D 网格模型，相比之前需要分数小时优化的多视图重建方法是质的飞跃。

项目在 GitHub 上收获超过 12K Star，模型权重在 HuggingFace 上开源，是单图 3D 重建领域的里程碑项目。

核心特性

• 极快速度：单图 3D 重建仅需 0.5 秒（GPU）
• 单图输入：只需一张普通照片，无需多视角拍摄
• 完整网格：输出带纹理的三角网格，不是点云
• 多格式导出：支持 GLB、OBJ、PLY、STL 等格式
• 开源权重：模型在 HuggingFace 免费下载
• ComfyUI 集成：可作为节点集成到 ComfyUI 工作流
• MIT 协议：可商用
• CPU 可跑：虽然慢，但 CPU 也能生成（约 10 秒）

环境要求

• 操作系统：Ubuntu 20.04+/Windows 10+/macOS 12+
• Python：3.8 ~ 3.11
• 显卡：NVIDIA GPU 推荐（6GB 显存以上），CPU 也可运行
• CUDA：11.7+
• 内存：最低 8GB，推荐 16GB
• 磁盘空间：约 4GB（含模型权重）

详细部署步骤

方式一：源码部署（推荐）

第 1 步：克隆仓库

git clone https://github.com/VAST-AI-Research/TripoSR.git
cd TripoSR

第 2 步：创建虚拟环境

conda create -n triposr python=3.10 -y
conda activate triposr

# 升级 pip 和 setuptools
pip install --upgrade pip setuptools wheel

第 3 步：安装 PyTorch

# CUDA 11.8
pip install torch==2.1.0 torchvision==0.16.0 --index-url https://download.pytorch.org/whl/cu118

# CPU 版本
pip install torch torchvision

第 4 步：安装依赖

pip install -r requirements.txt

第 5 步：首次运行（自动下载模型权重）

# 对示例图片生成 3D 模型
python run.py examples/chair.jpg --output-dir output/

# 首次运行会自动从 HuggingFace 下载模型权重（约 2GB）
# 国内用户可先设置镜像：
export HF_ENDPOINT=https://hf-mirror.com

方式二：Docker 部署

# 拉取镜像
docker pull ghcr.io/vaast-ai-research/triposr:latest

# 运行（挂载输入输出目录）
docker run --gpus all -v $(pwd)/input:/input -v $(pwd)/output:/output \
  ghcr.io/vaast-ai-research/triposr:latest \
  python run.py /input/chair.jpg --output-dir /output/

方式三：ComfyUI 集成

# 进入 ComfyUI 自定义节点目录
cd ComfyUI/custom_nodes/

# 克隆 TripoSR 节点
git clone https://github.com/Stability-AI/ComfyUI-TripoSR.git
cd ComfyUI-TripoSR
pip install -r requirements.txt

# 重启 ComfyUI，在节点列表中找到 TripoSR 节点

使用方法

命令行生成 3D 模型

# 基础用法
python run.py input.jpg --output-dir output/

# 指定输出格式和网格密度
python run.py input.jpg \
  --output-dir output/ \
  --format glb \
  --mc-resolution 256

# 参数说明：
# --output-dir 输出目录
# --format 输出格式（glb/obj/ply）
# --mc-resolution Marching Cubes 分辨率（越高越精细，默认 256）
# --remove-background 是否自动移除背景（默认 True）

Python API 调用

from triposr import load_model, generate

# 加载模型（首次会自动下载权重）
model = load_model("stabilityai/TripoSR")

# 从图片生成 3D 模型
mesh = model.generate("chair.jpg")

# 导出为 GLB
mesh.export("chair.glb")

# 导出为 OBJ
mesh.export("chair.obj")

输出文件说明

• mesh.glb - 带纹理的 3D 模型（推荐，可直接拖入 Blender/Unity）
• model.obj + model.mtl - Wavefront OBJ 格式
• preview.png - 生成结果的预览图

常见问题 FAQ

Q1：模型下载很慢？
A：设置环境变量使用国内镜像：export HF_ENDPOINT=https://hf-mirror.com。或手动从 hf-mirror.com/stabilityai/TripoSR 下载模型文件，放到 ~/.cache/huggingface/hub/ 目录。

Q2：生成的 3D 模型背面有破洞？
A：TripoSR 是单图重建，只能看到照片正面，背面是 AI"想象"出来的，必然有缺陷。适合做预览和快速原型，不适合直接用于生产。游戏开发建议再用 Blender 精修。

Q3：CPU 模式要多久？
A：CPU 模式约 10~30 秒一张图，比 GPU 慢 20~50 倍。没有 N 卡的用户可以考虑用 HuggingFace Space 在线 demo。

Q4：支持人像生成吗？
A：不建议。TripoSR 训练数据主要是物体（椅子、动物、道具），人物效果很差，面部会变形。人像 3D 重建建议用专门的模型。

Q5：导出的 GLB 怎么在 Blender 中打开？
A：Blender → File → Import → glTF 2.0 (.glb)，选择生成的 mesh.glb 文件即可。导入后可以编辑、贴图、导出其他格式。

跳转链接

• GitHub 仓库：https://github.com/VAST-AI-Research/TripoSR
• HuggingFace 模型：https://huggingface.co/stabilityai/TripoSR
• 在线 Demo：HuggingFace Space
• ComfyUI 节点：https://github.com/Stability-AI/ComfyUI-TripoSR