LingBot-Depth-ViT-L14开源模型实战：Python调用REST API返回base64深度图

LingBot-Depth-ViT-L14开源模型实战：Python调用REST API返回base64深度图

1. 引言

想象一下，你手头只有一张普通的室内照片，但你需要知道照片里每个物体离摄像头到底有多远。比如，你想让机器人在这间屋子里自主导航，或者想为这个场景创建一个3D模型。传统方法要么需要昂贵的激光雷达，要么需要复杂的双目摄像头。但现在，有了像 LingBot-Depth-ViT-L14 这样的模型，事情就简单多了。

LingBot-Depth-ViT-L14 是一个基于 DINOv2 视觉大模型（ViT-Large/14）的深度估计与补全模型。简单来说，它就像一个拥有“几何视觉”的AI。给它一张彩色照片，它就能“猜”出照片里每个像素点的深度（距离），生成一张深度图。更厉害的是，如果你已经有了一些稀疏的深度数据（比如来自低成本的深度传感器），它还能把这些不完整的数据“补全”，生成一张完整、平滑的高质量深度图。

这篇文章，我将带你从零开始，快速上手这个强大的模型。我们不仅会通过网页界面直观感受它的能力，更重要的是，我会手把手教你如何用 Python 代码，通过 REST API 来调用它，并直接获取 base64 编码的深度图结果。无论你是做机器人、3D重建，还是AR/VR开发，掌握这个技能都能让你的项目如虎添翼。

2. 环境准备与快速部署

2.1 部署模型镜像

首先，我们需要一个运行环境。LingBot-Depth-ViT-L14 已经被封装成了一个开箱即用的 Docker 镜像，部署过程非常简单。

1. 找到镜像：在你使用的云平台或服务器的镜像市场中，搜索镜像名ins-lingbot-depth-vitl14-v1。
2. 启动实例：点击“部署实例”按钮。系统会基于insbase-cuda124-pt250-dual-v7这个底座（它包含了 PyTorch 2.6.0 和 CUDA 12.4 环境）来创建。
3. 等待启动：实例创建后，状态会变为“启动中”。首次启动需要大约 1-2 分钟来初始化环境，并且会加载这个 3.21 亿参数的大模型到 GPU 显存中，这个过程大约需要 5-8 秒。当状态变为“已启动”时，就说明一切就绪了。

2.2 访问与验证服务

实例启动后，会开放两个端口供我们访问：

• 7860 端口：这是 Gradio 提供的可视化 Web 界面，适合手动测试和效果预览。
• 8000 端口：这是 FastAPI 提供的 REST API 接口，正是我们写代码要调用的核心。

快速验证（通过 WebUI）： 在实例管理页面，找到你刚部署的实例，点击旁边的“HTTP”入口按钮（或者直接在浏览器地址栏输入http://<你的实例IP地址>:7860），就能打开测试页面。

页面上传一张图片（比如镜像内自带的示例图片/root/assets/lingbot-depth-main/examples/0/rgb.png），选择“Monocular Depth”模式，点击“Generate Depth”，几秒钟后你就能在右侧看到生成的伪彩色深度图了。红色/橙色代表距离近，蓝色/紫色代表距离远。这个直观的体验能让你立刻明白模型在做什么。

3. 核心概念：它到底能做什么？

在写代码之前，我们先搞清楚这个模型的两个核心模式，这决定了我们调用 API 时要传递什么数据。

3.1 单目深度估计

这是最常用的模式。你只需要给它一张普通的 RGB 彩色图片，模型就能像人眼一样，根据物体的透视、遮挡、纹理等信息，“脑补”出整个场景的深度。

• 输入：一张 JPG 或 PNG 格式的彩色图片。
• 输出：一张与输入图片同分辨率的深度图，每个像素值代表该点到相机的实际距离（单位：米）。
• 好比：你看着一张风景照片，能大致判断出远处的山和近处的树哪个离你更“远”。模型做的就是把这个感觉量化成精确的数字。

3.2 深度补全

这个模式更强大。当你已经有一些深度数据，但数据不完整、有噪声或者非常稀疏时（例如来自某些深度相机的原始数据），可以用这个模式。

• 输入：一张彩色图片 + 一张对应的稀疏深度图。
• 输出：一张完整的、质量更高的深度图。模型会结合彩色图片的语义信息和稀疏深度的几何信息，把缺失的部分“画”出来，并平滑掉噪声。
• 好比：你有一张点了些疏疏拉拉高度点的地图（稀疏深度），再结合一张卫星照片（RGB），模型能帮你画出一张完整、连续的地形等高线图（完整深度）。

