Skip to content

Train an RFDETR Model ​

SUMMARY

Train and fine-tune RF-DETR object-detection and instance-segmentation models with Iris. Select an RFDETRVariant, configure RFDETRConfig, prepare COCO datasets, and run or resume training with the shared Trainer.

Python Version Support

Iris training supports Python 3.11 and 3.12 only. Create an environment with one of these versions before installing dependencies.

Requirements ​

RequirementValue
Python3.11 or 3.12
PlatformLinux, macOS, or Windows
DatasetCOCO detection or instance-segmentation annotations
GPUCUDA GPU recommended for practical training times

Quick Installation ​

Install PyTorch for your CUDA version, then install the RF-DETR dependencies:

bash
python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
python -m pip install "telekinesis-ai[iris-rfdetr]"

PyTorch Installation

For CPU, macOS, or another CUDA version, select the appropriate command in the PyTorch installation guide.

Training Workflow ​

The example below exposes RF-DETR model and Trainer settings as command-line arguments, reads the class count from COCO metadata, enables the extended RF-DETR augmentation preset, and optionally resumes from a checkpoint.

Create train_rfdetr.py ​

python
"""Train an RF-DETR model on a COCO dataset."""

import argparse
from pathlib import Path

import torch
from loguru import logger

from telekinesis.iris.dataset import AugmentationPreset, COCODataset, prepare_coco_datasets
from telekinesis.iris.logger import TensorBoardMetricLogger
from telekinesis.iris.models import RFDETR, RFDETRConfig, RFDETRVariant
from telekinesis.iris.trainer import Precision, Trainer


def parse_args() -> argparse.Namespace:
    """Parse command-line arguments."""
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--dataset-dir", type=Path, required=True)
    parser.add_argument("--output-dir", type=Path, required=True)
    parser.add_argument("--run-name", default="rfdetr")
    parser.add_argument(
        "--variant",
        choices=[variant.value for variant in RFDETRVariant],
        default=RFDETRVariant.SEG_MEDIUM.value,
    )
    parser.add_argument("--epochs", type=int, default=500)
    parser.add_argument("--batch-size", type=int, default=8)
    parser.add_argument("--gradient-accumulation-steps", type=int, default=4)
    parser.add_argument("--num-workers", type=int, default=2)
    parser.add_argument("--learning-rate", type=float, default=1e-4)
    parser.add_argument("--encoder-learning-rate", type=float, default=1.5e-4)
    parser.add_argument("--weight-decay", type=float, default=1e-4)
    parser.add_argument("--learning-rate-drop-epochs", type=int, default=100)
    parser.add_argument("--resolution", type=int)
    parser.add_argument("--validation-split", type=float, default=0.3)
    parser.add_argument("--evaluation-interval", type=int, default=5)
    parser.add_argument("--checkpoint-interval", type=int, default=50)
    parser.add_argument("--seed", type=int, default=42)
    parser.add_argument("--device", help="For example: cuda, cuda:0, or cpu.")
    parser.add_argument(
        "--precision",
        choices=[precision.value for precision in Precision],
        default=Precision.AUTO.value,
    )
    parser.add_argument("--pretrained", action=argparse.BooleanOptionalAction, default=True)
    parser.add_argument("--resume-from", type=Path)
    return parser.parse_args()


