目标检测

定义

目标检测回答每个目标在哪里、是什么。输入一张图像，每个实例输出一行：矩形的四个数、 一个类别索引和一个分数。像素形状、朝向和部件的信息一概不包含，这正是它区别于 实例分割、 旋转框和 姿态的地方。

detect 是这个任务的规范任务键，也是默认值：文件名不带任务后缀的检查点（checkpoint） 会作为检测器加载。

predict() 会填充 result.boxes。.xyxy 给出原图画布上的像素角点，.conf 给出 分数，.cls 给出指向 result.names 的类别索引。.xywh、.xyxyn 和 .xywhn 是 同一批行的派生视图，而 .id 在接上跟踪器之后会带上跟踪 id。遍历一个 Boxes 对象 得到的是单行切片，所以 box.cls、box.conf 和 box.xyxy 都能按单个检测使用。

模型

以下家族支持训练和预测：YOLOv9、RF-DETR、EdgeCrafter、RT-DETR、D-FINE、DEIM、Dome-DETR、GTR、YOLO-NAS、YOLOX、YOLOv7、RTMDet 和 PicoDet。YOLOv9 和 RF-DETR 是两个旗舰家族，新功能优先在它们上面落地。RF-DETR 需要自己的 extra，pip install "libreyolo[rfdetr]"；其余家族使用基础包即可运行。

另有十一个家族可以预测、验证和导出，但它们的 train() 会抛出 NotImplementedError：LW-DETR、 DETR、Deformable DETR、 DINO-DETR、Faster R-CNN、 Mask R-CNN、FCOS、 RetinaNet、SSD、 CenterNet 和 EfficientDet。

Darknet 一脉的 YOLOv1、 YOLOv2、YOLOv3 和 YOLOv4 作为冻结的展品保留下来：预测、验证和导出可用， 训练不可用。

另有一组模型的类别列表是在运行时给出的，而不是来自检查点，所以它们能检测训练中 从未见过的名称： Grounding DINO、OWLv2、 OMDet-Turbo 和 OV-DEIM， 外加视觉语言家族 Florence-2、Kosmos-2、 Qwen3-VL、SmolVLM2、 InternVL3、LFM2-VL、 Gemma 4、Moondream、 North Micro Vision、 LocateAnything、 SenseNova-Vision、 WeVisOne-VL 和 LibreMODUS。这些通过它们自己的工厂函数和 extra 加载； 每个模型页上都写着确切的调用方式。

PP-YOLOE 和 TinyFormer 也支持检测训练。

预测

权重会在首次使用时从 Hugging Face 下载，并缓存到本地。

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt")result = model(SAMPLE_IMAGE, save=True) for box in result.boxes:    print(result.names[int(box.cls)], float(box.conf), box.xyxy)

libreyolo predict model=LibreYOLO9t.pt save=True \  source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg

from libreyolo import LibreYOLO, SAMPLE_IMAGE # 工厂函数按检查点分发，而且每个检测器返回的都是同一个# Results 对象，所以换一个家族只是改一行的事model = LibreYOLO("LibreDFINEn.pt")result = model(SAMPLE_IMAGE) print(result.boxes.xyxy.shape)

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt") # 库接受的任何输入源：文件、文件夹、URL、摄像头序号、# RTSP 流，或者一个 .streams 列表for result in model.predict("clip.mp4", stream=True, save=True):    print(len(result.boxes))

conf 设置置信度阈值，max_det 限制输出的行数上限。iou 是 NMS 阈值，所以它只对 会跑 NMS 的家族有影响；RF-DETR 和端到端的 YOLOv9 head 解码的是一组固定数量的预测， 会忽略它。agnostic_nms=True 会在 iou 处增加一个与类别无关的抑制步骤，这两者也适用；见阈值与过滤。输入源、流式处理和结果处理见预测。

数据集格式

每张图像对应一个 .txt 标注文件，把图像路径里的 images 换成 labels、再改掉 扩展名就能找到它。

dataset/  data.yaml  images/    train/000001.jpg    val/000101.jpg  labels/    train/000001.txt    val/000101.txt

每一行正好是五个字段，一个类别索引，后面跟一个归一化的中心点加尺寸的框：

<class_id> <cx> <cy> <w> <h>

坐标是 [0, 1] 之间的浮点数，相对于原图的宽和高。w 和 h 必须为正。标注文件缺失 或为空表示这张图里没有目标。行里不带置信度，也不带跟踪 id。

YAML 指明各个划分（split）和类别：

