From ee2ac9e43491e5ca61a158fb3a42e621a6710ee1 Mon Sep 17 00:00:00 2001 From: artest08 <43647848+artest08@users.noreply.github.com> Date: Wed, 21 Jan 2026 18:16:20 +0300 Subject: [PATCH] Fix `multi_scale` range sampling and clarify docs (#23284) Co-authored-by: UltralyticsAssistant Co-authored-by: Ultralytics Assistant <135830346+UltralyticsAssistant@users.noreply.github.com> Co-authored-by: Laughing-q <1185102784@qq.com> --- docs/en/guides/model-training-tips.md | 4 +++- docs/en/guides/yolo-common-issues.md | 4 ++-- docs/macros/train-args.md | 2 +- docs/mkdocs_github_authors.yaml | 3 +++ ultralytics/cfg/default.yaml | 2 +- ultralytics/models/yolo/detect/train.py | 8 +++++--- 6 files changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/en/guides/model-training-tips.md b/docs/en/guides/model-training-tips.md index 38074d3b..35de6e0c 100644 --- a/docs/en/guides/model-training-tips.md +++ b/docs/en/guides/model-training-tips.md @@ -71,6 +71,8 @@ Multiscale training is a technique that improves your model's ability to general For example, when you train YOLO26, you can enable multiscale training by setting the `scale` parameter. This parameter adjusts the size of training images by a specified factor, simulating objects at different distances. For example, setting `scale=0.5` randomly zooms training images by a factor between 0.5 and 1.5 during training. Configuring this parameter allows your model to experience a variety of image scales and improve its detection capabilities across different object sizes and scenarios. +Ultralytics also supports image-size multi-scale training via the `multi_scale` parameter. Unlike `scale`, which zooms images and then pads/crops back to `imgsz`, `multi_scale` changes `imgsz` itself each batch (rounded to the model stride). For example, with `imgsz=640` and `multi_scale=0.25`, the training size is sampled from 480 up to 800 in stride steps (e.g., 480, 512, 544, ..., 800), while `multi_scale=0.0` keeps a fixed size. + ### Caching Caching is an important technique to improve the efficiency of training machine learning models. By storing preprocessed images in memory, caching reduces the time the GPU spends waiting for data to be loaded from the disk. The model can continuously receive data without delays caused by disk I/O operations. @@ -191,7 +193,7 @@ Mixed precision training utilizes both 16-bit (FP16) and 32-bit (FP32) floating- ### How does multiscale training enhance YOLO26 model performance? -Multiscale training enhances model performance by training on images of varying sizes, allowing the model to better generalize across different scales and distances. In YOLO26, you can enable multiscale training by setting the `scale` parameter in the training configuration. For example, `scale=0.5` reduces the image size by half, while `scale=2.0` doubles it. This technique simulates objects at different distances, making the model more robust across various scenarios. For settings and more details, check out the [training configuration](../modes/train.md). +Multiscale training enhances model performance by training on images of varying sizes, allowing the model to better generalize across different scales and distances. In YOLO26, you can enable multiscale training by setting the `scale` parameter in the training configuration. For example, `scale=0.5` samples a zoom factor between 0.5 and 1.5, then pads/crops back to `imgsz`. This technique simulates objects at different distances, making the model more robust across various scenarios. For settings and more details, check out the [training configuration](../modes/train.md). ### How can I use pretrained weights to speed up training in YOLO26? diff --git a/docs/en/guides/yolo-common-issues.md b/docs/en/guides/yolo-common-issues.md index 8fcab3c6..6143282c 100644 --- a/docs/en/guides/yolo-common-issues.md +++ b/docs/en/guides/yolo-common-issues.md @@ -92,7 +92,7 @@ This section will address common issues faced while training and their respectiv ```python # Adjust the batch size and other settings as needed to optimize training speed - model.train(data="/path/to/your/data.yaml", batch=32, multi_scale=True) + model.train(data="/path/to/your/data.yaml", batch=32) ``` #### Continuous Monitoring Parameters @@ -279,7 +279,7 @@ Installation errors can often be due to compatibility issues or missing dependen Training on a single GPU might be slow due to large batch sizes or insufficient memory. To speed up training, use multiple GPUs. Ensure your system has multiple GPUs available and adjust your `.yaml` configuration file to specify the number of GPUs, e.g., `gpus: 4`. Increase the batch size accordingly to fully utilize the GPUs without exceeding memory limits. Example command: ```python -model.train(data="/path/to/your/data.yaml", batch=32, multi_scale=True) +model.train(data="/path/to/your/data.yaml", batch=32) ``` ### How can I ensure my YOLO26 model is training on the GPU? diff --git a/docs/macros/train-args.md b/docs/macros/train-args.md index 31dfc54d..f8252abb 100644 --- a/docs/macros/train-args.md +++ b/docs/macros/train-args.md @@ -23,7 +23,7 @@ | `single_cls` | `bool` | `False` | Treats all classes in multi-class datasets as a single class during training. Useful for binary classification tasks or when focusing on object presence rather than classification. | | `classes` | `list[int]` | `None` | Specifies a list of class IDs to train on. Useful for filtering out and focusing only on certain classes during training. | | `rect` | `bool` | `False` | Enables minimum padding strategy—images in a batch are minimally padded to reach a common size, with the longest side equal to `imgsz`. Can improve efficiency and speed but may affect model accuracy. | -| `multi_scale` | `bool` | `False` | Enables multi-scale training by increasing/decreasing `imgsz` by up to a factor of `0.5` during training. Trains the model to be more accurate with multiple `imgsz` during inference. | +| `multi_scale` | `float` | `0.0` | Randomly vary `imgsz` each batch by +/- `multi_scale` (e.g. `0.25` -> `0.75x` to `1.25x`), rounding to model stride multiples; `0.0` disables multi-scale training. | | `cos_lr` | `bool` | `False` | Utilizes a cosine [learning rate](https://www.ultralytics.com/glossary/learning-rate) scheduler, adjusting the learning rate following a cosine curve over epochs. Helps in managing learning rate for better convergence. | | `close_mosaic` | `int` | `10` | Disables mosaic [data augmentation](https://www.ultralytics.com/glossary/data-augmentation) in the last N epochs to stabilize training before completion. Setting to 0 disables this feature. | | `resume` | `bool` | `False` | Resumes training from the last saved checkpoint. Automatically loads model weights, optimizer state, and epoch count, continuing training seamlessly. | diff --git a/docs/mkdocs_github_authors.yaml b/docs/mkdocs_github_authors.yaml index 2580315a..42397065 100644 --- a/docs/mkdocs_github_authors.yaml +++ b/docs/mkdocs_github_authors.yaml @@ -196,6 +196,9 @@ chr043416@gmail.com: davis.justin@mssm.org: avatar: https://avatars.githubusercontent.com/u/23462437?v=4 username: justincdavis +esat@ultralytics.com: + avatar: https://avatars.githubusercontent.com/u/43647848?v=4 + username: artest08 fatih@ultralytics.com: avatar: https://avatars.githubusercontent.com/u/34196005?v=4 username: fcakyon diff --git a/ultralytics/cfg/default.yaml b/ultralytics/cfg/default.yaml index ede10611..cb869a80 100644 --- a/ultralytics/cfg/default.yaml +++ b/ultralytics/cfg/default.yaml @@ -36,7 +36,7 @@ amp: True # (bool) Automatic Mixed Precision (AMP) training; True runs AMP capab fraction: 1.0 # (float) fraction of training dataset to use (1.0 = all) profile: False # (bool) profile ONNX/TensorRT speeds during training for loggers freeze: # (int | list, optional) freeze first N layers (int) or specific layer indices (list) -multi_scale: 0.0 # (float) multiscale training by varying image size +multi_scale: 0.0 # (float) multi-scale range as a fraction of imgsz; sizes are rounded to stride multiples compile: False # (bool | str) enable torch.compile() backend='inductor'; True="default", False=off, or "default|reduce-overhead|max-autotune-no-cudagraphs" # Segmentation diff --git a/ultralytics/models/yolo/detect/train.py b/ultralytics/models/yolo/detect/train.py index e61cb94d..074826b7 100644 --- a/ultralytics/models/yolo/detect/train.py +++ b/ultralytics/models/yolo/detect/train.py @@ -117,11 +117,13 @@ class DetectionTrainer(BaseTrainer): if isinstance(v, torch.Tensor): batch[k] = v.to(self.device, non_blocking=self.device.type == "cuda") batch["img"] = batch["img"].float() / 255 - multi_scale = self.args.multi_scale - if random.random() < multi_scale: + if self.args.multi_scale > 0.0: imgs = batch["img"] sz = ( - random.randrange(int(self.args.imgsz * 0.5), int(self.args.imgsz * 1 + self.stride)) + random.randrange( + int(self.args.imgsz * (1.0 - self.args.multi_scale)), + int(self.args.imgsz * (1.0 + self.args.multi_scale) + self.stride), + ) // self.stride * self.stride ) # size