我们的 REST API 同时支持这两种模式。接下来，我们就进入正题，看看如何用 Python 来驾驭它。

4. Python调用REST API实战

我们将通过一个完整的 Python 脚本来演示如何调用 API。请确保你的 Python 环境安装了requests和PIL(Pillow) 库，如果没有，可以通过pip install requests Pillow安装。

4.1 编写调用脚本

创建一个名为call_lingbot_api.py的文件，将以下代码复制进去。代码里有详细的注释，我会分段解释关键部分。

import requests import base64 import json import numpy as np from PIL import Image import io import cv2 def call_lingbot_depth_api(api_url, image_path, mode='monocular', depth_path=None, camera_intrinsics=None): """ 调用 LingBot-Depth REST API 获取深度图。 参数: api_url (str): API地址，例如 'http://127.0.0.1:8000/predict' image_path (str): RGB彩色图片的本地路径。 mode (str): 模式，'monocular' 或 'completion'。 depth_path (str, optional): 稀疏深度图的本地路径（仅completion模式需要）。 camera_intrinsics (dict, optional): 相机内参字典，格式为: {'fx': 460.14, 'fy': 460.20, 'cx': 319.66, 'cy': 237.40} 返回: dict: 包含状态、深度图(base64)、原始深度数据(numpy数组)等信息的字典。 """ # 1. 准备请求数据 with open(image_path, 'rb') as f: rgb_image_bytes = f.read() rgb_image_b64 = base64.b64encode(rgb_image_bytes).decode('utf-8') payload = { "image": rgb_image_b64, "mode": mode } # 2. 如果是深度补全模式，添加深度图数据 if mode.lower() == 'completion': if not depth_path: raise ValueError("深度补全模式必须提供 depth_path 参数。") with open(depth_path, 'rb') as f: depth_image_bytes = f.read() depth_image_b64 = base64.b64encode(depth_image_bytes).decode('utf-8') payload["depth"] = depth_image_b64 # 3. 如果提供了相机内参，添加到请求中 if camera_intrinsics: # API期望的键名是 `intrinsics` payload["intrinsics"] = camera_intrinsics # 4. 设置请求头并发送POST请求 headers = {'Content-Type': 'application/json'} try: response = requests.post(api_url, json=payload, headers=headers, timeout=30) response.raise_for_status() # 如果状态码不是200，抛出异常 result = response.json() except requests.exceptions.RequestException as e: return {"status": "error", "message": f"API请求失败: {e}"} except json.JSONDecodeError: return {"status": "error", "message": "API返回的不是有效JSON格式"} # 5. 处理成功返回的结果 if result.get('status') == 'success': # 解码base64深度图，保存为图片文件 depth_map_b64 = result.get('depth_map') if depth_map_b64: depth_map_bytes = base64.b64decode(depth_map_b64) depth_image = Image.open(io.BytesIO(depth_map_bytes)) output_image_path = f"depth_result_{mode}.png" depth_image.save(output_image_path) print(f"[成功] 深度图已保存至: {output_image_path}") # 解码base64的原始深度数据（numpy数组，单位：米） depth_data_b64 = result.get('depth_data') if depth_data_b64: # 解码base64字符串为字节 depth_bytes = base64.b64decode(depth_data_b64) # 将字节加载为numpy数组 # 注意：API返回的是经过base64编码的`.npy`文件内容 depth_array = np.load(io.BytesIO(depth_bytes)) output_npy_path = f"depth_data_{mode}.npy" np.save(output_npy_path, depth_array) print(f"[成功] 原始深度数据(numpy数组)已保存至: {output_npy_path}") print(f" 深度数组形状: {depth_array.shape}, 数据类型: {depth_array.dtype}") print(f" 深度值范围: {depth_array.min():.3f}m ~ {depth_array.max():.3f}m") # 打印其他信息 print(f"[信息] 推理模式: {result.get('mode')}") print(f"[信息] 使用设备: {result.get('device')}") print(f"[信息] 输入尺寸: {result.get('input_size')}") if 'depth_range' in result: print(f"[信息] 估计深度范围: {result.get('depth_range')}") else: print(f"[失败] API返回错误: {result.get('message', '未知错误')}") return result if __name__ == "__main__": # ============ 配置区：根据你的实际情况修改 ============ # 你的实例IP和端口 API_BASE_URL = "http://<你的实例IP>:8000" PREDICT_ENDPOINT = f"{API_BASE_URL}/predict" # 测试图片路径 (使用镜像内的示例图片，或替换为你自己的图片路径) RGB_IMAGE_PATH = "/root/assets/lingbot-depth-main/examples/0/rgb.png" SPARSE_DEPTH_PATH = "/root/assets/lingbot-depth-main/examples/0/raw_depth.png" # 相机内参 (可选，用于深度补全和更精确的3D重建) INTRINSICS = { "fx": 460.14, "fy": 460.20, "cx": 319.66, "cy": 237.40 } # ===================================================== print("开始测试 LingBot-Depth REST API...") print(f"API地址: {PREDICT_ENDPOINT}") # 测试1: 单目深度估计模式 print("\n" + "="*50) print("测试1: 单目深度估计模式") print("="*50) result_mono = call_lingbot_depth_api( api_url=PREDICT_ENDPOINT, image_path=RGB_IMAGE_PATH, mode='monocular' # camera_intrinsics 在单目模式下非必需，但提供有助于尺度一致性 # intrinsics=INTRINSICS ) # 测试2: 深度补全模式 print("\n" + "="*50) print("测试2: 深度补全模式") print("="*50) result_comp = call_lingbot_depth_api( api_url=PREDICT_ENDPOINT, image_path=RGB_IMAGE_PATH, mode='completion', depth_path=SPARSE_DEPTH_PATH, camera_intrinsics=INTRINSICS )

