DFINETraining
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 setInstallation
Install the published package using pip or uv.
pip install sinapsis-dfine==1.0.0uv pip install sinapsis-dfine==1.0.0uv add sinapsis-dfine==1.0.0Configuration
Effective fields from the inspector schema, including nested Pydantic model fields.
Optional
Default: "auto"
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.
Optional
Default: null
Optional
Default: null
Path to the directory where the fine-tuned model will be saved.
Required
Default: null
Required
Default: null
The target width and height for image resizing.
Optional
Default: null
The target width for resizing.
Optional
Default: 640
The target height for resizing.
Optional
Default: 640
Optional
Default: "ustc-community/dfine-nano-coco"
Path to the dataset to be loaded.
Required
Default: null
Parameters for the dataset preprocessing step.
Optional
Default: null
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).
Optional
Default: 0
The batch size for applying transformations. A larger size can speed up preprocessing but requires more RAM.
Optional
Default: 16
A nested configuration object for all Hugging Face `Trainer` hyperparameters.
Optional
Default: null
Optional
Default: false
Optional
Default: false
Optional
Default: 42
Optional
Default: "adamw_torch"
Optional
Default: -1
Optional
Default: "none"
Optional
Default: null
Optional
Default: null
Optional
Default: "trainer_output"
Optional
Default: 500
Optional
Default: 0
Optional
Default: 0
Optional
Default: 0
Optional
Default: "no"
Optional
Default: 0.00005
Optional
Default: 500
Optional
Default: 1
Optional
Default: "steps"
Optional
Default: "no"
Optional
Default: 3
Optional
Default: null
Optional
Default: null
Optional
Default: "linear"
Optional
Default: null
Optional
Default: false
Optional
Default: 0
Optional
Default: false
Optional
Default: false
Optional
Default: null
Optional
Default: null
Optional
Default: 8
Optional
Default: 1
Optional
Default: 8
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.
Optional
Default: "fine-tune"
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.
Optional
Default: null
The dictionary key for the bounding box area. If not provided, area will be calculated from the bbox. Defaults to "area".
Optional
Default: "area"
The dictionary key for the bounding box annotations. Defaults to "bbox".
Optional
Default: "bbox"
The dictionary key for the category/class label annotations. Defaults to "category".
Optional
Default: "category"
Optional
Default: "/home/ariel/.cache/sinapsis"
The proportion of the dataset to reserve for validation.
Optional
Default: 0.15
Configuration example
Example from the Python docstring:
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
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
sinapsis_dfine.templates.dfine_base.DFINEBaseEnvironment variables
Environment definitions belong to their canonical Python modules.