v1.11.2 — Safer Threaded Inference and Training Inputs2026-10-04
1.11.2 加固了多线程推理，把一次静默的类别错位变成了显式报错，同时修好了 predict() 处理翻转帧的问题。
共享同一模型的多个线程不再互相污染权重：冷启动模型的权重会在首次 predict()、inference() 与 export() 恢复步骤中从 CPU 搬到加速器，此前四个线程并发调用可让 573 个张量中的 13 个损坏，且不报错、返回空检测。现在这一搬移由模型级锁保护。同理，分割头里 torch.backends.cudnn.flags(enabled=False) 这一进程级开关也不再被第二个线程误关，避免后续卷积悄悄绕过 cuDNN。
classnames 若混入 Roboflow 的根类别（如 animals），此前会让所有标签整体错位一位且毫无提示，如今 RFDETR.train() 会在写入 trainingconfig.json 和启动 wandb/MLflow 前抛出 ValueError，指出多余条目。
predict() 现在接受 frame[:, :, ::-1] 这类负步长 NumPy 视图，docs/learn/pretrained.md 中的视频、摄像头与 RTSP 示例可以直接跑通。YOLO data.yaml 加载也更稳定：类别 ID 按数值排序，images/train 布局可正常识别。ONNX 导出经 Apple CoreML 加速，Nano 在 M4 Max（ONNX Runtime 1.30）上由 9.3 ms 降至 8.3 ms。
从 1.11.1 升级有一处破坏性改动：常量 REQUIREDDATASUBDIRS 已删除，若你导入过它，需自行内联 ["images", "labels"]。另有四项行为变化，详见迁移指南。
v1.11.1: Correctness Fixes for LoRA, TensorRT & Crowd mAP2026-09-30
RF-DETR 1.11.1 是一个正确性补丁，把此前静默给出错误结果的情况改成明确报错。三处主要修复：backbonelora=True 的检查点过去在用 LoRA 包裹编码器之前就加载权重，PEFT 命名的权重全都对不上，编码器一直停在随机初始化、评估分数接近零却不报错，现在先包裹再加载；TRTInference 遇到设备、dtype 或非连续内存与预期不符的输入会直接拒绝，不再返回错乱的检测结果；验证集 mAP 不再把 COCO crowd 区域内的检测计为误报，数值与 pycocotools 对齐（Nano COCO val2017 从 0.4802 升至 0.4842）。last.ckpt 现在携带重载所需的信息，1.11.0 及更早写入的旧文件无法就地修复，会抛出指向 checkpointbestema.pth 的 ValueError。唯一的 API 变更是 RFDETRModelModule.clipgradients 更名为 configuregradientclipping。5 项所谓破坏性变更里有 4 项只是让原本就在出错的代码显形，多数用户无需改动。
v1.11.0: Wider export surface, faster training2026-09-24
RF-DETR 1.11.0 扩大了导出覆盖，也提速了训练。新增三种导出格式：OpenVINO IR（openvinoprecision 可选 float32/float16）、经 litert-torch 的 LiteRT，以及 Apple Core AI（.aimodel，面向 iOS/iPadOS/macOS 27+，实验性，省去 ONNX 环节）；TensorRT 改用单一优化 profile 生成动态 batch 引擎，一个引擎即可覆盖 1 到 maxbatch_size，不再一种 batch 一个引擎。训练侧新增可选 CUDA graph 重放，可与 torch.compile 叠加，支持的硬件上还有 Transformer Engine FP8 路径；另有 WebDataset 流式读取，直接从 tar 分片训练。
这版也收尾了 1.9.0 的弃用周期：RFDETR.optimizeforinference()、TrainConfig.lrdrop/lrmin_factor 和独立的合成数据集生成器均被删除；导出内部重构为按格式一个 Exporter 类，经注册表访问。RFDETR.export() 的签名与返回值不变，但直接 import 旧转换函数的代码需要改引用，具体改法见文末迁移指南。
v1.10.1: CUDA Compile Fixes & Memory Reduction2026-09-07
RF-DETR 1.10.1 是一个补丁版本，无破坏性变更。
这版修好了一个关键问题：默认的 multi_scale=True 配置下，compile=True 此前只是打条提示就回退到 eager 训练，真正能走通 CUDA 编译的路径反而被关掉了；现在会正常触发 torch.compile。
``python
from rfdetr import RFDETRSmall
model = RFDETRSmall()
model.train(datasetdir="...", compile=True) # 默认 multiscale=True —— 现在在 CUDA 上会真正编译
`
分割损失的显存占用也降了：多图批次里布尔掩码改为逐图采样并及时释放，不再一次性拼出整批的浮点掩码张量，训练大图时峰值显存会更友好。
另外还带了几个 TPU/XLA 训练路径的修复（实验性，暂无文档，见 #1058）：设备同步残留、strategy="auto" 下多设备 XLA 的策略选择崩溃等都已处理。文档站的版本横幅误报「当前版本已过期」的问题也一并修了。
若你直接调用 dicelossjit / sigmoidceloss_jit（非公开 API），NumPy 标量分母现在大多需要先转 float`，详见 MIGRATION.md。
v1.10.0: Faster Training & Inference2026-09-04
RF-DETR 1.10.0 是一版以训练提速为主的更新：一万张图训练十个 epoch，在 L4 上从 55 分钟缩到 31 分钟。多数改动无需改代码——优化器参数分组按超参合并后，AdamW 的 foreach/fused 才真正生效，默认 batch 下单步训练快约 23%；predict() 把 uint8 转换挪到加速器上做，大分辨率输入最多快 46%；DataLoader 在输入受限的场景下吞吐提升 1.25–2.26 倍。另新增 CUDA 上的批量线性分配求解器，符合条件的设备自动启用。
需要留意的是，有六项默认行为变了：验证改为每 epoch 只跑一个模型（val/ 指标对应 EMA 权重）、gradaccumsteps 默认从 4 降到 1、优化器分组方式调整、数据集构建器改为校验配置而非静默回退、logperclassmetrics 默认关闭、computevalloss 默认 "auto"。重新训练前请先看迁移指南。
v1.9.4: Export & Aug Correctness Fixes2026-08-24
RF-DETR 1.9.4 是一个纯修复版本，公开 API 没有任何增删改，共修了七个 bug。
导出环节占两个：ONNX/TFLite 推理辅助函数原先假定背景类固定占据最后一个 logit 槽位，导致稀疏 ID 的 COCO 权重和旧式「背景在前」的关键点检查点解码错误；新增私有参数 backgroundclassid，默认 -1 保持原行为，遇到上述权重需显式传 None（官方预训练 COCO 权重同样受影响）。同时 TFLite 辅助函数不再靠「猜任意 4 维输出就是 mask」，改为 rank4_output 参数，修复了关键点张量被静默上采样成 Detections.mask 的问题。
数据增强修了两处静默污染标注的错误：keypointflippairs 为空列表时（pydantic 默认值），torchvision 后端照常镜像关键点坐标却不改左右标签；Albumentations 的 TimeReverse 此前只翻转图像、不动框和关键点，现已纳入几何变换处理，SquareSymmetry 也补上了无配对过滤。
训练侧：BestModelCallback 不再把 PyTorch Lightning 的 sanity check 打分当成真实 epoch 写入「最佳」EMA 检查点——用 pretrain_weights 起新训练时极易踩中，一旦写入真实训练永远无法超越；另有非方形训练尺寸缩放修复和一个依赖环境的 TFLite 导出失败修复。升级前请核对迁移指南中的三项行为变更。
v1.9.3: Faster Predict, Correct YOLO Test-Split & Export Fixes2026-08-17
RF-DETR 1.9.3 是维护版本：无破坏性变更、不新增公开 API，修掉十个 bug、打磨五处行为，横跨训练、推理、导出与分割。
对使用者最实在的几处：predict() 不再对 CUDA 张量输入逐张同步主机，批量推理少停顿；YOLO 数据集 evaluate(split="test") 终于评测真正的 test/，缺失时回退 valid/ 并告警，data.yaml 声明却解析失败则直接报错；ONNX/TFLite 导出不再悄悄丢掉多标签检测，解码器改为展平 (queries, classes) 后取高分再过阈值；batch_size="auto" 补上了 AdamW 优化器状态的内存占用，避免探测值偏大、第一步就 OOM。
PostProcess 的平分排序改为确定性 tie-break——分数降序、索引升序，与导出侧解码器规则统一。输出内容不变，但依赖精确输出顺序的代码值得扫一眼。分割训练的 skip_blocks 路径补回此前遗漏的特征投影，ONNX 基准测试也认 --device 了；断训续跑的指标历史与 EMA 跨 epoch 重复计数一并修好。
v1.9.2: Fixed Roboflow COCO & perf. optim2026-08-11
RF-DETR 1.9.2 is a fix-and-performance release: one breaking change, no new public APIs. Hierarchical COCO datasets — most commonly Roboflow exports carrying a synthetic unannotated grouping category — now get a correct, shared label mapping across train/valid/test, closing a case where per-class metrics could silently corrupt on the smaller split. The matcher's compact cost-matrix path is faster and lower-memory on real batches, training-resume from BestModelCallback's lightweight checkpoints now restores per-callback state instead of restarting cold, and a handful of training/eval fixes round it out.
✨ Spotlights / highlights
Breaking: hierarchical COCO datasets get a correct, shared label space
Roboflow COCO exports prepend a synthetic root category (unannotated, supercategory: "none") that every real class lists as its own supercategory. It never carried annotations but still consumed a label slot — training such a dataset built an N+1-class head instead of N.
``python
from rfdetr.datasets.coco import filterparentcategories, annotatedcategoryids
categories = [
{"id": 0, "name": "project-root", "supercategory": "none"},
{"id": 1, "name": "car", "supercategory": "project-root"},
{"id": 2, "name": "truck", "supercategory": "project-root"},
]
anns = {"annotations": [{"categoryid": 1}, {"categoryid": 2}]}
kept = filterparentcategories(categories, annotatedcategoryids(anns))
[c["name"] for c in kept]
-> ['car', 'truck'] — the unannotated root no longer takes a label slot
`
For datasets where a parent category does carry its own annotations, label indices are now derived once from the train split and shared into valid/test, so a grouping category annotated in one split but not another no longer shifts that split's label indices independently of the others.
> ⚠️ Checkpoints trained before 1.9.2 keep their old head width and label ordering. Evaluating one against a re-filtered dataset misaligns per-class metrics (an existing UserWarning fires). See the migration notes below.
Matcher: faster and lower-memory on real COCO batches
HungarianMatcher's detection-only cost matrix is now built padded to each batch's max(Ti) target count instead of the cross-image sum(Ti), when a fast eligibility check passes — identical results on eligible batches, automatic full-computation fallback otherwise.
| | before | after | change |
| -------------------- | ---------- | ---------- | ------------- |
| Matcher time | — | — | ~51% faster |
| Peak CUDA memory | — | — | ~73–76% lower |
| Training step (A100) | 288.364 ms | 232.457 ms | — |
The saving scales with target-count evenness across a batch — a batch where nearly all targets sit in one image sees little to no improvement.
Training resume restores per-callback state
Resuming from one of BestModelCallback's four lightweight checkpoints (checkpointbestregular.pth, checkpointbestema.pth, checkpointbesttotal.pth, last_ema.pth) previously restarted best-score tracking, EMA, and early-stopping cold, silently. It now restores that state:
`python
model.train(
datasetdir="mydataset",
resume="output/checkpointbestema.pth",
output_dir="output", # must match the original run for best-score restore
)
`
📝 Notable changes
🌱 Changed
- HungarianMatcher compact-path speedup — detection-only cost matrix padded to max(Ti) instead of sum(Ti); ~51% faster matcher, ~73–76% lower peak CUDA memory on real COCO batches. Compact path also copies only diagonal cost blocks to CPU and batches its safety-gate sweeps into one sync. (#1297, #1281, #1312)
- Deterministic-algorithm coverage — seedall() now also enables torch.usedeterministicalgorithms(True, warnonly=True); ops without a deterministic kernel warn at execution time instead of raising. (#1307)
- predict() — pins CPU image tensors before the CUDA transfer. (#1313)
- Two-stage query selection — avoids materialising repeated top-k gather indices. (#1278)
- Evaluation matching — counts labels on host instead of device. (#1276)
- Keypoint postprocessing — skips redundant CUDA presence checks. (#1282)
🔧 Fixed
- BestModelCallback resume — resuming from a lightweight checkpoint (checkpointbest.pth, last_ema.pth) now restores per-callback state instead of restarting best-score tracking, EMA, and early-stopping cold; a warning distinguishes checkpoints that intentionally omit optimizer state from ones that predate callback-state persistence entirely. (#1318)
- Rich epoch progress bar — no longer corrupted or duplicated by training-time log calls under RichProgressBar(leave=True). (#1316)
- kpactivemask false-positive warning** — loading a pre-keypoint-support checkpoint no longer warns about a deterministic schema buffer as a missing parameter. (#1302)
- Deferred CUDA-device move — an index-less torch.device("cuda") is normalised to the current device index before comparison, fixing spurious re-moves of every parameter on every call. (#1311)
- Legacy query-embedding fallback — only warns when it actually truncates weights. (#1301)
- evalemaonly — no longer logs an empty validation pass when the base metric is empty; EMA metrics (val/emamAP5095, val/emamAP50, val/emamAR, per-class AP, val (ema) summary table) are computed instead, and val/F1 is no longer silently dropped. (#1289)
- ModelContext.reinitializedetectionhead — raises a clear RuntimeError instead of AttributeError: 'NoneType' after RFDETR.inference(inplace=True) clears the weights. (#1283)
- evaluate() — builds its datamodule from the resolution-override config. (#1280)
⚠️ Breaking Changes
- Hierarchical COCO label filtering — unannotated grouping categories no longer consume a label slot; train/valid/test now share one label mapping derived from train. Checkpoints trained before this change need retraining against the new label space — see Migration guide. (#1303)
🏆 Contributors
- @JESUSROYETH — matcher perf (padded cost matrix, diagonal-only CPU copy, batched safety-gate sync), BestModelCallback resume-state restore, Rich progress-bar fix, evalemaonly fix, and five other training/inference fixes
- @atikulmunna (LinkedIn) — guarded ModelContext.reinitializedetectionhead against cleared weights; strict-typed rfdetr.detr and datasets.yolo module boundaries
- @Jonathan-Jesni — strict-typed rfdetr.datasets.save_grids` module boundary
- @Borda (LinkedIn) — hierarchical COCO label-filtering fix and release maintenance
---
Full changelog: https://github.com/roboflow/rf-detr/compare/1.9.1...1.9.2
v1.9.1: Faster Inference & Export, Correct Export Resize2026-08-04
RF-DETR v1.9.1 是一次维护更新：没有破坏性变更，升级后无需改代码，但推理与导出同时更快也更准。分割后处理提速 2.6–3.0 倍，PostProcess 不再为 mask 头反复构造 int64 索引（每张图省下 21–84 MiB），改用 index_select/expand 取行，输出逐位一致。1080p 下 predict() 快约 20%——低于阈值的掩码在上采样前就被丢弃，典型 COCO 图
v1.9.0: Configurable Training, ExecuTorch & CoreML Export2026-07-29
RF-DETR v1.9.0 让训练更灵活、部署更轻便：优化器与学习率调度器改为可插拔，写 torch.optim 里的名字、点分导入路径或可调用对象都行；关键点模型支持多卡多节点 DDP 训练；导出新增 ExecuTorch（.pte）与原生 CoreML（.mlpackage，不经 ONNX），TensorRT 路径同步改进，端上推理选择更多。另外 RFDETR.fromcheckpoint() 默认 weightsonly=True 安全反序列化，可信文件需显式传 trust_checkpoint=True。
升级前务必看迁移指南：[train]、[kornia] 已合并为 rfdetr[augment]，旧别名安装会失败；默认缩放插值从 Albumentations 换成 torchvision，像素值与 mAP 可能偏移，要锁定行为需显式指定 augmentation_backend="torchvision"；train() 传错参数不再静默忽略，直接抛 ValueError。v1.6、v1.7 起弃用的导入路径、配置字段和 .train() 参数已全部移除，老代码需要同步改造。