4.2 代码关键点解析

1. 构建请求：API 的端点（Endpoint）是/predict，我们使用 HTTP POST 方法，并以 JSON 格式发送数据。核心数据就是把图片文件读取为字节，然后用base64编码成字符串。
2. 模式选择：通过mode字段告诉 API 你要用哪种模式：monocular（单目）或completion（补全）。
3. 处理返回结果：API 成功后会返回一个 JSON。里面最重要的两个字段是：
   • depth_map: Base64 编码的深度图（PNG格式，伪彩色）。我们可以直接解码并保存为图片，方便可视化。
   • depth_data: Base64 编码的原始深度数据（NumPy.npy格式）。这是我们进行后续三维计算（如生成点云）真正需要的数据，单位是米。
4. 相机内参：intrinsics参数包含相机的焦距（fx, fy）和主点（cx, cy）。在深度补全模式下，提供准确的内参对生成正确的 3D 点云至关重要。单目模式下，它有助于稳定深度尺度。

4.3 运行与结果

在运行脚本前，请务必将代码中的<你的实例IP>替换成你实际部署实例的 IP 地址。

python call_lingbot_api.py

如果一切顺利，你将在终端看到类似以下的输出，并且在当前目录下生成两个结果文件：

开始测试 LingBot-Depth REST API... API地址: http://192.168.1.100:8000/predict ================================================== 测试1: 单目深度估计模式 ================================================== [成功] 深度图已保存至: depth_result_monocular.png [成功] 原始深度数据(numpy数组)已保存至: depth_data_monocular.npy 深度数组形状: (480, 640), 数据类型: float32 深度值范围: 0.523m ~ 8.145m [信息] 推理模式: Monocular Depth [信息] 使用设备: cuda [信息] 输入尺寸: 640x480 [信息] 估计深度范围: 0.523m ~ 8.145m ================================================== 测试2: 深度补全模式 ================================================== [成功] 深度图已保存至: depth_result_completion.png [成功] 原始深度数据(numpy数组)已保存至: depth_data_completion.npy 深度数组形状: (480, 640), 数据类型: float32 深度值范围: 0.501m ~ 7.892m [信息] 推理模式: Depth Completion [信息] 使用设备: cuda [信息] 输入尺寸: 640x480

打开生成的depth_result_monocular.png，你就能看到模型“猜”出来的深度热力图。而depth_data_monocular.npy文件则可以用np.load()读回 Python，得到一个二维的 NumPy 数组，里面就是每个像素的精确深度值。

5. 进阶使用与技巧

掌握了基础调用后，我们来看看如何用得更好，以及需要注意什么。

5.1 如何处理你自己的图片？

