Reference for ultralytics/models/yolo/classify/train.py#

class ClassificationTrainer(BaseTrainer):
    """A trainer class extending BaseTrainer for training image classification models.

    This trainer handles image classification with YOLO models and TorchVision backbones configured in model YAMLs,
    including dataset handling and validation.

    Attributes:
        model (ClassificationModel): The classification model to be trained.
        data (dict[str, Any]): Dictionary containing dataset information including class names and number of classes.
        loss_names (tuple): Names of the loss items, derived from the loss dict returned by the criterion.
        validator (ClassificationValidator): Validator instance for model evaluation.

    Methods:
        set_model_attributes: Set the model's class names from the loaded dataset.
        get_model: Return a modified PyTorch model configured for training.
        setup_model: Load, create or download model for classification.
        build_dataset: Create a ClassificationDataset instance.
        get_dataloader: Return PyTorch DataLoader with transforms for image preprocessing.
        preprocess_batch: Preprocess a batch of images and classes.
        progress_string: Return a formatted string showing training progress.
        get_validator: Return an instance of ClassificationValidator.
        plot_training_samples: Plot training samples with their annotations.

    Examples:
        Initialize and train a classification model
        >>> from ultralytics.models.yolo.classify import ClassificationTrainer
        >>> args = dict(model="yolo26n-cls.pt", data="imagenet10", epochs=3)
        >>> trainer = ClassificationTrainer(overrides=args)
        >>> trainer.train()
    """

    def __init__(self, cfg=DEFAULT_CFG, overrides: dict[str, Any] | None = None, _callbacks: dict | None = None):
        """Initialize a ClassificationTrainer object.

        Args:
            cfg (dict[str, Any], optional): Default configuration dictionary containing training parameters.
            overrides (dict[str, Any], optional): Dictionary of parameter overrides for the default configuration.
            _callbacks (dict, optional): Dictionary of callback functions to be executed during training.
        """
        if overrides is None:
            overrides = {}
        overrides["task"] = "classify"
        overrides["multi_scale"] = 0.0  # classification batches are never rescaled
        if overrides.get("imgsz") is None and not overrides.get("resume"):
            overrides["imgsz"] = 224
        super().__init__(cfg, overrides, _callbacks)

def build_dataset(self, img_path: str, mode: str = "train", batch=None):
    """Create a ClassificationDataset instance given an image path and mode.

    Args:
        img_path (str): Path to the dataset images.
        mode (str, optional): Dataset mode ('train', 'val', or 'test').
        batch (Any, optional): Batch information (unused in this implementation).

    Returns:
        (ClassificationDataset): Dataset for the specified mode.
    """
    return ClassificationDataset(
        img_path,
        self.args,
        augment=mode == "train",
        prefix="train" if mode == "train" else self.args.split,
        names=self.data["names"],
    )

def get_dataloader(self, dataset_path: str, batch_size: int = 16, rank: int = 0, mode: str = "train"):
    """Return PyTorch DataLoader with transforms to preprocess images.

    Args:
        dataset_path (str): Path to the dataset.
        batch_size (int, optional): Number of images per batch.
        rank (int, optional): Process rank for distributed training.
        mode (str, optional): 'train', 'val', or 'test' mode.

    Returns:
        (torch.utils.data.DataLoader): DataLoader for the specified dataset and mode.
    """
    with torch_distributed_zero_first(rank):  # init dataset *.cache only once if DDP
        dataset = self.build_dataset(dataset_path, mode)

    if not dataset.samples:
        raise FileNotFoundError(
            f"No images found in '{mode}' split of {dataset_path}. "
            f"See https://docs.ultralytics.com/datasets/classify for cls dataset format."
        )

    drop_last = self.args.compile and mode == "train"
    loader = build_dataloader(
        dataset, batch_size, self.args.workers, rank=rank, drop_last=drop_last, device=self.device
    )
    # Attach inference transforms
    if mode != "train":
        if is_parallel(self.model):
            self.model.module.transforms = loader.dataset.torch_transforms
        else:
            self.model.transforms = loader.dataset.torch_transforms
    return loader

def get_model(self, cfg: str | dict | None = None, weights: torch.nn.Module | None = None, verbose: bool = True):
    """Return a modified PyTorch model configured for training YOLO classification.

    Args:
        cfg (str | dict, optional): Model configuration file path or dictionary.
        weights (torch.nn.Module, optional): Pretrained model whose weights are loaded into the new model.
        verbose (bool, optional): Whether to display model information.

    Returns:
        (ClassificationModel): Configured PyTorch model for classification.
    """
    model = ClassificationModel(cfg, nc=self.data["nc"], ch=self.data["channels"], verbose=verbose and RANK == -1)
    if weights:
        model.load(weights)

    for m in model.modules():
        if self.args.pretrained is False and not self.resume and hasattr(m, "reset_parameters"):
            m.reset_parameters()
        if isinstance(m, torch.nn.Dropout) and self.args.dropout:
            m.p = self.args.dropout  # set dropout
    for p in model.parameters():
        p.requires_grad = True  # for training
    return model

def get_validator(self):
    """Return an instance of ClassificationValidator for validation."""
    return yolo.classify.ClassificationValidator(
        self.test_loader, self.save_dir, args=copy(self.args), _callbacks=self.callbacks
    )

def plot_training_samples(self, batch: dict[str, torch.Tensor], ni: int):
    """Plot training samples with their annotations.

    Args:
        batch (dict[str, torch.Tensor]): Batch containing images and class labels.
        ni (int): Batch index used for naming the output file.
    """
    batch["batch_idx"] = torch.arange(batch["img"].shape[0])  # add batch index for plotting
    plot_images(
        labels=batch,
        fname=self.save_dir / f"train_batch{ni}.jpg",
        on_plot=self.on_plot,
    )

def preprocess_batch(self, batch: dict[str, torch.Tensor]) -> dict[str, torch.Tensor]:
    """Preprocess a batch of images and classes."""
    batch["img"] = batch["img"].to(self.device, non_blocking=self.device.type not in {"cpu", "mps"})
    batch["cls"] = batch["cls"].to(self.device, non_blocking=self.device.type not in {"cpu", "mps"})
    return batch

def progress_string(self) -> str:
    """Return a formatted string showing training progress."""
    return ("\n" + "%11s" * (4 + len(self.loss_names))) % (
        "Epoch",
        "GPU_mem",
        *self.loss_names,
        "Instances",
        "Size",
    )

def set_model_attributes(self):
    """Set the YOLO model's class names from the loaded dataset."""
    self.model.names = self.data["names"]

def setup_model(self):
    """Load, create or download model for classification tasks.

    Returns:
        (Any): Model checkpoint if applicable, otherwise None.
    """
    ckpt = super().setup_model()
    ClassificationModel.reshape_outputs(self.model, self.data["nc"])
    return ckpt