## 🌱 Changed - **Class names on predictions.** `predict()` now includes `class_name` in the returned `detections.data` dict, mapping each detection's 0-indexed class ID to its human-readable name. No more manual lookups. ```python model = RFDETRSmall(pretrain_weights="path/to/fine_tuned.pth") detections = model.predict("image.jpg", threshold=0.5) print(detections.data["class_name"]) # ["cat", "dog", "cat"] ``` ## 🔧 Fixed - Fixed segmentation training crashing on multi-GPU DDP setups. The segmentation head leaves some parameters unused on certain forward steps, which triggered `RuntimeError: parameters that were not used in producing the loss`. `build_trainer()` now automatically enables `find_unused_parameters=True` when `segmentation_head=True`. - Fixed fused AdamW optimizer crash during FP32 multi-GPU training. On Ampere+ GPUs, fused AdamW was enabled whenever the hardware supported BF16 — even when the trainer was explicitly configured for `precision="32-true"`. This caused a dtype mismatch in DDP gradient buckets. The optimizer now checks the trainer's actual precision setting, not just GPU capability. - Fixed multi-GPU DDP training failing in Jupyter notebooks and Kaggle. Fork-based DDP corrupted PyTorch's OpenMP thread pool, causing `SIGABRT` on the second process. RF-DETR now uses a spawn-based DDP strategy in interactive environments, avoiding the thread pool issue entirely. - Fixed `RFDETR.train(resolution=...)` being silently ignored. The `resolution` kwarg is a model-level setting, not a training config field, so it was quietly dropped. It is now applied to the model config before training begins, with validation that the value is divisible by `patch_size * num_windows`. ```python model = RFDETRSmall() model.train(dataset_dir="./dataset", resolution=768) # now works ``` - Fixed `save_dataset_grids` being silently a no-op. The grid saver was never wired into the training loop. Dataset sample grids are now saved to `{output_dir}/dataset_grids/` when enabled. Grid save failures are caught and logged without interrupting training. - Fixed partial gradient-accumulation windows at the end of training epochs. When the dataset length was not evenly divisible by `effective_batch_size * world_size`, PyTorch Lightning would fire the optimizer on an incomplete accumulation window. The training dataset is now padded to an exact multiple, ensuring every optimizer step uses a full gradient window. - Fixed `torch.export.export` failing on the transformer decoder. The `spatial_shapes_hw` parameter was not threaded through the decoder layers, breaking export for models using multi-scale deformable attention. - Fixed `download_pretrain_weights()` silently overwriting fine-tuned checkpoints. When a fine-tuned checkpoint shared a filename with a registry model (e.g. `rf-detr-nano.pth`), an MD5 mismatch would trigger a re-download that replaced the user's weights. The function now returns early when the file exists and `redownload=False`, emitting a warning instead. --- ## 🏆 Contributors Welcome to our new contributors, and thank you to everyone who helped with this release: - **M. Fazri Nizar** (@mfazrinizar) ([LinkedIn](https://linkedin.com/in/mfazrinizar)) — *multi-GPU DDP training in notebooks* - **Jiahao Sun** (@sjhddh) ([LinkedIn](https://www.linkedin.com/in/jiahao7sun/)) — *config type hint fix* - **Jirka Borovec** (@Borda) ([LinkedIn](https://www.linkedin.com/in/jirka-borovec)) — *release coordination, reviews* *Automated contributions: @copilot-swe-agent[bot], @pre-commit-ci[bot]* --- **Full changelog**: https://github.com/roboflow/rf-detr/compare/1.6.3...1.6.4

