Sinapsis Rfdetr
Train, evaluate and infer with RF-DETR detectors.
Overview
sinapsis-rfdetr — Training and inference templates based on the RF-DETR object detection model.
RF-DETR brings transformer-based detection into the same DataContainer contract as other Sinapsis vision components. This means a model can be swapped in a detection and tracking pipeline without rewriting the data-handling steps.
Where it fits
Choose it when its accuracy/latency characteristics match your workload; training and high-resolution inference can be GPU-intensive. Separate export and inference configs are provided.
Installation
Requires Python 3.13 or later, as declared in this package’s manifest. Install the base distribution using your preferred package manager:
uv pip install sinapsis-rfdetr
# or
pip install sinapsis-rfdetr
Optional features and dependencies
The base installation includes the dependencies required by the package. The following extras are declared in this package’s pyproject.toml; install only those needed by your workflow. They are standard Python optional dependencies, not separate execution profiles.
| Extra | Adds / when to select it |
|---|---|
all |
Bundle declared by this package; its manifest includes data-tools. |
data-tools |
Media readers/writers or data utilities for a complete pipeline. Dependencies: sinapsis-data-readers, sinapsis-data-visualization[all], sinapsis-data-writers[all] |
For example:
uv pip install "sinapsis-rfdetr[data-tools]"
The manifest also defines development-only dependency groups: dev (ruff, pre-commit). These support source development and testing and are not runtime extras.
🚀 Features
🗂️ Templates Supported
-
RFDETRExport and RFDETRLargeExport: Templates for exporting the RFDETRBase and RFDETRLarge models to ONNX format.
Attributes
model_params(Optional): A dictionary containing model parameters for initializing the RF-DETR model (default: None). The parameters inmodel_paramscan include:resolution: Defines the resolution of the input images. It must be divisible by 56.pretrain_weights: Specifies pretrained weights path for loading a fine-tuned model.num_classes: Specifies the number of classes for the model.
export_params(Optional): A dictionary containing the export parameters for the RF-DETR model (default: None). Key parameters that can be included inexport_paramsare:output_dir: The directory where the exported ONNX model will be saved (default:SINAPSIS_CACHE_DIR/rfdetr).
-
RFDETRInference and RFDETRLargeInference: Templates designed to perform inference on a set of images using the RFDETRBase and RFDETRLarge models.
Attributes
model_params(Optional): A dictionary containing model parameters for initializing the RF-DETR model (default: None). The parameters inmodel_paramscan include:resolution: Defines the resolution of the input images. It must be divisible by 56.pretrain_weights: Specifies pretrained weights path for loading a fine-tuned model.num_classes: Specifies the number of classes for the model.
annotations_path(Optional): The file path to a JSON file containing annotations (default: "").threshold(Required): A threshold for the confidence score used to filter the model's predictions (default: 0.5).
-
RFDETRTrain and RFDETRLargeTrain: Templates for training the RFDETRBase and RFDETRLarge models.
Attributes
model_params(Optional): A dictionary containing model parameters for initializing the RF-DETR model (default: None). The parameters inmodel_paramscan include:resolution: Defines the resolution of the input images. It must be divisible by 56.num_classes: Specifies the number of classes for the model.
callback(Required): Specifies the callback that will be used during training (default:on_fit_epoch_end).training_params(Required): A dictionary containing the training parameters for the RF-DETR model (default: None). The only required argument isdataset_dir, which is the path to the COCO-formatted dataset directory, includingtrain,valid, andtestfolders, each containing an_annotations.coco.jsonfile.
You can find the complete documentation for the available training parameters on the RF-DETR GitHub page.
For example, for RFDETRTrain use sinx templates example-config RFDETRTrain to produce an example config like:
agent:
name: my_sinapsis_rfdetr_agent
templates:
- template_name: InputTemplate
class_name: InputTemplate
attributes: {}
- template_name: RFDETRTrain
class_name: RFDETRTrain
template_input: InputTemplate
attributes:
model_params:
encoder: dinov2_windowed_small
out_feature_indexes:
- 2
- 5
- 8
- 11
dec_layers: 3
two_stage: true
projector_scale:
- P4
hidden_dim: 256
sa_nheads: 8
ca_nheads: 16
dec_n_points: 2
bbox_reparam: true
lite_refpoint_refine: true
layer_norm: true
amp: true
num_classes: 90
pretrain_weights: rf-detr-base.pth
device: cuda
resolution: 560
group_detr: 13
gradient_checkpointing: false
num_queries: 300
callback: on_fit_epoch_end
training_params:
lr: 0.0001
lr_encoder: 0.00015
batch_size: 4
grad_accum_steps: 4
epochs: 100
ema_decay: 0.993
ema_tau: 100
lr_drop: 100
checkpoint_interval: 10
warmup_epochs: 0
lr_vit_layer_decay: 0.8
lr_component_decay: 0.7
drop_path: 0.0
group_detr: 13
ia_bce_loss: true
cls_loss_coef: 1.0
num_select: 300
dataset_file: roboflow
square_resize_div_64: true
dataset_dir: 'path/to/dataset'
output_dir: output
multi_scale: true
expanded_scales: true
use_ema: true
num_workers: 2
weight_decay: 0.0001
early_stopping: false
early_stopping_patience: 10
early_stopping_min_delta: 0.001
early_stopping_use_ema: false
tensorboard: true
wandb: false
project: null
run: null
class_names: null
📈 Training the RF-DETR model
The RFDETRTrain and RFDETRLargeTrain templates in sinapsis-rfdetr simplify the process of training RF-DETR models using custom datasets. Here’s a breakdown of the training process and how to use the attributes effectively:
- Dataset Requirements: Your dataset must be in COCO format, split into three directories:
train,valid, andtest. Each directory should contain an_annotations.coco.jsonfile, which holds annotations for the respective subset, along with the corresponding image files.
The Roboflow Universe provides a diverse selection of pre-labeled datasets for various use cases. To access and download a dataset, simply create a free account account. Additionally, Roboflow allows you to create custom object detection datasets from scratch or convert existing datasets (e.g., YOLO) into COCO JSON format for training.
- Key Training Parameters: The following parameters in
training_paramshelp configure and fine-tune the training process:
dataset_dir: The path to the COCO-formatted dataset directory, containingtrain,valid, andtestfolders, each of which contains an_annotations.coco.jsonfile.epochs: Total number of training epochs.batch_size: The number of samples per training iteration. Adjust based on available GPU memory, and use it alongsidegrad_accum_stepsto maintain the intended effective batch size.grad_accum_steps: The number of mini-batches over which gradients are accumulated. This increases the total batch size without requiring additional memory, making it useful for GPUs with less VRAM.lr: Learning rate for optimization.resume: Allows resuming training from a saved checkpoint by specifying the checkpoint file path. This is helpful for continuing interrupted training or fine-tuning a previously trained model.early_stopping: Halts training when the model's validation performance (mAP) shows no improvement over a specified number of epochs. The stopping behavior can be adjusted using parameters likeearly_stopping_patience,early_stopping_min_delta, andearly_stopping_use_ema.
Note on memory usage: Adjust batch_size and grad_accum_steps according to GPU VRAM. For example:
- On powerful GPUs like the A100, you can use
batch_size=16andgrad_accum_steps=1. - On smaller GPUs like the T4, you may want to use
batch_size=4andgrad_accum_steps=4.
Detail documentation is available on the RF-DETR GitHub page.
-
Checkpoints: During training, two model checkpoints will be saved: one for regular weights (
checkpoint_best_regular.pth) and another for the Exponential Moving Average (EMA) of the model’s weights (checkpoint_best_total.pth), which helps improve stability and generalization. -
Using the Fine-Tuned Model: After training, load the fine-tuned model by setting the path to the pre-trained weights in
pretrain_weightswithin themodel_paramsargument. Use the RFDETRInference template to run predictions on images.
Example Agent
The following is adapted directly from the package’s shipped rfdetr_demo.yml configuration. Save it as my_rfdetr_agent.yaml. The example may require model checkpoints, input files, additional Template packages, or provider credentials as described in its configuration.
agent:
name: my_rfdetr_agent
description: Agent that runs inferences on images using the gradio interface
templates:
- template_name: InputTemplate
class_name: InputTemplate
attributes: {}
- template_name: RFDETRInference
class_name: RFDETRInference
template_input: InputTemplate
attributes:
threshold: 0.5
#annotations_path: datasets/COCO Dataset.v37i.coco/test/_annotations.coco.json
#model_params:
# pretrain_weights: checkpoint_best_total.pth
# num_classes: 78
- template_name: BBoxDrawer
class_name: BBoxDrawer
template_input: RFDETRInference
attributes:
randomized_color: false
sinx jobs run my_rfdetr_agent.yaml
More configurations: rfdetr_export.yml, rfdetr_train.yml, rfdetr_demo.yml, rfdetr_inference.yml, rfdetr_inference_trained.yml.
Documentation
License
Sinapsis open-source components are available under your choice of the MIT License or the Apache License 2.0, unless otherwise noted.
Metadata
Release files for sinapsis-rfdetr 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sinapsis_rfdetr-1.0.0.tar.gz | 174.2 kB | Without provenance | Details for sinapsis_rfdetr-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sinapsis_rfdetr-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for sinapsis_rfdetr-1.0.0-py3-none-any.whl |
Total release size: 198.3 kB
Release files / sinapsis_rfdetr-1.0.0.tar.gz
| Download URL | sinapsis_rfdetr-1.0.0.tar.gz |
|---|---|
| Size | 174.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0de045f8cc7504a235f29b0c1954f35ce272f88c7c5a92395a9f5c7ba33d98c6
|
|
BLAKE2b-256 checksum How to use checksums |
6e35949daa4c5b956440ed098c2c7ec90f3dda4a27990232f4017ceb5ea00e71
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.17
|
Release files / sinapsis_rfdetr-1.0.0-py3-none-any.whl
| Download URL | sinapsis_rfdetr-1.0.0-py3-none-any.whl |
|---|---|
| Size | 24.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
eed670daef145f3dc91574b465abfea65b9137a3fcd1d847b09e7574449092df
|
|
BLAKE2b-256 checksum How to use checksums |
2b1c48d76b397531fb8cf791aa2c14de013112f2eb45f0b4cbf8ed5f44fc9e25
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.17
|
Security for sinapsis-rfdetr 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.