下一步是什么
检测与分割路径是经过验证的核心。本页介绍我们正在其之上积极构建的新任务头与训练技巧:分类、旋转框、姿态,以及参数高效微调。
概述
LibreYOLO 是一个多任务框架:同一个模型家族可以搭配不同的任务头。除了经过验证的检测与分割路径外, 两大旗舰家族 YOLO9 和 RF-DETR 还在陆续加入若干新任务。它们都接入相同的 LibreYOLO(...) 工厂函数与相同的 Results 容器,因此只要你熟悉核心 API,这些都只是小幅扩展。
- 分类,支持 YOLO9 和 RF-DETR。输出整图标签及 top-1 / top-5 概率。
- 旋转边界框 (OBB),支持 YOLO9 和 RF-DETR。为航拍与文档图像提供带旋转角的检测框。
- 关键点 / 姿态,支持 YOLO9 和 RF-DETR。COCO-17 人体关键点。
- LoRA / DoRA 微调,支持 RF-DETR。以极少的显存适配 Transformer 主干。
请先阅读
本页所有内容均为实验性,其中部分仍在功能分支上开发中。在被提升进经过验证的核心之前,API、默认值与标签格式都可能发生变化。稳定性 一节准确记录了各项功能当前所处的阶段。
选择任务
每个家族默认执行检测。你可以通过以下三种方式之一选择其他任务,并按以下优先级顺序解析:
| 优先级 | 机制 | 示例 |
|---|---|---|
| 1 | 显式参数 | task="obb" |
| 2 | 检查点元数据 | 记录在已训练 .pt 文件中的 task |
| 3 | 文件名后缀 | -cls, -obb, -pose |
| 4 | 家族默认值 | detect |
由于公开的 LibreYOLO(...) 工厂函数需要一个真实的权重文件, 从零开始启动这些任务最简洁的方式是直接构造家族类并传入 task=。 已训练的检查点可通过统一工厂函数加载,并自动检测其任务。
1 from libreyolo import LibreYOLO, LibreYOLO9, LibreRFDETR 2 3 # Start a task from scratch via the family class 4 m = LibreYOLO9(None, size="t", task="classify", nb_classes=10) 5 6 # Load a trained checkpoint via the unified factory (task auto-detected) 7 m = LibreYOLO("LibreYOLO9t-obb.pt")
图像分类
分类为整张图像给出单一标签。YOLO9 保留其主干并加装一个轻量分类头;RF-DETR 复用其 DINOv2 编码器 并添加一个池化线性头。两者均在 224×224 分辨率下运行。
推理与 Probs 结果
预测返回一个 Results 对象,其 probs 字段携带各类别的 softmax 概率。
1 from libreyolo import LibreYOLO 2 3 model = LibreYOLO("LibreYOLO9t-cls.pt") 4 r = model.predict("cat.jpg") 5 6 print(r.probs.top1) # class id of the argmax 7 print(r.probs.top1conf) # its probability 8 print(r.probs.top5) # [id, id, id, id, id] 9 print(model.names[r.probs.top1]) # human-readable label
| 字段 | 类型 | 含义 |
|---|---|---|
probs.top1 | int | argmax 的类别 id。 |
probs.top5 | list[int] | 按降序排列的 top-5 类别 id。 |
probs.top1conf | float | top-1 类别的概率。 |
probs.top5conf | tensor | top-5 类别的概率。 |
probs.data | tensor | 完整的 softmax 向量。 |
数据集格式与训练
分类使用 ImageFolder 布局,而非 YAML。类别名称取自排序后的子文件夹名,以 train 划分为准。
1 dataset/ 2 train/ 3 cat/ img001.jpg ... 4 dog/ img104.jpg ... 5 val/ 6 cat/ ... 7 dog/ ...
data= 参数接受一个文件夹、一个 .zip URL, 或一个已知的自动下载名称(imagenette160 与 imagenet10)。分类头会自动重建以匹配数据集的类别数。
1 from libreyolo import LibreYOLO9 2 3 model = LibreYOLO9(None, size="t", task="classify", nb_classes=10) 4 result = model.train( 5 data="imagenette160", # folder, .zip URL, or known name 6 epochs=10, batch=64, imgsz=224, 7 optimizer="adamw", lr0=1e-3, 8 ) 9 # Validation reports metrics/accuracy_top1 and metrics/accuracy_top5
参考运行结果
开发期间的快速验证:YOLO9-t 在 imagenette160 上达到 top-1 0.79 / top-5 0.975(10 个 epoch), RF-DETR-n 达到 top-1 0.69 / top-5 0.96(6 个 epoch)。RF-DETR 在首次运行时如能联网获取其 DINOv2 主干会更好;离线时则回退到随机初始化。
旋转边界框 (OBB)
旋转框带有一个旋转角,这正是航拍图像、文档以及密集排布场景所需要的。YOLO9 在其检测头上增加了一个 角度分支;RF-DETR 则在其解码器中加入了一个可学习的角度嵌入。
推理与 OBB 结果
Results 暴露一个 obb 字段。角度以 弧度为单位。
1 from libreyolo import LibreYOLO 2 3 model = LibreYOLO("LibreYOLO9t-obb.pt") 4 r = model.predict("aerial.jpg") 5 6 for i in range(len(r.obb.cls)): 7 cx, cy, w, h, angle = r.obb.xywhr[i] # angle in radians 8 corners = r.obb.xyxyxyxy[i] # 4 (x, y) corner points 9 conf, cls = r.obb.conf[i], r.obb.cls[i]
| 字段 | 形状 | 含义 |
|---|---|---|
obb.xywhr | N x 5 | [cx, cy, w, h, angle],angle 以弧度为单位。 |
obb.xyxyxyxy | N x 4 x 2 | 每个框的四个角点。 |
obb.conf | N | 每个框的置信度。 |
obb.cls | N | 每个框的类别 id。 |
数据集格式与训练
OBB 使用标准的检测式数据 YAML,但标签是 YOLO-OBB 文本文件,每行 恰好九个字段:一个类别 id, 后跟四个归一化角点。角度由角点推导得出,并不存储。
1 # class_id x1 y1 x2 y2 x3 y3 x4 y4 (all normalized to [0, 1]) 2 0 0.51 0.32 0.66 0.38 0.62 0.55 0.47 0.49 3 2 0.10 0.71 0.18 0.69 0.20 0.80 0.12 0.82
普通的检测检查点无法直接加载到 OBB 模型中。从检测转到 OBB 仅允许作为训练时的热启动:传入 pretrained=True(YOLO9)或 RF-DETR 上的显式迁移标志。在角点感知增强落地之前, OBB 会禁用 Mosaic 与 mixup,且不支持分块推理。
1 from libreyolo import LibreYOLO9 2 3 model = LibreYOLO9(None, size="t", task="obb") 4 # Warm-start the backbone from a same-family detect checkpoint 5 result = model.train(data="dota8.yaml", pretrained=True, epochs=100, imgsz=640) 6 7 # CLI equivalent 8 # libreyolo train model=LibreYOLO9t.pt data=dota8.yaml --task obb
验证使用旋转 IoU 的 AP,在 OBB 指标组下以 mAP50 与 mAP50-95 报告。
关键点 / 姿态
姿态估计为每个检测到的实例预测关键点。默认布局为 COCO-17 人体关键点。YOLO9 和 RF-DETR 姿态在首个版本中 仅支持人体单类别;YOLO-NAS 与 EdgeCrafter 姿态在代码库中已经可用。
推理与 Keypoints 结果
Results 暴露一个形状为 (N, K, 3) 的 keypoints 字段,其中最后一个通道为可见性或置信度,坐标为原始图像的像素坐标。
1 from libreyolo import LibreYOLO 2 3 model = LibreYOLO("LibreYOLO9t-pose.pt") 4 r = model.predict("athletes.jpg") 5 6 kp = r.keypoints 7 print(kp.xy.shape) # (N, 17, 2) pixel coordinates 8 print(kp.conf) # (N, 17) per-keypoint visibility / confidence 9 print(kp.xyn) # normalized coordinates 10 print(r.boxes.xyxy) # person boxes still come along
| 字段 | 形状 | 含义 |
|---|---|---|
keypoints.xy | N x K x 2 | 关键点像素坐标。 |
keypoints.xyn | N x K x 2 | 归一化关键点坐标。 |
keypoints.conf | N x K | 每个关键点的可见性 / 置信度。 |
keypoints.has_visible | N x K | 布尔型可见性掩码。 |
数据集格式与训练
姿态使用的数据 YAML 必须声明 kpt_shape: [K, 2|3],若需水平翻转增强还需声明 flip_idx。标签为 YOLO-pose 文本行:一个类别 id、一个归一化框,然后是 K 个关键点三元组 (x, y, v),其中可见性 v 取值于 {0, 1, 2}。
1 path: coco8-pose 2 train: images/train 3 val: images/val 4 nc: 1 5 names: 6 0: person 7 kpt_shape: [17, 3] 8 flip_idx: [0, 2, 1, 4, 3, 6, 5, 8, 7, 10, 9, 12, 11, 14, 13, 16, 15]
1 from libreyolo import LibreYOLO9 2 3 # Warm-start from a detection checkpoint; the keypoint head is reinitialized 4 model = LibreYOLO9("LibreYOLO9t.pt", size="t", task="pose") 5 model.train(data="coco8-pose.yaml", epochs=100, imgsz=640) 6 7 # Validation reports OKS-based AP via the pose validator
正在积极开发中
YOLO9 和 RF-DETR 姿态尚在功能分支上,尚未合并;请将上述 API 视为预期约定而非冻结契约。 YOLO-NAS 姿态权重是从上游链接而非镜像,需要手动准备。
LoRA / DoRA 微调
LoRA 式适配器让你通过训练一小组低秩矩阵来微调 RF-DETR 的 Transformer 主干,同时保持基础权重冻结。 这能削减优化器与梯度的显存占用,非常适合在普通硬件上将一个强力检查点适配到新领域。
启用方式
整个公开 API 就是 train() 上的一个标志。没有 rank、alpha 或目标模块等参数可调; 配方固定为一套经过充分测试的配置。底层实现使用 DoRA (权重分解的 LoRA,秩 16),应用于 DINOv2 注意力的 query、key 与 value 投影。
1 from libreyolo import LibreYOLO 2 3 model = LibreYOLO("rf-detr-nano.pth") # sizes n, s, m, l 4 result = model.train( 5 data="data.yaml", 6 lora=True, # DoRA on the frozen DINOv2 backbone 7 epochs=100, batch_size=4, lr=1e-4, 8 ) 9 10 # Resume: LoRA is auto-detected from the checkpoint, no need to repeat the flag 11 model.train(data="data.yaml", resume=True)
1 # CLI equivalent 2 libreyolo train --model rf-detr-nano.pth --data data.yaml --lora
检查点与导出
- 训练检查点会保留适配器张量,配置中也会记录已使用 LoRA,因此加载与续训会自动重建适配器图。
- 检测头始终保持可训练,因此你仍可适配到新的类别数。
export()会将适配器合并回稠密权重。导出的模型是普通模型,不带peft依赖。- LoRA 仅限 RF-DETR;向其他家族传入
lora=True会抛出明确的错误。
安装额外依赖
LoRA 训练需要适配器依赖:pip install "libreyolo[lora]", 它会引入 RF-DETR 相关组件与 peft。导出(已合并)的模型在推理时无需该依赖。
稳定性
各项功能当前所处的阶段。这里的一切都是实验性的;此表是真实情况的映射。
| 功能 | 家族 | 状态 |
|---|---|---|
| 分类 | YOLO9, RF-DETR | PR 已开启 |
| 旋转框 (OBB) | YOLO9, RF-DETR | 实验性 |
| 关键点 / 姿态 | YOLO9, RF-DETR | 即将上线 |
| 关键点 / 姿态 | YOLO-NAS, EdgeCrafter | 已可用 |
| LoRA / DoRA | RF-DETR | 已评审 |