通过百舸平台快速开始运行 LingBot-Depth
更新时间：2026-03-27
LingBot-Depth 简介
LingBot-Depth 是基于 Masked Depth Modeling 的深度补全与精化模型，由蚂蚁集团 Robbyant 团队开发。模型将不完整、噪声较大的深度传感器数据转化为高质量、保持度量精度的 3D 测量结果，在统一的潜空间中联合对齐 RGB 外观和深度几何。
核心能力：
- 深度补全与精化：填充缺失区域，同时保持度量精度
- 场景重建：利用强深度先验进行室内建图
- 4D 点跟踪：在度量空间中进行动态跟踪
- 灵巧操作：通过精确几何理解实现鲁棒抓取
环境配置
硬件配置
| 部署要求 | 最佳实践 | |
|---|---|---|
| CPU | 按需 | 建议按表单默认值及以上 |
| 内存 | 按需 | 建议 32G 及以上 |
| GPU | Nvidia 显卡一卡以上（bfloat16 支持，Ampere+） | L20 * 1 |
| CDS | 按需 | 模型较小，按需挂载 |
部署环境要求 & 最佳实践建议
| 部署要求 | 最佳实践 | |
|---|---|---|
| Python | >= 3.9 | 3.9 |
| PyTorch | == 2.6.0 | 2.6.0（pyproject.toml 锁定） |
| xformers | == v0.0.29.post2 | v0.0.29.post2（pyproject.toml 锁定） |
| CUDA | 需要 | CPU 推理目前不可用 |
注意：LingBot-Depth 仅提供推理代码，不包含训练脚本。
基础环境
百舸预置镜像已经为您封装了运行环境以及项目代码，您可以快速进入工作目录：
Bash
1cd /root/workspace/lingbot-depth
2conda activate lingbot-depth目录结构
Plain Text
1/root/workspace/lingbot-depth/
2├── example.py # 推理入口脚本
3├── requirements.txt # 依赖声明
4├── pyproject.toml # 包配置（包名: mdm）
5├── examples/ # 8 个示例场景
6│ ├── 0/ ... 7/ # 每个包含:
7│ │ ├── rgb.png # RGB 图像
8│ │ ├── raw_depth.png # 原始深度（16-bit PNG）
9│ │ ├── raw_depth_color.png # 深度可视化
10│ │ └── intrinsics.txt # 相机内参矩阵
11└── mdm/ # 核心 Python 包
12 ├── model/
13 │ ├── v2.py # MDMModel 主类
14 │ ├── dinov2_rgbd/ # DINOv2 RGB-D backbone
15 │ └── ...
16 └── utils/
17 ├── geo.py # 深度转点云
18 └── vis.py # 可视化推理
本快速开始演示了如何基于百舸预置 LingBot-Depth 镜像快速运行深度估计推理。
快速运行
Bash
1cd /root/workspace/lingbot-depth
2conda activate lingbot-depth
3
4# 处理示例场景 0（首次运行会自动从 HuggingFace 下载模型）
5python example.py
6
7# 指定不同场景（0-7）
8python example.py --example 1
9
10# 使用深度补全模型（针对稀疏深度优化）
11python example.py --model robbyant/lingbot-depth-postrain-dc-vitl14
12
13# 自定义输出目录
14python example.py --output my_results参数说明
| 参数 | 默认值 | 说明 |
|---|---|---|
--example |
0 |
示例场景编号（0-7） |
--model |
robbyant/lingbot-depth-pretrain-vitl-14-v0.5 |
HuggingFace 模型 ID 或本地路径 |
--output |
result |
输出目录 |
--device |
auto |
设备：auto / cuda |
--no-mask |
False | 禁用无效区域掩码 |
输出文件
Plain Text
1result/
2├── rgb.png # 原始 RGB
3├── depth_input.npy # 输入深度（numpy 格式）
4├── depth_refined.npy # 精化后深度（numpy 格式）
5├── depth_input.png # 输入深度可视化
6├── depth_refined.png # 精化深度可视化
7├── depth_comparison.png # 对比图
8└── point_cloud.ply # 3D 点云Python API 调用
Python
1import torch
2from mdm.model.v2 import MDMModel
3
4device = torch.device("cuda")
5model = MDMModel.from_pretrained(
6 'robbyant/lingbot-depth-pretrain-vitl-14-v0.5'
7).to(device)
8
9# image: [B, 3, H, W] float32 归一化到 [0,1]
10# depth: [B, H, W] float32 米制单位，无效值设为 0 或 NaN
11# intrinsics: [B, 3, 3] 归一化相机内参（fx/W, fy/H, cx/W, cy/H）
12output = model.infer(image, depth_in=depth, intrinsics=intrinsics)
13
14depth_pred = output['depth'] # [B, H, W] 精化后深度
15points = output['points'] # [B, H, W, 3] 点云
16mask = output['mask'] # [B, H, W] 有效区域掩码可用模型
| 模型 | HuggingFace ID | 说明 |
|---|---|---|
| v0.5（推荐） | robbyant/lingbot-depth-pretrain-vitl-14-v0.5 |
通用深度精化与补全 |
| v0.1 | robbyant/lingbot-depth-pretrain-vitl-14 |
通用深度精化 |
| DC（深度补全） | robbyant/lingbot-depth-postrain-dc-vitl14 |
针对稀疏深度补全优化 |
模型通过 huggingface_hub 自动下载，首次运行时触发。
手动下载模型
Bash
1# 方式一：通过百舸 BOS（推荐，内网高速）
2bcecmd bos cp bos:/aihc-models-bj/lingbot/lingbot-depth-v0.5 /root/workspace/lingbot-depth-model -r
3
4# 使用本地模型
5python example.py --model /root/workspace/lingbot-depth-model/model.pt
6
7# 方式二：通过 HuggingFace（自动下载到缓存）
8export HF_ENDPOINT=https://hf-mirror.com
9python example.py # 自动下载与 LingBot 其他模块的关系
LingBot-Depth 作为 LingBot-VLA 的子模块被集成，为 VLA 的深度蒸馏变体提供空间感知能力：
Plain Text
1LingBot-VLA-4B-Depth
2├── 视觉编码器
3├── LingBot-Depth ← 深度精化（git submodule）
4├── MoGe ← 单目几何（git submodule）
5└── 动作预测头常见问题
1. CPU 推理失败
Plain Text
1RuntimeError: ...解决：LingBot-Depth 使用 bfloat16 autocast，目前仅支持 CUDA 设备（已知 issue #22）。百舸开发机默认配备 GPU，不受影响。
2. 输出点云噪声较大
解决：检查输入深度数据质量，确保无效值设为 0 或 NaN（已知 issue #21）。
3. 输入数据格式
- RGB：float32，归一化到 [0, 1]
- 深度：float32，米制单位（原始 uint16 除以 1000），无效值为 0 或 NaN
- 内参：3x3 矩阵，按图像尺寸归一化（fx/W, fy/H, cx/W, cy/H）
评价此篇文章