DEIM

一个用密集一对一匹配训练的检测 transformer，收敛所需的轮数远少于它所基于的 DETR 方案。LibreYOLO 收录了它的两个版本，靠你加载的检查点（checkpoint）区分。

任务: detection
尺寸: deim: n, s, m, l, x at 640 px
安装: pip install libreyolo
支持层级: 核心，自 v1.2.0 起。核心的可训练检测器：功能在同一个发布波次里紧跟旗舰。
上游: DEIM and DEIMv2，由 Intellindust AI Lab 发布，采用 Apache-2.0; the DEIMv2 DINOv3 backbone adds Meta's DINOv3 License 许可。论文、源码
许可: 代码采用 Apache-2.0，权重采用 Apache-2.0; the DEIMv2 DINOv3 backbone adds Meta's DINOv3 License。商用

安装

两个版本都不需要任何可选 extra。它们导入的一切都在基础安装里。

bash

pip install libreyolo

用 lora=True 做适配器微调是例外，它需要 lora extra。

bash

pip install "libreyolo[lora]"

预测

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

Python

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreDEIMn.pt")result = model(SAMPLE_IMAGE, save=True) for box in result.boxes:    print(box.cls, box.conf, box.xyxy)

CLI

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

视频

from libreyolo import LibreYOLO # 版本是文件名的一部分，工厂又按检查点分发，所以两者的加载方式# 完全一样model = LibreYOLO("LibreDEIMv2pico.pt") # 库接受的任何数据源：文件、文件夹、URL、摄像头索引、# RTSP 流，或者一个 .streams 列表for result in model.predict("clip.mp4", stream=True, save=True):    print(len(result.boxes))

返回的 Results 对象和每个家族返回的都是同一个，所以换成另一个检测器只是改一行的事。conf 和 max_det 过滤的是在 query 和类别上做的 top-k 解码；没有 NMS 步骤需要调，iou 会被接受但不会用到。数据源、流式处理和结果处理见预测。

变体

版本 1 提供五种尺寸，输入尺寸都相同。版本 2 保留了这五个名字，又加了三个更小的——atto、femto 和 pico，其中前两个的原生输入尺寸比其余的更低。因此有五个尺寸代号在两个版本里都存在，指向的却是不同的模型；版本写在检查点的文件名里。

检查点	输入（px）	mAP 50-95	参数量（M）
LibreDEIMl	640	57.8	31.24
LibreDEIMm	640	55.4	19.59
LibreDEIMn	640	46.8	3.78
LibreDEIMs	640	52.1	10.32
LibreDEIMx	640	59.6	62.62
LibreDEIMv2atto	320	27.5	0.51
LibreDEIMv2femto	416	34.5	0.98
LibreDEIMv2l	640	58.6	32.55
LibreDEIMv2m	640	56.0	18.36
LibreDEIMv2n	640	46.7	3.6
LibreDEIMv2pico	640	42.2	1.54
LibreDEIMv2s	640	53.0	9.78
LibreDEIMv2x	640	61.3	51.21

COCO val2017, 500 images。数据由 LibreYOLO 基准测试工具测得，并发布在 Vision Analysis 上，可在此比较不同硬件和运行时的延迟，并查看完整的运行记录。

版本 1 沿用 D-FINE 的架构，把它的分类目标换成了密集一对一方案里的 matchability-aware 损失函数，所以这两个家族几乎共享全部 state dict 键，靠检查点里的元数据区分。版本 2 保持同样的训练约定，并混用骨干：s 以下是 HGNetv2，s 及以上是带空间调优适配器的 DINOv3 vision transformer。正是这个骨干给那四个检查点加上了第二份许可证，所以在你把其中之一发布出去之前，先读一读许可证。

训练

训练从一个已发布的检查点开始。pretrained 永远到不了训练器：版本 1 会警告这个键未知然后忽略它，版本 2 会把它删掉。两者都不会给你一个随机初始化的模型。

Python

from libreyolo import LibreYOLO model = LibreYOLO("LibreDEIMn.pt") # coco128.yaml 在首次使用时下载一份 128 张图的样本；真正要跑的时候，# 把 `data` 指向你自己的数据集 YAMLmodel.train(data="coco128.yaml", epochs=50, batch=8, lr0=1e-4)

CLI

libreyolo train model=LibreDEIMn.pt data=coco128.yaml \  epochs=50 batch=8 lr0=1e-4

DEIMv2

from libreyolo import LibreYOLO # 不设置时，epochs、batch、imgsz 和 lr0 取自所加载尺寸对应的# 已发布方案model = LibreYOLO("LibreDEIMv2pico.pt")model.train(data="coco128.yaml", epochs=50)

LoRA

# 需要 lora extra：pip install "libreyolo[lora]"from libreyolo import LibreYOLO model = LibreYOLO("LibreDEIMn.pt")model.train(data="coco128.yaml", epochs=50, lora=True)

多卡训练

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

在版本 1 上要自己传 lr0。它的 Python train() 签名默认是 4e-4，也就是已发布的 COCO 方案里的学习率，而这个家族的训练配置文件把 1e-4 作为微调默认值，参数缺省时 CLI 解析出来的正是这个更低的值。配置文件记录了背后的实测：在微调实际会用到的批大小下，在小数据集上，COCO 的学习率明显拖累了迁移效果。

版本 2 自己解析这些默认值。不设置 epochs、batch、imgsz 和 lr0，它就会为所加载的那个尺寸从发布的方案里逐个读取，所以小尺寸不用你交代就会用自己的输入分辨率训练，而你传入的值会覆盖方案。imgsz 是它会加约束的那个参数：必须是 32 的正整数倍，否则版本 2 会在运行开始前抛错。

数据集、数据增强、多卡训练和日志记录器见训练。

验证

