rf-detr

1.11.2 hardens threaded inference, turns a silent class-name shift into an error, and fixes predict() on flipped frames.

• Threads sharing one model no longer corrupt its weights or switch off cuDNN for the whole process.
• A class_names list that includes the Roboflow root category now errors instead of shifting every label.
• predict() takes frame[:, :, ::-1], so the docs' video, webcam and RTSP examples run as written.
• YOLO data.yaml files load consistently: class IDs sort numerically and images/train layouts work.
• ONNX exports run faster through Apple's CoreML: Nano drops from 9.3 to 8.3 ms on an M4 Max with ONNX Runtime 1.30.

Upgrading from 1.11.1 means one removed constant: inline ["images", "labels"] if you imported REQUIRED_DATA_SUBDIRS. Four behaviour changes are worth a skim in the Migration guide.

✨ Spotlights

Threads sharing a model could corrupt its weights

A cold model's weights move from CPU to the accelerator on first use (predict(), inference(), and export()'s restore step), and several threads could run that move at once. On a cold RF-DETR segmentation model, four threads calling predict() together left 13 of 573 state_dict tensors corrupted. Nothing raised, and every frame came back with no detections. The check and the move now happen under a per-model lock, so a thread that arrives mid-move waits for it. (#1564)

from concurrent.futures import ThreadPoolExecutor

model = RFDETRSegNano()  # cold: weights still on CPU
with ThreadPoolExecutor(max_workers=4) as pool:
    detections = list(pool.map(model.predict, frames))

Segmentation threads no longer disable cuDNN for everyone

The segmentation head wraps its depthwise convolution in torch.backends.cudnn.flags(enabled=False). That flag is process-global and not thread-safe: a second thread entering mid-scope saved False and restored it last, so every later convolution in the process quietly skipped cuDNN. Detections near the score threshold changed (25 instead of 24 on one real frame). Forward and backward scopes now share a lock, and a CPU input skips them entirely. No code change on your side. (#1565)

A root category in class_names is now an error

Roboflow COCO exports list a top-level category first, such as animals above cat, dog and horse. Since 1.9.2 it isn't one of the model's classes, so a list built from every category gave each class its neighbour's name, in checkpoints and in predict() output, with no warning. RFDETR.train() now compares class_names with the dataset before it writes training_config.json or starts a wandb/MLflow run. (#1572)

# 1.11.1 trained, with every name shifted by one
model.train(dataset_dir=ds, class_names=["animals", "cat", "dog", "horse"])

# 1.11.2 raises ValueError naming the extra entry; pass the real classes
model.train(dataset_dir=ds, class_names=["cat", "dog", "horse"])

predict() accepts flipped frames

frame[:, :, ::-1], the BGR-to-RGB flip in the video file, webcam and RTSP examples of docs/learn/pretrained.md, is a negative-stride NumPy view, and torch.from_numpy rejects those. The examples raised ValueError: At least one stride in the given numpy array is negative on the first frame. Only arrays with a negative stride get copied now. (#1573)

detections = model.predict(frame[:, :, ::-1])

REQUIRED_DATA_SUBDIRS is gone

is_valid_yolo_dataset finds split directories through the YAML-aware resolver, and that resolver derives the labels directory from the resolved images path. Its only reader was is_valid_yolo_dataset, rewritten in this release, so nothing reads the ["images", "labels"] constant any more. A split directory that resolves outside the dataset root is refused too, even through a conventional train/images symlink. (#1570)

🔄 Migration guide

One removal, in rfdetr.datasets.yolo:

# 1.1

RF-DETR 1.11.1 is a correctness patch. It turns silent wrong results into loud, correct ones:

• LoRA backbone — backbone_lora=True checkpoints trained on a random encoder, no error. Now loads correctly.
• TensorRT inference — wrong-device/dtype/non-contiguous inputs returned wrong detections, no error. Now refused.
• Crowd-region mAP — val/test mAP overcounted false positives on COCO crowd regions. Now matches pycocotools.

Most users need no action. 4 of the 5 "breaking" changes only affect code that was already getting a wrong result or an uncaught KeyError — this release just stops hiding it. See the Migration guide for exact before/after code.

The one real API change: RFDETRModelModule.clip_gradients → configure_gradient_clipping. Only affects code that calls clip_gradients directly, or relies on super().clip_gradients(...) inside an override.

Everything else is a bug fix or documentation update.

✨ Spotlights

backbone_lora=True checkpoints silently trained a random encoder — now fixed

RFDETR.from_checkpoint(), RFDETRSmall(pretrain_weights=...), and train() all loaded a LoRA checkpoint before wrapping the encoder with LoRA, so none of the stored PEFT-named weights matched — the encoder silently stayed at random initialization, and evaluate() scored near zero with no error.

# Before (1.11.0): silent — encoder never actually reloads
model = RFDETRLarge(pretrain_weights="checkpoint_best_total.pth", backbone_lora=True)
model.evaluate()  # mAP50:95 ≈ 0.0001 — looks broken, no exception

# After (1.11.1): encoder is wrapped before load, weights match
model = RFDETRLarge(pretrain_weights="checkpoint_best_total.pth", backbone_lora=True)
model.evaluate()  # mAP50:95 ≈ 0.6221 — same as the in-memory trained model

Measured: RF-DETR Large @640, LoRA-tuned on 262 COCO person images. (#1543)

last.ckpt and interval checkpoints now carry enough to reload

# Before (1.11.0)
RFDETR.from_checkpoint("output/last.ckpt")  # KeyError: 'args'

# After (1.11.1)
model = RFDETR.from_checkpoint("output/last.ckpt")  # rebuilds trained resolution/architecture

Files written by 1.11.0 and earlier can't be repaired in place — from_checkpoint now raises a named ValueError pointing at checkpoint_best_ema.pth and training_config.json instead. (#1561)

Val/test mAP now matches pycocotools on COCO crowd regions

Detections inside iscrowd=1 regions no longer count as false positives. Numbers shift on crowd-labelled data — Nano COCO val2017: 0.4802 → 0.4842 mAP. Training is unchanged. (#1532)

TRTInference refuses inputs TensorRT would misread

# Before (1.11.0): silent wrong output
trt_model(image_tensor.to(memory_format=torch.channels_last))  # 13 detections → 0, no error

# After (1.11.1): explicit refusal
trt_model(image_tensor.to(memory_format=torch.channels_last))
# ValueError: Input 'input' is not contiguous (strides (...)), and TensorRT reads it as dense
# row-major memory. Pass tensor.contiguous().

(#1546)

RFDETRModelModule.clip_gradients renamed → configure_gradient_clipping (Breaking)

# Before (1.11.0)
class MyModule(RFDETRModelModule):
    def clip_gradients(self, optimizer, gradient_clip_val=None, gradient_clip_algorithm=None): ...


# After (1.11.1)
class MyModule(RFDETRModelModule):
    def configure_gradient_clipping(self, optimizer, gradient_clip_val=None, gradient_clip_algorithm=None): ...

Moves the keypoint fp16 clipping fix onto the Lightning hook meant for it — clip_gradients itself now reverts to Lightning's base implementation. Narrower than it looks: configure_gradient_clipping's non-fused branch calls `self.clip_grad

RF-DETR 1.11.0 widens the export surface and speeds up training. Three new export formats land — OpenVINO IR (with configurable precision), LiteRT via litert-torch, and Apple Core AI (.aimodel, for iOS/iPadOS/macOS 27+) — alongside dynamic-batch TensorRT engines built through a single optimization profile, so one engine now serves a batch range instead of one fixed size. Training gains opt-in CUDA-graph replay (combinable with torch.compile, plus a Transformer Engine FP8 capture route on supported hardware) and a WebDataset streaming reader for tar-shard training input at scale.

This release also completes a deprecation cycle from 1.9.0: RFDETR.optimize_for_inference(), TrainConfig.lr_drop/lr_min_factor, and the standalone synthetic-dataset generator are removed, and export internals were restructured into one Exporter class per format behind a registry. RFDETR.export()'s own signature is unchanged, but code importing the old converter functions directly needs updated imports. See the Migration guide below for exact before/after code.

✨ Spotlights / highlights

Breaking: export internals restructured into one Exporter class per format

Each export format (onnx, openvino, coreml, executorch, tflite, tensorrt, litert) is now written by a <Format>Exporter class built from that format's own frozen config dataclass, reached through a registry. RFDETR.export()'s own signature and return value are unchanged — this only breaks code that imported the old converter functions directly. (#1448)

# Before (removed)
from rfdetr.export._onnx.exporter import export_onnx

# After
from rfdetr.export._onnx.exporter import OnnxExporter

New: OpenVINO IR export

from rfdetr import RFDETRNano

model = RFDETRNano()
model.export(format="openvino", openvino_precision="float32", output_dir="output")
# -> output/rfdetr-nano.xml + output/rfdetr-nano.bin

openvino_precision accepts "float32", "float16", or None. Install with pip install "rfdetr[openvino]". (#1238)

New: Apple Core AI export

from rfdetr import RFDETRNano

model = RFDETRNano(pretrain_weights="<path/to/checkpoint.pth>")
model.export(format="coreai")
# -> output/rfdetr-nano_fp32.aimodel

Experimental. Targets iOS, iPadOS and macOS 27+ via coreai-torch, no ONNX step. coreai_precision="float16" halves asset size; the exporter runs the two-stage topk in float32 even in a float16 graph because the Neural Engine returns corrupt float16 topk indices. Install with pip install "rfdetr[coreai]" (Python 3.11-3.13, macOS Apple silicon or Linux x86-64 to build the asset). (#1521)

New: opt-in CUDA graph training replay, combinable with compile and FP8

model = RFDETRNano(cuda_graphs=True)
# or, delegated to Inductor's own CUDA graph trees:
model = RFDETRNano(cuda_graphs=True, compile=True)

Single-GPU detection training only. BF16/eager route supports gradient accumulation; a separate FP8 route through Transformer Engine (amp_dtype="fp8", compile=False) is limited to grad_accum_steps=1. Measured on an RTX PRO 6000 (Nano, batch 64, BF16): compile=True alone is ~17% faster than eager; cuda_graphs=True combined with compile=True is fastest at large batch. (#1468, #1479, #1481)

New: stream training input directly from WebDataset tar shards

from rfdetr.config import TrainConfig

config = TrainConfig(dataset_file="webdataset", dataset_dir="path/to/shards")

Pack shards with python -m rfdetr.cli.webdataset. Requires the data extra: pip install "rfdetr[data]" (not [webdataset] — that extra never existed). (#1396)

New: dynamic-batch TensorRT engines through a single optimization profile

model.export(format="tensorrt", dynamic_batch=True, batch_size=4, max_batch_size=16)

One engine now accepts any batch from 1 to max_batch_size, tuned for batch_size; w

RF-DETR 1.10.1 is a patch release: compile=True now actually reaches CUDA's torch.compile path under the default multi_scale=True recipe, and peak CUDA memory in segmentation loss drops by sampling ground-truth masks one image at a time. It also carries several device-sync and strategy-selection fixes for the still-experimental, undocumented TPU/XLA training path (tracked under issue #1058) — see Notable Changes below. No breaking changes in this release.

✨ Spotlights

⚡ compile=True now actually compiles on CUDA with the default multi_scale=True

The compile gate previously excluded multi-scale training, but the exclusion sat behind checks that already required a CUDA device and CUDA accelerator — so it only ever blocked the CUDA path, where dynamic=True already handles the varying input size. Setting compile=True on a default recipe previously logged a notice and trained eagerly instead. ([#1436]; [#1411], shipped in 1.10.0, made compilation reachable in the first place)

from rfdetr import RFDETRSmall

model = RFDETRSmall()
model.train(dataset_dir="...", compile=True)  # multi_scale=True by default — now actually compiles on CUDA

💾 Reduced peak CUDA memory in segmentation loss

For multi-image CUDA batches with boolean ground-truth masks, sampling now happens one image at a time, releasing each image's float masks before the next, instead of concatenating a batch-wide float mask tensor. Narrower inputs (single-image batches, non-CUDA, non-bool masks) keep the prior concat path unchanged. ([#1437])

🔄 Migration guide

No breaking changes in this release. One thing to know: if you call dice_loss_jit / sigmoid_ce_loss_jit directly — not part of the public API, only reachable through rfdetr.models.lwdetr's backward-compat re-exports — most NumPy scalar denominators now need casting to float first. See MIGRATION.md for details.

📝 Notable changes

🔧 Fixed

• compile=True now takes effect on CUDA with the default multi_scale=True, instead of previously logging a notice and training eagerly. Also fixes the now-stale multi_scale=False claim in the COCO2017 training cookbook. (#1436; #1411, shipped in 1.10.0, made compilation reachable in the first place)
• Reduced peak CUDA memory in segmentation loss by sampling matched ground-truth masks one image at a time, for multi-image CUDA batches with boolean masks. (#1437)
• Docs site: the version banner no longer flags the current release as outdated. (#1429)
• TPU/XLA training (experimental, undocumented): point_sample(mode="nearest") no longer leaves the device on MPS/XLA (#1432, issue #1058); SetCriterion.loss_masks no longer syncs its normalizing denominator to the host, with a side effect that dice_loss_jit/sigmoid_ce_loss_jit — reachable only through lwdetr.py's backward-compat re-exports, not the public API — now reject most NumPy scalar denominators (#1428, issue #1058); build_trainer now selects XLAStrategy for multi-device XLA/TPU training when strategy="auto", previously a crash at Trainer construction, and changes the precision-plugin path for single-device accelerator="auto" XLA runs too (#1427, issue #1058); XLA-marked tests pass on real TPU silicon (#1426, issue #1058).

🏆 Contributors

• Jesús Royeth (@JESUSROYETH): all six code/test fixes in this release — the compile=True/CUDA multi-scale fix, reduced peak CUDA memory in segmentation loss, and the experimental TPU/XLA device-sync, strategy-selection, and test-suite fixes.
• Jirka Borovec (@Borda, LinkedIn): fixed the docs-site version banner falsely flagging the current release as outdated, and this release's own prep.

Full changelog: https://github.com/roboflow/rf-detr/compare/1.10.0...1.10.1 *Co-authored with [/oss:release](https://bord