引言

本文整理了一份SAM 3D保姆级使用指南：从硬件要求、基础环境准备，到 SAM 3D Objects 与 SAM 3D Body 的代码获取、依赖安装、模型 checkpoint 下载，再到单物体重建、多场景合成、提示引导式推理等实操教程，还附上了常见问题排查和结果导出技巧。无论你是 AI 新手还是有一定经验的开发者，都能跟着步骤直接 “抄作业”，轻松实现本地部署与 3D 重建，让这项前沿技术快速落地到你的项目中。

一、前期准备

（一）硬件要求

需配备支持 GPU 的计算设备，确保满足 PyTorch3D、CUDA 等依赖项的运行需求，建议 GPU 显存不低于 16GB（适配模型推理和批量处理场景）。

（二）基础环境依赖

• 操作系统：支持 Linux（推荐 Ubuntu 20.04 及以上）；
• 包管理工具：conda/mamba（推荐 mamba，提升环境创建速度）；
• Python 版本：3.8-3.10（需与 PyTorch、PyTorch3D 版本兼容）；
• 核心依赖库：PyTorch、PyTorch3D、Hydra、Hugging Face Hub、NVIDIA Kaolin 等。

二、模型与代码获取

（一）代码仓库地址

• SAM 3D Objects：https://github.com/facebookresearch/sam-3d-objects
• SAM 3D Body：https://github.com/facebookresearch/sam-3d-body

（二）许可证说明

代码采用 SAM 许可证（类似 Apache 2.0 的宽松许可证），允许商业用途，无需额外授权（遵守许可证条款即可）。

三、详细安装步骤

以下以 SAM 3D Objects 为例说明安装流程，SAM 3D Body 安装逻辑类似，仅需替换对应仓库和依赖配置。

（一）环境创建与激活

1. 克隆代码仓库（可选，也可直接通过配置文件创建环境）：

   git clone https://github.com/facebookresearch/sam-3d-objects.git
   cd sam-3d-objects
   

2. 用 mamba 创建并激活专用环境：

   mamba env create -f environments/default.yml
   mamba activate sam3d-objects
   

（二）依赖库安装

1. 配置 PyTorch/CUDA 依赖项的额外索引 URL：

   export PIP_EXTRA_INDEX_URL="https://pypi.ngc.nvidia.com https://download.pytorch.org/whl/cu121"
   

2. 安装核心依赖与 PyTorch3D：

   # 安装核心开发依赖
   pip install -e '.[dev]'
   # 单独安装 PyTorch3D（解决依赖兼容问题）
   pip install -e '.[p3d]'
   

3. 安装推理相关依赖：

   export PIP_FIND_LINKS="https://nvidia-kaolin.s3.us-east-2.amazonaws.com/torch-2.5.1_cu121.html"
   pip install -e '.[inference]'
   

4. 修补 Hydra 相关组件（适配最新功能）：

   ./patching/hydra
   

   （注：该补丁对应 Hydra 官方 PR：https://github.com/facebookresearch/hydra/pull/2863，若后续版本已集成该功能，可跳过此步骤）

（三）模型下载

1. 安装 Hugging Face Hub 命令行工具：

   pip install 'huggingface-hub[cli]<1.0'
   

2. 下载 SAM 3D Objects 检查点（需先在 Hugging Face 申请访问权限）：

   TAG=hf
   hf download \
     --repo-type model \
     --local-dir checkpoints/${TAG}-download \
     --max-workers 1 \
     facebook/sam-3d-objects
   # 整理检查点目录
   mv checkpoints/${TAG}-download/checkpoints checkpoints/${TAG}
   rm -rf checkpoints/${TAG}-download
   

（四）SAM 3D Body 额外配置

1. 克隆 SAM 3D Body 仓库并创建环境（步骤同 SAM 3D Objects，使用对应仓库的 default.yml 配置文件）；
2. 可用模型检查点（需申请访问权限）：
• facebook/sam-3d-body-dinov3
• facebook/sam-3d-body-vith
3. 按仓库 README 说明安装额外依赖（与 SAM 3D Objects 重叠依赖可跳过重复安装）。

四、推理运行教程

（一）SAM 3D Objects 推理

1. 基础推理（单物体重建）

import sys
# 添加 notebook 目录到系统路径，导入推理模块
sys.path.append("notebook")
from inference import Inference, load_image, load_single_mask

# 配置模型路径
tag = "hf"
config_path = f"checkpoints/{tag}/pipeline.yaml"
# 初始化推理器（compile=False 可适配更多环境，如需提速可设为 True）
inference = Inference(config_path, compile=False)

