lingbot-depth-pretrain-vitl-14实战教程：使用curl命令行调用/predict REST接口示例

lingbot-depth-pretrain-vitl-14实战教程：使用curl命令行调用/predict REST接口示例

1. 引言：为什么需要命令行调用？

当你通过网页界面测试了lingbot-depth-pretrain-vitl-14模型，看到它能够从一张普通照片中“猜出”深度信息，或者把稀疏的深度点云补全成完整的深度图时，你可能会想：这功能很酷，但怎么把它用在我自己的程序里呢？

这就是我们今天要解决的问题。虽然Gradio网页界面很方便，适合快速测试和演示，但在实际项目中，你更可能需要的是通过代码来调用这个模型。比如，你想开发一个机器人导航系统，需要实时处理摄像头画面；或者你想搭建一个批量处理图片的流水线，自动为大量图片生成深度信息。

lingbot-depth-pretrain-vitl-14镜像贴心地提供了REST API接口，让你可以用任何支持HTTP请求的编程语言来调用它。而今天，我们就从最简单、最通用的方式开始——使用curl命令行工具。

学习目标：

• 理解lingbot-depth-pretrain-vitl-14的REST API接口格式
• 掌握使用curl命令行调用深度估计和深度补全功能
• 学会处理API返回的JSON数据和深度图文件
• 了解在实际项目中集成这个模型的思路

前置知识：

• 基本的命令行操作（知道怎么打开终端、运行命令）
• 对HTTP请求有基本了解（知道什么是POST请求、JSON数据）
• 不需要深度学习或计算机视觉的专业知识

教程价值： 即使你之前没怎么用过命令行，跟着这篇教程一步步操作，你也能在10分钟内学会如何用代码的方式调用这个强大的深度估计模型。我们会用最直白的语言，配上详细的命令示例，让你真正掌握这个实用技能。

2. 环境准备：确保一切就绪

在开始调用API之前，我们需要确保模型服务已经正常运行。如果你还没有部署lingbot-depth-pretrain-vitl-14镜像，或者不确定当前状态，可以按以下步骤检查。

2.1 确认模型服务状态

首先，你需要知道你的模型实例运行在哪台服务器上。在部署平台找到你的实例，记下它的IP地址。假设你的实例IP是192.168.1.100。

打开终端（Linux/macOS）或命令提示符/PowerShell（Windows），运行以下命令检查服务是否正常：

# 检查FastAPI REST服务（端口8000） curl http://192.168.1.100:8000/ # 或者检查Gradio WebUI服务（端口7860） curl http://192.168.1.100:7860/

如果服务正常运行，你应该能看到类似这样的响应：

• FastAPI服务会返回一个JSON，包含{"message":"LingBot-Depth API is running"}
• Gradio服务会返回HTML页面代码

如果连接失败（比如显示“连接被拒绝”或超时），可能是以下原因：

1. 实例还没有完全启动（等待1-2分钟再试）
2. 防火墙或网络策略阻止了访问
3. 实例IP地址记错了

2.2 准备测试数据

为了测试API，我们需要准备一些图片。如果你按照之前的教程部署了镜像，实例里已经自带了一些示例图片。我们主要用这两个：

1. RGB彩色图片：/root/assets/lingbot-depth-main/examples/0/rgb.png

   • 这是一张室内场景的彩色照片
   • 用于测试“单目深度估计”功能

2. 稀疏深度图：/root/assets/lingbot-depth-main/examples/0/raw_depth.png

   • 这是同一场景的深度信息，但很多地方是缺失的（黑色区域）
   • 用于测试“深度补全”功能

如果你需要用自己的图片测试，可以先把图片上传到实例里。最简单的方法是使用scp命令（Linux/macOS）或者WinSCP等工具（Windows）。

3. 理解API接口：/predict端点详解

lingbot-depth-pretrain-vitl-14的REST API设计得很简洁，只有一个主要端点：/predict。但这个端点很强大，通过不同的参数配置，可以实现两种核心功能。

3.1 API基本信息

• 接口地址：http://<你的实例IP>:8000/predict
• 请求方法：POST
• 请求格式：multipart/form-data（因为要上传文件）
• 响应格式：JSON

3.2 请求参数说明

调用/predict接口时，你需要提供以下参数：

参数详解：

1. image（必填）：

   • 就是普通的彩色照片，支持PNG、JPEG等常见格式
   • 建议分辨率保持14的倍数（如448x448），但不是强制要求
   • 模型会自动调整图片大小