val() 返回一个由 metrics/ 键组成的字典，涵盖查准率、查全率、mAP 50 和 mAP 50-95，在任何与你训练时格式相同的数据集上测量。

Python

from libreyolo import LibreYOLO model = LibreYOLO("LibreDEIMn.pt") # val() 返回的是普通 dict，不是对象metrics = model.val(data="coco128.yaml") print(metrics["metrics/mAP50-95"])print(metrics["metrics/mAP50"])print(metrics["metrics/precision"], metrics["metrics/recall"])

CLI

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

在 COCO 上验证

# coco-val-only.yaml 会取回 5000 张 val2017 图片并跳过训练集；# 它带着一个内嵌的下载脚本，所以除非数据集已经在本地，否则# 需要显式放行libreyolo val model=LibreDEIMn.pt data=coco-val-only.yaml \  allow_download_scripts=True

上面基准测试表里的行来自 LibreYOLO 的基准测试框架；表下的说明记录了它们出自哪个数据集，并链接到运行记录。

导出

任务	ONNX	TorchScript	ExecuTorch	TensorRT	OpenVINO	Paddle	MNN	RKNN	ncnn	TFLite	CoreML	Core AI
Detection	Detection to ONNX：支持	Detection to TorchScript：支持	Detection to ExecuTorch：不支持	Detection to TensorRT：支持	Detection to OpenVINO：支持	Detection to Paddle：支持	Detection to MNN：支持	Detection to RKNN：不支持	Detection to ncnn：不支持	Detection to TFLite：不支持	Detection to CoreML：不支持	Detection to Core AI：支持

这份矩阵把两个版本放在同一页上：两者对某种格式的支持不一致时，单元格显示的是两者中较弱的那个，所以不论你加载的是哪个版本，这里都不会夸大。

导出的产物按文件后缀经由 LibreYOLO() 重新加载，所以一个 .onnx 或 .engine 文件的表现和检查点一样，返回同样的 Results。

Python

# 需要 onnx extra：pip install "libreyolo[onnx]"from libreyolo import LibreYOLO model = LibreYOLO("LibreDEIMn.pt")path = model.export(format="onnx")print(path)

CLI

libreyolo export model=LibreDEIMn.pt format=onnx

使用导出的文件

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

检查点

这个家族已发布的全部权重文件。

文件	输入（px）	权重许可
Detection
LibreDEIMn.pt	640	apache-2.0
LibreDEIMs.pt	640	apache-2.0
LibreDEIMm.pt	640	apache-2.0
LibreDEIMl.pt	640	apache-2.0
LibreDEIMx.pt	640	apache-2.0
LibreDEIMv2n.pt	640	apache-2.0
LibreDEIMv2s.pt	640	other
LibreDEIMv2m.pt	640	other
LibreDEIMv2l.pt	640	other
LibreDEIMv2x.pt	640	other
LibreDEIMv2atto.pt		apache-2.0
LibreDEIMv2femto.pt		apache-2.0
LibreDEIMv2pico.pt		apache-2.0

上面的每个文件目前都在 LibreYOLO 组织中，并会在首次使用时下载。

许可证

请检查你所下载的具体权重在 Hugging Face 仓库中的许可。LibreYOLO 组织里的每个检查点都附有许可，同一家族内也不一定相同。该仓库是权威来源；以下摘要说明本页上次验证时适用的情况。

这里只说明涉及的许可证，不构成法律意见。如果答案对商用很重要，请自行阅读许可证并咨询法律顾问。

原始工作: DEIM and DEIMv2, Intellindust AI Lab
上游许可: Apache-2.0; the DEIMv2 DINOv3 backbone adds Meta's DINOv3 License
上游来源: github.com/Intellindust-AI-Lab/DEIM
LibreYOLO 代码: MIT
权重: 采用 Apache-2.0; the DEIMv2 DINOv3 backbone adds Meta's DINOv3 License 许可，重新发布在 huggingface.co/LibreYOLO
解读: Apache-2.0 is a permissive license, so these weights can be used in commercial and closed-source products. It asks you to keep its license text and attribution notices with any copy of the weights you redistribute, and it grants a patent license. It places no obligation on your own application code, and weights you train yourself on your own data are yours. DEIM is Apache-2.0 throughout, and so are the DEIMv2 sizes below S, which use an HGNetv2 backbone. The DEIMv2 S, M, L and X sizes take their backbone from DINOv3, so both their weights and the backbone source vendored in LibreYOLO are additionally governed by Meta's DINOv3 License Agreement, which is not an OSI license: redistribution has to carry the agreement with it, and it forbids use for military or warfare purposes, weapons development, espionage, nuclear industries and anything subject to ITAR. Their Hugging Face repositories declare both licenses, and DEIMv2 is also cited separately (arXiv 2509.20787).

从 S 往上的四个 DEIMv2 尺寸，骨干取自 DINOv3，所以它们的权重仓库同时带有 Apache-2.0 和 Meta 的 DINOv3 License，LibreYOLO 随库提供的 DINOv3 骨干源码也适用同一份许可。这个家族的其余部分，包括 S 以下的每个 DEIMv2 尺寸，只采用 Apache-2.0 许可。

引用

@misc{huang2024deim,
      title={DEIM: DETR with Improved Matching for Fast Convergence},
      author={Shihua, Huang and Zhichao, Lu and Xiaodong, Cun and Yongjun, Yu and Xiao, Zhou and Xi, Shen},
      booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition},
      year={2025},
}

复制自作者在 github.com/Intellindust-AI-Lab/DEIM#5-citation 上提供的引用块。

DEIMv2 是另一篇论文，在 github.com/Intellindust-AI-Lab/DEIMv2 有它自己的引用块；如果你用的是版本 2 的检查点，就引用那一篇。