# 加载输入图像和分割掩码（需替换为自己的图像路径）
# 图像路径：notebook/images/[你的图像目录]/image.png
# 掩码路径：notebook/images/[你的图像目录]，index 为掩码编号
image = load_image("notebook/images/shutterstock_stylish_kidsroom_1640806567/image.png")
mask = load_single_mask("notebook/images/shutterstock_stylish_kidsroom_1640806567", index=14)

# 运行推理（seed 用于固定结果，可修改探索不同重建效果）
output = inference(image, mask, seed=42)

# 导出结果（支持 .ply、.obj、.glb 等格式）
# 导出高斯泼溅结果
output["gs"].save_ply(f"splat.ply")
# 导出网格结果（若需）
# output["mesh"].export("output_mesh.obj")

2. 进阶使用（多物体场景重建）

1. 先用 2D 分割模型（如 SAM 3、DeepLab）获取场景中所有物体的掩码；
2. 循环遍历每个（图像-掩码）对，调用推理器生成单个物体的 3D 重建结果；
3. 按坐标系对齐所有物体的 3D 表示，合成完整场景。

3. 参数调整技巧

• seed：扩散种子，修改可生成不同风格的重建结果（如 seed=100、200）；

• noise schedule：噪声调度，可通过配置文件调整，平衡重建速度与细节；

• 批量处理：传入列表格式的（image, mask）对，示例：

  # 批量处理示例
  image_mask_pairs = [
      (load_image("path/to/image1.png"), load_single_mask("path/to/mask_dir1", index=0)),
      (load_image("path/to/image2.png"), load_single_mask("path/to/mask_dir2", index=1))
  ]
  outputs = [inference(img, msk, seed=42) for img, msk in image_mask_pairs]
  

（二）SAM 3D Body 推理

1. 基础全身体重建

# 参考仓库 demo.py 脚本，核心步骤如下
from sam3d_body.inference import BodyInference

# 初始化推理器（加载对应检查点）
inference = BodyInference("checkpoints/facebook/sam-3d-body-dinov3")

# 加载人体图像（建议裁剪后输入，聚焦人体区域）
image = load_image("path/to/human_image.png")

# 运行推理（可选传入 2D 关键点或掩码提示）
output = inference(image, keypoints=None, mask=None, seed=42)

# 导出 MHR 格式网格（支持在 Unity、Blender 中打开编辑）
output["mesh"].save("human_body_mesh.glb")

2. 提示引导式重建（优化复杂姿态）

当人体存在遮挡或复杂姿态时，可传入 2D 关键点提示提升精度：

# 示例：传入 2D 关键点（格式：[(x1,y1,label1), (x2,y2,label2), ...]）
keypoints = [(100, 200, "right_shoulder"), (150, 220, "left_shoulder"), ...]
output = inference(image, keypoints=keypoints, seed=42)

五、在线体验

对于快速测试或非开发场景，可直接使用 Meta 提供的在线实验平台：

❝

地址：https://aidemos.meta.com/segment-anything/editor/convert-image-to-3d/?ref=blog.roboflow.com

• SAM 3D Object 在线平台：上传图像后点击选择物体，实时生成 3D 重建结果；

❝

地址：https://aidemos.meta.com/segment-anything/editor/convert-body-to-3d/?ref=blog.roboflow.com

• SAM 3D Body 在线平台：上传人体图像，支持交互式调整重建细节；
• 平台集成 SAM 3 分割功能，可直接在浏览器中完成“分割-重建”全流程，结果支持下载导出。

六、常见问题排查

1. 依赖安装失败：
• 确保 CUDA 版本与 PyTorch 兼容（推荐 CUDA 12.1）；
• PyTorch3D 安装失败时，参考官方文档手动安装：https://pytorch3d.org/docs/installation；
2. 检查点下载权限不足：在 Hugging Face 对应模型页面提交访问申请，审核通过后重新运行下载命令；
3. 推理时显存不足：
• 降低批量处理规模；
• 关闭 compile 选项（inference = Inference(config_path, compile=False)）；
• 减少每个体素的高斯泼溅点数（通过配置文件调整）；
4. 重建结果模糊或遮挡处理不佳：
• 传入更精准的分割掩码；
• 调整 seed 或噪声调度参数；
• 对复杂场景启用提示引导式重建。

七、结果导出与应用

• 支持导出格式：.ply、.obj（多边形网格）、.glb（通用 3D 格式）；
• 兼容软件：Unity、Blender、Maya 等主流 3D 建模/渲染工具；
• 应用场景：AR 场景搭建、虚拟人动画制作、游戏资产生成、机器人视觉导航等。

好了，这篇文章就介绍到这里，喜欢的小伙伴感谢给点个赞和关注，更多精彩内容持续更新~~