LingBot-Depth 2.0 空间感知模型与开源框架的兼容性配置

LingBot-Depth 2.0 这类深度估计模型在接入开源框架时，主要瓶颈并不在模型结构，而在权重格式与算子兼容性。先确认模型交付的是 PyTorch 权重、ONNX 还是 TensorRT 引擎，再决定沿用原框架推理还是转换后接入。这一判断决定后续所有配置动作，如果拿到的是 PyTorch 权重，却直接拿去给 ONNX Runtime 加载，会得到“无法解析模型”之类的错误；反过来，若目标环境只支持 ONNX，就需要先完成导出和校验。

LingBot-Depth 2.0 兼容性配置通常按“格式确认 → 最小推理 → 预处理对齐 → 封装接口”四步走。建议优先用 ONNX Runtime 接入，PyTorch 环境可直接加载原始权重；若目标框架是 OpenCV 或 ROS，先转 ONNX 并验证动态尺寸支持。

先确认模型交付的三种形态

第一种是 PyTorch 权重文件（如 .pt / .pth），适合 Python 环境直接加载，保留完整模型结构。第二种是 ONNX 文件，适合跨语言、跨框架调用，也是接入 C++/Rust 等场景最稳妥的中间格式。第三种是 TensorRT 引擎（.engine），它绑定 GPU 型号和 TensorRT 版本，只能在打包机器上运行，不适合直接分发给其他环境。拿到文件后先用 onnx.checker.check_model 或简单打印输入输出结构验证，而不是直接丢进目标框架。

PyTorch 环境的最小推理骨架

如果目标服务本身就在 PyTorch 生态，不需要额外转换。以下代码展示加载权重并做一次前向推理，输入尺寸和均值方差需要按模型发布时的配置填写，通常深度模型输入是 3 通道 RGB，归一化到 [0,1] 或 [-1,1]。

import torch

model = torch.load('lingbot_depth.pt', map_location='cpu')
model.eval()

input_tensor = torch.randn(1, 3, 384, 384)

with torch.no_grad():
    depth = model(input_tensor)

print(depth.shape)

这个骨架只解决“能不能跑”的问题。验证方式是看输出 depth 的 shape 和值域是否符合预期；风险是 torch.load 可能执行反序列化代码，建议只在信得过的权重上直接加载，否则先转成 ONNX 再接入。

ONNX Runtime 接入时的兼容性检查

转到 ONNX Runtime 是多数开源框架接入的通用路径。先把模型导出为 ONNX，再写一个最小推理脚本。以下代码假设模型已导出为 lingbot_depth.onnx，输入输出名需要先用工具查看。

import onnxruntime as ort
import numpy as np

sess = ort.InferenceSession('lingbot_depth.onnx', providers=['CPUExecutionProvider'])

input_name = sess.get_inputs()[0].name
output_name = sess.get_outputs()[0].name

x = np.random.randn(1, 3, 384, 384).astype(np.float32)

depth = sess.run([output_name], {input_name: x})[0]
print(depth.shape)

这一步重点检查三件事：输入通道顺序是不是 RGB、归一化参数是否与原版训练一致、输出 depth 是否带 inverse 或其他变换。如果模型在导出时声明了动态维度，输入尺寸可以放宽；如果固定尺寸，输入必须严格匹配，否则会报维度错误。

验证清单与常见风险

按照下面的项逐条确认，能覆盖大多数兼容性问题：

输入尺寸与通道：确认模型训练时的高度、宽度、通道数，以及是否需要 resize 到固定尺寸；
归一化参数：找模型的 mean/std 配置，预处理时若不一致，输出深度值会整体偏移；
输出值含义：确认输出是视差、逆深度还是绝对深度，是否需要指数还原或缩放；
动态轴支持：如果目标框架需要多分辨率输入，导出 ONNX 时应声明动态轴，并在运行前测试两个不同尺寸；
后端算子限制：ONNX Runtime 的 CPU 与 CUDA 实现存在算子差异，遇到不支持的算子时改成显式导出子图或换 PyTorch 后端。

最后一条容易忽略：很多深度模型包含 Resize、GridSample 这类算子，不同版本的 ONNX Runtime 支持情况不同。建议先在本地跑通最小推理，再接入 ROS 或 OpenCV 的封装层，这样排查问题时可以更快定位是框架问题还是模型问题。