diff --git a/README.md b/README.md index a8da7684f..0f266e8d2 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,15 @@ +Ultralytics logo +

- - Ultralytics YOLO banner + + Ultralytics YOLOv8 banner

[中文](https://docs.ultralytics.com/zh) | [한국어](https://docs.ultralytics.com/ko) | [日本語](https://docs.ultralytics.com/ja) | [Русский](https://docs.ultralytics.com/ru) | [Deutsch](https://docs.ultralytics.com/de) | [Français](https://docs.ultralytics.com/fr) | [Español](https://docs.ultralytics.com/es) | [Português](https://docs.ultralytics.com/pt) | [Türkçe](https://docs.ultralytics.com/tr) | [Tiếng Việt](https://docs.ultralytics.com/vi) | [العربية](https://docs.ultralytics.com/ar)
- YOLOv5 CI + YOLOv5 CI Testing YOLOv5 Citation Docker Pulls Discord Ultralytics Forums Ultralytics Reddit @@ -18,11 +20,11 @@

-YOLOv5 🚀 is the world's most loved vision AI, representing Ultralytics open-source research into future vision AI methods, incorporating lessons learned and best practices evolved over thousands of hours of research and development. +Ultralytics YOLOv5 🚀 is a cutting-edge, state-of-the-art (SOTA) computer vision model developed by [Ultralytics](https://www.ultralytics.com/). Based on the PyTorch framework, YOLOv5 is renowned for its ease of use, speed, and accuracy. It incorporates insights and best practices from extensive research and development, making it a popular choice for a wide range of vision AI tasks, including [object detection](https://docs.ultralytics.com/tasks/detect/), [image segmentation](https://docs.ultralytics.com/tasks/segment/), and [image classification](https://docs.ultralytics.com/tasks/classify/). -We hope that the resources here will help you get the most out of YOLOv5. Please browse the YOLOv5 Docs for details, raise an issue on GitHub for support, and join our Discord community for questions and discussions! +We hope the resources here help you get the most out of YOLOv5. Please browse the [YOLOv5 Docs](https://docs.ultralytics.com/yolov5/) for detailed information, raise an issue on [GitHub](https://github.com/ultralytics/yolov5/issues/new/choose) for support, and join our [Discord community](https://discord.com/invite/ultralytics) for questions and discussions! -To request an Enterprise License please complete the form at [Ultralytics Licensing](https://www.ultralytics.com/license). +To request an Enterprise License, please complete the form at [Ultralytics Licensing](https://www.ultralytics.com/license).
Ultralytics GitHub @@ -43,59 +45,67 @@ To request an Enterprise License please complete the form at [Ultralytics Licens

-##
YOLO11 🚀 NEW
+## 🚀 YOLO11: The Next Evolution -We are excited to unveil the launch of Ultralytics YOLO11 🚀, the latest advancement in our state-of-the-art (SOTA) vision models! Available now at **[GitHub](https://github.com/ultralytics/ultralytics)**, YOLO11 builds on our legacy of speed, precision, and ease of use. Whether you're tackling object detection, image segmentation, or image classification, YOLO11 delivers the performance and versatility needed to excel in diverse applications. +We are excited to announce the launch of **Ultralytics YOLO11** 🚀, the latest advancement in our state-of-the-art (SOTA) vision models! Available now at the [Ultralytics YOLO GitHub repository](https://github.com/ultralytics/ultralytics), YOLO11 builds on our legacy of speed, precision, and ease of use. Whether you're tackling [object detection](https://docs.ultralytics.com/tasks/detect/), [instance segmentation](https://docs.ultralytics.com/tasks/segment/), [pose estimation](https://docs.ultralytics.com/tasks/pose/), [image classification](https://docs.ultralytics.com/tasks/classify/), or [oriented object detection (OBB)](https://docs.ultralytics.com/tasks/obb/), YOLO11 delivers the performance and versatility needed to excel in diverse applications. Get started today and unlock the full potential of YOLO11! Visit the [Ultralytics Docs](https://docs.ultralytics.com/) for comprehensive guides and resources: [![PyPI version](https://badge.fury.io/py/ultralytics.svg)](https://badge.fury.io/py/ultralytics) [![Downloads](https://static.pepy.tech/badge/ultralytics)](https://www.pepy.tech/projects/ultralytics) ```bash +# Install the ultralytics package pip install ultralytics ```
- + Ultralytics YOLO Performance Comparison
-##
Documentation
+## 📚 Documentation -See the [YOLOv5 Docs](https://docs.ultralytics.com/yolov5/) for full documentation on training, testing and deployment. See below for quickstart examples. +See the [YOLOv5 Docs](https://docs.ultralytics.com/yolov5/) for full documentation on training, testing, and deployment. See below for quickstart examples.
Install -Clone repo and install [requirements.txt](https://github.com/ultralytics/yolov5/blob/master/requirements.txt) in a [**Python>=3.8.0**](https://www.python.org/) environment, including [**PyTorch>=1.8**](https://pytorch.org/get-started/locally/). +Clone the repository and install dependencies from [requirements.txt](https://github.com/ultralytics/yolov5/blob/master/requirements.txt) in a [**Python>=3.8.0**](https://www.python.org/) environment. Ensure you have [**PyTorch>=1.8**](https://pytorch.org/get-started/locally/) installed. ```bash -git clone https://github.com/ultralytics/yolov5 # clone +# Clone the YOLOv5 repository +git clone https://github.com/ultralytics/yolov5 + +# Navigate to the cloned directory cd yolov5 -pip install -r requirements.txt # install + +# Install required packages +pip install -r requirements.txt ```
-Inference +Inference with PyTorch Hub -YOLOv5 [PyTorch Hub](https://docs.ultralytics.com/yolov5/tutorials/pytorch_hub_model_loading/) inference. [Models](https://github.com/ultralytics/yolov5/tree/master/models) download automatically from the latest YOLOv5 [release](https://github.com/ultralytics/yolov5/releases). +Use YOLOv5 via [PyTorch Hub](https://docs.ultralytics.com/yolov5/tutorials/pytorch_hub_model_loading/) for inference. [Models](https://github.com/ultralytics/yolov5/tree/master/models) are automatically downloaded from the latest YOLOv5 [release](https://github.com/ultralytics/yolov5/releases). ```python import torch -# Load YOLOv5 model (options: yolov5n, yolov5s, yolov5m, yolov5l, yolov5x) -model = torch.hub.load("ultralytics/yolov5", "yolov5s") +# Load a YOLOv5 model (options: yolov5n, yolov5s, yolov5m, yolov5l, yolov5x) +model = torch.hub.load("ultralytics/yolov5", "yolov5s") # Default: yolov5s -# Input source (URL, file, PIL, OpenCV, numpy array, or list) -img = "https://ultralytics.com/images/zidane.jpg" +# Define the input image source (URL, local file, PIL image, OpenCV frame, numpy array, or list) +img = "https://ultralytics.com/images/zidane.jpg" # Example image -# Perform inference (handles batching, resizing, normalization) +# Perform inference (handles batching, resizing, normalization automatically) results = model(img) -# Process results (options: .print(), .show(), .save(), .crop(), .pandas()) -results.print() +# Process the results (options: .print(), .show(), .save(), .crop(), .pandas()) +results.print() # Print results to console +results.show() # Display results in a window +results.save() # Save results to runs/detect/exp ```
@@ -103,19 +113,38 @@ results.print()
Inference with detect.py -`detect.py` runs inference on a variety of sources, downloading [models](https://github.com/ultralytics/yolov5/tree/master/models) automatically from the latest YOLOv5 [release](https://github.com/ultralytics/yolov5/releases) and saving results to `runs/detect`. +The `detect.py` script runs inference on various sources. It automatically downloads [models](https://github.com/ultralytics/yolov5/tree/master/models) from the latest YOLOv5 [release](https://github.com/ultralytics/yolov5/releases) and saves the results to the `runs/detect` directory. ```bash -python detect.py --weights yolov5s.pt --source 0 # webcam -python detect.py --weights yolov5s.pt --source img.jpg # image -python detect.py --weights yolov5s.pt --source vid.mp4 # video -python detect.py --weights yolov5s.pt --source screen # screenshot -python detect.py --weights yolov5s.pt --source path/ # directory -python detect.py --weights yolov5s.pt --source list.txt # list of images -python detect.py --weights yolov5s.pt --source list.streams # list of streams -python detect.py --weights yolov5s.pt --source 'path/*.jpg' # glob -python detect.py --weights yolov5s.pt --source 'https://youtu.be/LNwODJXcvt4' # YouTube -python detect.py --weights yolov5s.pt --source 'rtsp://example.com/media.mp4' # RTSP, RTMP, HTTP stream +# Run inference using a webcam +python detect.py --weights yolov5s.pt --source 0 + +# Run inference on a local image file +python detect.py --weights yolov5s.pt --source img.jpg + +# Run inference on a local video file +python detect.py --weights yolov5s.pt --source vid.mp4 + +# Run inference on a screen capture +python detect.py --weights yolov5s.pt --source screen + +# Run inference on a directory of images +python detect.py --weights yolov5s.pt --source path/to/images/ + +# Run inference on a text file listing image paths +python detect.py --weights yolov5s.pt --source list.txt + +# Run inference on a text file listing stream URLs +python detect.py --weights yolov5s.pt --source list.streams + +# Run inference using a glob pattern for images +python detect.py --weights yolov5s.pt --source 'path/to/*.jpg' + +# Run inference on a YouTube video URL +python detect.py --weights yolov5s.pt --source 'https://youtu.be/LNwODJXcvt4' + +# Run inference on an RTSP, RTMP, or HTTP stream +python detect.py --weights yolov5s.pt --source 'rtsp://example.com/media.mp4' ```
@@ -123,49 +152,58 @@ python detect.py --weights yolov5s.pt --source 'rtsp://example.com/media.mp4' #
Training -The commands below reproduce YOLOv5 [COCO](https://github.com/ultralytics/yolov5/blob/master/data/scripts/get_coco.sh) results. [Models](https://github.com/ultralytics/yolov5/tree/master/models) and [datasets](https://github.com/ultralytics/yolov5/tree/master/data) download automatically from the latest YOLOv5 [release](https://github.com/ultralytics/yolov5/releases). Training times for YOLOv5n/s/m/l/x are 1/2/4/6/8 days on a V100 GPU ([Multi-GPU](https://docs.ultralytics.com/yolov5/tutorials/multi_gpu_training/) times faster). Use the largest `--batch-size` possible, or pass `--batch-size -1` for YOLOv5 [AutoBatch](https://github.com/ultralytics/yolov5/pull/5092). Batch sizes shown for V100-16GB. +The commands below demonstrate how to reproduce YOLOv5 [COCO dataset](https://docs.ultralytics.com/datasets/detect/coco/) results. Both [models](https://github.com/ultralytics/yolov5/tree/master/models) and [datasets](https://github.com/ultralytics/yolov5/tree/master/data) are downloaded automatically from the latest YOLOv5 [release](https://github.com/ultralytics/yolov5/releases). Training times for YOLOv5n/s/m/l/x are approximately 1/2/4/6/8 days on a single V100 GPU. Using [Multi-GPU training](https://docs.ultralytics.com/yolov5/tutorials/multi_gpu_training/) can significantly reduce training time. Use the largest `--batch-size` your hardware allows, or use `--batch-size -1` for YOLOv5 [AutoBatch](https://github.com/ultralytics/yolov5/pull/5092). The batch sizes shown below are for V100-16GB GPUs. ```bash +# Train YOLOv5n on COCO for 300 epochs python train.py --data coco.yaml --epochs 300 --weights '' --cfg yolov5n.yaml --batch-size 128 + +# Train YOLOv5s on COCO for 300 epochs python train.py --data coco.yaml --epochs 300 --weights '' --cfg yolov5s.yaml --batch-size 64 + +# Train YOLOv5m on COCO for 300 epochs python train.py --data coco.yaml --epochs 300 --weights '' --cfg yolov5m.yaml --batch-size 40 + +# Train YOLOv5l on COCO for 300 epochs python train.py --data coco.yaml --epochs 300 --weights '' --cfg yolov5l.yaml --batch-size 24 + +# Train YOLOv5x on COCO for 300 epochs python train.py --data coco.yaml --epochs 300 --weights '' --cfg yolov5x.yaml --batch-size 16 ``` - +YOLOv5 Training Results
Tutorials -- [Train Custom Data](https://docs.ultralytics.com/yolov5/tutorials/train_custom_data/) 🚀 RECOMMENDED -- [Tips for Best Training Results](https://docs.ultralytics.com/guides/model-training-tips/) ☘️ -- [Multi-GPU Training](https://docs.ultralytics.com/yolov5/tutorials/multi_gpu_training/) -- [PyTorch Hub](https://docs.ultralytics.com/yolov5/tutorials/pytorch_hub_model_loading/) 🌟 NEW -- [TFLite, ONNX, CoreML, TensorRT Export](https://docs.ultralytics.com/yolov5/tutorials/model_export/) 🚀 -- [NVIDIA Jetson platform Deployment](https://docs.ultralytics.com/yolov5/tutorials/running_on_jetson_nano/) 🌟 NEW -- [Test-Time Augmentation (TTA)](https://docs.ultralytics.com/yolov5/tutorials/test_time_augmentation/) -- [Model Ensembling](https://docs.ultralytics.com/yolov5/tutorials/model_ensembling/) -- [Model Pruning/Sparsity](https://docs.ultralytics.com/yolov5/tutorials/model_pruning_and_sparsity/) -- [Hyperparameter Evolution](https://docs.ultralytics.com/yolov5/tutorials/hyperparameter_evolution/) -- [Transfer Learning with Frozen Layers](https://docs.ultralytics.com/yolov5/tutorials/transfer_learning_with_frozen_layers/) -- [Architecture Summary](https://docs.ultralytics.com/yolov5/tutorials/architecture_description/) 🌟 NEW -- [Ultralytics HUB to train and deploy YOLO](https://www.ultralytics.com/hub) 🚀 RECOMMENDED -- [ClearML Logging](https://docs.ultralytics.com/yolov5/tutorials/clearml_logging_integration/) -- [YOLOv5 with Neural Magic's Deepsparse](https://docs.ultralytics.com/yolov5/tutorials/neural_magic_pruning_quantization/) -- [Comet Logging](https://docs.ultralytics.com/yolov5/tutorials/comet_logging_integration/) 🌟 NEW +- **[Train Custom Data](https://docs.ultralytics.com/yolov5/tutorials/train_custom_data/)** 🚀 **RECOMMENDED**: Learn how to train YOLOv5 on your own datasets. +- **[Tips for Best Training Results](https://docs.ultralytics.com/guides/model-training-tips/)** ☘️: Improve your model's performance with expert tips. +- **[Multi-GPU Training](https://docs.ultralytics.com/yolov5/tutorials/multi_gpu_training/)**: Speed up training using multiple GPUs. +- **[PyTorch Hub Integration](https://docs.ultralytics.com/yolov5/tutorials/pytorch_hub_model_loading/)** 🌟 **NEW**: Easily load models using PyTorch Hub. +- **[Model Export (TFLite, ONNX, CoreML, TensorRT)](https://docs.ultralytics.com/yolov5/tutorials/model_export/)** 🚀: Convert your models to various deployment formats. +- **[NVIDIA Jetson Deployment](https://docs.ultralytics.com/yolov5/tutorials/running_on_jetson_nano/)** 🌟 **NEW**: Deploy YOLOv5 on NVIDIA Jetson devices. +- **[Test-Time Augmentation (TTA)](https://docs.ultralytics.com/yolov5/tutorials/test_time_augmentation/)**: Enhance prediction accuracy with TTA. +- **[Model Ensembling](https://docs.ultralytics.com/yolov5/tutorials/model_ensembling/)**: Combine multiple models for better performance. +- **[Model Pruning/Sparsity](https://docs.ultralytics.com/yolov5/tutorials/model_pruning_and_sparsity/)**: Optimize models for size and speed. +- **[Hyperparameter Evolution](https://docs.ultralytics.com/yolov5/tutorials/hyperparameter_evolution/)**: Automatically find the best training hyperparameters. +- **[Transfer Learning with Frozen Layers](https://docs.ultralytics.com/yolov5/tutorials/transfer_learning_with_frozen_layers/)**: Adapt pretrained models to new tasks efficiently. +- **[Architecture Summary](https://docs.ultralytics.com/yolov5/tutorials/architecture_description/)** 🌟 **NEW**: Understand the YOLOv5 model architecture. +- **[Ultralytics HUB Training](https://www.ultralytics.com/hub)** 🚀 **RECOMMENDED**: Train and deploy YOLO models using Ultralytics HUB. +- **[ClearML Logging](https://docs.ultralytics.com/yolov5/tutorials/clearml_logging_integration/)**: Integrate with ClearML for experiment tracking. +- **[Neural Magic DeepSparse Integration](https://docs.ultralytics.com/yolov5/tutorials/neural_magic_pruning_quantization/)**: Accelerate inference with DeepSparse. +- **[Comet Logging](https://docs.ultralytics.com/yolov5/tutorials/comet_logging_integration/)** 🌟 **NEW**: Log experiments using Comet ML.
-##
Integrations
+## 🛠️ Integrations -Our key integrations with leading AI platforms extend the functionality of Ultralytics' offerings, enhancing tasks like dataset labeling, training, visualization, and model management. Discover how Ultralytics, in collaboration with [W&B](https://docs.wandb.ai/guides/integrations/ultralytics/), [Comet](https://bit.ly/yolov8-readme-comet), [Roboflow](https://roboflow.com/?ref=ultralytics) and [OpenVINO](https://docs.ultralytics.com/integrations/openvino/), can optimize your AI workflow. +Explore Ultralytics' key integrations with leading AI platforms. These collaborations enhance capabilities for dataset labeling, training, visualization, and model management. Discover how Ultralytics works with [Weights & Biases (W&B)](https://docs.wandb.ai/guides/integrations/ultralytics/), [Comet ML](https://bit.ly/yolov5-readme-comet), [Roboflow](https://roboflow.com/?ref=ultralytics), and [Intel OpenVINO](https://docs.ultralytics.com/integrations/openvino/) to optimize your AI workflows.
-Ultralytics active learning integrations +Ultralytics Active Learning Integrations Banner

@@ -174,49 +212,51 @@ Our key integrations with leading AI platforms extend the functionality of Ultra Ultralytics HUB logo space - ClearML logo + Weights & Biases logo space - + Comet ML logo space - NeuralMagic logo + Neural Magic logo
| Ultralytics HUB 🚀 | W&B | Comet ⭐ NEW | Neural Magic | | :--------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------: | -| Streamline YOLO workflows: Label, train, and deploy effortlessly with [Ultralytics HUB](https://www.ultralytics.com/hub). Try now! | Track experiments, hyperparameters, and results with [Weights & Biases](https://docs.wandb.ai/guides/integrations/ultralytics/) | Free forever, [Comet](https://bit.ly/yolov5-readme-comet) lets you save YOLOv5 models, resume training, and interactively visualize and debug predictions | Run YOLO11 inference up to 6x faster with [Neural Magic DeepSparse](https://bit.ly/yolov5-neuralmagic) | +| Streamline YOLO workflows: Label, train, and deploy effortlessly with [Ultralytics HUB](https://www.ultralytics.com/hub). Try now! | Track experiments, hyperparameters, and results seamlessly with [Weights & Biases](https://docs.wandb.ai/guides/integrations/ultralytics/). | Free forever, [Comet](https://bit.ly/yolov5-readme-comet) lets you save YOLOv5 models, resume training, and interactively visualize and debug predictions. | Run YOLOv5 inference up to 6x faster on CPUs with [Neural Magic DeepSparse](https://bit.ly/yolov5-neuralmagic). | -##
Ultralytics HUB
+## ⭐ Ultralytics HUB -Experience seamless AI with [Ultralytics HUB](https://www.ultralytics.com/hub) ⭐, the all-in-one solution for data visualization, YOLOv5 and YOLOv8 🚀 model training and deployment, without any coding. Transform images into actionable insights and bring your AI visions to life with ease using our cutting-edge platform and user-friendly [Ultralytics App](https://www.ultralytics.com/app-install). Start your journey for **Free** now! +Experience seamless AI development with [Ultralytics HUB](https://www.ultralytics.com/hub) ⭐, the ultimate platform for building, training, and deploying computer vision models. Visualize datasets, train YOLOv5 and YOLOv8 🚀 models, and deploy them to real-world applications without writing any code. Transform images into actionable insights using our cutting-edge tools and user-friendly [Ultralytics App](https://www.ultralytics.com/app-install). Start your journey for **Free** today! - +Ultralytics HUB Platform Screenshot -##
Why YOLOv5
+## 🤔 Why YOLOv5? -YOLOv5 has been designed to be super easy to get started and simple to learn. We prioritize real-world results. +YOLOv5 is designed for simplicity and ease of use. We prioritize real-world performance and accessibility. -

+

YOLOv5 Performance Chart

YOLOv5-P5 640 Figure -

+

YOLOv5 P5 640 Performance Chart

Figure Notes -- **COCO AP val** denotes mAP@0.5:0.95 metric measured on the 5000-image [COCO val2017](http://cocodataset.org) dataset over various inference sizes from 256 to 1536. -- **GPU Speed** measures average inference time per image on [COCO val2017](http://cocodataset.org) dataset using a [AWS p3.2xlarge](https://aws.amazon.com/ec2/instance-types/p4/) V100 instance at batch-size 32. -- **EfficientDet** data from [google/automl](https://github.com/google/automl) at batch size 8. -- **Reproduce** by `python val.py --task study --data coco.yaml --iou 0.7 --weights yolov5n6.pt yolov5s6.pt yolov5m6.pt yolov5l6.pt yolov5x6.pt` +- **COCO AP val** denotes the mean Average Precision (mAP) at IoU thresholds from 0.5 to 0.95, measured on the 5,000-image [COCO val2017 dataset](http://cocodataset.org) across various inference sizes (256 to 1536 pixels). +- **GPU Speed** measures the average inference time per image on the [COCO val2017 dataset](http://cocodataset.org) using an [AWS p3.2xlarge V100 instance](https://aws.amazon.com/ec2/instance-types/p4/) with a batch size of 32. +- **EfficientDet** data is sourced from the [google/automl repository](https://github.com/google/automl) at batch size 8. +- **Reproduce** these results using the command: `python val.py --task study --data coco.yaml --iou 0.7 --weights yolov5n6.pt yolov5s6.pt yolov5m6.pt yolov5l6.pt yolov5x6.pt`
### Pretrained Checkpoints -| Model | size
(pixels) | mAPval
50-95 | mAPval
50 | Speed
CPU b1
(ms) | Speed
V100 b1
(ms) | Speed
V100 b32
(ms) | params
(M) | FLOPs
@640 (B) | +This table shows the performance metrics for various YOLOv5 models trained on the COCO dataset. + +| Model | Size
(pixels) | mAPval
50-95 | mAPval
50 | Speed
CPU b1
(ms) | Speed
V100 b1
(ms) | Speed
V100 b32
(ms) | Params
(M) | FLOPs
@640 (B) | | ----------------------------------------------------------------------------------------------- | --------------------- | -------------------- | ----------------- | ---------------------------- | ----------------------------- | ------------------------------ | ------------------ | ---------------------- | | [YOLOv5n](https://github.com/ultralytics/yolov5/releases/download/v7.0/yolov5n.pt) | 640 | 28.0 | 45.7 | **45** | **6.3** | **0.6** | **1.9** | **4.5** | | [YOLOv5s](https://github.com/ultralytics/yolov5/releases/download/v7.0/yolov5s.pt) | 640 | 37.4 | 56.8 | 98 | 6.4 | 0.9 | 7.2 | 16.5 | @@ -228,33 +268,33 @@ YOLOv5 has been designed to be super easy to get started and simple to learn. We | [YOLOv5s6](https://github.com/ultralytics/yolov5/releases/download/v7.0/yolov5s6.pt) | 1280 | 44.8 | 63.7 | 385 | 8.2 | 3.6 | 12.6 | 16.8 | | [YOLOv5m6](https://github.com/ultralytics/yolov5/releases/download/v7.0/yolov5m6.pt) | 1280 | 51.3 | 69.3 | 887 | 11.1 | 6.8 | 35.7 | 50.0 | | [YOLOv5l6](https://github.com/ultralytics/yolov5/releases/download/v7.0/yolov5l6.pt) | 1280 | 53.7 | 71.3 | 1784 | 15.8 | 10.5 | 76.8 | 111.4 | -| [YOLOv5x6](https://github.com/ultralytics/yolov5/releases/download/v7.0/yolov5x6.pt)
+ [TTA] | 1280
1536 | 55.0
**55.8** | 72.7
**72.7** | 3136
- | 26.2
- | 19.4
- | 140.7
- | 209.8
- | +| [YOLOv5x6](https://github.com/ultralytics/yolov5/releases/download/v7.0/yolov5x6.pt)
+ [[TTA]][tta] | 1280
1536 | 55.0
**55.8** | 72.7
**72.7** | 3136
- | 26.2
- | 19.4
- | 140.7
- | 209.8
- |
Table Notes -- All checkpoints are trained to 300 epochs with default settings. Nano and Small models use [hyp.scratch-low.yaml](https://github.com/ultralytics/yolov5/blob/master/data/hyps/hyp.scratch-low.yaml) hyps, all others use [hyp.scratch-high.yaml](https://github.com/ultralytics/yolov5/blob/master/data/hyps/hyp.scratch-high.yaml). -- **mAPval** values are for single-model single-scale on [COCO val2017](http://cocodataset.org) dataset.
Reproduce by `python val.py --data coco.yaml --img 640 --conf 0.001 --iou 0.65` -- **Speed** averaged over COCO val images using a [AWS p3.2xlarge](https://aws.amazon.com/ec2/instance-types/p4/) instance. NMS times (~1 ms/img) not included.
Reproduce by `python val.py --data coco.yaml --img 640 --task speed --batch 1` -- **TTA** [Test Time Augmentation](https://docs.ultralytics.com/yolov5/tutorials/test_time_augmentation/) includes reflection and scale augmentations.
Reproduce by `python val.py --data coco.yaml --img 1536 --iou 0.7 --augment` +- All checkpoints were trained for 300 epochs using default settings. Nano (n) and Small (s) models use [hyp.scratch-low.yaml](https://github.com/ultralytics/yolov5/blob/master/data/hyps/hyp.scratch-low.yaml) hyperparameters, while Medium (m), Large (l), and Extra-Large (x) models use [hyp.scratch-high.yaml](https://github.com/ultralytics/yolov5/blob/master/data/hyps/hyp.scratch-high.yaml). +- **mAPval** values represent single-model, single-scale performance on the [COCO val2017 dataset](http://cocodataset.org).
Reproduce using: `python val.py --data coco.yaml --img 640 --conf 0.001 --iou 0.65` +- **Speed** metrics are averaged over COCO val images using an [AWS p3.2xlarge V100 instance](https://aws.amazon.com/ec2/instance-types/p4/). Non-Maximum Suppression (NMS) time (~1 ms/image) is not included.
Reproduce using: `python val.py --data coco.yaml --img 640 --task speed --batch 1` +- **TTA** ([Test Time Augmentation](https://docs.ultralytics.com/yolov5/tutorials/test_time_augmentation/)) includes reflection and scale augmentations for improved accuracy.
Reproduce using: `python val.py --data coco.yaml --img 1536 --iou 0.7 --augment`
-##
Segmentation
+## 🖼️ Segmentation -Our new YOLOv5 [release v7.0](https://github.com/ultralytics/yolov5/releases/v7.0) instance segmentation models are the fastest and most accurate in the world, beating all current [SOTA benchmarks](https://paperswithcode.com/sota/real-time-instance-segmentation-on-mscoco). We've made them super simple to train, validate and deploy. See full details in our [Release Notes](https://github.com/ultralytics/yolov5/releases/v7.0) and visit our [YOLOv5 Segmentation Colab Notebook](https://github.com/ultralytics/yolov5/blob/master/segment/tutorial.ipynb) for quickstart tutorials. +The YOLOv5 [release v7.0](https://github.com/ultralytics/yolov5/releases/v7.0) introduced instance segmentation models that achieve state-of-the-art performance. These models are designed for easy training, validation, and deployment. For full details, see the [Release Notes](https://github.com/ultralytics/yolov5/releases/v7.0) and explore the [YOLOv5 Segmentation Colab Notebook](https://github.com/ultralytics/yolov5/blob/master/segment/tutorial.ipynb) for quickstart examples.
Segmentation Checkpoints
- +YOLOv5 Segmentation Performance Chart
-We trained YOLOv5 segmentations models on COCO for 300 epochs at image size 640 using A100 GPUs. We exported all models to ONNX FP32 for CPU speed tests and to TensorRT FP16 for GPU speed tests. We ran all speed tests on Google [Colab Pro](https://colab.research.google.com/signup) notebooks for easy reproducibility. +YOLOv5 segmentation models were trained on the COCO dataset for 300 epochs at an image size of 640 pixels using A100 GPUs. Models were exported to ONNX FP32 for CPU speed tests and TensorRT FP16 for GPU speed tests. All speed tests were conducted on Google [Colab Pro](https://colab.research.google.com/signup) notebooks for reproducibility. -| Model | size
(pixels) | mAPbox
50-95 | mAPmask
50-95 | Train time
300 epochs
A100 (hours) | Speed
ONNX CPU
(ms) | Speed
TRT A100
(ms) | params
(M) | FLOPs
@640 (B) | +| Model | Size
(pixels) | mAPbox
50-95 | mAPmask
50-95 | Train Time
300 epochs
A100 (hours) | Speed
ONNX CPU
(ms) | Speed
TRT A100
(ms) | Params
(M) | FLOPs
@640 (B) | | ------------------------------------------------------------------------------------------ | --------------------- | -------------------- | --------------------- | --------------------------------------------- | ------------------------------ | ------------------------------ | ------------------ | ---------------------- | | [YOLOv5n-seg](https://github.com/ultralytics/yolov5/releases/download/v7.0/yolov5n-seg.pt) | 640 | 27.6 | 23.4 | 80:17 | **62.7** | **1.2** | **2.0** | **7.1** | | [YOLOv5s-seg](https://github.com/ultralytics/yolov5/releases/download/v7.0/yolov5s-seg.pt) | 640 | 37.6 | 31.7 | 88:16 | 173.3 | 1.4 | 7.6 | 26.4 | @@ -262,10 +302,10 @@ We trained YOLOv5 segmentations models on COCO for 300 epochs at image size 640 | [YOLOv5l-seg](https://github.com/ultralytics/yolov5/releases/download/v7.0/yolov5l-seg.pt) | 640 | 49.0 | 39.9 | 66:43 (2x) | 857.4 | 2.9 | 47.9 | 147.7 | | [YOLOv5x-seg](https://github.com/ultralytics/yolov5/releases/download/v7.0/yolov5x-seg.pt) | 640 | **50.7** | **41.4** | 62:56 (3x) | 1579.2 | 4.5 | 88.8 | 265.7 | -- All checkpoints are trained to 300 epochs with SGD optimizer with `lr0=0.01` and `weight_decay=5e-5` at image size 640 and all default settings.
Runs logged to https://wandb.ai/glenn-jocher/YOLOv5_v70_official -- **Accuracy** values are for single-model single-scale on COCO dataset.
Reproduce by `python segment/val.py --data coco.yaml --weights yolov5s-seg.pt` -- **Speed** averaged over 100 inference images using a [Colab Pro](https://colab.research.google.com/signup) A100 High-RAM instance. Values indicate inference speed only (NMS adds about 1ms per image).
Reproduce by `python segment/val.py --data coco.yaml --weights yolov5s-seg.pt --batch 1` -- **Export** to ONNX at FP32 and TensorRT at FP16 done with `export.py`.
Reproduce by `python export.py --weights yolov5s-seg.pt --include engine --device 0 --half` +- All checkpoints were trained for 300 epochs using the SGD optimizer with `lr0=0.01` and `weight_decay=5e-5` at an image size of 640 pixels, using default settings.
Training runs are logged at [https://wandb.ai/glenn-jocher/YOLOv5_v70_official](https://wandb.ai/glenn-jocher/YOLOv5_v70_official). +- **Accuracy** values represent single-model, single-scale performance on the COCO dataset.
Reproduce using: `python segment/val.py --data coco.yaml --weights yolov5s-seg.pt` +- **Speed** metrics are averaged over 100 inference images using a [Colab Pro A100 High-RAM instance](https://colab.research.google.com/signup). Values indicate inference speed only (NMS adds approximately 1ms per image).
Reproduce using: `python segment/val.py --data coco.yaml --weights yolov5s-seg.pt --batch 1` +- **Export** to ONNX (FP32) and TensorRT (FP16) was performed using `export.py`.
Reproduce using: `python export.py --weights yolov5s-seg.pt --include engine --device 0 --half`
@@ -274,64 +314,70 @@ We trained YOLOv5 segmentations models on COCO for 300 epochs at image size 640 ### Train -YOLOv5 segmentation training supports auto-download COCO128-seg segmentation dataset with `--data coco128-seg.yaml` argument and manual download of COCO-segments dataset with `bash data/scripts/get_coco.sh --train --val --segments` and then `python train.py --data coco.yaml`. +YOLOv5 segmentation training supports automatic download of the COCO128-seg dataset via the `--data coco128-seg.yaml` argument. For the full COCO-segments dataset, download it manually using `bash data/scripts/get_coco.sh --train --val --segments` and then train with `python train.py --data coco.yaml`. ```bash -# Single-GPU +# Train on a single GPU python segment/train.py --data coco128-seg.yaml --weights yolov5s-seg.pt --img 640 -# Multi-GPU DDP +# Train using Multi-GPU Distributed Data Parallel (DDP) python -m torch.distributed.run --nproc_per_node 4 --master_port 1 segment/train.py --data coco128-seg.yaml --weights yolov5s-seg.pt --img 640 --device 0,1,2,3 ``` ### Val -Validate YOLOv5s-seg mask mAP on COCO dataset: +Validate the mask mean Average Precision (mAP) of YOLOv5s-seg on the COCO dataset: ```bash -bash data/scripts/get_coco.sh --val --segments # download COCO val segments split (780MB, 5000 images) -python segment/val.py --weights yolov5s-seg.pt --data coco.yaml --img 640 # validate +# Download COCO validation segments split (780MB, 5000 images) +bash data/scripts/get_coco.sh --val --segments + +# Validate the model +python segment/val.py --weights yolov5s-seg.pt --data coco.yaml --img 640 ``` ### Predict -Use pretrained YOLOv5m-seg.pt to predict bus.jpg: +Use the pretrained YOLOv5m-seg.pt model to perform segmentation on `bus.jpg`: ```bash +# Run prediction python segment/predict.py --weights yolov5m-seg.pt --source data/images/bus.jpg ``` ```python +# Load model from PyTorch Hub (Note: Inference support might vary) model = torch.hub.load( "ultralytics/yolov5", "custom", "yolov5m-seg.pt" -) # load from PyTorch Hub (WARNING: inference not yet supported) +) ``` -| ![zidane](https://user-images.githubusercontent.com/26833433/203113421-decef4c4-183d-4a0a-a6c2-6435b33bc5d3.jpg) | ![bus](https://user-images.githubusercontent.com/26833433/203113416-11fe0025-69f7-4874-a0a6-65d0bfe2999a.jpg) | -| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| ![Zidane Segmentation Example](https://user-images.githubusercontent.com/26833433/203113421-decef4c4-183d-4a0a-a6c2-6435b33bc5d3.jpg) | ![Bus Segmentation Example](https://user-images.githubusercontent.com/26833433/203113416-11fe0025-69f7-4874-a0a6-65d0bfe2999a.jpg) | +| :---------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------: | ### Export -Export YOLOv5s-seg model to ONNX and TensorRT: +Export the YOLOv5s-seg model to ONNX and TensorRT formats: ```bash +# Export model python export.py --weights yolov5s-seg.pt --include onnx engine --img 640 --device 0 ``` -##
Classification
+## 🏷️ Classification -YOLOv5 [release v6.2](https://github.com/ultralytics/yolov5/releases) brings support for classification model training, validation and deployment! See full details in our [Release Notes](https://github.com/ultralytics/yolov5/releases/v6.2) and visit our [YOLOv5 Classification Colab Notebook](https://github.com/ultralytics/yolov5/blob/master/classify/tutorial.ipynb) for quickstart tutorials. +YOLOv5 [release v6.2](https://github.com/ultralytics/yolov5/releases/v6.2) introduced support for image classification model training, validation, and deployment. Check the [Release Notes](https://github.com/ultralytics/yolov5/releases/v6.2) for details and the [YOLOv5 Classification Colab Notebook](https://github.com/ultralytics/yolov5/blob/master/classify/tutorial.ipynb) for quickstart guides.
Classification Checkpoints
-We trained YOLOv5-cls classification models on ImageNet for 90 epochs using a 4xA100 instance, and we trained ResNet and EfficientNet models alongside with the same default training settings to compare. We exported all models to ONNX FP32 for CPU speed tests and to TensorRT FP16 for GPU speed tests. We ran all speed tests on Google [Colab Pro](https://colab.research.google.com/signup) for easy reproducibility. +YOLOv5-cls classification models were trained on ImageNet for 90 epochs using a 4xA100 instance. ResNet and EfficientNet models were trained alongside under identical settings for comparison. Models were exported to ONNX FP32 (CPU speed tests) and TensorRT FP16 (GPU speed tests). All speed tests were run on Google [Colab Pro](https://colab.research.google.com/signup) for reproducibility. -| Model | size
(pixels) | acc
top1 | acc
top5 | Training
90 epochs
4xA100 (hours) | Speed
ONNX CPU
(ms) | Speed
TensorRT V100
(ms) | params
(M) | FLOPs
@224 (B) | +| Model | Size
(pixels) | Acc
top1 | Acc
top5 | Training
90 epochs
4xA100 (hours) | Speed
ONNX CPU
(ms) | Speed
TensorRT V100
(ms) | Params
(M) | FLOPs
@224 (B) | | -------------------------------------------------------------------------------------------------- | --------------------- | ---------------- | ---------------- | -------------------------------------------- | ------------------------------ | ----------------------------------- | ------------------ | ---------------------- | | [YOLOv5n-cls](https://github.com/ultralytics/yolov5/releases/download/v7.0/yolov5n-cls.pt) | 224 | 64.6 | 85.4 | 7:59 | **3.3** | **0.5** | **2.5** | **0.5** | | [YOLOv5s-cls](https://github.com/ultralytics/yolov5/releases/download/v7.0/yolov5s-cls.pt) | 224 | 71.5 | 90.2 | 8:09 | 6.6 | 0.6 | 5.4 | 1.4 | @@ -352,10 +398,10 @@ We trained YOLOv5-cls classification models on ImageNet for 90 epochs using a 4x
Table Notes (click to expand) -- All checkpoints are trained to 90 epochs with SGD optimizer with `lr0=0.001` and `weight_decay=5e-5` at image size 224 and all default settings.
Runs logged to https://wandb.ai/glenn-jocher/YOLOv5-Classifier-v6-2 -- **Accuracy** values are for single-model single-scale on [ImageNet-1k](https://www.image-net.org/index.php) dataset.
Reproduce by `python classify/val.py --data ../datasets/imagenet --img 224` -- **Speed** averaged over 100 inference images using a Google [Colab Pro](https://colab.research.google.com/signup) V100 High-RAM instance.
Reproduce by `python classify/val.py --data ../datasets/imagenet --img 224 --batch 1` -- **Export** to ONNX at FP32 and TensorRT at FP16 done with `export.py`.
Reproduce by `python export.py --weights yolov5s-cls.pt --include engine onnx --imgsz 224` +- All checkpoints were trained for 90 epochs using the SGD optimizer with `lr0=0.001` and `weight_decay=5e-5` at an image size of 224 pixels, using default settings.
Training runs are logged at [https://wandb.ai/glenn-jocher/YOLOv5-Classifier-v6-2](https://wandb.ai/glenn-jocher/YOLOv5-Classifier-v6-2). +- **Accuracy** values (top-1 and top-5) represent single-model, single-scale performance on the [ImageNet-1k dataset](https://www.image-net.org/index.php).
Reproduce using: `python classify/val.py --data ../datasets/imagenet --img 224` +- **Speed** metrics are averaged over 100 inference images using a Google [Colab Pro V100 High-RAM instance](https://colab.research.google.com/signup).
Reproduce using: `python classify/val.py --data ../datasets/imagenet --img 224 --batch 1` +- **Export** to ONNX (FP32) and TensorRT (FP16) was performed using `export.py`.
Reproduce using: `python export.py --weights yolov5s-cls.pt --include engine onnx --imgsz 224`
@@ -365,106 +411,107 @@ We trained YOLOv5-cls classification models on ImageNet for 90 epochs using a 4x ### Train -YOLOv5 classification training supports auto-download of MNIST, Fashion-MNIST, CIFAR10, CIFAR100, Imagenette, Imagewoof, and ImageNet datasets with the `--data` argument. To start training on MNIST for example use `--data mnist`. +YOLOv5 classification training supports automatic download for datasets like MNIST, Fashion-MNIST, CIFAR10, CIFAR100, Imagenette, Imagewoof, and ImageNet using the `--data` argument. For example, start training on MNIST with `--data mnist`. ```bash -# Single-GPU +# Train on a single GPU using CIFAR-100 dataset python classify/train.py --model yolov5s-cls.pt --data cifar100 --epochs 5 --img 224 --batch 128 -# Multi-GPU DDP +# Train using Multi-GPU DDP on ImageNet dataset python -m torch.distributed.run --nproc_per_node 4 --master_port 1 classify/train.py --model yolov5s-cls.pt --data imagenet --epochs 5 --img 224 --device 0,1,2,3 ``` ### Val -Validate YOLOv5m-cls accuracy on ImageNet-1k dataset: +Validate the accuracy of the YOLOv5m-cls model on the ImageNet-1k validation dataset: ```bash -bash data/scripts/get_imagenet.sh --val # download ImageNet val split (6.3G, 50000 images) -python classify/val.py --weights yolov5m-cls.pt --data ../datasets/imagenet --img 224 # validate +# Download ImageNet validation split (6.3GB, 50,000 images) +bash data/scripts/get_imagenet.sh --val + +# Validate the model +python classify/val.py --weights yolov5m-cls.pt --data ../datasets/imagenet --img 224 ``` ### Predict -Use pretrained YOLOv5s-cls.pt to predict bus.jpg: +Use the pretrained YOLOv5s-cls.pt model to classify the image `bus.jpg`: ```bash +# Run prediction python classify/predict.py --weights yolov5s-cls.pt --source data/images/bus.jpg ``` ```python -model = torch.hub.load("ultralytics/yolov5", "custom", "yolov5s-cls.pt") # load from PyTorch Hub +# Load model from PyTorch Hub +model = torch.hub.load("ultralytics/yolov5", "custom", "yolov5s-cls.pt") ``` ### Export -Export a group of trained YOLOv5s-cls, ResNet and EfficientNet models to ONNX and TensorRT: +Export trained YOLOv5s-cls, ResNet50, and EfficientNet_b0 models to ONNX and TensorRT formats: ```bash +# Export models python export.py --weights yolov5s-cls.pt resnet50.pt efficientnet_b0.pt --include onnx engine --img 224 ``` -##
Environments
+## ☁️ Environments -Get started in seconds with our verified environments. Click each icon below for details. +Get started quickly with our pre-configured environments. Click the icons below for setup details. -##
Contribute
+## 🤝 Contribute -We love your input! We want to make contributing to YOLOv5 as easy and transparent as possible. Please see our [Contributing Guide](https://docs.ultralytics.com/help/contributing/) to get started, and fill out the [YOLOv5 Survey](https://www.ultralytics.com/survey?utm_source=github&utm_medium=social&utm_campaign=Survey) to send us feedback on your experiences. Thank you to all our contributors! +We welcome your contributions! Making YOLOv5 accessible and effective is a community effort. Please see our [Contributing Guide](https://docs.ultralytics.com/help/contributing/) to get started. Share your feedback through the [YOLOv5 Survey](https://www.ultralytics.com/survey?utm_source=github&utm_medium=social&utm_campaign=Survey). Thank you to all our contributors for making YOLOv5 better! - +[![Ultralytics open-source contributors](https://raw.githubusercontent.com/ultralytics/assets/main/im/image-contributors.png)](https://github.com/ultralytics/yolov5/graphs/contributors) - - +## 📜 License -##
License
+Ultralytics provides two licensing options to meet different needs: -Ultralytics offers two licensing options to accommodate diverse use cases: +- **AGPL-3.0 License**: An [OSI-approved](https://opensource.org/license/agpl-v3) open-source license ideal for academic research, personal projects, and testing. It promotes open collaboration and knowledge sharing. See the [LICENSE](https://github.com/ultralytics/yolov5/blob/master/LICENSE) file for details. +- **Enterprise License**: Tailored for commercial applications, this license allows seamless integration of Ultralytics software and AI models into commercial products and services, bypassing the open-source requirements of AGPL-3.0. For commercial use cases, please contact us via [Ultralytics Licensing](https://www.ultralytics.com/license). -- **AGPL-3.0 License**: This [OSI-approved](https://opensource.org/license) open-source license is ideal for students and enthusiasts, promoting open collaboration and knowledge sharing. See the [LICENSE](https://github.com/ultralytics/yolov5/blob/master/LICENSE) file for more details. -- **Enterprise License**: Designed for commercial use, this license permits seamless integration of Ultralytics software and AI models into commercial goods and services, bypassing the open-source requirements of AGPL-3.0. If your scenario involves embedding our solutions into a commercial offering, reach out through [Ultralytics Licensing](https://www.ultralytics.com/license). +## 📧 Contact -##
Contact
- -For YOLOv5 bug reports and feature requests please visit [GitHub Issues](https://github.com/ultralytics/yolov5/issues), and join our [Discord](https://discord.com/invite/ultralytics) community for questions and discussions! +For bug reports and feature requests related to YOLOv5, please visit [GitHub Issues](https://github.com/ultralytics/yolov5/issues). For general questions, discussions, and community support, join our [Discord server](https://discord.com/invite/ultralytics)!
- Ultralytics GitHub + Ultralytics GitHub - Ultralytics LinkedIn + Ultralytics LinkedIn - Ultralytics Twitter + Ultralytics Twitter - Ultralytics YouTube + Ultralytics YouTube - Ultralytics TikTok + Ultralytics TikTok - Ultralytics BiliBili + Ultralytics BiliBili - Ultralytics Discord + Ultralytics Discord
- -[tta]: https://docs.ultralytics.com/yolov5/tutorials/test_time_augmentation diff --git a/benchmarks.py b/benchmarks.py index 45ae55b36..2bf39f547 100644 --- a/benchmarks.py +++ b/benchmarks.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """ Run YOLOv5 benchmarks on all supported export formats. diff --git a/classify/predict.py b/classify/predict.py index 59db1330a..8492b897c 100644 --- a/classify/predict.py +++ b/classify/predict.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """ Run YOLOv5 classification inference on images, videos, directories, globs, YouTube, webcam, streams, etc. diff --git a/classify/train.py b/classify/train.py index d454c7187..1f990ff35 100644 --- a/classify/train.py +++ b/classify/train.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """ Train a YOLOv5 classifier model on a classification dataset. diff --git a/classify/val.py b/classify/val.py index 72bd0e14e..efbf3e140 100644 --- a/classify/val.py +++ b/classify/val.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """ Validate a trained YOLOv5 classification model on a classification dataset. diff --git a/data/scripts/download_weights.sh b/data/scripts/download_weights.sh index e408959b3..7726a9bd1 100755 --- a/data/scripts/download_weights.sh +++ b/data/scripts/download_weights.sh @@ -1,5 +1,6 @@ #!/bin/bash -# YOLOv5 🚀 by Ultralytics, AGPL-3.0 license +# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + # Download latest models from https://github.com/ultralytics/yolov5/releases # Example usage: bash data/scripts/download_weights.sh # parent diff --git a/data/scripts/get_coco.sh b/data/scripts/get_coco.sh index 0bb276140..e8ea16944 100755 --- a/data/scripts/get_coco.sh +++ b/data/scripts/get_coco.sh @@ -1,5 +1,6 @@ #!/bin/bash -# YOLOv5 🚀 by Ultralytics, AGPL-3.0 license +# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + # Download COCO 2017 dataset http://cocodataset.org # Example usage: bash data/scripts/get_coco.sh # parent diff --git a/data/scripts/get_coco128.sh b/data/scripts/get_coco128.sh index 2bfd6a2b3..a44eb8452 100755 --- a/data/scripts/get_coco128.sh +++ b/data/scripts/get_coco128.sh @@ -1,5 +1,6 @@ #!/bin/bash -# YOLOv5 🚀 by Ultralytics, AGPL-3.0 license +# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + # Download COCO128 dataset https://www.kaggle.com/ultralytics/coco128 (first 128 images from COCO train2017) # Example usage: bash data/scripts/get_coco128.sh # parent diff --git a/data/scripts/get_imagenet.sh b/data/scripts/get_imagenet.sh index 1df0fc7b6..359cded85 100755 --- a/data/scripts/get_imagenet.sh +++ b/data/scripts/get_imagenet.sh @@ -1,5 +1,6 @@ #!/bin/bash -# YOLOv5 🚀 by Ultralytics, AGPL-3.0 license +# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + # Download ILSVRC2012 ImageNet dataset https://image-net.org # Example usage: bash data/scripts/get_imagenet.sh # parent diff --git a/data/scripts/get_imagenet10.sh b/data/scripts/get_imagenet10.sh index 71e17c5d3..135cab672 100644 --- a/data/scripts/get_imagenet10.sh +++ b/data/scripts/get_imagenet10.sh @@ -1,5 +1,6 @@ #!/bin/bash -# YOLOv5 🚀 by Ultralytics, AGPL-3.0 license +# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + # Download ILSVRC2012 ImageNet dataset https://image-net.org # Example usage: bash data/scripts/get_imagenet.sh # parent diff --git a/data/scripts/get_imagenet100.sh b/data/scripts/get_imagenet100.sh index c57106b48..708ad771a 100644 --- a/data/scripts/get_imagenet100.sh +++ b/data/scripts/get_imagenet100.sh @@ -1,5 +1,6 @@ #!/bin/bash -# YOLOv5 🚀 by Ultralytics, AGPL-3.0 license +# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + # Download ILSVRC2012 ImageNet dataset https://image-net.org # Example usage: bash data/scripts/get_imagenet.sh # parent diff --git a/data/scripts/get_imagenet1000.sh b/data/scripts/get_imagenet1000.sh index 451dd0f6b..e4c59387a 100644 --- a/data/scripts/get_imagenet1000.sh +++ b/data/scripts/get_imagenet1000.sh @@ -1,5 +1,6 @@ #!/bin/bash -# YOLOv5 🚀 by Ultralytics, AGPL-3.0 license +# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + # Download ILSVRC2012 ImageNet dataset https://image-net.org # Example usage: bash data/scripts/get_imagenet.sh # parent diff --git a/detect.py b/detect.py index 24724a35f..84c683c18 100644 --- a/detect.py +++ b/detect.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """ Run YOLOv5 detection inference on images, videos, directories, globs, YouTube, webcam, streams, etc. diff --git a/export.py b/export.py index 8f87b2d56..19ac57ac7 100644 --- a/export.py +++ b/export.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """ Export a YOLOv5 PyTorch model to other formats. TensorFlow exports authored by https://github.com/zldrobit. diff --git a/hubconf.py b/hubconf.py index 2eeac4edd..3529b0a76 100644 --- a/hubconf.py +++ b/hubconf.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """ PyTorch Hub models https://pytorch.org/hub/ultralytics_yolov5. diff --git a/models/common.py b/models/common.py index 341e878b9..92ea830ed 100644 --- a/models/common.py +++ b/models/common.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """Common modules.""" import ast diff --git a/models/experimental.py b/models/experimental.py index 63d9c461a..5a86d2f55 100644 --- a/models/experimental.py +++ b/models/experimental.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """Experimental modules.""" import math diff --git a/models/tf.py b/models/tf.py index c2cad393e..1fb57b528 100644 --- a/models/tf.py +++ b/models/tf.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """ TensorFlow, Keras and TFLite versions of YOLOv5 Authored by https://github.com/zldrobit in PR https://github.com/ultralytics/yolov5/pull/1127. diff --git a/models/yolo.py b/models/yolo.py index 13498aced..62e5ee18c 100644 --- a/models/yolo.py +++ b/models/yolo.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """ YOLO-specific modules. diff --git a/segment/predict.py b/segment/predict.py index e0e4336c1..76647a49d 100644 --- a/segment/predict.py +++ b/segment/predict.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """ Run YOLOv5 segmentation inference on images, videos, directories, streams, etc. diff --git a/segment/train.py b/segment/train.py index 815c97ce1..dcfbcb41d 100644 --- a/segment/train.py +++ b/segment/train.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """ Train a YOLOv5 segment model on a segment dataset Models and datasets download automatically from the latest YOLOv5 release. diff --git a/segment/val.py b/segment/val.py index edd6a08fa..0c9b320f5 100644 --- a/segment/val.py +++ b/segment/val.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """ Validate a trained YOLOv5 segment model on a segment dataset. diff --git a/train.py b/train.py index 1401ccb96..fb548edd3 100644 --- a/train.py +++ b/train.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """ Train a YOLOv5 model on a custom dataset. Models and datasets download automatically from the latest YOLOv5 release. diff --git a/utils/__init__.py b/utils/__init__.py index 3c43c9b68..2072b4061 100644 --- a/utils/__init__.py +++ b/utils/__init__.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """utils/initialization.""" import contextlib diff --git a/utils/activations.py b/utils/activations.py index 4652540db..b54604057 100644 --- a/utils/activations.py +++ b/utils/activations.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """Activation functions.""" import torch diff --git a/utils/augmentations.py b/utils/augmentations.py index 79e7afc8d..3b31b8742 100644 --- a/utils/augmentations.py +++ b/utils/augmentations.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """Image augmentation functions.""" import math diff --git a/utils/autoanchor.py b/utils/autoanchor.py index 1fc420759..4a434ddeb 100644 --- a/utils/autoanchor.py +++ b/utils/autoanchor.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """AutoAnchor utils.""" import random diff --git a/utils/autobatch.py b/utils/autobatch.py index 9d5ea0a94..e9c39ea91 100644 --- a/utils/autobatch.py +++ b/utils/autobatch.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """Auto-batch utils.""" from copy import deepcopy diff --git a/utils/aws/mime.sh b/utils/aws/mime.sh index c319a83cf..f69cab0a8 100644 --- a/utils/aws/mime.sh +++ b/utils/aws/mime.sh @@ -1,3 +1,5 @@ +# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + # AWS EC2 instance startup 'MIME' script https://aws.amazon.com/premiumsupport/knowledge-center/execute-user-data-ec2/ # This script will run on every instance restart, not only on first start # --- DO NOT COPY ABOVE COMMENTS WHEN PASTING INTO USERDATA --- diff --git a/utils/aws/userdata.sh b/utils/aws/userdata.sh index 5fc1332ac..4e5dfadec 100644 --- a/utils/aws/userdata.sh +++ b/utils/aws/userdata.sh @@ -1,4 +1,6 @@ #!/bin/bash +# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + # AWS EC2 instance startup script https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html # This script will run only once on first instance start (for a re-start script see mime.sh) # /home/ubuntu (ubuntu) or /home/ec2-user (amazon-linux) is working dir diff --git a/utils/callbacks.py b/utils/callbacks.py index 1a6092840..7e376074d 100644 --- a/utils/callbacks.py +++ b/utils/callbacks.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """Callback utils.""" import threading diff --git a/utils/dataloaders.py b/utils/dataloaders.py index e8341d629..4ef394f92 100644 --- a/utils/dataloaders.py +++ b/utils/dataloaders.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """Dataloaders and dataset utils.""" import contextlib diff --git a/utils/downloads.py b/utils/downloads.py index f51d67aa9..037eca084 100644 --- a/utils/downloads.py +++ b/utils/downloads.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """Download utils.""" import logging diff --git a/utils/flask_rest_api/README.md b/utils/flask_rest_api/README.md index d3ffaa206..d2636f565 100644 --- a/utils/flask_rest_api/README.md +++ b/utils/flask_rest_api/README.md @@ -1,30 +1,36 @@ -# Flask REST API +Ultralytics logo -[REST](https://en.wikipedia.org/wiki/Representational_state_transfer) [API](https://en.wikipedia.org/wiki/API)s are commonly used to expose Machine Learning (ML) models to other services. This folder contains an example REST API created using Flask to expose the YOLOv5s model from [PyTorch Hub](https://pytorch.org/hub/ultralytics_yolov5/). +# Flask REST API for YOLOv5 -## Requirements +[Representational State Transfer (REST)](https://en.wikipedia.org/wiki/Representational_state_transfer) [Application Programming Interfaces (APIs)](https://en.wikipedia.org/wiki/API) are a standard way to expose [Machine Learning (ML)](https://www.ultralytics.com/glossary/machine-learning-ml) models for consumption by other services or applications. This directory provides an example REST API built with [Flask](https://flask.palletsprojects.com/en/stable/) to serve the Ultralytics [YOLOv5s](https://docs.ultralytics.com/models/yolov5/) model loaded directly from [PyTorch Hub](https://pytorch.org/hub/ultralytics_yolov5/). This allows you to easily integrate YOLOv5 object detection capabilities into your web applications or microservices. -[Flask](https://palletsprojects.com/projects/flask/) is required. Install with: +## 💻 Requirements + +The primary requirement is the [Flask](https://flask.palletsprojects.com/en/stable/) web framework. Install it using pip: ```shell -$ pip install Flask +pip install Flask ``` -## Run +You will also need `torch` and `yolov5` which are implicitly handled when loading the model from PyTorch Hub in the script. Ensure you have a working Python environment. -After Flask installation run: +## ▶️ Run the API + +Once Flask is installed, you can start the API server: ```shell -$ python3 restapi.py --port 5000 +python restapi.py --port 5000 ``` -Then use [curl](https://curl.se/) to perform a request: +The server will start listening on the specified port (default is 5000). You can then send inference requests to the API endpoint using tools like [curl](https://curl.se/) or any HTTP client. + +To test the API with an image file (e.g., `zidane.jpg` from the `yolov5/data/images` directory): ```shell -$ curl -X POST -F image=@zidane.jpg 'http://localhost:5000/v1/object-detection/yolov5s' +curl -X POST -F image=@../data/images/zidane.jpg 'http://localhost:5000/v1/object-detection/yolov5s' ``` -The model inference results are returned as a JSON response: +The API processes the image using the YOLOv5s model and returns the detection results in [JSON](https://www.json.org/json-en.html) format. Each object in the JSON array represents a detected object with its class ID, confidence score, bounding box coordinates (normalized), and class name. ```json [ @@ -67,4 +73,8 @@ The model inference results are returned as a JSON response: ] ``` -An example python script to perform inference using [requests](https://docs.python-requests.org/en/master/) is given in `example_request.py` +An example Python script, `example_request.py`, demonstrates how to perform inference using the popular [requests](https://requests.readthedocs.io/en/latest/) library. This script provides a simple way to interact with the running API programmatically. + +## 🤝 Contribute + +Contributions to enhance this Flask API example are welcome! Whether it's adding support for different YOLO models, improving error handling, or adding new features, feel free to fork the repository, make your changes, and submit a pull request. Check out the main [Ultralytics YOLOv5 repository](https://github.com/ultralytics/yolov5) for more details on contributing. diff --git a/utils/flask_rest_api/example_request.py b/utils/flask_rest_api/example_request.py index db88e8040..bf4fa0ba2 100644 --- a/utils/flask_rest_api/example_request.py +++ b/utils/flask_rest_api/example_request.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """Perform test request.""" import pprint diff --git a/utils/flask_rest_api/restapi.py b/utils/flask_rest_api/restapi.py index 410ae26c5..09d4e72fd 100644 --- a/utils/flask_rest_api/restapi.py +++ b/utils/flask_rest_api/restapi.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """Run a Flask REST API exposing one or more YOLOv5s models.""" import argparse diff --git a/utils/general.py b/utils/general.py index 89bbc61f4..b5820447f 100644 --- a/utils/general.py +++ b/utils/general.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """General utils.""" import contextlib diff --git a/utils/loggers/__init__.py b/utils/loggers/__init__.py index 9ff5f56f2..aabdbae86 100644 --- a/utils/loggers/__init__.py +++ b/utils/loggers/__init__.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """Logging utils.""" import json diff --git a/utils/loggers/clearml/README.md b/utils/loggers/clearml/README.md index dddefa132..de3175508 100644 --- a/utils/loggers/clearml/README.md +++ b/utils/loggers/clearml/README.md @@ -1,222 +1,221 @@ -# ClearML Integration +Ultralytics logo + +# ClearML Integration with Ultralytics YOLOv5 Clear|MLClear|ML -## About ClearML +## ℹ️ About ClearML -[ClearML](https://clear.ml/) is an [open-source](https://github.com/clearml/clearml) toolbox designed to save you time ⏱️. +[ClearML](https://clear.ml/) is an [open-source](https://github.com/clearml/clearml) MLOps platform designed to streamline your machine learning workflow and save you valuable time ⏱️. Integrating ClearML with Ultralytics YOLOv5 allows you to leverage a powerful suite of tools: -🔨 Track every YOLOv5 training run in the experiment manager +- **Experiment Management:** 🔨 Track every [YOLOv5](https://docs.ultralytics.com/models/yolov5/) training run, including parameters, metrics, and outputs. See the [Ultralytics ClearML integration guide](https://docs.ultralytics.com/integrations/clearml/) for more details. +- **Data Versioning:** 🔧 Version and easily access your custom training data using the integrated ClearML Data Versioning Tool, similar to concepts in [DVC integration](https://docs.ultralytics.com/integrations/dvc/). +- **Remote Execution:** 🔦 [Remotely train and monitor](https://docs.ultralytics.com/hub/cloud-training/) your YOLOv5 models using ClearML Agent. +- **Hyperparameter Optimization:** 🔬 Achieve optimal [Mean Average Precision (mAP)](https://docs.ultralytics.com/guides/yolo-performance-metrics/) using ClearML's [Hyperparameter Optimization](https://docs.ultralytics.com/guides/hyperparameter-tuning/) capabilities. +- **Model Deployment:** 🔭 Turn your trained YOLOv5 model into an API with just a few commands using ClearML Serving, complementing [Ultralytics deployment options](https://docs.ultralytics.com/guides/model-deployment-options/). -🔧 Version and easily access your custom training data with the integrated ClearML Data Versioning Tool - -🔦 Remotely train and monitor your YOLOv5 training runs using ClearML Agent - -🔬 Get the very best mAP using ClearML Hyperparameter Optimization - -🔭 Turn your newly trained YOLOv5 model into an API with just a few commands using ClearML Serving - -And so much more. It's up to you how many of these tools you want to use, you can stick to the experiment manager, or chain them all together into an impressive pipeline! +You can choose to use only the experiment manager or combine multiple tools into a comprehensive MLOps pipeline. ![ClearML scalars dashboard](https://raw.githubusercontent.com/thepycoder/clearml_screenshots/main/experiment_manager_with_compare.gif) ## 🦾 Setting Things Up -To keep track of your experiments and/or data, ClearML needs to communicate to a server. You have 2 options to get one: +ClearML requires communication with a server to track experiments and data. You have two main options: -Either sign up for free to the [ClearML Hosted Service](https://clear.ml/) or you can set up your own server, see [here](https://clear.ml/docs/latest/docs/deploying_clearml/clearml_server). Even the server is open-source, so even if you're dealing with sensitive data, you should be good to go! +1. **ClearML Hosted Service:** Sign up for a free account at [app.clear.ml](https://app.clear.ml/). +2. **Self-Hosted Server:** Set up your own ClearML server. Find instructions [here](https://clear.ml/docs/latest/docs/deploying_clearml/clearml_server). The server is also open-source, ensuring data privacy. -1. Install the `clearml` python package: +Follow these steps to get started: - ```bash - pip install clearml - ``` +1. Install the `clearml` Python package: + ```bash + pip install clearml + ``` + *Note: This package is included in the `requirements.txt` of YOLOv5.* -2. Connect the ClearML SDK to the server by [creating credentials](https://app.clear.ml/settings/workspace-configuration) (go right top to Settings -> Workspace -> Create new credentials), then execute the command below and follow the instructions: +2. Connect the ClearML SDK to your server. [Create credentials](https://app.clear.ml/settings/workspace-configuration) (Settings -> Workspace -> Create new credentials), then run the following command and follow the prompts: + ```bash + clearml-init + ``` - ```bash - clearml-init - ``` - -That's it! You're done 😎 +That's it! You're ready to integrate ClearML with your YOLOv5 projects 😎. For a general Ultralytics setup, see the [Quickstart Guide](https://docs.ultralytics.com/quickstart/). ## 🚀 Training YOLOv5 With ClearML -To enable ClearML experiment tracking, simply install the ClearML pip package. - -```bash -pip install clearml -``` - -This will enable integration with the YOLOv5 training script. Every training run from now on, will be captured and stored by the ClearML experiment manager. - -If you want to change the `project_name` or `task_name`, use the `--project` and `--name` arguments of the `train.py` script, by default the project will be called `YOLOv5` and the task `Training`. PLEASE NOTE: ClearML uses `/` as a delimiter for subprojects, so be careful when using `/` in your project name! +ClearML experiment tracking is automatically enabled when the `clearml` package is installed. Every YOLOv5 [training run](https://docs.ultralytics.com/modes/train/) will be captured and stored in the ClearML experiment manager. + +To customize the project or task name in ClearML, use the `--project` and `--name` arguments when running `train.py`. By default, the project is `YOLOv5` and the task is `Training`. Note that ClearML uses `/` as a delimiter for subprojects. + +**Example Training Command:** ```bash +# Train YOLOv5s on COCO128 dataset for 3 epochs python train.py --img 640 --batch 16 --epochs 3 --data coco128.yaml --weights yolov5s.pt --cache ``` -or with custom project and task name: +**Example with Custom Project and Task Names:** ```bash -python train.py --project my_project --name my_training --img 640 --batch 16 --epochs 3 --data coco128.yaml --weights yolov5s.pt --cache +# Train with custom names +python train.py --project my_yolo_project --name experiment_001 --img 640 --batch 16 --epochs 3 --data coco128.yaml --weights yolov5s.pt --cache ``` -This will capture: +ClearML automatically captures comprehensive information about your training run: -- Source code + uncommitted changes -- Installed packages -- (Hyper)parameters -- Model files (use `--save-period n` to save a checkpoint every n epochs) -- Console output -- Scalars (mAP_0.5, mAP_0.5:0.95, precision, recall, losses, learning rates, ...) -- General info such as machine details, runtime, creation date etc. -- All produced plots such as label correlogram and confusion matrix -- Images with bounding boxes per epoch -- Mosaic per epoch -- Validation images per epoch -- ... +- Source code and uncommitted changes +- Installed Python packages +- Hyperparameters and configuration settings +- Model checkpoints (use `--save-period n` to save every `n` epochs) +- Console output logs +- Performance metrics ([mAP_0.5](https://docs.ultralytics.com/guides/yolo-performance-metrics/), mAP_0.5:0.95, [precision, recall](https://docs.ultralytics.com/guides/yolo-performance-metrics/), [losses](https://docs.ultralytics.com/reference/utils/loss/), [learning rates](https://www.ultralytics.com/glossary/learning-rate), etc.) +- System details (machine specs, runtime, creation date) +- Generated plots (e.g., label correlogram, [confusion matrix](https://www.ultralytics.com/glossary/confusion-matrix)) +- Images with bounding boxes per epoch +- Mosaic augmentation previews per epoch +- Validation images per epoch -That's a lot right? 🤯 Now, we can visualize all of this information in the ClearML UI to get an overview of our training progress. Add custom columns to the table view (such as e.g. mAP_0.5) so you can easily sort on the best performing model. Or select multiple experiments and directly compare them! - -There even more we can do with all of this information, like hyperparameter optimization and remote execution, so keep reading if you want to see how that works! +This wealth of information 🤯 can be visualized in the ClearML UI. You can customize table views, sort experiments by metrics like mAP, and directly compare multiple runs. This detailed tracking enables advanced features like hyperparameter optimization and remote execution. ## 🔗 Dataset Version Management -Versioning your data separately from your code is generally a good idea and makes it easy to acquire the latest version too. This repository supports supplying a dataset version ID, and it will make sure to get the data if it's not there yet. Next to that, this workflow also saves the used dataset ID as part of the task parameters, so you will always know for sure which data was used in which experiment! +Versioning your [datasets](https://docs.ultralytics.com/datasets/) separately from code is crucial for reproducibility and collaboration. ClearML's Data Versioning Tool helps manage this process. YOLOv5 supports using ClearML dataset version IDs, automatically downloading the data if needed. The dataset ID used is saved as a task parameter, ensuring you always know which data version was used for each experiment. ![ClearML Dataset Interface](https://raw.githubusercontent.com/thepycoder/clearml_screenshots/main/clearml_data.gif) ### Prepare Your Dataset -The YOLOv5 repository supports a number of different datasets by using yaml files containing their information. By default datasets are downloaded to the `../datasets` folder in relation to the repository root folder. So if you downloaded the `coco128` dataset using the link in the yaml or with the scripts provided by yolov5, you get this folder structure: +YOLOv5 uses [YAML](https://www.ultralytics.com/glossary/yaml) files to define dataset configurations. By default, datasets are expected in the `../datasets` directory relative to the repository root. For example, the [COCO128 dataset](https://docs.ultralytics.com/datasets/detect/coco128/) structure looks like this: ``` -.. -|_ yolov5 -|_ datasets - |_ coco128 - |_ images - |_ labels - |_ LICENSE - |_ README.txt +../ +├── yolov5/ # Your YOLOv5 repository clone +└── datasets/ + └── coco128/ + ├── images/ + ├── labels/ + ├── LICENSE + └── README.txt ``` -But this can be any dataset you wish. Feel free to use your own, as long as you keep to this folder structure. +Ensure your custom dataset follows a similar structure. -Next, ⚠️**copy the corresponding yaml file to the root of the dataset folder**⚠️. This yaml files contains the information ClearML will need to properly use the dataset. You can make this yourself too, of course, just follow the structure of the example yamls. - -Basically we need the following keys: `path`, `train`, `test`, `val`, `nc`, `names`. +Next, ⚠️**copy the corresponding dataset `.yaml` file into the root of your dataset folder**⚠️. This file contains essential information (`path`, `train`, `test`, `val`, `nc`, `names`) that ClearML needs. ``` -.. -|_ yolov5 -|_ datasets - |_ coco128 - |_ images - |_ labels - |_ coco128.yaml # <---- HERE! - |_ LICENSE - |_ README.txt +../ +└── datasets/ + └── coco128/ + ├── images/ + ├── labels/ + ├── coco128.yaml # <---- Place the YAML file here! + ├── LICENSE + └── README.txt ``` ### Upload Your Dataset -To get this dataset into ClearML as a versioned dataset, go to the dataset root folder and run the following command: +Navigate to your dataset's root directory in the terminal and use the `clearml-data` CLI tool to upload it: ```bash -cd coco128 -clearml-data sync --project YOLOv5 --name coco128 --folder . +cd ../datasets/coco128 +clearml-data sync --project YOLOv5_Datasets --name coco128 --folder . ``` -The command `clearml-data sync` is actually a shorthand command. You could also run these commands one after the other: +Alternatively, you can use the following commands: ```bash -# Optionally add --parent if you want to base -# this version on another dataset version, so no duplicate files are uploaded! -clearml-data create --name coco128 --project YOLOv5 +# Create a new dataset entry in ClearML +clearml-data create --project YOLOv5_Datasets --name coco128 + +# Add the dataset files (use '.' for the current directory) clearml-data add --files . + +# Finalize and upload the dataset version clearml-data close ``` +*Tip: Use `--parent ` with `clearml-data create` to link versions and avoid re-uploading unchanged files.* -### Run Training Using A ClearML Dataset +### Run Training Using a ClearML Dataset -Now that you have a ClearML dataset, you can very simply use it to train custom YOLOv5 🚀 models! +Once your dataset is versioned in ClearML, you can easily use it for training by providing the dataset ID via the `--data` argument with the `clearml://` prefix: ```bash -python train.py --img 640 --batch 16 --epochs 3 --data clearml:// yolov5s.pt --cache YOUR_DATASET_ID --weights +# Replace YOUR_DATASET_ID with the actual ID from ClearML +python train.py --img 640 --batch 16 --epochs 3 --data clearml://YOUR_DATASET_ID --weights yolov5s.pt --cache ``` ## 👀 Hyperparameter Optimization -Now that we have our experiments and data versioned, it's time to take a look at what we can build on top! +With experiments and data versioned, you can leverage ClearML for [Hyperparameter Optimization (HPO)](https://docs.ultralytics.com/guides/hyperparameter-tuning/). Since ClearML captures all necessary information (code, packages, environment), experiments are fully reproducible. ClearML's HPO tools clone an existing experiment, modify its hyperparameters, and automatically rerun it. -Using the code information, installed packages and environment details, the experiment itself is now **completely reproducible**. In fact, ClearML allows you to clone an experiment and even change its parameters. We can then just rerun it with these new parameters automatically, this is basically what HPO does! - -To **run hyperparameter optimization locally**, we've included a pre-made script for you. Just make sure a training task has been run at least once, so it is in the ClearML experiment manager, we will essentially clone it and change its hyperparameters. - -You'll need to fill in the ID of this `template task` in the script found at `utils/loggers/clearml/hpo.py` and then just run it :) You can change `task.execute_locally()` to `task.execute()` to put it in a ClearML queue and have a remote agent work on it instead. +To run HPO locally, use the provided script `utils/loggers/clearml/hpo.py`. You'll need the ID of a previously run training task (the "template task") to clone. Update the script with this ID and run it. ```bash -# To use optuna, install it first, otherwise you can change the optimizer to just be RandomSearch -pip install optuna +# Install Optuna for advanced optimization strategies (optional) +# pip install optuna + +# Run the HPO script python utils/loggers/clearml/hpo.py ``` -![HPO](https://raw.githubusercontent.com/thepycoder/clearml_screenshots/main/hpo.png) +The script uses [Optuna](https://optuna.org/) by default if installed; otherwise, it falls back to `RandomSearch`. You can modify `task.execute_locally()` to `task.execute()` in the script to enqueue the HPO tasks for a remote ClearML agent. -## 🤯 Remote Execution (advanced) +![HPO in ClearML UI](https://raw.githubusercontent.com/thepycoder/clearml_screenshots/main/hpo.png) -Running HPO locally is really handy, but what if we want to run our experiments on a remote machine instead? Maybe you have access to a very powerful GPU machine on-site, or you have some budget to use cloud GPUs. This is where the ClearML Agent comes into play. Check out what the agent can do here: +## 🤯 Remote Execution (Advanced) -- [YouTube video](https://www.youtube.com/watch?v=MX3BrXnaULs&feature=youtu.be) -- [Documentation](https://clear.ml/docs/latest/docs/clearml_agent) +ClearML Agent allows you to execute experiments on remote machines (e.g., powerful on-site servers, cloud GPUs like [AWS](https://aws.amazon.com/), [GCP](https://cloud.google.com/), or [Azure](https://azure.microsoft.com/)). The agent listens to task queues, reproduces the experiment environment, runs the task, and reports results back to the ClearML server. -In short: every experiment tracked by the experiment manager contains enough information to reproduce it on a different machine (installed packages, uncommitted changes etc.). So a ClearML agent does just that: it listens to a queue for incoming tasks and when it finds one, it recreates the environment and runs it while still reporting scalars, plots etc. to the experiment manager. +Learn more about ClearML Agent: -You can turn any machine (a cloud VM, a local GPU machine, your own laptop ... ) into a ClearML agent by simply running: +- [YouTube Introduction](https://www.youtube.com/watch?v=MX3BrXnaULs) +- [Official Documentation](https://clear.ml/docs/latest/docs/clearml_agent) + +Turn any machine into a ClearML agent by running: ```bash -clearml-agent daemon --queue QUEUES_TO_LISTEN_TO [--docker] +# Replace QUEUES_TO_LISTEN_TO with the name(s) of your queue(s) +clearml-agent daemon --queue QUEUES_TO_LISTEN_TO [--docker] # Use --docker to run in a Docker container ``` -### Cloning, Editing And Enqueuing +### Cloning, Editing, and Enqueuing Tasks -With our agent running, we can give it some work. Remember from the HPO section that we can clone a task and edit the hyperparameters? We can do that from the interface too! +You can manage remote execution directly from the ClearML web UI: -🪄 Clone the experiment by right-clicking it +1. **Clone:** Right-click an existing experiment to clone it. +2. **Edit:** Modify hyperparameters or other settings as needed in the cloned task. +3. **Enqueue:** Right-click the modified task and select "Enqueue" to assign it to a specific queue for an agent to pick up. -🎯 Edit the hyperparameters to what you wish them to be +![Enqueue a task from the ClearML UI](https://raw.githubusercontent.com/thepycoder/clearml_screenshots/main/enqueue.gif) -⏳ Enqueue the task to any of the queues by right-clicking it +### Executing a Task Remotely via Code -![Enqueue a task from the UI](https://raw.githubusercontent.com/thepycoder/clearml_screenshots/main/enqueue.gif) - -### Executing A Task Remotely - -Now you can clone a task like we explained above, or simply mark your current script by adding `task.execute_remotely()` and on execution it will be put into a queue, for the agent to start working on! - -To run the YOLOv5 training script remotely, all you have to do is add this line to the training.py script after the clearml logger has been instantiated: +Alternatively, you can modify your training script to automatically enqueue tasks for remote execution. Add `task.execute_remotely()` after the ClearML logger is initialized in `train.py`: ```python -# ... -# Loggers -data_dict = None +# Inside train.py, after logger initialization... if RANK in {-1, 0}: - loggers = Loggers(save_dir, weights, opt, hyp, LOGGER) # loggers instance + # Initialize loggers + loggers = Loggers(save_dir, weights, opt, hyp, LOGGER) + + # Check if ClearML logger is active and enqueue the task if loggers.clearml: - loggers.clearml.task.execute_remotely(queue="my_queue") # <------ ADD THIS LINE - # Data_dict is either None is user did not choose for ClearML dataset or is filled in by ClearML + # Specify the queue name for the remote agent + loggers.clearml.task.execute_remotely(queue_name="my_remote_queue") # <------ ADD THIS LINE + # data_dict might be populated by ClearML if using a ClearML dataset data_dict = loggers.clearml.data_dict -# ... ``` -When running the training script after this change, python will run the script up until that line, after which it will package the code and send it to the queue instead! +Running the script with this modification will package the code and its environment and send it to the specified queue, rather than executing locally. -### Autoscaling workers +### Autoscaling Workers -ClearML comes with autoscalers too! This tool will automatically spin up new remote machines in the cloud of your choice (AWS, GCP, Azure) and turn them into ClearML agents for you whenever there are experiments detected in the queue. Once the tasks are processed, the autoscaler will automatically shut down the remote machines, and you stop paying! +ClearML also provides Autoscalers that automatically manage cloud resources (AWS, GCP, Azure). They spin up new virtual machines and configure them as ClearML agents when tasks appear in a queue, then shut them down when the queue is empty, optimizing cost. -Check out the autoscalers getting started video below. +Watch the Autoscalers getting started video: -[![Watch the video](https://img.youtube.com/vi/j4XVMAaUt3E/0.jpg)](https://youtu.be/j4XVMAaUt3E) +[![Watch the ClearML Autoscalers video](https://img.youtube.com/vi/j4XVMAaUt3E/0.jpg)](https://youtu.be/j4XVMAaUt3E) + +## 🤝 Contributing + +Contributions to enhance the ClearML integration are welcome! Please see the [Ultralytics Contributing Guide](https://docs.ultralytics.com/help/contributing/) for more information on how to get involved. diff --git a/utils/loggers/clearml/clearml_utils.py b/utils/loggers/clearml/clearml_utils.py index 67553bdb4..5969e9657 100644 --- a/utils/loggers/clearml/clearml_utils.py +++ b/utils/loggers/clearml/clearml_utils.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """Main Logger class for ClearML experiment tracking.""" import glob diff --git a/utils/loggers/comet/README.md b/utils/loggers/comet/README.md index 353698dd4..b0b1c297e 100644 --- a/utils/loggers/comet/README.md +++ b/utils/loggers/comet/README.md @@ -1,104 +1,112 @@ +Ultralytics logo + -# YOLOv5 with Comet +# Using YOLOv5 with Comet -This guide will cover how to use YOLOv5 with [Comet](https://bit.ly/yolov5-readme-comet2) +Welcome to the guide on integrating [Ultralytics YOLOv5](https://github.com/ultralytics/yolov5) with [Comet](https://www.comet.com/site/?utm_source=yolov5&utm_medium=partner&utm_campaign=partner_yolov5_2022&utm_content=github_readme)! Comet provides powerful tools for experiment tracking, model management, and visualization, enhancing your machine learning workflow. This document details how to leverage Comet to monitor training, log results, manage datasets, and optimize hyperparameters for your YOLOv5 models. -# About Comet +## 🧪 About Comet -Comet builds tools that help data scientists, engineers, and team leaders accelerate and optimize machine learning and deep learning models. +[Comet](https://www.comet.com/site/?utm_source=yolov5&utm_medium=partner&utm_campaign=partner_yolov5_2022&utm_content=github_readme) builds tools that help data scientists, engineers, and team leaders accelerate and optimize machine learning and deep learning models. -Track and visualize model metrics in real time, save your hyperparameters, datasets, and model checkpoints, and visualize your model predictions with [Comet Custom Panels](https://www.comet.com/docs/v2/guides/comet-dashboard/code-panels/about-panels/?utm_source=yolov5&utm_medium=partner&utm_campaign=partner_yolov5_2022&utm_content=github)! Comet makes sure you never lose track of your work and makes it easy to share results and collaborate across teams of all sizes! +Track and visualize model metrics in real-time, save your hyperparameters, datasets, and model checkpoints, and visualize your model predictions with [Comet Custom Panels](https://www.comet.com/docs/v2/guides/comet-dashboard/code-panels/about-panels/?utm_source=yolov5&utm_medium=partner&utm_campaign=partner_yolov5_2022&utm_content=github_readme)! Comet ensures you never lose track of your work and makes it easy to share results and collaborate across teams of all sizes. -# Getting Started +## 🚀 Getting Started -## Install Comet +Follow these steps to set up Comet for your YOLOv5 projects. + +### Install Comet + +Install the necessary [Python package](https://pypi.org/project/comet-ml/) using pip: ```shell pip install comet_ml ``` -## Configure Comet Credentials +### Configure Comet Credentials -There are two ways to configure Comet with YOLOv5. +You can configure Comet in two ways: -You can either set your credentials through environment variables +1. **Environment Variables:** Set your credentials directly in your environment. + ```shell + export COMET_API_KEY= + export COMET_PROJECT_NAME= # Defaults to 'yolov5' if not set + ``` + Find your API key in your [Comet Account Settings](https://www.comet.com/docs/v2/guides/getting-started/quickstart/#get-an-api-key?utm_source=yolov5&utm_medium=partner&utm_campaign=partner_yolov5_2022&utm_content=github_readme). -**Environment Variables** +2. **Configuration File:** Create a `.comet.config` file in your working directory with the following content: + ```ini + [comet] + api_key= + project_name= # Defaults to 'yolov5' if not set + ``` -```shell -export COMET_API_KEY= -export COMET_PROJECT_NAME= # This will default to 'yolov5' -``` +### Run the Training Script -Or create a `.comet.config` file in your working directory and set your credentials there. - -**Comet Configuration File** - -``` -[comet] -api_key= -project_name= # This will default to 'yolov5' -``` - -## Run the Training Script +Execute the YOLOv5 training script. Comet will automatically start logging your run. ```shell # Train YOLOv5s on COCO128 for 5 epochs python train.py --img 640 --batch 16 --epochs 5 --data coco128.yaml --weights yolov5s.pt ``` -That's it! Comet will automatically log your hyperparameters, command line arguments, training and validation metrics. You can visualize and analyze your runs in the Comet UI +That's it! Comet automatically logs hyperparameters, command-line arguments, and training/validation metrics. Visualize and analyze your runs in the Comet UI. For more details on training, see the [YOLOv5 Train documentation](https://docs.ultralytics.com/yolov5/tutorials/train_custom_data/). -yolo-ui +Comet UI showing YOLOv5 training metrics -# Try out an Example! +## ✨ Try an Example! -Check out an example of a [completed run here](https://www.comet.com/examples/comet-example-yolov5/a0e29e0e9b984e4a822db2a62d0cb357?experiment-tab=chart&showOutliers=true&smoothing=0&transformY=smoothing&xAxis=step&utm_source=yolov5&utm_medium=partner&utm_campaign=partner_yolov5_2022&utm_content=github) +Explore a completed YOLOv5 training run tracked with Comet: -Or better yet, try it out yourself in this Colab Notebook +- **[View Example Run on Comet](https://www.comet.com/examples/comet-example-yolov5/a0e29e0e9b984e4a822db2a62d0cb357?experiment-tab=chart&showOutliers=true&smoothing=0&transformY=smoothing&xAxis=step&utm_source=yolov5&utm_medium=partner&utm_campaign=partner_yolov5_2022&utm_content=github_readme)** + +Run the example yourself using this [Google Colab](https://colab.research.google.com/) Notebook: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/comet-ml/comet-examples/blob/master/integrations/model-training/yolov5/notebooks/Comet_and_YOLOv5.ipynb) -# Log automatically +## 📊 Automatic Logging -By default, Comet will log the following items +Comet automatically logs the following information by default: -## Metrics +### Metrics -- Box Loss, Object Loss, Classification Loss for the training and validation data -- mAP_0.5, mAP_0.5:0.95 metrics for the validation data. -- Precision and Recall for the validation data +- **Losses:** Box Loss, Object Loss, Classification Loss (Training and Validation). +- **Performance:** [mAP@0.5](https://docs.ultralytics.com/guides/yolo-performance-metrics/), mAP@0.5:0.95 (Validation). +- **Precision and Recall:** Validation data metrics. -## Parameters +### Parameters -- Model Hyperparameters -- All parameters passed through the command line options +- **Model Hyperparameters:** Configuration used for the model. +- **Command Line Arguments:** All arguments passed via the CLI. -## Visualizations +### Visualizations -- Confusion Matrix of the model predictions on the validation data -- Plots for the PR and F1 curves across all classes -- Correlogram of the Class Labels +- **[Confusion Matrix](https://en.wikipedia.org/wiki/Confusion_matrix):** Model predictions on validation data. +- **Curves:** PR and F1 curves across all classes. +- **Label Correlogram:** Correlation visualization of class labels. -# Configure Comet Logging +## ⚙️ Advanced Configuration -Comet can be configured to log additional data either through command line flags passed to the training script or through environment variables. +Customize Comet's logging behavior using command-line flags or environment variables. ```shell -export COMET_MODE=online # Set whether to run Comet in 'online' or 'offline' mode. Defaults to online -export COMET_MODEL_NAME= #Set the name for the saved model. Defaults to yolov5 -export COMET_LOG_CONFUSION_MATRIX=false # Set to disable logging a Comet Confusion Matrix. Defaults to true -export COMET_MAX_IMAGE_UPLOADS= # Controls how many total image predictions to log to Comet. Defaults to 100. -export COMET_LOG_PER_CLASS_METRICS=true # Set to log evaluation metrics for each detected class at the end of training. Defaults to false -export COMET_DEFAULT_CHECKPOINT_FILENAME= # Set this if you would like to resume training from a different checkpoint. Defaults to 'last.pt' -export COMET_LOG_BATCH_LEVEL_METRICS=true # Set this if you would like to log training metrics at the batch level. Defaults to false. -export COMET_LOG_PREDICTIONS=true # Set this to false to disable logging model predictions +# Environment Variables for Comet Configuration +export COMET_MODE=online # 'online' or 'offline'. Default: online +export COMET_MODEL_NAME= # Name for the saved model. Default: yolov5 +export COMET_LOG_CONFUSION_MATRIX=false # Disable confusion matrix logging. Default: true +export COMET_MAX_IMAGE_UPLOADS= # Max prediction images to log. Default: 100 +export COMET_LOG_PER_CLASS_METRICS=true # Log metrics per class. Default: false +export COMET_DEFAULT_CHECKPOINT_FILENAME= # Checkpoint for resuming. Default: 'last.pt' +export COMET_LOG_BATCH_LEVEL_METRICS=true # Log training metrics per batch. Default: false +export COMET_LOG_PREDICTIONS=true # Disable prediction logging if set to false. Default: true ``` -## Logging Checkpoints with Comet +Refer to the [Comet documentation](https://www.comet.com/docs/v2/guides/experiment-logging/configure-comet/?utm_source=yolov5&utm_medium=partner&utm_campaign=partner_yolov5_2022&utm_content=github_readme) for more configuration options. -Logging Models to Comet is disabled by default. To enable it, pass the `save-period` argument to the training script. This will save the logged checkpoints to Comet based on the interval value provided by `save-period` +### Logging Checkpoints with Comet + +Model checkpoint logging to Comet is disabled by default. Enable it using the `--save-period` argument during training. This saves checkpoints to Comet at the specified epoch interval. ```shell python train.py \ @@ -107,18 +115,18 @@ python train.py \ --epochs 5 \ --data coco128.yaml \ --weights yolov5s.pt \ - --save-period 1 + --save-period 1 # Save checkpoint every epoch ``` -## Logging Model Predictions +Checkpoints will appear in the "Assets & Artifacts" tab of your Comet experiment. Learn more about model management in the [Comet Model Registry](https://www.comet.com/docs/v2/guides/model-registry/overview/?utm_source=yolov5&utm_medium=partner&utm_campaign=partner_yolov5_2022&utm_content=github_readme). -By default, model predictions (images, ground truth labels and bounding boxes) will be logged to Comet. +### Logging Model Predictions -You can control the frequency of logged predictions and the associated images by passing the `bbox_interval` command line argument. Predictions can be visualized using Comet's Object Detection Custom Panel. This frequency corresponds to every Nth batch of data per epoch. In the example below, we are logging every 2nd batch of data for each epoch. +By default, model predictions (images, ground truth labels, bounding boxes) for the validation set are logged. Control the logging frequency using the `--bbox_interval` argument, which specifies logging every Nth batch per epoch. -**Note:** The YOLOv5 validation dataloader will default to a batch size of 32, so you will have to set the logging frequency accordingly. +**Note:** The YOLOv5 validation dataloader defaults to a batch size of 32. Adjust `--bbox_interval` accordingly. -Here is an [example project using the Panel](https://www.comet.com/examples/comet-example-yolov5?shareable=YcwMiJaZSXfcEXpGOHDD12vA1&utm_source=yolov5&utm_medium=partner&utm_campaign=partner_yolov5_2022&utm_content=github) +Visualize predictions using Comet's [Object Detection Custom Panel](https://www.comet.com/docs/v2/guides/comet-dashboard/built-in-panels/object-detection-panel/?utm_source=yolov5&utm_medium=partner&utm_campaign=partner_yolov5_2022&utm_content=github_readme). See an [example project using the Panel here](https://www.comet.com/examples/comet-example-yolov5?shareable=YcwMiJaZSXfcEXpGOHDD12vA1&utm_source=yolov5&utm_medium=partner&utm_campaign=partner_yolov5_2022&utm_content=github_readme). ```shell python train.py \ @@ -127,12 +135,12 @@ python train.py \ --epochs 5 \ --data coco128.yaml \ --weights yolov5s.pt \ - --bbox_interval 2 + --bbox_interval 2 # Log predictions every 2nd validation batch per epoch ``` -### Controlling the number of Prediction Images logged to Comet +#### Controlling the Number of Prediction Images -When logging predictions from YOLOv5, Comet will log the images associated with each set of predictions. By default a maximum of 100 validation images are logged. You can increase or decrease this number using the `COMET_MAX_IMAGE_UPLOADS` environment variable. +Adjust the maximum number of validation images logged using the `COMET_MAX_IMAGE_UPLOADS` environment variable. ```shell env COMET_MAX_IMAGE_UPLOADS=200 python train.py \ @@ -141,12 +149,12 @@ env COMET_MAX_IMAGE_UPLOADS=200 python train.py \ --epochs 5 \ --data coco128.yaml \ --weights yolov5s.pt \ - --bbox_interval 1 + --bbox_interval 1 # Log every batch ``` ### Logging Class Level Metrics -Use the `COMET_LOG_PER_CLASS_METRICS` environment variable to log mAP, precision, recall, f1 for each class. +Enable logging of mAP, precision, recall, and F1-score for each class using the `COMET_LOG_PER_CLASS_METRICS` environment variable. ```shell env COMET_LOG_PER_CLASS_METRICS=true python train.py \ @@ -157,11 +165,13 @@ env COMET_LOG_PER_CLASS_METRICS=true python train.py \ --weights yolov5s.pt ``` -## Uploading a Dataset to Comet Artifacts +## 💾 Dataset Management with Comet Artifacts -If you would like to store your data using [Comet Artifacts](https://www.comet.com/docs/v2/guides/data-management/using-artifacts/#learn-more?utm_source=yolov5&utm_medium=partner&utm_campaign=partner_yolov5_2022&utm_content=github), you can do so using the `upload_dataset` flag. +Use [Comet Artifacts](https://www.comet.com/docs/v2/guides/data-management/using-artifacts/?utm_source=yolov5&utm_medium=partner&utm_campaign=partner_yolov5_2022&utm_content=github_readme) to version, store, and manage your datasets. -The dataset be organized in the way described in the [YOLOv5 documentation](https://docs.ultralytics.com/yolov5/tutorials/train_custom_data/). The dataset config `yaml` file must follow the same format as that of the `coco128.yaml` file. +### Uploading a Dataset + +Upload your dataset using the `--upload_dataset` flag. Ensure your dataset follows the structure described in the [YOLOv5 documentation](https://docs.ultralytics.com/yolov5/tutorials/train_custom_data/) and the dataset config [YAML](https://yaml.org/) file matches the format of `coco128.yaml`. ```shell python train.py \ @@ -170,25 +180,32 @@ python train.py \ --epochs 5 \ --data coco128.yaml \ --weights yolov5s.pt \ - --upload_dataset + --upload_dataset # Upload the dataset specified in coco128.yaml ``` -You can find the uploaded dataset in the Artifacts tab in your Comet Workspace artifact-1 +View the uploaded dataset in the Artifacts tab of your Comet Workspace. +Comet Artifacts tab showing uploaded dataset -You can preview the data directly in the Comet UI. artifact-2 +Preview data directly in the Comet UI. +Comet UI previewing dataset images -Artifacts are versioned and also support adding metadata about the dataset. Comet will automatically log the metadata from your dataset `yaml` file artifact-3 +Artifacts are versioned and support metadata. Comet automatically logs metadata from your dataset `yaml` file. +Comet Artifact metadata view -### Using a saved Artifact +### Using a Saved Artifact -If you would like to use a dataset from Comet Artifacts, set the `path` variable in your dataset `yaml` file to point to the following Artifact resource URL. +To use a dataset stored in Comet Artifacts, update the `path` in your dataset `yaml` file to the Artifact resource URL: -``` -# contents of artifact.yaml file -path: "comet:///:" +```yaml +# contents of artifact.yaml +path: "comet:///:" +train: images/train # Adjust subdirectory if needed +val: images/val # Adjust subdirectory if needed + +# Other dataset configurations... ``` -Then pass this file to your training script in the following way +Then, pass this configuration file to your training script: ```shell python train.py \ @@ -199,35 +216,36 @@ python train.py \ --weights yolov5s.pt ``` -Artifacts also allow you to track the lineage of data as it flows through your Experimentation workflow. Here you can see a graph that shows you all the experiments that have used your uploaded dataset. artifact-4 +Artifacts track data lineage, showing which experiments used specific dataset versions. +Comet Artifact lineage graph -## Resuming a Training Run +## 🔄 Resuming Training Runs -If your training run is interrupted for any reason, e.g. disrupted internet connection, you can resume the run using the `resume` flag and the Comet Run Path. +If a training run is interrupted (e.g., due to connection issues), you can resume it using the `--resume` flag with the Comet Run Path (`comet:////`). -The Run Path has the following format `comet:////`. - -This will restore the run to its state before the interruption, which includes restoring the model from a checkpoint, restoring all hyperparameters and training arguments and downloading Comet dataset Artifacts if they were used in the original run. The resumed run will continue logging to the existing Experiment in the Comet UI +This restores the model state, hyperparameters, arguments, and downloads necessary Artifacts, continuing logging to the existing Comet Experiment. Learn more about [resuming runs in Comet](https://www.comet.com/docs/v2/guides/experiment-logging/resume-experiment/?utm_source=yolov5&utm_medium=partner&utm_campaign=partner_yolov5_2022&utm_content=github_readme). ```shell python train.py \ - --resume "comet://" + --resume "comet:////" ``` -## Hyperparameter Search with the Comet Optimizer +## 🔍 Hyperparameter Optimization (HPO) -YOLOv5 is also integrated with Comet's Optimizer, making is simple to visualize hyperparameter sweeps in the Comet UI. +YOLOv5 integrates with the [Comet Optimizer](https://www.comet.com/docs/v2/guides/hyperparameter-optimization/overview/?utm_source=yolov5&utm_medium=partner&utm_campaign=partner_yolov5_2022&utm_content=github_readme) for easy hyperparameter sweeps and visualization. This helps in finding the best set of parameters for your model, a process often referred to as [Hyperparameter Tuning](https://docs.ultralytics.com/guides/hyperparameter-tuning/). ### Configuring an Optimizer Sweep -To configure the Comet Optimizer, you will have to create a JSON file with the information about the sweep. An example file has been provided in `utils/loggers/comet/optimizer_config.json` +Create a [JSON](https://www.json.org/json-en.html) configuration file defining the sweep parameters, search strategy, and objective metric. An example is provided at `utils/loggers/comet/optimizer_config.json`. + +Run the sweep using the `hpo.py` script: ```shell python utils/loggers/comet/hpo.py \ --comet_optimizer_config "utils/loggers/comet/optimizer_config.json" ``` -The `hpo.py` script accepts the same arguments as `train.py`. If you wish to pass additional arguments to your sweep simply add them after the script. +The `hpo.py` script accepts the same arguments as `train.py`. Pass additional fixed arguments for the sweep: ```shell python utils/loggers/comet/hpo.py \ @@ -238,13 +256,21 @@ python utils/loggers/comet/hpo.py \ ### Running a Sweep in Parallel +Execute multiple sweep trials concurrently using the `comet optimizer` command: + ```shell -comet optimizer -j utils/loggers/comet/hpo.py \ - utils/loggers/comet/optimizer_config.json" +comet optimizer -j utils/loggers/comet/hpo.py \ + utils/loggers/comet/optimizer_config.json ``` -### Visualizing Results +Replace `` with the desired number of parallel processes. -Comet provides a number of ways to visualize the results of your sweep. Take a look at a [project with a completed sweep here](https://www.comet.com/examples/comet-example-yolov5/view/PrlArHGuuhDTKC1UuBmTtOSXD/panels?utm_source=yolov5&utm_medium=partner&utm_campaign=partner_yolov5_2022&utm_content=github) +### Visualizing HPO Results -hyperparameter-yolo +Comet offers various visualizations for analyzing sweep results, such as parallel coordinate plots and parameter importance plots. Explore a [project with a completed sweep here](https://www.comet.com/examples/comet-example-yolov5/view/PrlArHGuuhDTKC1UuBmTtOSXD/panels?utm_source=yolov5&utm_medium=partner&utm_campaign=partner_yolov5_2022&utm_content=github_readme). + +Comet HPO visualization + +## 🤝 Contributing + +Contributions to enhance the YOLOv5-Comet integration are welcome! Please see the [Ultralytics Contributing Guide](https://docs.ultralytics.com/help/contributing/) for more information on how to get involved. Thank you for helping improve this integration! diff --git a/utils/loss.py b/utils/loss.py index 35ce6d792..a1317b481 100644 --- a/utils/loss.py +++ b/utils/loss.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """Loss functions.""" import torch diff --git a/utils/metrics.py b/utils/metrics.py index 03013f4e3..e50eea0db 100644 --- a/utils/metrics.py +++ b/utils/metrics.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """Model validation metrics.""" import math diff --git a/utils/plots.py b/utils/plots.py index f70775f26..c3d604d71 100644 --- a/utils/plots.py +++ b/utils/plots.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """Plotting utils.""" import contextlib diff --git a/utils/segment/augmentations.py b/utils/segment/augmentations.py index 14a81cf7d..a530cd58b 100644 --- a/utils/segment/augmentations.py +++ b/utils/segment/augmentations.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """Image augmentation functions.""" import math diff --git a/utils/segment/dataloaders.py b/utils/segment/dataloaders.py index 2363d7265..7ed136e43 100644 --- a/utils/segment/dataloaders.py +++ b/utils/segment/dataloaders.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """Dataloaders.""" import os diff --git a/utils/segment/metrics.py b/utils/segment/metrics.py index 3bb7aeec4..6bd941efb 100644 --- a/utils/segment/metrics.py +++ b/utils/segment/metrics.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """Model validation metrics.""" import numpy as np diff --git a/utils/torch_utils.py b/utils/torch_utils.py index 8b3c43b5b..5090df7ad 100644 --- a/utils/torch_utils.py +++ b/utils/torch_utils.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """PyTorch utils.""" import math diff --git a/utils/triton.py b/utils/triton.py index 88c0bd7b2..69bf3f8c1 100644 --- a/utils/triton.py +++ b/utils/triton.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """Utils to interact with the Triton Inference Server.""" import typing diff --git a/val.py b/val.py index 600353b1c..2f959602f 100644 --- a/val.py +++ b/val.py @@ -1,4 +1,5 @@ # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license + """ Validate a trained YOLOv5 detection model on a detection dataset.