# Changelog ## 🌱 Changed * Refined the licensing - update checkpoint tables with license column (#614) ## 🔧 Fixed * Pinned `transformers` dependency to version range `<5.0.0` to prevent compatibility issues with newer versions. (#599) * Fixed license link badges in the installation section of the documentation. (#591) * Addressed various issues in YOLO dataset processing, including image ID start values, class ID mismatches, and better user notifications for skipped files. (#74) # 🏆 Contributors @SkalskiP ([Piotr Skalski](https://www.linkedin.com/in/skalskip92/)), @Borda ([Jirka Borovec](https://www.linkedin.com/in/jirka-borovec/)), @mario-dg ([Mario da Graca](https://www.linkedin.com/in/mario-da-graca-1796b8273/)), @ferraridamiano ([Damiano Ferrari](https://www.linkedin.com/in/damiano-ferrari/)), @omkar-334 ([Omkar Kabde](https://www.linkedin.com/in/omkar-kabde/)), @panagiotamoraiti ([Panagiota Moraiti](https://www.linkedin.com/in/panagiota-moraiti/)), @surya3214, @PierreMarieCurie

## What's new 🔥 ### Support for instance segmentation RF-DETR 1.3.0 adds RF-DETR Seg (Preview), a new, state-of-the-art instance segmentation model. RF-DETR Seg (Preview) is 3x faster and more accurate than the largest YOLO11 when evaluated on the Microsoft COCO Segmentation benchmark, defining a new real-time state-of-the-art for the industry-standard benchmark in segmentation model evaluation. <img width="1309" height="736" alt="Screenshot 2025-10-02 at 21 33 37 (1)" src="https://github.com/user-attachments/assets/35248e18-a236-4db5-89b0-8e73dd909407" /> With the `rfdetr` Python package, you can train and run models with the new `RFDETRSegPreview` trainer. The training API is as follows: ```python from rfdetr import RFDETRSegPreview model = RFDETRSegPreview() model.train( dataset_dir=<DATASET_PATH>, epochs=10, batch_size=4, grad_accum_steps=4, lr=1e-4, output_dir=<OUTPUT_PATH> ) ``` Trained models can also be [deployed with Roboflow Inference](https://rfdetr.roboflow.com/learn/deploy/) with the new `deploy_to_roboflow` function. This allows you to provision a serverless cloud API for running your model, as well as deploy your model in a Roboflow Workflow or with a Roboflow Inference server: ```python from rfdetr import RFDETRSegPreview x = RFDETRSegPreview(pretrain_weights="<path/to/prtrain/weights/dir>") x.deploy_to_roboflow( workspace="<your-workspace>", project_ids=["<your-project-id>"], api_key="<YOUR_API_KEY>" ) ``` 🏆 Contributors @probicheaux @isaacrob-roboflow @Matvezy @SkalskiP @capjamesg

