图像里的“距离感”一直是计算机视觉中最难也最有价值的能力之一。自动驾驶需要判断前车是 3 米还是 30 米机器人抓取需要知道物体离机械臂多远安防摄像头要估算人员相对位置AR/VR 要让虚拟物体贴合真实空间。过去做这类项目通常是一套独立的深度估计论文源码、一套单独的数据预处理脚本、再加一个和 YOLO 完全无关的部署流程。而现在Ultralytics YOLO26 把深度估计任务正式纳入训练和推理链路开发者可以用和训练目标检测几乎一样的 YAML 和 Python API 来做单目深度估计。这个变化值得关注但也要说清楚YOLO26 降低的是多任务视觉系统的集成成本而不是把深度估计这件事本身变简单。数据标注、尺度标定、训练调参、端侧部署仍然有大量细节。这篇文章不是复述官方文档而是从“我该在哪里接入这个功能、数据集怎么组织、训练怎么调、部署要注意什么”的角度梳理一条能跑通的路径。如果你正在做自动驾驶、机器人、智能安防或 AR/VR 项目或者你已经在用 Ultralytics 做目标检测、想尝试多任务扩展这篇文章会比较合适。读完你会理解深度估计的输入输出到底是什么能把自定义深度数据集组织成 Ultralytics 格式能用 YOLO26 跑训练和推理也能知道真正容易踩坑的环节在哪儿。1. 这篇文章真正要解决的问题1.1 传统深度估计方案的工程痛点在 YOLO26 把深度估计纳入统一框架之前一个做多任务视觉系统的工程团队通常会面临三件很割裂的事情。第一数据格式难统一。目标检测一般用 COCO 格式或 YOLO 格式的标签而深度估计的训练数据往往是 KITTI 的 16 位深度图、NYU Depth V2 的 MATLAB 格式或者自定义传感器输出的 16 位 PNG。每换一个数据源就要写一套预处理脚本。第二训练代码难复用。很多深度估计开源项目的代码依赖某个特定模型结构换 backbone 要改的地方很多不像 Ultralytics 那样通过一个 YAML 配置文件就能切换模型结构。第三部署链路不统一。检测模型有一套导出、量化和 C 部署流程深度模型又要单独处理预处理、输出解析和性能优化最后项目里维护两套甚至三套视觉推理管线。所以YOLO26 把深度估计纳入同一套train、val、predict、export接口真正的价值不只是多了一个新 demo而是开发者可以复用同一套工程经验、同一套部署流程、同一套训练日志体系。1.2 深度估计和检测有本质区别新手最容易误解的地方是以为深度估计只是给目标检测加一个“距离输出”分支。这个理解不够准确。目标检测输出的是边界框坐标和类别本质是离散的分类加坐标回归。而单目深度估计输出的是每个像素的深度值本质是稠密的像素级回归任务。也就是说它更像语义分割的“输出形状”但评估方式和训练损失完全不同。语义分割通常用交叉熵深度估计更关心预测值和真实深度值之间的绝对误差、相对误差、梯度一致性等指标。因此在任何场景下都要先记住一个判断YOLO26 把深度估计“接入”了而不是把深度估计“简化”成了一个普通的检测任务。数据组织、损失函数、评价指标和部署输出都会和检测不一样。以下是 YOLO26 中几种常见任务的输入输出对比。任务类型输入输出典型表示目标检测RGB 图像边界框 类别2D 框坐标和类别概率实例分割RGB 图像边界框 类别 像素掩码每个目标的多边形或 mask姿态估计RGB 图像关键点坐标 类别关节点的 2D 坐标深度估计RGB 图像稠密深度图每个像素的深度值或相对深度1.3 本文的学习路径建议按三条线推进。第一条线先用官方示例或很小的自定义数据跑通一次完整训练不要一上来就上几千张图第二条线理解数据集 YAML 和模型 YAML 的写法知道模型配置在哪里改、任务头如何切换第三条线把训练好的模型导出为 ONNX在 C 或边缘设备上验证输出这一步才是生产环境最重要的一环。2. YOLO26 与单目深度估计的核心概念2.1 单目深度估计到底是什么单目深度估计就是只给一张普通 RGB 图像让模型估计出每一个像素对应的空间点到相机平面的距离。人的眼睛能比较精准地判断距离靠的是双眼视差。但单目图像没有另一只眼的视差信息模型只能通过画面里的透视关系、物体大小、遮挡情况、阴影、纹理梯度等线索来推测远近。比如人眼看到铁轨在远处交汇看到远处的人比近处的车更小这些几何线索就是单目深度估计的主要信息来源。训练时模型需要拿到 RGB 图像和对应的“真实深度图”然后不断调整参数让预测深度图尽量接近真实深度图。推理时模型输入一张新的 RGB 图输出一张同样分辨率的深度图。2.2 绝对深度与相对深度深度估计的输出有两种常见形式。绝对深度指的是真实物理尺度下的距离比如“这个像素距离相机 5.3 米”。这种深度图通常来自激光雷达、结构光相机、双目相机生成的真值单位可能是米或毫米。自动驾驶、机器人导航这类任务一般需要绝对深度。相对深度不关心真实物理距离是多少只关心“这个点比那个点更远还是更近”。比如手机人像模式要做背景虚化只需要知道前景和背景的远近关系不一定要输出准确米数。很多移动端深度估计模型输出的是 0 到 1 的相对深度后处理时再根据设备参数映射到实际物理距离。这两种深度对训练数据和损失函数的要求不同。如果你的深度图单位不一致或者有的数据是绝对深度、有的是相对深度训练很容易出现乱套的情况。2.3 深度图的数据格式深度图本质上是一张单通道图像每个像素值表示一个深度值。常见格式有 16 位 PNG、32 位浮点 TIFF、npy 数组等。16 位 PNG 一般会把深度尺度转换到 0 到 65535需要除以缩放因子才能得到米数npy 数组则可以直接保存浮点深度。组织数据集时最关键的一点是RGB 图像和深度图必须对齐。这里的对齐包括空间对齐、分辨率对齐和时间戳对齐。如果 RGB 是 1920x1080深度图是 640x480那训练前必须明确采样策略。如果深度图里有无效像素或遮挡区域通常还需要准备一个 mask或者在损失计算时忽略这些无效点否则模型会被异常值带偏。2.4 YOLO26 的模型 YAML 与任务头YOLO26 继承了 Ultralytics 的模块化设计思路模型结构写到 YAML 文件里不同任务对应不同的任务头。你可以通过修改 YAML 来切换 backbone、neck 和 head而不是像早期 YOLO 那样要改大量 Python 源码。从社区讨论和实际使用情况看YOLO26 在模型设计上吸收了不少端到端检测思路也保留了通过 YAML 替换检测头的自由度。很多人会在 RT-DETR-R18/R34 结构中修改 Ultralytics 的 YAML 文件把不同任务头组合起来实验这类改动本质上都是在复用同一套训练器和同一套数据加载逻辑。对深度估计来说最稳妥的做法是先使用官方提供的深度估计配置不要在第一次训练时就大改 backbone 和 neck。等跑通一次完整实验后再用控制变量的方式尝试替换模块能省下大量排查模型结构错误的时间。3. 环境准备与基础配置3.1 安装 Ultralytics深度估计任务需要一个较新的 Ultralytics 版本。如果你之前安装过旧版本建议先升级避免模型 YAML 文件或任务关键字对不上。最直接的方式是使用 pip 安装pip install -U ultralytics如果你希望紧跟源码更新也可以从 GitHub 克隆源码并用可编辑模式安装git clone https://github.com/ultralytics/ultralytics cd ultralytics pip install -e .安装完成后先检查版本是否可以正常导入python -c import ultralytics; print(ultralytics.__version__) python -c import torch; print(torch.cuda.is_available())第一行会输出 Ultralytics 版本号第二行会输出True或False用来判断当前环境是否能使用 GPU。没有 GPU 也能运行但训练速度会很慢建议第一次验证时把图片尺寸调小、epoch 数量调少。3.2 依赖说明Ultralytics 依赖 PyTorch、OpenCV、NumPy、PyYAML 等常见库。安装时需要注意 PyTorch 和 CUDA 的版本匹配这部分建议参考 PyTorch 官网的安装命令而不是盲目安装最新版。如果你不打算用 GPUCPU 版本 PyTorch 也足够跑通推理和少量训练。一个通用的检查思路是先装好 Ultralytics再运行一次小数据训练。如果训练能正常启动说明环境基本没问题如果卡在某个依赖上优先看报错最后几行通常都会明确告诉你缺少哪个库。4. 数据集准备与核心流程拆解4.1 整体流程用 YOLO26 训练深度估计模型的流程可以拆成六步准备 RGB 图像和对应的深度图。将数据组织成 Ultralytics 能识别的目录结构。编写数据集 YAML 文件。选择或编写模型 YAML 文件。执行训练命令观察训练日志。用验证集评估效果再导出部署。这套流程和训练检测模型的逻辑很像核心差异只在于数据集目录和 YAML 字段。如果你已经熟悉 Ultralytics 训练检测模型这部分上手会很快。4.2 自定义深度数据集目录结构深度估计数据集的常见组织方式如下。因为不同版本的 Ultralytics 可能支持不同字段名下面的目录结构是一种比较通用的示例实际字段请以当前版本中官方内置深度数据集 YAML 为准。depth_dataset/ images/ train/ img_0001.jpg img_0002.jpg val/ img_1001.jpg depth_maps/ train/ img_0001.png img_0002.png val/ img_1001.png depth_yolo.yaml这里要特别注意两点。第一RGB 文件和深度图文件的文件名必须一一对应否则训练时会把错误的数据对加载进来。第二train 和 val 的划分在文件组织层面就要完成不要靠程序随机切分否则可能出现验证集泄漏导致最终评估结果虚高。4.3 编写数据集 YAML在depth_dataset目录下创建depth_yolo.yaml内容可以参考下面的格式。字段名depth_maps不一定在所有版本中都支持如果你运行时报 KeyError第一件事就是打开 Ultralytics 官方内置的深度估计数据集 YAML看它用了什么字段名然后照抄。path: ./depth_dataset train: images/train val: images/val depth_maps: depth_maps names: 0: depthpath表示数据集根目录train和val表示 RGB 图像的路径depth_maps表示深度图目录的路径names是任务类别名。深度估计不像目标检测有多个类别所以这里可以只写一个类别名。4.4 训练前先做数据小样本检查在正式训练前建议先写一个简单的脚本或直接用 Ultralytics 的可视化接口把若干张 RGB 图和对应的深度图叠加起来看一遍。这一步能发现大量问题深度图是否黑白颠倒、是否全部为 0、分辨率是否匹配、文件命名是否一致、是否有缺失。不要跳过这步。很多训练跑出来的模型效果很差的根因根本不是网络结构不对而是深度图本身已经错了。5. 完整示例与代码实现5.1 使用 CLI 训练 YOLO26 深度模型Ultralytics 提供命令行工具。先用小图、少 epoch 跑通流程。假设你的模型 YAML 文件是yolo26n-depth.yaml数据集 YAML 是depth_yolo.yaml可以这样训练yolo train modelyolo26n-depth.yaml datadepth_yolo.yaml epochs50 imgsz640 batch8 device0如果你的机器没有 GPU把device0改成devicecpu。这里model的值不一定是固定文件名不同版本可能命名不同。可以先查看当前安装版本内置的模型目录确认有哪些深度估计模型可用ls ultralytics/cfg/models/如果没有看到深度估计相关的 YAML说明当前 Ultralytics 版本不够新需要先升级。5.2 使用 Python 脚本训练命令行训练方便但如果你想做多组对照实验Python 脚本会更灵活。下面是一个最小训练脚本。# 文件路径train_depth.py from ultralytics import YOLO model YOLO(yolo26n-depth.yaml) model.train( datadepth_yolo.yaml, epochs50, imgsz640, batch8, device0, projectdepth_project, nameyolo26_depth_custom, )这段代码做的事情是加载深度估计模型配置指定数据集配置设置训练超参数然后启动训练。训练结束后模型权重会保存到runs/depth_project/yolo26_depth_custom/weights/目录下。这里有两点值得提醒。第一epochs和batch是训练中最常调整的两个参数小数据集可以先从 50 个 epoch 开始。第二project和name最好按实验语义命名比如projectdepth_project、nameyolo26n_640方便后面对比不同配置。5.3 推理与可视化验证训练完成后用best.pt做推理。以下脚本会输出一张深度可视化结果并保存到指定目录。# 文件路径predict_depth.py from ultralytics import YOLO model YOLO(runs/depth_project/yolo26_depth_custom/weights/best.pt) results model.predict( sourcedemo.jpg, saveTrue, projectpredict_out, namedemo, ) for i, r in enumerate(results): print(输入图像 shape:, r.orig_img.shape) # 不同版本保存深度图的属性名可能不同 # 如果这里打印不到深度信息就用 dir(r) 查看当前版本有哪些字段 print(当前结果对象可用字段:, [attr for attr in dir(r) if not attr.startswith(_)])这里我不直接写死某个属性名因为 Ultralytics 的 API 版本迭代较快。如果r.depth不存在不要慌打印出dir(r)就能看到当前版本实际提供的字段。深度图本质上是和输入图像分辨率对齐的二维数组你需要把这个二维数组换算成可视化的灰度图或伪彩图。下面是一个通用的深度结果保存示例。假设模型输出是pred_depth是一个二维数组你可以用 OpenCV 做归一化并保存import cv2 import numpy as np depth pred_depth.astype(np.float32) depth cv2.normalize(depth, None, 0, 255, cv2.NORM_MINMAX) depth depth.astype(np.uint8) cv2.imwrite(output_depth.png, depth)如果深度图整体是黑的大概率是输出值没有做归一化或者你的后处理流程没有正确读取模型输出。5.4 导出为 ONNX 并做 C 端部署前验证把训练好的模型导出为 ONNX是 C 部署和边缘设备部署的关键一步。Ultralytics 的导出接口非常统一model YOLO(runs/depth_project/yolo26_depth_custom/weights/best.pt) model.export(formatonnx, imgsz640)导出完成后会生成best.onnx。接下来用 ONNX Runtime 做一个简单推理验证导出的模型在脱离 PyTorch 后是否还能正常输出深度图。import cv2 import numpy as np import onnxruntime as ort session ort.InferenceSession(best.onnx, providers[CPUExecutionProvider]) input_name session.get_inputs()[0].name img cv2.imread(demo.jpg) img cv2.resize(img, (640, 640)) input_data img.astype(np.float32) / 255.0 input_data input_data.transpose(2, 0, 1)[None] pred session.run(None, {input_name: input_data})[0] depth pred[0, 0] # 实际输出 layout 需要根据导出模型确认 depth cv2.normalize(depth, None, 0, 255, cv2.NORM_MINMAX) cv2.imwrite(onnx_output_depth.png, depth)这里有一个非常关键的提醒ONNX 推理时的预处理和训练时保持一致。如果你训练时用了 letterbox 等比缩放ONNX 推理阶段也要先做 letterbox否则输出结果会出现偏移和变形。6. 运行结果与效果验证6.1 训练日志怎么看训练开始后终端会持续输出 epoch、loss 等信息。不要只盯着数值的大小而是要观察 loss 是否呈下降趋势。一个比较正常的现象是前几个 epoch loss 下降很快后续变慢最终趋于平稳。如果 loss 出现 NaN或者从一开始就不下降那就不是“训练还没收敛”的问题而是数据或超参数配置有问题。第一次跑通时不建议把目标定成“拿到一个完美模型”。目标应该是数据加载正常、loss 能下降、推理接口能输出深度图、导出 ONNX 能正常运行。这四条都通过以后再开始调精度。6.2 可视化效果判断深度估计的结果最终要回到视觉上做判断。你可以在验证集上随机挑几张图片把预测深度图和真实深度图放在一起看。判断标准有三个第一物体边界是否清晰。深度突变位置应该对应物体的边缘如果整张图糊成一片说明模型没有学到有效的几何特征。第二远近关系是否正确。近处物体应该更亮远处物体应该更暗如果出现大范围黑白反转说明后处理或数据的相对符号有问题。第三空洞是否严重。如果预测图里有大量黑色区域或噪声点可能是数据集无效像素太多也可能是训练时没有对无效深度做忽略处理。6.3 数值指标验证深度估计常用指标包括绝对相对误差、均方根误差、平均绝对误差等。不同指标强调不同特性只看一个指标容易得出片面结论。更稳妥的做法是数值指标和可视化结果一起看。指标数值也依赖后处理流程。如果你把深度图做了归一化再计算指标和直接用原始尺度计算结果会完全不同。所以实验记录里要写清楚后处理方式避免不同实验之间的指标不可比。6.4 首次运行失败排查顺序如果运行失败不要急着改模型结构。先按下面的顺序检查大部分问题都能定位到数据加载是否正常打印一批输入图像的 shape 和深度图的 shape。模型配置是否存在确认model参数对应的 YAML 文件真实存在。损失是否稳定训练前几个 batch 的 loss 是否出现 NaN。GPU 是否足够OOM 就先降 batch 或 imgsz。导出和推理是否正确ONNX 输出结果是否和 PyTorch 输出基本一致。这个排查顺序可以让你快速区分“环境问题、数据问题、模型问题”和“部署问题”而不是把所有问题混在一起。7. 常见问题与排查思路深度估计任务在 YOLO26 中的常见问题多数集中在数据格式、模型命名和后处理三个环节。问题现象可能原因排查方式解决方案训练启动报 KeyError 或字段不存在当前版本的数据集 YAML 字段名与示例不同查看官方内置深度数据集 YAML按官方字段名修改配置模型名称不存在Ultralytics 版本过旧或模型 YAML 文件名不一致查看模型配置目录升级 Ultralytics使用正确文件名训练 loss 为 NaN学习率过大、深度图包含 NaN 或无效像素检查深度图数值范围打印日志降低学习率清理深度图添加 mask 或忽略无效点GPU 显存溢出batch 或 imgsz 太大查看报错是否与 CUDA out of memory 相关降低 batch降低 imgsz开启 AMP 或梯度累积深度图全部为黑色输出没有归一化或读取的输出通道不对打印原始预测值的 min 和 max使用 min-max 归一化确认输出数组维度CPU 推理速度很慢模型较大未做转换优化测量单次推理耗时导出 ONNX使用 TensorRT/NCNN/RKNN 等优化后端训练集 loss 下降但验证效果差数据量过少或深度图噪声大检查验证集可视化结果增加数据清洗无效深度值使用更强正则C 部署输出和 Python 不一致预处理不一致对比 letterbox、归一化、通道顺序统一预处理代码逐层验证中间结果ONNX 导出失败PyTorch 版本或导出参数问题查看报错堆栈确认 opset 版本升级依赖或调整导出参数推理结果存在明显偏移RGB 和深度图未对齐叠加可视化 RGB 和深度图修复数据对齐重新训练这里尤其要提醒一点训练数据如果是真实业务数据务必先确认数据的获取和标注是否合法、是否做了脱敏是否具备授权。涉及用户隐私或商业敏感数据时尽量在本地环境完成训练不要在公共平台上传未经处理的原始数据。8. 最佳实践与工程建议8.1 数据质量决定深度估计上限深度估计模型对训练数据的质量非常敏感。以下几点在实际项目中很值得做好第一统一深度单位。所有训练样本要么都是米要么都是毫米不要混用。第二处理无效像素。深度相机在某些反光区域、黑色物体或超出量程的地方会输出 0 值这些像素必须在训练时被忽略否则会严重干扰损失计算。第三多做配对校验。RGB 图像和深度图必须来自同一个时间戳和空间位置哪怕差一帧物体边缘都会出现重影。如果条件允许建议在数据准备阶段就生成一个可视化报告随机抽取几十组图片把深度图以伪彩图方式叠加在 RGB 图上人工快速过一遍。这个环节成本不高但能显著减少后续训练的时间浪费。8.2 训练策略与低光场景建议训练策略上我的建议是小步快跑。先用小分辨率、小 batch、少量 epoch 跑通一次确认数据流和验证流程没有问题再逐步加大训练规模。如果你想在低光环境下使用 YOLO26 深度估计需要额外考虑数据增强和图像质量。低光图像往往对比度低、噪声大模型很难从阴影和纹理中提取几何信息。做法上可以从两个方向入手一是训练时加入亮度增强、Gamma 变换、噪声增强二是在推理前做图像增强预处理但要注意推理时这张增强图和训练数据分布一致否则会引入新的偏差。从工程角度讲不要指望一个模型天然适配所有光照场景。在低光场景中更稳妥的思路是先评估现有训练集是否包含足量低光样本再决定是补数据还是做增强。8.3 评估与验证要成体系深度估计项目一定要建立独立的测试集。训练集、验证集、测试集要分开验证集用于调参测试集最后统一评估一次。否则你在验证集上调多了验证集的分数就不再能反映真实效果。在实验记录里建议把下面这些信息记清楚模型 YAML、数据 YAML、imgsz、batch、epoch、学习率、是否使用 AMP、深度图后处理方式、指标脚本版本。这些信息缺一个后面想复现实验都会很痛苦。8.4 部署上线要注意的坑部署阶段最容易被忽视的就是训练和推理的预处理不一致。训练时如果用了 letterbox 等比缩放推理阶段也一定要用同样的方式。训练时做了归一化推理阶段也要做相同归一化。很多 C 部署项目出错不是模型有问题而是图像缩放函数、通道顺序、归一化系数这三处不一致。如果目标设备是 RK3588 这类边缘平台建议在导出 ONNX 后就先跑一次纯 CPU 推理确认模型输出正确再转 RKNN 或 TensorRT。转完平台后还要再做一次精度验证不能只看模型能不能编译通过。生产环境上线时建议做灰度发布。新模型先在少量设备上运行观察输出深度图的分布是否异常再逐步放量。一旦发现异常指标要能快速回滚到上一版模型。9. 总结与后续学习方向YOLO26 把深度估计任务正式接入了 Ultralytics 这套统一训练框架对做多任务视觉系统的团队来说确实能省掉不少重复的工程工作。但深度估计本质上是一个像素级回归任务它的数据格式、损失函数、评价指标和部署输出都和检测、分割不一样。上手时最应该花时间的地方不是调模型结构而是先把数据配好、把流程跑通、把验证指标定义清楚。下一步你可以这样实践选一个公开的深度估计数据集或者用自己的小规模数据先用小图和小 epoch 跑通一次训练训练完成后做推理可视化确认深度图的远近关系是否正确再把模型导出为 ONNX用 ONNX Runtime 跑一次推理验证部署链路最后再回到模型 YAML研究如何替换 backbone、neck 和任务头尝试做更高精度的实验。建议把这篇文章收藏备用。当你真正开始配置 YOLO26 深度估计训练时把里面提到的数据对齐、字段名、预处理一致性这几个点对照检查一遍能帮你避开大部分新手容易遇到的坑。