2. mode（必填）：

   • "monocular"：单目深度估计模式。只需要RGB图片，模型会“猜出”深度
   • "completion"：深度补全模式。需要RGB图片+稀疏深度图，模型会补全缺失的深度信息

3. depth_image（条件必填）：

   • 只有当mode="completion"时才需要
   • 必须是单通道的深度图（通常保存为PNG格式）
   • 黑色区域（值为0）表示深度信息缺失，需要模型补全

4. 相机内参（可选）：

   • 这四个参数描述了相机的光学特性
   • 对于单目深度估计（mode="monocular"），可以不提供，模型会用默认值
   • 对于深度补全（mode="completion"），建议提供准确的内参，这样生成的3D点云更精确
   • 如果你不知道相机的内参，可以先用默认值测试

3.3 响应数据结构

API调用成功后，会返回一个JSON对象，包含以下信息：

{ "status": "success", "message": "处理成功的描述信息", "depth_range": "0.523m ~ 8.145m", "input_size": "640x480", "mode": "monocular", "device": "cuda", "depth_image_base64": "很长的一串base64编码字符串...", "depth_data_url": "http://.../download/depth_data.npy" }

关键字段说明：

• depth_image_base64：这是生成的深度图，用base64编码成了字符串。你需要解码这个字符串才能得到图片文件。
• depth_data_url：这是原始深度数据的下载链接。深度图是可视化效果（用颜色表示远近），而这个.npy文件是原始的浮点数矩阵，单位是米。如果你要做进一步的计算（比如3D重建），就需要下载这个文件。

4. 实战开始：用curl调用单目深度估计

现在我们来实际操作。首先从最简单的开始：单目深度估计。这种模式下，你只需要提供一张彩色照片，模型就能估算出每个像素点的深度。

4.1 基础调用命令

打开终端，切换到你的工作目录，然后运行以下命令：

curl -X POST http://192.168.1.100:8000/predict \ -F "image=@/root/assets/lingbot-depth-main/examples/0/rgb.png" \ -F "mode=monocular"

命令分解讲解：

• curl：命令行工具，用于发送HTTP请求
• -X POST：指定使用POST方法
• http://192.168.1.100:8000/predict：API的完整地址（记得把IP换成你的）
• -F "image=@..."：上传文件参数。@符号后面是文件路径
• -F "mode=monocular"：设置处理模式为单目深度估计

运行这个命令后，你会看到一大段JSON输出，开头大概长这样：

{ "status": "success", "message": "Monocular depth estimation completed successfully", "depth_range": "0.523m ~ 8.145m", "input_size": "640x480", "mode": "monocular", "device": "cuda", "depth_image_base64": "iVBORw0KGgoAAAANSUhEUgAA...（后面很长很长）", "depth_data_url": "http://192.168.1.100:8000/download/depth_data_123456.npy" }

4.2 保存深度图到文件

上面返回的JSON里有个depth_image_base64字段，这是深度图的base64编码。我们需要把它解码保存成图片文件。

这里有个小技巧：我们可以用jq工具（需要先安装）来提取base64字符串，然后用base64命令解码：

# 先安装jq（如果还没安装的话） # Ubuntu/Debian: sudo apt-get install jq # macOS: brew install jq # 调用API并保存深度图 curl -X POST http://192.168.1.100:8000/predict \ -F "image=@/root/assets/lingbot-depth-main/examples/0/rgb.png" \ -F "mode=monocular" \ | jq -r '.depth_image_base64' \ | base64 --decode > depth_output.png

这个命令做了三件事：

1. 调用API获取JSON响应
2. 用jq -r '.depth_image_base64'提取base64字符串（-r表示输出纯文本，不带引号）
3. 用base64 --decode解码并保存为depth_output.png

现在用图片查看器打开depth_output.png，你会看到一张用颜色表示深度的图片：

• 红色/橙色：距离近的物体
• 蓝色/紫色：距离远的物体
• 这就是所谓的“伪彩色热力图”，让人眼更容易看出深度差异

4.3 下载原始深度数据

如果你需要原始的深度数据（比如用于3D重建或进一步计算），可以下载.npy文件：

# 先获取下载链接 DOWNLOAD_URL=$(curl -X POST http://192.168.1.100:8000/predict \ -F "image=@/root/assets/lingbot-depth-main/examples/0/rgb.png" \ -F "mode=monocular" \ | jq -r '.depth_data_url') # 然后下载文件 curl -o depth_data.npy "$DOWNLOAD_URL"

现在你有了两个文件：