path: datasettrain: images/trainval: images/valnames:  0: person  1: bicycle

train 和 val 可以是图像目录、图像列表 .txt 文件，或者两者的列表。nc 是可选 的，出现时必须和 names 对得上。原生的 COCO JSON 也可以：加一个 annotations 映射， 把划分名映射到 JSON 文件，此时划分路径给出的就是图像根目录。当 names 存在时，它 定义了标签 id，所以 JSON 里的类别名必须和它一致。

训练

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt") # coco128.yaml 会在首次使用时下载一份 128 张图的样例。真正要跑的时候，# 把 data 指向你自己的数据集 YAMLmodel.train(data="coco128.yaml", epochs=50, imgsz=640, batch=8)

libreyolo train model=LibreYOLO9t.pt data=coco128.yaml \  epochs=50 imgsz=640 batch=8

libreyolo train model=LibreYOLO9t.pt data=coco128.yaml \  epochs=50 device=0,1 batch=-1

epochs、imgsz、batch 和 lr0 是最先要动的参数。lr0 是那个不能跨家族照搬的： 一个卷积检测器能接受的学习率会让 transformer 检测器发散，所以要从模型页上取这个值， 而不是从另一个家族的例子里取。一个家族也可能干脆忽略某个参数，它的页面上列出了是 哪些。数据集、数据增强、多卡训练和日志记录见训练。

使用 classes= 保留指定的原始数据集 ID；single_cls=True 将保留的标签合并到类别 0。支持的家族和验证继承规则见超参数。

验证

val() 返回一个由 metrics/ 键组成的字典，是在数据集 YAML 里 val 指定的划分 上用 COCO 评测算出来的，逐类别结果作为属性附在上面。

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt") # 一个由 metrics/ 键组成的 dict，逐类别结果作为属性metrics = model.val(data="coco128.yaml") print(metrics["metrics/mAP50-95"])print(metrics["metrics/mAP50"], metrics["metrics/mAP75"])print(metrics["metrics/AR100"])print(metrics.confusion_matrix.class_accuracy())

libreyolo val model=LibreYOLO9t.pt data=coco128.yaml

metrics/mAP50-95 是在 0.50 到 0.95 的 IoU 阈值上取平均的 mean average precision， 也是最主要的那个数。metrics/mAP50 和 metrics/mAP75 是单阈值的版本。 metrics/mAP_small、metrics/mAP_medium 和 metrics/mAP_large 把同一个平均值按 目标面积拆开，而 metrics/AR1、metrics/AR10、metrics/AR100、 metrics/AR_small、metrics/AR_medium 和 metrics/AR_large 是对应的平均查全率 数字。metrics/AR_max_det 和 metrics/max_det 记录这次运行用的检测数上限。

在这个任务上，metrics/precision 和 metrics/recall 要仔细读。它们是为了向后兼容 保留下来的别名，而不是一个工作点：metrics/precision 存的值和 metrics/mAP50-95 相同，metrics/recall 存的值和 metrics/AR100 相同。把它们当成一对查准率-查全率 来画图，等于把同一个数报了两遍。还有四个键会在 (B) 后缀下再重复一遍，B 表示 box，这样在同时也预测掩码的模型上，检测的键读起来是一样的：metrics/mAP50-95(B)、 metrics/mAP50(B)、metrics/precision(B) 和 metrics/recall(B)。

结果还带有 confusion_matrix，索引为 matrix[predicted, true]，带有 background 行和列，以及 box 上跨置信度的逐类别查准率、查全率和 F1：box.px、box.p_curve、box.r_curve、box.f1_curve，box.ap_class_index 中的每个类别一行。验证与指标对两者以及 val(agnostic_nms=True) 都有说明。

导出

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt")model.export(format="onnx", imgsz=640)

libreyolo export model=LibreYOLO9t.pt format=onnx imgsz=640

from libreyolo import LibreYOLO, SAMPLE_IMAGE # 工厂函数按文件后缀分发，所以导出产物的加载方式和检查点一样，# 返回的也是同一个 Results 对象model = LibreYOLO("LibreYOLO9t.onnx")result = model(SAMPLE_IMAGE) print(result.boxes.xyxy)

导出的产物会按文件后缀通过 LibreYOLO() 加载回来，所以一个 .onnx 或 .engine 文件的表现和检查点一样，返回同样的 Results。各个家族支持的格式不同；每个模型页上 的矩阵是从已验证的集合生成的，而不是手写的。格式、它们的 extra 和限制见 导出与部署。