# Changelog https://github.com/user-attachments/assets/87a3cefe-f3d1-42df-a799-f1d45dddf75e ## 🚀 Added - Early stopping - Early stopping monitors validation mAP and halts training if improvements remain below a threshold for a set number of epochs. This can reduce wasted computation once the model converges. Additional parameters—such as `early_stopping_patience`, `early_stopping_min_delta`, and `early_stopping_use_ema`—let you fine-tune the stopping behavior. (https://github.com/roboflow/rf-detr/pull/87) ```python from rfdetr import RFDETRBase model = RFDETRBase() model.train(dataset_dir=<DATASET_PATH>, epochs=12, batch_size=4, grad_accum_steps=4, early_stopping=True) ``` - Gradient checkpointing - Gradient checkpointing - Gradient checkpointing re-computes certain parts of the forward pass during backpropagation to reduce peak memory usage. This allows training larger models or higher batch sizes on limited GPU memory at the cost of slightly longer training time. Enable it by setting `gradient_checkpointing=True`. (https://github.com/roboflow/rf-detr/pull/91) ```python from rfdetr import RFDETRBase model = RFDETRBase() model.train(dataset_dir=<DATASET_PATH>, epochs=12, batch_size=8, grad_accum_steps=2, gradient_checkpointing=True) ``` - Saving metrics - Training and validation metrics (e.g., losses, mAP) are now automatically saved to your output directory after training. (https://github.com/roboflow/rf-detr/pull/58)  - Logging with TensorBoard - Added support for logging training progress and metrics to TensorBoard, providing live visualizations of your model’s performance. Simply pass `tensorboard=True` to `.train()`, then run `tensorboard --logdir <OUTPUT_DIR>` to monitor. (https://github.com/roboflow/rf-detr/pull/62) <details> <summary>Using TensorBoard with RF-DETR</summary> <br> - TensorBoard logging requires additional packages. Install them with: ```bash pip install "rfdetr[metrics]" ``` - To activate logging, pass the extra parameter `tensorboard=True` to `.train()`: ```python from rfdetr import RFDETRBase model = RFDETRBase() model.train(dataset_dir=<DATASET_PATH>, epochs=12, batch_size=4, grad_accum_steps=4, tensorboard=True, output_dir=<OUTPUT_PATH>) ``` - To use TensorBoard locally, navigate to your project directory and run: ```bash tensorboard --logdir <OUTPUT_DIR> ``` Then open `http://localhost:6006/` in your browser to view your logs. - To use TensorBoard in Google Colab run: ```bash %load_ext tensorboard %tensorboard --logdir <OUTPUT_DIR> ``` </details> - Logging with Weights and Biases - Integrated Weights and Biases (W&B) for collaborative, cloud-based experiment tracking. Passing wandb=True to .train() will automatically log metrics, hyperparameters, and system stats to your W&B project. (https://github.com/roboflow/rf-detr/pull/70) <details> <summary>Using Weights and Biases with RF-DETR</summary> <br> - Weights and Biases logging requires additional packages. Install them with: ```bash pip install "rfdetr[metrics]" ``` - Before using W&B, make sure you are logged in: ```bash wandb login ``` You can retrieve your API key at wandb.ai/authorize. - To activate logging, pass the extra parameter `wandb=True` to `.train()`: ```python from rfdetr import RFDETRBase model = RFDETRBase() model.train(dataset_dir=<DATASET_PATH>, epochs=12, batch_size=4, grad_accum_steps=4, wandb=True, project=<PROJECT_NAME>, run=<RUN_NAME>) ``` In W&B, projects are collections of related machine learning experiments, and runs are individual sessions where training or evaluation happens. If you don't specify a name for a run, W&B will assign a random one automatically. </details> - Automated Python package publish - Implemented a GitHub Actions workflow to build and publish the `rfdetr` package to PyPI on each new release, ensuring the latest version is immediately available. (https://github.com/roboflow/rf-detr/pull/71) ## 🔧 Fixed - Resume training - You can resume training from a previously saved checkpoint by passing the path to the `checkpoint.pth` file using the `resume` argument. This is useful when training is interrupted or you want to continue fine-tuning an already partially trained model. The training loop will automatically load the weights and optimizer state from the provided checkpoint file. (https://github.com/roboflow/rf-detr/pull/88) ```python from rfdetr import RFDETRBase model = RFDETRBase() model.train(dataset_dir=<DATASET_PATH>, epochs=12, batch_size=4, grad_accum_steps=4, resume=<CHECKPOINT_PATH>) ``` # 🏆 Contributors @mario-dg ([Mario da Graca](https://www.linkedin.com/in/mario-da-graca-1796b8273/overlay/about-this-profile/)), @onuralpszr ([Onuralp SEZER](https://www.linkedin.com/in/osezer/)), @farukalamai ([Md Faruk Alam](https://www.linkedin.com/in/farukalamai/overlay/about-this-profile/)), @probicheaux ([Peter Robicheaux](https://www.linkedin.com/in/peter-robicheaux-01958813b/overlay/about-this-profile/)), @isaacrob-roboflow ([Isaac Robinson](https://www.linkedin.com/in/robinsonish/overlay/about-this-profile/)), @Matvezy ([Matvei Popov](https://www.linkedin.com/in/matvezy/overlay/about-this-profile/)), @SkalskiP ([Piotr Skalski](https://www.linkedin.com/in/skalskip92/overlay/about-this-profile/))