• depth_output.png：可视化深度图，适合给人看
• depth_data.npy：原始深度数据，适合给程序用

你可以用Python加载这个.npy文件查看具体数值：

import numpy as np # 加载深度数据 depth_data = np.load('depth_data.npy') print(f"深度图尺寸: {depth_data.shape}") print(f"最近距离: {depth_data.min():.3f}米") print(f"最远距离: {depth_data.max():.3f}米") print(f"示例点深度: {depth_data[100, 200]:.3f}米") # 第100行第200列的深度值

5. 进阶功能：深度补全模式调用

单目深度估计已经很厉害了，但有时候我们有更精确的需求。比如，你的机器人上装了深度相机，但深度相机在某些表面（如玻璃、镜子）测不准，或者分辨率不够高。这时候就可以用深度补全模式：你提供彩色照片+稀疏的深度测量值，模型会融合两者信息，输出更完整、更准确的深度图。

5.1 深度补全调用命令

深度补全需要两个图片文件：RGB彩色图和稀疏深度图。命令如下：

curl -X POST http://192.168.1.100:8000/predict \ -F "image=@/root/assets/lingbot-depth-main/examples/0/rgb.png" \ -F "depth_image=@/root/assets/lingbot-depth-main/examples/0/raw_depth.png" \ -F "mode=completion" \ -F "fx=460.14" \ -F "fy=460.20" \ -F "cx=319.66" \ -F "cy=237.40"

注意这次的变化：

1. 多了depth_image参数：上传稀疏深度图
2. mode改为"completion"：告诉模型这是深度补全任务
3. 添加了相机内参：fx,fy,cx,cy。这些参数帮助模型理解图片的几何关系

5.2 稀疏深度图是什么？

你可能好奇：raw_depth.png这个稀疏深度图长什么样？它其实是一张灰度图，但有很多黑色区域（值为0）。

• 有值的像素：表示深度相机实际测量到的距离（单位可能是毫米或米）
• 黑色区域（值为0）：表示深度相机没测到数据，需要模型“猜出来”

你可以用Python简单查看一下：

from PIL import Image import numpy as np # 加载稀疏深度图 depth_img = Image.open('/root/assets/lingbot-depth-main/examples/0/raw_depth.png') depth_array = np.array(depth_img) print(f"图片尺寸: {depth_array.shape}") print(f"最小值: {depth_array.min()}") print(f"最大值: {depth_array.max()}") print(f"零值像素比例: {(depth_array == 0).sum() / depth_array.size:.1%}")

通常你会发现，稀疏深度图里可能只有10%-30%的像素有实际测量值，其他都是0。模型的任务就是根据这些稀疏的测量点+彩色图片的纹理信息，推断出完整的深度图。

5.3 保存和比较结果

和单目模式一样，我们可以保存深度补全的结果：

# 调用API并保存深度图 curl -X POST http://192.168.1.100:8000/predict \ -F "image=@/root/assets/lingbot-depth-main/examples/0/rgb.png" \ -F "depth_image=@/root/assets/lingbot-depth-main/examples/0/raw_depth.png" \ -F "mode=completion" \ -F "fx=460.14" -F "fy=460.20" -F "cx=319.66" -F "cy=237.40" \ | jq -r '.depth_image_base64' \ | base64 --decode > depth_completion_output.png

现在你有两个深度图了：

• depth_output.png：只用彩色图“猜”出来的深度
• depth_completion_output.png：用彩色图+稀疏深度测量“算”出来的深度

对比一下两个结果，你可能会发现：

• 深度补全的结果通常边缘更清晰（因为有了部分真实测量值作为锚点）
• 在纹理复杂的区域，深度补全可能更准确
• 深度范围可能略有不同

6. 实用技巧与常见问题

在实际使用中，你可能会遇到一些问题。这里总结了一些实用技巧和常见问题的解决方法。

6.1 处理大图片或批量图片

模型对输入图片尺寸没有严格限制，但建议保持合理的分辨率：

# 如果你的图片很大，可以先调整大小再上传 # 使用ImageMagick调整图片大小（安装：sudo apt-get install imagemagick） convert large_image.jpg -resize 448x448 resized_image.jpg # 然后使用调整后的图片调用API curl -X POST http://192.168.1.100:8000/predict \ -F "image=@resized_image.jpg" \ -F "mode=monocular"

批量处理建议： 如果你有很多图片要处理，不要用循环一个个调用curl，这样效率很低。建议：

1. 写一个Python脚本，用requests库调用API
2. 或者用parallel命令并行处理：

