Implementation:Roboflow Rf detr Best Checkpoint Selection

Knowledge Sources	RF-DETR
Domains	Training, Model_Selection
Last Updated	2026-02-08 15:00 GMT

Overview

Concrete tool for tracking best model performance and managing checkpoints during RF-DETR training.

Description

BestMetricHolder tracks the best mAP across training epochs for both regular and EMA models. ModelEma maintains an exponential moving average of model weights updated after each optimization step. At training end, the best overall checkpoint (regular or EMA) is copied to checkpoint_best_total.pth and stripped of optimizer state for efficient deployment.

Usage

Used internally by the training loop. The output checkpoint_best_total.pth is the recommended file for inference and deployment.

Code Reference

Source Location

• Repository: rf-detr
• File: rfdetr/util/utils.py
• Lines: L16-62 (ModelEma), L102-138 (BestMetricHolder)
• File: rfdetr/main.py
• Lines: L383-460 (checkpoint saving logic)

Signature

class ModelEma(torch.nn.Module):
    def __init__(
        self,
        model: torch.nn.Module,
        decay: float = 0.9997,
        tau: float = 0,
        device: Optional[torch.device] = None,
    ) -> None: ...

    def update(self, model: torch.nn.Module) -> None:
        """Update EMA weights with current model weights."""

class BestMetricHolder:
    def __init__(
        self,
        init_res: float = 0.0,
        better: str = 'large',
        use_ema: bool = False,
    ) -> None: ...

    def update(self, new_res: float, epoch: int, is_ema: bool = False) -> bool:
        """Update best metric. Returns True if new best."""

Import

from rfdetr.util.utils import ModelEma, BestMetricHolder

I/O Contract

Inputs

Name	Type	Required	Description
model	torch.nn.Module	Yes	Model to track EMA for
decay	float	No	EMA decay rate (default: 0.993)
tau	int	No	EMA warmup parameter (default: 100)
new_res	float	Yes	New metric value (mAP) to compare
epoch	int	Yes	Current epoch number

Outputs

Name	Type	Description
checkpoint_best_total.pth	File	Best overall model (regular or EMA), stripped of optimizer
checkpoint_best_regular.pth	File	Best regular model checkpoint
checkpoint_best_ema.pth	File	Best EMA model checkpoint
results.json	File	Per-class metrics from best epoch

Usage Examples

Checkpoint Files After Training

# After training completes, output directory contains:
# output/
#   checkpoint_best_total.pth    <- Use this for inference/deployment
#   checkpoint_best_regular.pth
#   checkpoint_best_ema.pth
#   checkpoint.pth               <- Latest epoch
#   results.json                 <- Per-class metrics
#   log.txt                      <- Training log

# Load best model for inference
from rfdetr import RFDETRBase
model = RFDETRBase(pretrain_weights="output/checkpoint_best_total.pth")

Related Pages

Implements Principle

• Principle:Roboflow_Rf_detr_Checkpoint_Management

Uses Heuristic

• Heuristic:Roboflow_Rf_detr_EMA_Best_Checkpoint_Strategy