Docs /Templates/ sinapsis-dfine

DFINETraining

sinapsis-dfineD-FINEdfineimageinferencemodels

Python template · sinapsis_dfine.templates.dfine_training

Overview

Fine-tunes a D-FINE object detection model on a custom dataset.

This template handles the entire training workflow: loading and preparing the dataset, configuring the model and processor, setting up the Hugging Face `Trainer`, running the training loop, and saving the resulting model.

Capabilities

Capabilities: not set

Installation

Install the published package using pip or uv.

Terminalbash
pip install sinapsis-dfine==1.0.0
uv pip install sinapsis-dfine==1.0.0
uv add sinapsis-dfine==1.0.0

Configuration

Effective fields from the inspector schema, including nested Pydantic model fields.

device
typing.Literal['auto', 'cuda', 'cpu']
Optional
Default: "auto"
id2label

An optional mapping from class ID to label name. It's recommended to let the template infer this from the dataset. This attribute should only be used as a fallback if the dataset features are non-standard and automatic inference fails. Defaults to None.

dict[int, str] | None
Optional
Default: null
metadata
sinapsis_core.template_base.base_models.TemplateMetadata | None
Optional
Default: null
save_dirRequired

Path to the directory where the fine-tuned model will be saved.

str
Required
Default: null
thresholdRequired
float
Required
Default: null
image_size

The target width and height for image resizing.

TrainingImageSize
Optional
Default: null
width

The target width for resizing.

int
Optional
Default: 640
height

The target height for resizing.

int
Optional
Default: 640
model_path
str
Optional
Default: "ustc-community/dfine-nano-coco"
dataset_pathRequired

Path to the dataset to be loaded.

str
Required
Default: null
mapping_args

Parameters for the dataset preprocessing step.

DatasetMappingArgs
Optional
Default: null
num_proc

The number of CPU processes to use for mapping. Set to > 1 for parallel processing, which can significantly reduce preprocessing time. Defaults to 0 (no multiprocessing).

int
Optional
Default: 0
batch_size

The batch size for applying transformations. A larger size can speed up preprocessing but requires more RAM.

int
Optional
Default: 16
training_args

A nested configuration object for all Hugging Face `Trainer` hyperparameters.

TrainingArgs
Optional
Default: null
bf16
bool
Optional
Default: false
fp16
bool
Optional
Default: false
seed
int
Optional
Default: 42
optim
str
Optional
Default: "adamw_torch"
max_steps
int
Optional
Default: -1
report_to
str | list[str]
Optional
Default: "none"
eval_delay
float | None
Optional
Default: null
eval_steps
int | float | None
Optional
Default: null
output_dir
str
Optional
Default: "trainer_output"
save_steps
int | float
Optional
Default: 500
warmup_ratio
float
Optional
Default: 0
warmup_steps
int
Optional
Default: 0
weight_decay
float
Optional
Default: 0
eval_strategy
typing.Literal['no', 'steps', 'epoch']
Optional
Default: "no"
learning_rate
float
Optional
Default: 0.00005
logging_steps
int | float
Optional
Default: 500
max_grad_norm
float
Optional
Default: 1
save_strategy
typing.Literal['no', 'steps', 'epoch', 'best']
Optional
Default: "steps"
logging_strategy
typing.Literal['no', 'steps', 'epoch']
Optional
Default: "no"
num_train_epochs
float
Optional
Default: 3
save_total_limit
int | None
Optional
Default: null
greater_is_better
bool | None
Optional
Default: null
lr_scheduler_type
str
Optional
Default: "linear"
metric_for_best_model
str | None
Optional
Default: null
remove_unused_columns
bool
Optional
Default: false
dataloader_num_workers
int
Optional
Default: 0
eval_do_concat_batches
bool
Optional
Default: false
load_best_model_at_end
bool
Optional
Default: false
resume_from_checkpoint
str | None
Optional
Default: null
eval_accumulation_steps
int | None
Optional
Default: null
per_device_eval_batch_size
int
Optional
Default: 8
gradient_accumulation_steps
int
Optional
Default: 1
per_device_train_batch_size
int
Optional
Default: 8
training_mode