# 假设你有一批jpg图片 ls *.jpg | parallel -j 4 ' curl -X POST http://192.168.1.100:8000/predict \ -F "image=@{}" \ -F "mode=monocular" \ | jq -r ".depth_image_base64" \ | base64 --decode > {.}_depth.png ' # -j 4 表示同时处理4张图片

6.2 错误处理与调试

API调用可能失败，常见错误和解决方法：

错误1：连接被拒绝

curl: (7) Failed to connect to 192.168.1.100 port 8000: Connection refused

解决方法：

• 检查实例IP是否正确
• 检查实例是否正常运行（状态应该是“已启动”）
• 等待1-2分钟让服务完全启动

错误2：超时

curl: (28) Operation timed out after 10000 milliseconds

解决方法：

• 图片太大，处理时间超过10秒。尝试减小图片尺寸
• 网络延迟高。如果是远程服务器，考虑增加超时时间：curl --max-time 30 ...

错误3：返回错误状态

{ "status": "error", "message": "Invalid mode parameter" }

解决方法：

• 检查mode参数是否正确（只能是"monocular"或"completion"）
• 检查是否漏了必填参数（比如深度补全模式忘了传depth_image）

6.3 性能优化建议

1. 图片预处理：

   • 将图片调整为14的倍数（如448x448、336x336），这样模型处理最快
   • 使用JPEG格式而不是PNG，文件更小，传输更快

2. 连接复用： 如果需要连续调用多次，考虑使用HTTP Keep-Alive：

# 创建一个持续连接的会话 curl -X POST http://192.168.1.100:8000/predict \ -H "Connection: keep-alive" \ -F "image=@image1.jpg" \ -F "mode=monocular" # 同一连接处理下一张图片（理论上更快） curl -X POST http://192.168.1.100:8000/predict \ -H "Connection: keep-alive" \ -F "image=@image2.jpg" \ -F "mode=monocular"

3. 异步处理： 如果处理时间较长，可以考虑异步调用模式（如果API支持的话）。不过当前版本是同步的，一张处理完再下一张。

7. 实际应用示例

学会了基本调用，我们来看看在实际项目中怎么用这个API。

7.1 示例1：机器人导航系统

假设你正在开发一个室内机器人，它有一个RGB摄像头。你想让机器人知道前方物体的距离，好避开障碍物。

#!/bin/bash # robot_navigation.sh # 机器人摄像头拍摄的图片 CAMERA_IMAGE="current_view.jpg" # 调用深度估计API DEPTH_RESPONSE=$(curl -s -X POST http://192.168.1.100:8000/predict \ -F "image=@$CAMERA_IMAGE" \ -F "mode=monocular") # 提取深度范围信息 DEPTH_RANGE=$(echo "$DEPTH_RESPONSE" | jq -r '.depth_range') echo "当前场景深度范围: $DEPTH_RANGE" # 保存深度图用于显示 echo "$DEPTH_RESPONSE" | jq -r '.depth_image_base64' | base64 --decode > depth_display.png # 下载原始数据用于路径规划 DOWNLOAD_URL=$(echo "$DEPTH_RESPONSE" | jq -r '.depth_data_url') curl -s -o depth_data.npy "$DOWNLOAD_URL" echo "深度信息已保存，可用于路径规划"

7.2 示例2：批量处理建筑图片

你有一批建筑外观照片，想批量生成深度信息，用于3D建模。

#!/usr/bin/env python3 # batch_process.py import requests import base64 import os from pathlib import Path def process_single_image(image_path, api_url="http://192.168.1.100:8000/predict"): """处理单张图片""" with open(image_path, 'rb') as f: files = { 'image': (os.path.basename(image_path), f, 'image/jpeg'), } data = {'mode': 'monocular'} response = requests.post(api_url, files=files, data=data) result = response.json() if result['status'] == 'success': # 保存深度图 depth_data = base64.b64decode(result['depth_image_base64']) output_path = image_path.replace('.jpg', '_depth.png') with open(output_path, 'wb') as out_f: out_f.write(depth_data) # 下载原始数据 data_url = result['depth_data_url'] data_response = requests.get(data_url) data_path = image_path.replace('.jpg', '_depth.npy') with open(data_path, 'wb') as data_f: data_f.write(data_response.content) print(f"处理完成: {image_path} -> 最近{result['depth_range'].split('~')[0]}") return True else: print(f"处理失败: {image_path} - {result['message']}") return False # 批量处理 image_dir = Path("./building_photos") for image_file in image_dir.glob("*.jpg"): process_single_image(image_file) # 避免请求过快，稍微等待一下 import time time.sleep(0.5) print("批量处理完成！")

