Stable Fast 3D：单图快速3D网格重建部署指南

官方信息

项目背景

3D 资产制作是游戏和影视行业的成本大头。一个高质量的角色或道具模型，建模师可能要花几十小时。如果能从一张概念图直接生成可用的 3D 网格，将大幅降低 3D 内容创作的门槛。

Stable Fast 3D（简称 SF3D）由 Stability AI 开发，基于 Large Reconstruction Model (LRM) 架构训练。与 TripoSR 相比，SF3D 的最大创新是输出 UV 展开的纹理网格 + 材质参数（PBR）——这意味着生成的 3D 模型可以直接用于游戏引擎（Unity/Unreal），不需要重新展 UV 和绘制贴图。模型在 0.5 秒内完成推理，是目前最快的开源 3D 重建模型之一。

项目在 GitHub 上收获超过 8K Star，论文发表后引起广泛关注，被视为 3D AIGC 领域的重要突破。

核心特性

• 极速推理：单图 3D 重建仅需 0.5 秒
• UV 展开网格：输出已经 UV unwrap 的三角网格，可直接导入引擎
• PBR 材质：同时生成反照率（albedo）、法线、粗糙度等材质贴图
• 反照率解耦：分离光照和材质，便于后续编辑
• Gradio WebUI：提供网页界面，上传图片即可生成
• MIT 协议：完全开源可商用
• 多格式导出：GLB、OBJ、USD 等
• HuggingFace Demo：无需本地部署即可在线体验

环境要求

• 操作系统：Ubuntu 22.04+/Windows 10+/macOS 12+
• Python：3.10
• 显卡：NVIDIA GPU 推荐（8GB 显存以上）
• CUDA：11.8+
• 内存：16GB 以上
• 磁盘空间：约 5GB（含模型权重）

详细部署步骤

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

第 1 步：克隆仓库

git clone https://github.com/Stability-AI/stable-fast-3d.git
cd stable-fast-3d

第 2 步：创建虚拟环境

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

第 3 步：安装 PyTorch

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

第 4 步：安装项目依赖

pip install -r requirements.txt

# 安装 PyMeshLab（用于网格处理）
pip install pymeshlab

第 5 步：下载模型权重

# 国内用户先设置镜像
export HF_ENDPOINT=https://hf-mirror.com

# 首次运行会自动从 HuggingFace 下载权重到 ~/.cache/huggingface/
# 模型仓库：stabilityai/stable-fast-3d

第 6 步：启动 Gradio WebUI

python gradio_app.py

启动后访问 http://localhost:7860。

方式二：Docker 部署

# 拉取镜像
docker pull ghcr.io/stability-ai/stable-fast-3d:latest

# 启动 WebUI
docker run --gpus all -p 7860:7860 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  ghcr.io/stability-ai/stable-fast-3d:latest

方式三：在线体验（免部署）

不想本地部署的用户，可以直接使用 HuggingFace Space 在线 Demo：

1. 访问 https://huggingface.co/spaces/stabilityai/stable-fast-3d
2. 上传图片（支持 JPG/PNG）
3. 点击 Generate，等待约 10 秒（排队时间除外）
4. 下载生成的 GLB 文件

使用方法

WebUI 操作

1. 打开 http://localhost:7860
2. 上传或拖入一张物体图片（背景简洁效果最佳）
3. 调整参数：
   • Remove Background：自动移除背景（默认开启）
   • Surface Simplification：网格简化比例（默认 0.9，数值越小面数越少）
   • Texture Resolution：贴图分辨率（1024/2048）
4. 点击"Generate"按钮
5. 等待 5~10 秒，右侧预览生成的 3D 模型（可旋转查看）
6. 点击"Download"下载 GLB 文件

Python API 调用

from sf3d.system import SF3D
from sf3d.utils import remove_background, resize_foreground
import torch
from PIL import Image

# 加载模型
device = "cuda" if torch.cuda.is_available() else "cpu"
model = SF3D.from_pretrained("stabilityai/stable-fast-3d", trust_remote_code=True).to(device)

# 加载图片
image = Image.open("chair.jpg").convert("RGB")
image = remove_background(image)
image = resize_foreground(image, 0.85)

# 生成 3D 模型
with torch.no_grad():
    mesh, glob_dict = model.run_image(image, device=device)

# 导出 GLB
mesh.export("chair.glb")
print("3D model saved to chair.glb")

输出文件说明

• mesh.glb - 带 PBR 材质的 3D 模型（可直接导入 Blender/Unity/Unreal）
• albedo.png - 反照率贴图（去光照后的纯材质颜色）
• normal.png - 法线贴图
• roughness.png - 粗糙度贴图

常见问题 FAQ

Q1：模型下载慢怎么办？
A：设置 export HF_ENDPOINT=https://hf-mirror.com 使用国内镜像。或手动从 hf-mirror.com/stabilityai/stable-fast-3d 下载全部文件，放到本地目录后用 SF3D.from_pretrained("./local_dir") 加载。

Q2：生成的模型有很多毛刺？
A：在 WebUI 中调高 Surface Simplification 比例（如 0.95），或导出后在 Blender 中用 Remesh + Smooth 修改器清理。输入图片背景越干净效果越好。

Q3：和 TripoSR 有什么区别？
A：两者都是单图 3D 重建。TripoSR 速度更快、模型更小；SF3D 输出 UV 展开 + PBR 材质，更适合直接用于游戏引擎。选择取决于使用场景。

Q4：显存不够怎么办？
A：把 Texture Resolution 降到 1024，Surface Simplification 调到 0.95。如果还是 OOM，尝试在 CPU 上运行（速度约 30 秒）。

Q5：生成的模型可以商用吗？
A：可以。Stable Fast 3D 采用 MIT 协议，模型权重可免费用于商业用途。

跳转链接

• GitHub 仓库：https://github.com/Stability-AI/stable-fast-3d
• 项目主页：https://stable-fast-3d.github.io
• HuggingFace 模型：https://huggingface.co/stabilityai/stable-fast-3d
• 在线 Demo：HuggingFace Space
• 论文 PDF：https://arxiv.org/abs/2408.00653