altametris.sara.yolo.trainer

YOLO trainer implementation.

Provides training interface for YOLO models using Ultralytics backend with Altametris standardized callbacks and configuration.

Example

>>> model = YoloModel(version="11", task="detect", size="x")
>>> trainer = YoloTrainer(model=model, device="cuda")
>>> results = trainer.train(dataset_config="coco128.yaml", epochs=100)

Attributes

logger

Classes

YoloTrainer

YOLO trainer implementing BaseTrainer interface.

Module Contents

altametris.sara.yolo.trainer.logger
class altametris.sara.yolo.trainer.YoloTrainer(model: altametris.sara.yolo.model.YoloModel, device: str = 'auto', callbacks: list[altametris.sara.core.base_callback.BaseCallback] | None = None)

Bases: altametris.sara.core.base_trainer.BaseTrainer

YOLO trainer implementing BaseTrainer interface.

Wraps Ultralytics training with Altametris callback system and standardized configuration.

Parameters:

  • model – YOLO model to train

  • device – Training device

  • callbacks – Training callbacks

Example

>>> model = YoloModel(version="11", task="detect", size="n")
>>> trainer = YoloTrainer(model=model, device="cuda")
>>> results = trainer.train(
...     dataset_config="data.yaml",
...     epochs=100,
...     batch_size=16,
...     imgsz=640
... )
model: altametris.sara.yolo.model.YoloModel
_resolve_device_for_ultralytics() → str

Convert Altametris device format to Ultralytics-compatible format.

Ultralytics does not support ‘auto’ device. It requires explicit device specification: ‘cpu’, ‘0’, ‘1’, etc.

Conversion rules:

  • ‘auto’ -> ‘cpu’ (if no GPU) or ‘0’ (if GPU available)

  • ‘cuda’ -> ‘0’ (first GPU)

  • ‘cuda:0’ -> ‘0’ (extract GPU index)

  • ‘cpu’ -> ‘cpu’ (unchanged)

Returns:

Device string compatible with Ultralytics (e.g., ‘cpu’, ‘0’)

Note

This method checks actual GPU availability using torch.cuda.device_count() to avoid errors when CUDA is installed but no GPU is present.

_register_ultralytics_callbacks() → None

Bridge between Altametris callbacks and Ultralytics callbacks.

Registers hooks into Ultralytics training lifecycle that forward events to the Altametris callback manager. This ensures callbacks are triggered automatically during Ultralytics training.

Ultralytics hooks registered:

  • on_train_start: Called when training begins

  • on_train_epoch_end: Called after each training epoch

  • on_val_end: Called after validation

  • on_train_end: Called when training completes

Note

This method is called automatically during __init__. Manual callback invocations in train() are not needed.

load_config(config_path: str | pathlib.Path) → Dict[str, Any]

Load and parse YAML configuration file.

Supports both dataset configuration files (data.yaml) and training parameter files (train-params.yaml).

Parameters:

config_path – Path to YAML configuration file

Returns:

Dictionary containing parsed configuration

Raises:

TrainingError – If config file not found or invalid YAML

Example

>>> # Load dataset config
>>> dataset_config = trainer.load_config("data/detect/config.yml")
>>> print(dataset_config['names'])
{0: 'Chassis A', 1: 'Chassis C', ...}

>>> # Load training params
>>> train_params = trainer.load_config("data/detect/train-parameter-detect.yaml")
>>> epochs = train_params['train']['epochs']
train(dataset_config: str | pathlib.Path | Dict[str, Any], epochs: int = 100, batch_size: int = 16, imgsz: int = 640, save_dir: str | pathlib.Path | None = None, **kwargs: Any) → dict[str, Any]

Train YOLO model.

Parameters:

  • dataset_config – Path to dataset YAML configuration or dict

  • epochs – Number of training epochs

  • batch_size – Batch size

  • imgsz – Input image size

  • save_dir – Directory to save results

  • **kwargs – Additional Ultralytics training arguments

Returns:

Training results dictionary

Raises:

TrainingError – If training fails

Example

>>> # Using YAML path
>>> results = trainer.train(
...     dataset_config="data.yaml",
...     epochs=10,
...     batch_size=8,
...     imgsz=640
... )

>>> # Using dict config
>>> config = trainer.load_config("train-params.yaml")
>>> results = trainer.train(
...     dataset_config="data.yaml",
...     epochs=config['train']['epochs'],
...     batch_size=config['train']['batch_size']
... )
validate(dataset_config: str | pathlib.Path, **kwargs: Any) → dict[str, Any]

Validate YOLO model.

Parameters:

  • dataset_config – Path to validation dataset config

  • **kwargs – Additional validation arguments

Returns:

Validation metrics

Raises:

TrainingError – If validation fails

Example

>>> metrics = trainer.validate(dataset_config="val.yaml")
_extract_metrics(results: Any) → dict[str, Any]

Extract metrics from Ultralytics results.

Parameters:

results – Ultralytics training/validation results

Returns:

Dictionary of metrics

resume_training(checkpoint_path: str | pathlib.Path, **kwargs: Any) → dict[str, Any]

Resume training from checkpoint.

Parameters:

  • checkpoint_path – Path to checkpoint file

  • **kwargs – Additional training arguments

Returns:

Training results

Example

>>> results = trainer.resume_training("runs/train/exp/weights/last.pt")