def train_rfdetr(args: argparse.Namespace) -> None:
    """Configure and train RF-DETR."""
    metadata_dir = args.dataset_dir / "train"
    if not metadata_dir.is_dir():
        metadata_dir = args.dataset_dir
    metadata = COCODataset(metadata_dir)
    torch.manual_seed(args.seed)

    config = RFDETRConfig(
        variant=RFDETRVariant(args.variant),
        num_classes=metadata.num_classes,
        pretrained=args.pretrained,
        resolution=args.resolution,
        learning_rate=args.learning_rate,
        encoder_learning_rate=args.encoder_learning_rate,
        weight_decay=args.weight_decay,
        learning_rate_drop_epochs=args.learning_rate_drop_epochs,
        augmentation=AugmentationPreset.RFDETR_EXTRA,
    )
    model = RFDETR(config=config)
    training_dataset, validation_dataset = prepare_coco_datasets(
        dataset_dir=args.dataset_dir,
        validation_split=args.validation_split,
        seed=args.seed,
        train_transforms=model.train_transforms,
        val_transforms=model.val_transforms,
        include_masks=model.requires_masks,
    )
    device = args.device or ("cuda" if torch.cuda.is_available() else "cpu")
    logger.info(
        f"Training RF-DETR {config.variant.value} on {len(training_dataset)} images "
        f"using {device}."
    )
    metric_logger = TensorBoardMetricLogger(args.output_dir / "tensorboard")
    model_trainer = Trainer(
        model=model,
        run_name=args.run_name,
        training_dataset=training_dataset,
        validation_dataset=validation_dataset,
        output_dir=args.output_dir,
        epochs=args.epochs,
        batch_size=args.batch_size,
        device=device,
        num_workers=args.num_workers,
        precision=args.precision,
        gradient_accumulation_steps=args.gradient_accumulation_steps,
        evaluation_interval=args.evaluation_interval,
        checkpoint_interval=args.checkpoint_interval,
        seed=args.seed,
        metric_logger=metric_logger,
    )
    if args.resume_from is None:
        model_trainer.train()
    else:
        model_trainer.resume(args.resume_from)


if __name__ == "__main__":
    train_rfdetr(parse_args())

Launch Training ​

Start a run with the default values from parse_args():

bash
python train_rfdetr.py \
  --dataset-dir path/to/dataset \
  --output-dir results/rfdetr

Override the most important model and Trainer settings as needed:

bash
python train_rfdetr.py \
  --dataset-dir path/to/dataset \
  --output-dir results/rfdetr \
  --run-name custom-rfdetr \
  --variant seg-medium \
  --epochs 500 \
  --batch-size 8 \
  --gradient-accumulation-steps 4 \
  --learning-rate 1e-4 \
  --device cuda \
  --precision auto

Resume Training ​

Resume from a Trainer checkpoint while keeping the model configuration compatible:

bash
python train_rfdetr.py \
  --dataset-dir path/to/dataset \
  --output-dir results/rfdetr \
  --resume-from results/rfdetr/latest.pt

Command-Line Arguments ​

The training script accepts the following options:

ArgumentDefaultDescription
--dataset-dirrequiredCOCO dataset root or split directory
--output-dirrequiredTraining outputs, logs, and checkpoints
--run-name"rfdetr"Name stored in run and export metadata
--variant"seg-medium"RF-DETR detection or segmentation variant
--epochs500Total training epochs, including restored epochs
--batch-size8Samples per micro-batch
--gradient-accumulation-steps4Micro-batches accumulated per optimizer update
--num-workers2DataLoader worker processes
--learning-rate1e-4Non-encoder learning rate
--encoder-learning-rate1.5e-4Encoder base learning rate
--weight-decay1e-4AdamW weight decay
--learning-rate-drop-epochs100Epoch used to resolve the step-scheduler drop
--resolutionNoneSquare resolution override; otherwise uses the variant default
--validation-split0.3Fallback validation fraction when no validation split exists
--evaluation-interval5Epochs between validation runs
--checkpoint-interval50Epochs between numbered checkpoints
--seed42Training and dataset-split seed
--deviceautomaticDevice such as cuda, cuda:0, or cpu
--precision"auto""auto", "fp32", "fp16", or "bf16"
--pretrained / --no-pretrainedenabledEnable or disable pretrained model weights
--resume-fromNoneTrainer checkpoint from which to continue

Training Guidance

See Best Practices: Trainer for guidance on tuning batch size, learning rate, epochs, workers, evaluation, and checkpoints.

Class Count and Masks