脚本里用的是镜像自带的示例图片。要处理你自己的图片，只需修改RGB_IMAGE_PATH变量。模型对输入尺寸有较好的适应性，但为了最佳效果，建议将图片的宽和高调整为14的倍数（因为 ViT-L/14 的 patch 大小是14），例如 448x448, 672x378 等。如果输入其他尺寸，模型内部会做缩放，可能对精度有细微影响。

5.2 深度补全模式的数据准备

深度补全需要一张与彩色图对齐的稀疏深度图。这张深度图通常来自深度传感器（如 iPhone 的 LiDAR、Intel RealSense 的深度流）。在保存为 PNG 或 JPG 时，深度值通常需要经过缩放，因为图片格式只能存储 0-255 或 0-65535 的整数。

• 常见格式：16位单通道 PNG（0-65535）。0 通常表示无效点。你需要知道传感器的最大量程，将真实的米制深度按比例映射到这个范围。
• API 期望：我们的 API 能够自动处理常见的缩放。但为了最准确的结果，最好在提供intrinsics的同时，也通过 API 参数指明深度值的单位（如果 API 支持该参数，请参考具体文档）。示例中的raw_depth.png就是一个已经对齐并缩放好的稀疏深度图。

5.3 从深度数据到3D点云

拿到depth_data（一个 H x W 的浮点数组，单位米）和相机内参后，你就可以轻松重建出 3D 点云了。原理是利用相机的小孔成像模型：

def depth_to_pointcloud(depth_map, intrinsics): """ 将深度图转换为3D点云。 depth_map: (H, W) numpy数组，单位米。 intrinsics: 字典，包含 fx, fy, cx, cy。 返回: (N, 3)的点云数组。 """ h, w = depth_map.shape fx, fy = intrinsics['fx'], intrinsics['fy'] cx, cy = intrinsics['cx'], intrinsics['cy'] # 为每个像素生成坐标网格 u, v = np.meshgrid(np.arange(w), np.arange(h)) z = depth_map # 过滤掉无效深度（例如为0的点） valid = z > 0 u, v, z = u[valid], v[valid], z[valid] # 根据相机模型计算x, y x = (u - cx) * z / fx y = (v - cy) * z / fy pointcloud = np.stack([x, y, z], axis=-1) # 形状变为 (N, 3) return pointcloud # 使用示例 depth_array = np.load("depth_data_completion.npy") pointcloud = depth_to_pointcloud(depth_array, INTRINSICS) print(f"生成点云，共有 {pointcloud.shape[0]} 个点。") # 接下来可以用Open3D、PyVista等库进行可视化或保存为PLY文件

5.4 性能与稳定性建议

• 批处理：如果需要处理大量图片，可以考虑在客户端实现一个队列，顺序调用 API，避免短时间内发送大量请求压垮服务。
• 超时与重试：生产环境中，务必为requests.post设置合理的timeout参数，并添加重试逻辑，以应对网络波动或服务临时繁忙。
• 错误处理：我们的脚本已经包含了基本的错误处理（网络错误、JSON解析错误）。在生产中，你还可以根据 API 返回的具体错误码（如status: error）进行更细致的处理。
• 分辨率与速度：输入图片越大，推理耗时越长，显存占用也越高。对于实时应用，需要在精度和速度之间做权衡。640x480 是一个常用的平衡点。

6. 总结

通过这篇文章，我们完成了从模型部署、原理理解到编程调用的完整闭环。LingBot-Depth-ViT-L14 通过 REST API 提供了极其便捷的服务方式，让我们能在自己的 Python 项目中轻松集成强大的单目深度估计与补全能力。

回顾一下关键步骤：

1. 一键部署：找到ins-lingbot-depth-vitl14-v1镜像并部署。
2. 理解接口：核心是http://<ip>:8000/predict这个 POST 接口，它接受 base64 编码的图片和模式参数。
3. 编写调用：用requests库发送 JSON 请求，并处理返回的 base64 深度图和深度数据。
4. 结果利用：可视化深度图，或利用深度数据和相机内参生成 3D 点云，用于机器人、AR/VR、三维重建等下游任务。

这个模型就像一个随时待命的“几何视觉专家”，你只需要通过几行 HTTP 请求代码，就能为你的应用赋予感知场景三维结构的能力。无论是想降低机器人传感器的成本，还是为旧照片添加3D信息，现在你都有了现成的工具。希望这篇实战指南能帮助你快速上手，将这项技术应用到你的创意和项目中去。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。