7.3 示例3：与现有系统集成

如果你已经有一个计算机视觉系统，只需要添加深度估计功能：

# 在你的现有代码中添加深度估计功能 def add_depth_estimation_to_pipeline(rgb_image, api_url): """ 将深度估计集成到现有处理流程中 rgb_image: numpy数组格式的RGB图片 api_url: lingbot-depth API地址 """ # 1. 将numpy数组保存为临时文件 import tempfile from PIL import Image import numpy as np with tempfile.NamedTemporaryFile(suffix='.png', delete=False) as tmp: # 保存为临时文件 Image.fromarray(rgb_image).save(tmp.name) # 2. 调用API with open(tmp.name, 'rb') as f: files = {'image': f} data = {'mode': 'monocular'} response = requests.post(api_url, files=files, data=data) # 3. 清理临时文件 os.unlink(tmp.name) if response.status_code == 200: result = response.json() if result['status'] == 'success': # 解码深度图 depth_image_data = base64.b64decode(result['depth_image_base64']) # 下载原始深度数据 depth_data_response = requests.get(result['depth_data_url']) depth_array = np.load(io.BytesIO(depth_data_response.content)) return { 'depth_image': depth_image_data, # PNG格式的深度图 'depth_array': depth_array, # numpy数组，单位米 'depth_range': result['depth_range'], 'success': True } return {'success': False, 'error': 'API调用失败'} # 在你的主流程中使用 def main_processing_pipeline(): # ... 你的现有代码 ... # 获取RGB图像 rgb_image = capture_image() # 你的图像获取函数 # 添加深度估计 depth_result = add_depth_estimation_to_pipeline(rgb_image, "http://192.168.1.100:8000/predict") if depth_result['success']: print(f"深度估计完成，范围: {depth_result['depth_range']}") # 使用深度信息进行后续处理 obstacle_distance = depth_result['depth_array'].min() print(f"最近障碍物距离: {obstacle_distance:.2f}米") # ... 继续你的处理流程 ...

8. 总结与下一步

通过这篇教程，你应该已经掌握了使用curl命令行调用lingbot-depth-pretrain-vitl-14模型的核心方法。我们来回顾一下关键点：

8.1 核心要点回顾

1. 两种模式，一个接口：

   • 单目深度估计（mode=monocular）：只需要RGB图片
   • 深度补全（mode=completion）：需要RGB图片+稀疏深度图

2. 调用流程很简单：

   curl -X POST http://IP:8000/predict \ -F "image=@图片文件" \ -F "mode=模式" \ [其他参数]

3. 结果处理：

   • 深度图是base64编码的，需要解码保存
   • 原始数据可以通过提供的URL下载
   • 深度范围等信息在JSON响应中

4. 实用技巧：

   • 图片尺寸建议是14的倍数
   • 深度补全模式需要相机内参（可选但推荐）
   • 批量处理时注意性能优化

8.2 你可以尝试的下一步

现在你已经掌握了基础，可以尝试更高级的应用：

1. 集成到你的项目中：

   • 用Python的requests库替代curl，更方便
   • 将深度估计功能嵌入到你的应用程序中

2. 探索更多功能：

   • 尝试不同的图片类型（室内、室外、人物、物体）
   • 比较单目模式和深度补全模式的效果差异
   • 实验不同的相机内参对结果的影响

3. 性能优化：

   • 测试不同分辨率图片的处理时间
   • 实现异步批量处理
   • 考虑缓存机制，避免重复处理相同图片

4. 结合其他工具：

   • 将深度图转换为3D点云（使用Open3D等库）
   • 用深度信息进行物体分割或场景理解
   • 结合SLAM系统进行实时建图

8.3 遇到问题怎么办？

如果在使用过程中遇到问题：

1. 检查服务状态：确保实例正常运行，端口可访问
2. 查看API文档：访问http://你的IP:8000/docs查看完整的API文档
3. 测试网页界面：先用Gradio网页界面（7860端口）测试，确保模型本身工作正常
4. 简化问题：先用示例图片测试，排除图片格式问题
5. 查看日志：如果有权限，可以查看服务日志找线索

记住，技术的学习是一个循序渐进的过程。从命令行调用开始，到你完全掌握并在实际项目中应用，可能需要一些时间和实践。但每一步的进步都是实实在在的——你现在已经能够用代码调用一个先进的深度估计模型了，这本身就是很大的成就。

获取更多AI镜像

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