Set num_classes to the classification-head size required by the dataset category IDs. Segmentation variants also require a valid polygon or RLE segmentation for every annotated object.

Run the Example ​

A runnable version is available in the Telekinesis examples repository:

bash
cd telekinesis-examples
python examples/iris/train_rfdetr.py \
  --dataset-dir path/to/dataset \
  --output-dir results/rfdetr

Add --resume-from results/rfdetr/latest.pt to continue a previous run.

Checkpoints and Metrics ​

The training script saves the following outputs to the configured output_dir:

OutputDescription
latest.ptUpdated after every completed epoch
best.ptUpdated when validation box mAP improves for detection, or mask mAP improves for segmentation
epoch_NNNN.ptWritten according to checkpoint_interval
TensorBoard logsTraining loss, learning rate, validation metrics, and configured previews

Validation reports COCO box metrics. Segmentation variants additionally report mask metrics.

Model Reference ​

Model Variants ​

Pass an RFDETRVariant enum member, or its string value, to RFDETRConfig.variant.

TaskEnum memberValue
Object detectionRFDETRVariant.NANO"nano"
Object detectionRFDETRVariant.SMALL"small"
Object detectionRFDETRVariant.MEDIUM"medium"
Object detectionRFDETRVariant.BASE"base"
Object detectionRFDETRVariant.LARGE"large"
Instance segmentationRFDETRVariant.SEG_NANO"seg-nano"
Instance segmentationRFDETRVariant.SEG_SMALL"seg-small"
Instance segmentationRFDETRVariant.SEG_MEDIUM"seg-medium"
Instance segmentationRFDETRVariant.SEG_LARGE"seg-large"

Start with a smaller variant while validating a new dataset and pipeline, then increase model size if accuracy requires it.

RFDETRConfig ​

RFDETRConfig combines model construction and training-adapter settings in one immutable configuration.

OptionDefaultDescription
variantRFDETRVariant.SEG_MEDIUMRF-DETR detection or segmentation variant
num_classes1Positive number of foreground class slots
pretrainedTrueLoads pretrained model weights
resolutionNoneSquare input resolution; uses the variant default when omitted
num_queriesNoneOverrides the variant's number of object queries
gradient_checkpointingNoneOverrides activation checkpointing
compileNoneOverrides torch.compile behavior
freeze_encoderNoneOverrides encoder freezing
image_mean(0.485, 0.456, 0.406)RGB normalization mean; None disables mean normalization
image_std(0.229, 0.224, 0.225)Positive RGB normalization standard deviation
box_format"xyxy"Adapter input box format: "xyxy" or "cxcywh"
normalize_boxesTrueNormalizes bounding-box coordinates for training
background_class_id0Background category ID; None disables background filtering
optimizer"adamw"Optimizer built by the RF-DETR adapter
optimizer_options{}Additional optimizer keyword arguments
learning_rate1e-4Non-encoder learning rate
encoder_learning_rate1.5e-4Encoder base learning rate before layer/component decay
weight_decay1e-4Optimizer weight decay
vit_layer_decay0.8Layer-wise ViT learning-rate decay
component_decay0.7Component learning-rate decay
scheduler"step"Scheduler name; RF-DETR fills the drop step from epochs
scheduler_options{}Scheduler-specific overrides
scheduler_interval"step"Scheduler update interval
scheduler_monitorNoneMetric for a monitored scheduler
warmup_steps0Linear warmup optimizer steps
learning_rate_drop_epochs100Epoch used to resolve the default step-scheduler drop
use_emaTrueEnables exponential moving average weights
ema_decay0.993EMA decay coefficient
ema_tau100.0EMA warmup constant
max_detections500Maximum detections during evaluation
augmentationRFDETR_DEFAULTSPreset name or declarative augmentation sequence

Custom Resolution

Custom resolutions must satisfy the selected variant's patch/window divisibility constraints. Prefer the variant default unless the input scale or available memory requires an override.

