• 计算机视觉
• 深度学习
• 大模型
• 媒体生成

SAM-3D-Objects 是一个零样本 3D 物体生成模型：只需提供一张图片，就能生成完整的 3D Mesh（OBJ）和 3D Gaussian Splatting（PLY）结果，无需任何额外标注或微调。本文带你快速了解这套基于 TRELLIS 架构的 3D 生成方案如何跑起来。

📦 模型是什么：3.15B 参数的两阶段稀疏3D扩散

SAM-3D-Objects 的核心是一个3.15B 参数的两阶段稀疏 3D 扩散模型（Two-stage Sparse 3D Diffusion），它把"单张 2D 图片 → 完整 3D 物体"拆成了可解释的两步：

它不执行 3D 分割，而是纯粹的3D 生成：给一张物体照片，模型推断出物体的完整几何结构。这也是"零样本"的含义——不用针对新物体做任何训练，模型直接泛化。

🔍 生成流程详解：一张图片的"四步旅行"

整条推理链路定义在 inference_pipeline_pointmap.py 的run方法中，分为四个阶段：

第 1 步：深度感知（Point Map 估计）由 MoGe 单目深度模型（配置见 weights/pipeline.yaml 中的depth_model段）从单张图片估计每个像素的 3D 位置，得到 pointmap——相当于给 2D 图片"穿上 3D 透视外套"，为后续生成提供尺度与位姿参考。

第 2 步：SS Generator 采样稀疏结构sample_sparse_structure用 Shortcut ODE solver 做扩散采样，输出 16×16×16 的稀疏体素占据图（ss > 0的坐标即物体所在空间），再经降采样得到更稀疏的坐标集。

第 3 步：SLAT Generator 生成潜在特征sample_slat在第 2 步的坐标位置上，用 Flow Matching 扩散采样生成每个位置的 8 维潜在特征（SparseTensor），编码物体的精细外观与几何细节。

第 4 步：双解码器输出两种 3D 表示decode_slat并行调用两个解码器（见 inference_pipeline.py）：

• GS Decoder→ 标准 3DGS PLY 文件（2400 个高斯点，含位置、颜色、不透明度、尺度、旋转共 17 个属性）
• Mesh Decoder（FlexiCubes）→ 标准 Wavefront OBJ 网格，res=64 分辨率等值面提取

💡 扩散采样（前两步）约占90% 的计算时间，这也是单样本耗时较长的主要原因。

⚙️ 环境准备与快速上手

本仓库已包含针对Ascend 910B2 + CANN 8.5.0的 NPU 适配（8 项兼容性修复），新手无需关心底层细节，直接按 README.md 执行即可。

硬件与软件要求

三步跑通：安装、准备、推理

# 1. 安装依赖 pip install -r adaptation/requirements.txt # 2. 设置权重镜像（DINOv2 视觉编码器下载） export HF_ENDPOINT=https://hf-mirror.com # 3. 执行推理（ISO3D 数据集上的 5 个样本） cd adaptation python ascend_infer.py --model-path weights/sam3dobjects/ \ --data-path ../dataset/iso3d-dataset/ --device npu:0

也可以只挑指定样本推理：

python ascend_infer.py --model-path weights/sam3dobjects/ \ --data-path ../dataset/iso3d-dataset/ --device npu:0 \ --samples A_cartoon_house_with_red_roof a_baby_penguin

推理完成后，输出保存在npu_inference_results/outputs/：

• *.obj— 3D Mesh（顶点 625~1642 个，面 1176~3142 个）
• *.ply— 3D Gaussian Splatting 点云
• *.npy— 稀疏体素坐标

用 Python API 直接调用

完整用法见 使用指导书，核心只有几行：

from sam3d_objects.pipeline.inference_pipeline import InferencePipeline pipeline = InferencePipeline( ss_generator_config_path="weights/ss_generator.yaml", # ... 5 组 ckpt 路径配置 decode_formats=["gaussian", "mesh"], # 同时输出两种 3D 表示 dtype="float32", # NPU 上必须 fp32 device="npu", ) result = pipeline.run(image=image, seed=42)

各模型模块的配置分别存放在 weights/ 目录：ss_generator.yaml、slat_generator.yaml、slat_decoder_gs.yaml、slat_decoder_mesh.yaml等，权重清单详见 WEIGHTS_README.md。

🖼️ ISO3D 数据集：101 张白底物体图

仓库自带ISO3D 数据集，专用于评估 image-to-3D 模型的零样本生成能力：

• dataset/iso3d-dataset/png@1024/ — 101 张 1024×1024 白底物体图（输入）
• dataset/iso3d-dataset/jpg@512/ — 512 缩略图
• dataset/iso3d-dataset/prompts.txt — 每张图对应的生成 prompt

数据集覆盖几何复杂度差异极大的物体——从简单球体、椅子到精细的花瓶、卡通房屋，是检验 3D 生成模型泛化能力的好基准。

📊 性能与精度：实际跑起来是什么水平

推理性能（Ascend 910B2，float32）

精度对齐（ISO3D 评测集）

论文复刻率100%（3/3 指标通过，验收标准 ≥95%）。更多评测细节可查 四阶段精度汇总 与 NPU 视觉质量评估报告。

⚠️ 新手必读：3 个常见坑

1. 推理出现 NaN→ 必须使用float32。NPU 上 fp16 会在 attention 层产生 NaN，这是 NPU 移植的头号坑点。
2. Mesh 输出 0 个顶点→ 检查 fp32 强制、手动 GroupNorm、FlexiCubes 设备同步三项修复是否生效（均已在仓库代码中集成，见 使用指导书 FAQ）。
3. 推理慢（~23.5s/样本）属正常现象→ 耗时主要来自 50 步扩散采样；可调低采样步数提速（会损失质量），或用 profiler 分析瓶颈算子（MatMul 占 74.4% 计算时间）。

📚 延伸阅读与关键路径

一句话总结：SAM-3D-Objects = 一张白底图片 + 一条命令 = 可导出的 3D Mesh 与 Gaussian 点云。从"看图"到"拿模型"，零样本 3D 生成从未如此接近——不妨从ascend_infer.py那条命令开始你的第一次尝试 🚀

• 计算机视觉
• 深度学习
• 大模型
• 媒体生成