weight of a sample

[max-dev-14]

I have heard that there is a technique to effectively train a model using an unbalanced dataset. The methodology is as follows:
Let's say there are two abstract categories: cats and dogs. But the number of cats is much less than the number of dogs (the case of an unbalanced dataset). You can set up the learning pipeline so that the sample weight is determined, which affects the gradient. For example, there are 100 cats and 10,000 dogs in the dataset. You indicate that the model should be more attentive to cats and change its weights faster than for dogs. It turns out that the model learns at different rates for different classes, since the model is more sensitive to errors in the cat category.
is this technique implemented in Ultralytics?

[UltralyticsAssistant]

👋 Hello @max-dev-14, thank you for your interest in Ultralytics 🚀! This is an automated response, and an Ultralytics engineer will also assist soon.

We recommend a visit to the Docs for new users where you can find many Python and CLI usage examples and where many of the most common questions may already be answered.

If this is a 🐛 Bug Report, please provide a minimum reproducible example to help us debug it.

If this is a custom training ❓ Question (like class imbalance / per-class sample weighting), please provide as much information as possible so we can point you to the right built-in options or recommended workflow, including dataset image examples and training logs, and verify you are following our Tips for Best Training Results.
Specifically helpful details:
-Which task/mode are you training (detect/segment/classify) and how are you launching training (Python or CLI from the Docs)?
-Your class counts (e.g., cats vs dogs) and a snippet of your dataset YAML
-Your training command/config and any logs that show the issue

Join the Ultralytics community where it suits you best 🙂. For real-time chat, head to Discord 🎧. Prefer in-depth discussions? Check out Discourse. Or dive into threads on our Subreddit to share knowledge with the community.

Upgrade

Upgrade to the latest ultralytics package including all requirements in a Python>=3.8 environment with PyTorch>=1.8 to verify your issue is not already resolved in the latest version:

pip install -U ultralytics

Environments

YOLO may be run in any of the following up-to-date verified environments (with all dependencies including CUDA/CUDNN, Python and PyTorch preinstalled):

• Notebooks with free GPU:
• Google Cloud Deep Learning VM. See GCP Quickstart Guide
• Amazon Deep Learning AMI. See AWS Quickstart Guide
• Docker Image. See Docker Quickstart Guide

Status

If this badge is green, all Ultralytics CI tests are currently passing. CI tests verify correct operation of all YOLO Modes and Tasks on macOS, Windows, and Ubuntu every 24 hours and on every commit.

[glenn-jocher]

Yes—Ultralytics already addresses class imbalance in detection primarily via loss re-weighting (e.g. FocalLoss / VarifocalLoss), which increases the gradient contribution from harder/rarer positives rather than treating every easy negative equally (see the loss implementations reference). If you specifically need explicit per-class/per-sample weighting or oversampling (your “cats get higher weight than dogs” example), that isn’t a single built-in training flag today, but you can implement it cleanly by customizing the trainer/dataloader (see Advanced Customization); let me know whether you’re training detect, segment, or classify and your class counts so we can point you to the best approach.

[max-dev-14]

My task is detection with 6 classes.

[Y-T-G]

You can try weighted dataloader:

https://y-t-g.github.io/tutorials/yolo-class-balancing/

[max-dev-14]

It looks interesting, thanks for the idea!

[glenn-jocher]

Glad it helps.

[max-dev-14]

Firstly, I'd like to thank for the idea with weighted dataloader. Nonetheless, I didn't quite put it exactly about my task (I'm sorry).
Here is a diagram that allows to understand better what I need.

Let's say, I have two videos with 2000 and 200 frames and each sample has a weight based on frames count. Train, val, test subsets include subfolders related to a corresponding video. So, the dataloader must know which video (i.e. which subfolder in the dataset) each sample belongs to. All the samples in the batch are fed to the model and the model predicts. Then the predictions are compared with the annotations and loss functions are computed. I need each loss function per sample must be multiplied by respective sample weight before averaging and feeding to back propagation process. Is it implemented in Ultralytics yet?

[glenn-jocher]

This exact “multiply each sample’s loss by a per-video weight before reduction” isn’t exposed as a built-in Ultralytics config option yet; to do it you’ll need a small customization where your dataset adds a weight field (based on the sample’s parent video/subfolder), and your model/trainer applies that weight inside the criterion before the final mean/sum (the supported hook for this is a custom model via init_criterion() as shown in the Advanced Customization guide and you can also attach/adjust fields in BaseTrainer.preprocess_batch() from the BaseTrainer reference). If you share which task you’re training (detect/segment/classify) and what batch keys you have right before loss, I can point you to the most appropriate place to apply the weighted reduction (the loss building blocks live in the loss reference).

[max-dev-14]

I'm working on a detection task. But I don't quite understand what batch keys you mean.

[glenn-jocher]

By “batch keys” I mean the fields in the Python dict produced by the dataloader and passed into the model loss; for detection it typically includes img, cls, bboxes, and batch_idx (where batch_idx tells you which image each label belongs to), as shown in the model loss reference. To see exactly what you have in your run (and whether you already get an im_file/path you can map back to a video subfolder), print batch.keys() once like this:

from ultralytics import YOLO
from ultralytics.models.yolo.detect import DetectionTrainer

class DebugTrainer(DetectionTrainer):
    def preprocess_batch(self, batch):
        batch = super().preprocess_batch(batch)
        if not hasattr(self, "_printed_batch"):
            self._printed_batch = True
            print("batch keys:", list(batch.keys()))
            for k, v in batch.items():
                print(k, getattr(v, "shape", type(v)))
        return batch

model = YOLO("yolo26n.pt")
model.train(data="your_dataset.yaml", epochs=1, trainer=DebugTrainer)

Paste the printed keys/output here (text, not a screenshot), and confirm whether your per-video weight should be per-image or per-label; that determines whether we index weights directly by image in the batch or expand via batch_idx (see the Detection task documentation for how detection batches are structured).

[max-dev-14]

batch keys: ['batch_idx', 'bboxes', 'cls', 'im_file', 'img', 'ori_shape', 'resized_shape']
batch_idx torch.Size([29])
bboxes torch.Size([29, 4])
cls torch.Size([29, 1])
im_file <class 'list'>
img torch.Size([4, 3, 640, 640])
ori_shape <class 'list'>
resized_shape <class 'list'>

Per-video weight should be per-image

[glenn-jocher]

Thanks—those keys are exactly what you need: im_file is a per-image list (length bs) that tells you which video/subfolder each image came from (it’s populated by the dataset) so you can derive a per-image weight directly from Path(im_file[i]).parent. See the YOLODataset reference for where im_file comes from. (docs.ultralytics.com)

The one catch is that detection loss isn’t naturally “per-image” internally (it’s accumulated over labels/assignments), so to get true per-image weighting you’d typically map image weights onto labels via batch_idx and apply the weights inside a custom criterion before the final reduction; if you’re OK with an equivalent effect in expectation, a simpler approach is to implement per-video weighted sampling (oversample frames from the short video) in a custom dataloader without touching loss.

If you paste 2–3 example im_file strings (as text) and your exact rule for converting “video frames count → weight”, I can point you to the cleanest place to inject that (sampler vs. custom criterion) for your setup.