RFDETR Properties ​

PropertyTypeDescription
configRFDETRConfigPublic unified configuration
model_configModelConfigResolved variant-specific model configuration
adapter_configRFDETRConfigConfiguration used by the training adapter
modelnn.ModuleUnderlying PyTorch model
adapterRFDETRTrainingAdapterCached RF-DETR training adapter
descriptorModelDescriptorFamily, variant, and task metadata
train_transformstarget-aware callableConfigured augmentation pipeline
val_transformsResizeTransformsValidation resize transforms
requires_masksboolTrue when the selected variant has a segmentation head

Trainer Reference

See Configuration: Trainer Reference for all Trainer constructor options, defaults, and methods.

RFDETR Best Practices ​

Categories and Annotations ​

  • Keep category IDs consistent between training and validation datasets.
  • Set num_classes to the classification-head size required by the category IDs. With standard COCO IDs starting at 1, this is typically the greatest category ID.
  • Keep background_class_id=0 for standard COCO datasets without a foreground category at ID 0. Set it to None only when no class slot should be filtered as background.
  • Use a segmentation variant only when every annotated object has a valid polygon or RLE mask.
  • Inspect boxes and masks visually before starting a long training run.

Variant Selection ​

  • Start with NANO or SEG_NANO while validating a new dataset and pipeline.
  • Increase model size only when validation metrics show that the smaller variant lacks capacity.
  • Use a detection variant when masks are not required; segmentation variants add memory and compute overhead.
  • Compare variants with the same dataset split and Trainer seed.
python
config = RFDETRConfig(
    variant=RFDETRVariant.SEG_NANO,
    num_classes=5,
    pretrained=True,
)

Pretrained Weights and Encoder Freezing ​

  • Keep pretrained=True for normal fine-tuning on a custom dataset.
  • Use freeze_encoder=True when compute or data is limited and only the prediction layers need adaptation.
  • Unfreeze the encoder when the deployment images differ substantially from the pretraining domain.
  • Validate the effect of encoder freezing rather than assuming it will improve generalization.

Resolution and Object Queries ​

  • Prefer the variant's default resolution initially.
  • Increase resolution when small-object detail is being lost; expect higher memory use and slower training.
  • Reduce Trainer batch_size before lowering resolution when GPU memory is limited.
  • Custom resolutions must be divisible by the selected variant's patch-size and window configuration.
  • Increase num_queries only when images routinely contain more objects than the variant can represent. Extra queries increase memory and compute.
python
config = RFDETRConfig(
    variant=RFDETRVariant.SEG_MEDIUM,
    num_classes=5,
    resolution=None,
    num_queries=None,
)

Memory and Performance ​

  • Enable gradient_checkpointing when activation memory limits training. It reduces memory use at the cost of additional computation.
  • Treat compile=True as an optimization to benchmark on the target environment; compilation adds startup cost and may not support every platform equally.
  • Reduce batch_size first when addressing out-of-memory errors.
  • Start with Trainer precision="auto"; use "fp32" if reduced precision is numerically unstable.
  • Change one performance setting at a time and compare both throughput and validation metrics.

Preprocessing and Boxes ​

  • Keep the default ImageNet image_mean and image_std when using pretrained weights unless the input pipeline has a documented alternative normalization.
  • COCODataset supplies boxes in xyxy, matching the default box_format="xyxy".
  • Keep normalize_boxes=True for the standard RF-DETR training adapter.
  • Change box_format, normalization, or RGB statistics only when using a custom dataset pipeline that requires it.

Validation and Resume ​

  • Use Trainer validation_images_to_log to inspect qualitative predictions alongside COCO metrics.
  • Select deployment candidates using validation results rather than training loss alone.
  • Use best.pt for the best monitored model and latest.pt to continue interrupted training.
  • Keep the variant, class count, resolution, query count, and preprocessing configuration compatible when resuming.

Next Steps ​