Specifies the training strategy. `"fine-tune"` (default) loads pre-trained weights and adapts them to the new task. `"from-scratch"` initializes the model with random weights.

typing.Literal['fine-tune', 'from-scratch']
Optional
Default: "fine-tune"
annotation_keys

A configuration object that specifies the dictionary keys for accessing annotation data (e.g., 'bbox', 'category') within the dataset. This allows the template to adapt to different dataset schemas.

AnnotationKeys
Optional
Default: null
area

The dictionary key for the bounding box area. If not provided, area will be calculated from the bbox. Defaults to "area".

str
Optional
Default: "area"
bbox

The dictionary key for the bounding box annotations. Defaults to "bbox".

str
Optional
Default: "bbox"
category

The dictionary key for the category/class label annotations. Defaults to "category".

str
Optional
Default: "category"
model_cache_dir
str
Optional
Default: "/home/ariel/.cache/sinapsis"
validation_split_size

The proportion of the dataset to reserve for validation.

float
Optional
Default: 0.15

Configuration example

Example from the Python docstring:

yaml
agent:
      name: my_test_agent
    templates:
    - template_name: DFINETraining
        class_name: DFINETraining
        template_input: InputTemplate
        attributes:
        model_path: ustc-community/dfine-nano-coco
        threshold: 0.1
        device: cuda
        dataset_path: cppe-5
        mapping_args:
            batch_size: 64
            num_proc: 1
        image_size:
            width: 480
            height: 480
        training_args:
            output_dir: "outputs"
            num_train_epochs: 3
            max_grad_norm: 0.1
            learning_rate: 5e-5
            warmup_steps: 0
            per_device_train_batch_size: 1
            dataloader_num_workers: 0
            fp16: true
            metric_for_best_model: "eval_map"
            greater_is_better: true
            load_best_model_at_end: true
            eval_strategy: "epoch"
            save_strategy: "epoch"
            save_total_limit: 2
        save_dir: "cppe-5-dfine-nano"
Show schema-based configuration skeleton
yaml
templates:
  - template_name: "DFINETraining"
    class_name: "DFINETraining"
    attributes:
      device: "auto"
      id2label: null
      save_dir: "<required>"
      threshold: "<required>"
      image_size:
        width: 640
        height: 640
      model_path: "ustc-community/dfine-nano-coco"
      dataset_path: "<required>"
      mapping_args:
        num_proc: 0
        batch_size: 16
      training_args:
        bf16: false
        fp16: false
        seed: 42
        optim: "adamw_torch"
        max_steps: -1
        report_to: "none"
        eval_delay: null
        eval_steps: null
        output_dir: "trainer_output"
        save_steps: 500
        warmup_ratio: 0
        warmup_steps: 0
        weight_decay: 0
        eval_strategy: "no"
        learning_rate: 0.00005
        logging_steps: 500
        max_grad_norm: 1
        save_strategy: "steps"
        logging_strategy: "no"
        num_train_epochs: 3
        save_total_limit: null
        greater_is_better: null
        lr_scheduler_type: "linear"
        metric_for_best_model: null
        remove_unused_columns: false
        dataloader_num_workers: 0
        eval_do_concat_batches: false
        load_best_model_at_end: false
        resume_from_checkpoint: null
        eval_accumulation_steps: null
        per_device_eval_batch_size: 8
        gradient_accumulation_steps: 1
        per_device_train_batch_size: 8
      training_mode: "fine-tune"
      annotation_keys:
        area: "area"
        bbox: "bbox"
        category: "category"
      model_cache_dir: "/home/ariel/.cache/sinapsis"
      validation_split_size: 0.15

Inheritance

Immediate parent: sinapsis_dfine.templates.dfine_base.DFINEBase

Environment variables

Environment definitions belong to their canonical Python modules.

SINAPSIS_CACHE_DIR · defined elsewhere