本部分目前仅提供英文版本。
实验性任务

下一步是什么

检测与分割路径是经过验证的核心。本页介绍我们正在其之上积极构建的新任务头与训练技巧:分类、旋转框、姿态,以及参数高效微调。

概述

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=。 已训练的检查点可通过统一工厂函数加载,并自动检测其任务。

python
1from libreyolo import LibreYOLO, LibreYOLO9, LibreRFDETR
2
3# Start a task from scratch via the family class
4m = LibreYOLO9(None, size="t", task="classify", nb_classes=10)
5
6# Load a trained checkpoint via the unified factory (task auto-detected)
7m = LibreYOLO("LibreYOLO9t-obb.pt")

图像分类

YOLO9: t, s, m, cRF-DETR: n, s, m, l

分类为整张图像给出单一标签。YOLO9 保留其主干并加装一个轻量分类头;RF-DETR 复用其 DINOv2 编码器 并添加一个池化线性头。两者均在 224×224 分辨率下运行。

推理与 Probs 结果

预测返回一个 Results 对象,其 probs 字段携带各类别的 softmax 概率。

python
1from libreyolo import LibreYOLO
2
3model = LibreYOLO("LibreYOLO9t-cls.pt")
4r = model.predict("cat.jpg")
5
6print(r.probs.top1) # class id of the argmax
7print(r.probs.top1conf) # its probability
8print(r.probs.top5) # [id, id, id, id, id]
9print(model.names[r.probs.top1]) # human-readable label
字段类型含义
probs.top1intargmax 的类别 id。
probs.top5list[int]按降序排列的 top-5 类别 id。
probs.top1conffloattop-1 类别的概率。
probs.top5conftensortop-5 类别的概率。
probs.datatensor完整的 softmax 向量。

数据集格式与训练

分类使用 ImageFolder 布局,而非 YAML。类别名称取自排序后的子文件夹名,以 train 划分为准。

dataset/
1dataset/
2 train/
3 cat/ img001.jpg ...
4 dog/ img104.jpg ...
5 val/
6 cat/ ...
7 dog/ ...

data= 参数接受一个文件夹、一个 .zip URL, 或一个已知的自动下载名称(imagenette160 imagenet10)。分类头会自动重建以匹配数据集的类别数。

python
1from libreyolo import LibreYOLO9
2
3model = LibreYOLO9(None, size="t", task="classify", nb_classes=10)
4result = 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: t, s, m, cRF-DETR: n, s, m, l

旋转框带有一个旋转角,这正是航拍图像、文档以及密集排布场景所需要的。YOLO9 在其检测头上增加了一个 角度分支;RF-DETR 则在其解码器中加入了一个可学习的角度嵌入。

推理与 OBB 结果

Results 暴露一个 obb 字段。角度以 弧度为单位。

python
1from libreyolo import LibreYOLO
2
3model = LibreYOLO("LibreYOLO9t-obb.pt")
4r = model.predict("aerial.jpg")
5
6for 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.xywhrN x 5[cx, cy, w, h, angle],angle 以弧度为单位。
obb.xyxyxyxyN x 4 x 2每个框的四个角点。
obb.confN每个框的置信度。
obb.clsN每个框的类别 id。

数据集格式与训练

OBB 使用标准的检测式数据 YAML,但标签是 YOLO-OBB 文本文件,每行 恰好九个字段:一个类别 id, 后跟四个归一化角点。角度由角点推导得出,并不存储。

labels/aerial_001.txt
1# class_id x1 y1 x2 y2 x3 y3 x4 y4 (all normalized to [0, 1])
20 0.51 0.32 0.66 0.38 0.62 0.55 0.47 0.49
32 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,且不支持分块推理。

python
1from libreyolo import LibreYOLO9
2
3model = LibreYOLO9(None, size="t", task="obb")
4# Warm-start the backbone from a same-family detect checkpoint
5result = 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 报告。

关键点 / 姿态

YOLO9 + RF-DETR:即将上线YOLO-NAS、EdgeCrafter:已可用

姿态估计为每个检测到的实例预测关键点。默认布局为 COCO-17 人体关键点。YOLO9 和 RF-DETR 姿态在首个版本中 仅支持人体单类别;YOLO-NAS 与 EdgeCrafter 姿态在代码库中已经可用。

推理与 Keypoints 结果

Results 暴露一个形状为 (N, K, 3)keypoints 字段,其中最后一个通道为可见性或置信度,坐标为原始图像的像素坐标。

python
1from libreyolo import LibreYOLO
2
3model = LibreYOLO("LibreYOLO9t-pose.pt")
4r = model.predict("athletes.jpg")
5
6kp = r.keypoints
7print(kp.xy.shape) # (N, 17, 2) pixel coordinates
8print(kp.conf) # (N, 17) per-keypoint visibility / confidence
9print(kp.xyn) # normalized coordinates
10print(r.boxes.xyxy) # person boxes still come along
字段形状含义
keypoints.xyN x K x 2关键点像素坐标。
keypoints.xynN x K x 2归一化关键点坐标。
keypoints.confN x K每个关键点的可见性 / 置信度。
keypoints.has_visibleN x K布尔型可见性掩码。

数据集格式与训练

姿态使用的数据 YAML 必须声明 kpt_shape: [K, 2|3],若需水平翻转增强还需声明 flip_idx。标签为 YOLO-pose 文本行:一个类别 id、一个归一化框,然后是 K 个关键点三元组 (x, y, v),其中可见性 v 取值于 {0, 1, 2}

coco8-pose.yaml
1path: coco8-pose
2train: images/train
3val: images/val
4nc: 1
5names:
6 0: person
7kpt_shape: [17, 3]
8flip_idx: [0, 2, 1, 4, 3, 6, 5, 8, 7, 10, 9, 12, 11, 14, 13, 16, 15]
python
1from libreyolo import LibreYOLO9
2
3# Warm-start from a detection checkpoint; the keypoint head is reinitialized
4model = LibreYOLO9("LibreYOLO9t.pt", size="t", task="pose")
5model.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 微调

RF-DETR: n, s, m, l

LoRA 式适配器让你通过训练一小组低秩矩阵来微调 RF-DETR 的 Transformer 主干,同时保持基础权重冻结。 这能削减优化器与梯度的显存占用,非常适合在普通硬件上将一个强力检查点适配到新领域。

启用方式

整个公开 API 就是 train() 上的一个标志。没有 rank、alpha 或目标模块等参数可调; 配方固定为一套经过充分测试的配置。底层实现使用 DoRA (权重分解的 LoRA,秩 16),应用于 DINOv2 注意力的 query、key 与 value 投影。

python
1from libreyolo import LibreYOLO
2
3model = LibreYOLO("rf-detr-nano.pth") # sizes n, s, m, l
4result = 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
11model.train(data="data.yaml", resume=True)
bash
1# CLI equivalent
2libreyolo 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-DETRPR 已开启
旋转框 (OBB)YOLO9, RF-DETR实验性
关键点 / 姿态YOLO9, RF-DETR即将上线
关键点 / 姿态YOLO-NAS, EdgeCrafter已可用
LoRA / DoRARF-DETR已评审

在寻找稳定的方案?

对于生产工作,经过验证的核心是 YOLO9 检测以及 RF-DETR 检测与分割。相关内容请参阅 核心文档, 开放词表检测请参阅 LibreVLM

GitHub 上追踪进展与源码