Sinapsis-Ultralytics

Templates to perform training, inference, validation and export operations for different computer vision tasks using Ultralytics models.

🐍 Installation • 🚀 Features • 📚 Usage example • 🌐 Webapp • 📙 Documentation • 🔍 License

The Sinapsis Ultralytics module provides templates for training, inference, validation and exporting models with Ultralytics.

🐍 Installation

Install using your package manager of choice. We encourage the use of uv

Example with uv:

  uv pip install sinapsis-ultralytics --extra-index-url https://pypi.sinapsis.tech

or with raw pip:

  pip install sinapsis-ultralytics --extra-index-url https://pypi.sinapsis.tech

with uv:

  uv pip install sinapsis-ultralytics[all] --extra-index-url https://pypi.sinapsis.tech

or with raw pip:

  pip install sinapsis-ultralytics[all] --extra-index-url https://pypi.sinapsis.tech

🚀 Features

Templates Supported

• UltralyticsTrain: Template for training Ultralytics models.

  Attributes

  • model_class(Required): The Ultralytics model class name. Options: YOLO, YOLOWorld, SAM, FastSAM, NAS, RTDETR.
  • model(Required): The model name or model path to be loaded.
  • task(Optional): The task to be performed by the model. Only needed by YOLO models if the task can't be obtained from the specified model name. Options: classify, detect, segment, pose, obb (default: None).
  • verbose(Optional): Whether to print verbose logs (default: False).
  • working_dir(Optional): The working directory for ultralytics. Ultralytics default models are downloaded to this directory (default :SINAPSIS_CACHE_DIR/ultralytics).
  • datasets_dir(Optional): The directory where the datasets are located. Ultralytics datasets ar downloaded to this directory (default: working_dir/datasets).
  • runs_dir(Optional): The directory where the training experiment artifacts are saved (default: working_dir/runs).
  • checkpoint_path(Optional): Optional explicit path to a checkpoint (pre-trained) model (default: None).
  • training_params(Optional): A dictionary containing the training parameters for the Ultralytics model. If not specified, default parameters will be used. The full documentation for available training parameters can be found in the Ultralytics docs.

• UltralyticsVal: Template for validating Ultralytics models.

  Attributes

  • model_class(Required): The Ultralytics model class name. Options: YOLO, YOLOWorld, SAM, FastSAM, NAS, RTDETR.
  • model(Required): The model name or model path to be loaded.
  • task(Optional): The task to be performed by the model. Only needed by YOLO models if the task can't be obtained from the specified model name. Options: classify, detect, segment, pose, obb (default: None).
  • verbose(Optional): Whether to print verbose logs (default: False).
  • working_dir(Optional): The working directory for ultralytics. Ultralytics default models are downloaded to this directory (default :SINAPSIS_CACHE_DIR/ultralytics).
  • datasets_dir(Optional): The directory where the datasets are located. Ultralytics datasets ar downloaded to this directory (default: working_dir/datasets).
  • runs_dir(Optional): The directory where the training experiment artifacts are saved (default: working_dir/runs).
  • checkpoint_path(Optional): Optional explicit path to a checkpoint (pre-trained) model (default: None).
  • validation_params(Optional): A dictionary containing the validation parameters for the Ultralytics model. If not specified, default parameters will be used. The full documentation for available validation parameters can be found in the Ultralytics docs.

• UltralyticsPredict: Template for generating inference predictions with trained models.

  Attributes

  • model_class(Required): The Ultralytics model class name. Options: YOLO, YOLOWorld, SAM, FastSAM, NAS, RTDETR.
  • model(Required): The model name or model path to be loaded.
  • task(Optional): The task to be performed by the model. Only needed by YOLO models if the task can't be obtained from the specified model name. Options: classify, detect, segment, pose, obb (default: None).
  • verbose(Optional): Whether to print verbose logs (default: False).
  • working_dir(Optional): The working directory for ultralytics. Ultralytics default models are downloaded to this directory (default :SINAPSIS_CACHE_DIR/ultralytics).
  • datasets_dir(Optional): The directory where the datasets are located. Ultralytics datasets ar downloaded to this directory (default: working_dir/datasets).
  • runs_dir(Optional): The directory where the training experiment artifacts are saved (default: working_dir/runs).
  • checkpoint_path(Optional): Optional explicit path to a checkpoint (pre-trained) model (default: None).
  • predict_params(Optional)**: A dictionary containing the inference parameters for the Ultralytics model. If not specified, default parameters will be used. The full documentation for available inference parameters can be found in the Ultralytics docs.
  • use_detections_as_sam_prompt(Optional): Whether to use the available detections as prompts for SAM model (default: False).

• UltralyticsExport: Template for exporting models to deployment-ready format.

  Attributes

  • model_class(Required): The Ultralytics model class name. Options: YOLO, YOLOWorld, SAM, FastSAM, NAS, RTDETR.
  • model(Required): The model name or model path to be loaded.
  • task(Optional): The task to be performed by the model. Only needed by YOLO models if the task can't be obtained from the specified model name. Options: classify, detect, segment, pose, obb (default: None).
  • verbose(Optional): Whether to print verbose logs (default: False).
  • working_dir(Optional): The working directory for ultralytics. Ultralytics default models are downloaded to this directory (default :SINAPSIS_CACHE_DIR/ultralytics).
  • datasets_dir(Optional): The directory where the datasets are located. Ultralytics datasets ar downloaded to this directory (default: working_dir/datasets).
  • runs_dir(Optional): The directory where the training experiment artifacts are saved (default: working_dir/runs).
  • checkpoint_path(Optional): Optional explicit path to a checkpoint (pre-trained) model (default: None).
  • export_params(Optional): A dictionary containing the export parameters for the Ultralytics model. If not specified, default parameters will be used. The full documentation for available export parameters can be found in the Ultralytics docs.

For example, for UltralyticsPredict use sinapsis info --example-template-config UltralyticsPredict to produce the following example config:

agent:
  name: my_test_agent
templates:
- template_name: InputTemplate
  class_name: InputTemplate
- template_name: UltralyticsPredict
  class_name: UltralyticsPredict
  template_input: InputTemplate
  attributes:
    model_class: 'YOLO'
    model: null
    task: null
    verbose: false
    working_dir: /path/to/sinapsis/cache
    datasets_dir: /path/to/sinapsis/cache/datasets
    run_id: null
    checkpoint_name: last.pt
    checkpoint_path: null
    predict_params: {}
    use_detections_as_sam_prompt: false

📚Usage example

The following example demonstrates how to use Sinapsis Ultralytics to use Ultralytics YOLO on a specific dataset. This setup loads a dataset of images, runs inferences with YOLO for detection, draws the bboxes and saves the results. Below is the full YAML configuration, followed by a breakdown of each component.

agent:
  name: inference_agent

templates:
- template_name: InputTemplate
  class_name: InputTemplate
  attributes: {}

- template_name: FolderImageDatasetCV2
  class_name: FolderImageDatasetCV2
  template_input: InputTemplate
  attributes:
    data_dir: my_dataset

- template_name: UltralyticsPredict
  class_name: UltralyticsPredict
  template_input: FolderImageDatasetCV2
  attributes:
    model_class: YOLO
    model: yolo11n.pt
    task: "detect"
    predict_params:
      classes: [0]

- template_name: BBoxDrawer
  class_name: BBoxDrawer
  template_input: UltralyticsPredict
  attributes:
    overwrite: true
    draw_classification_label: true
    randomized_color: false

- template_name: ImageSaver
  class_name: ImageSaver
  template_input: BBoxDrawer
  attributes:
    save_dir: results
    extension: jpg

This configuration defines an agent and a sequence of templates to run inferences on a dataset.

To run the config, use the CLI:

sinapsis run name_of_config.yml

🌐 Webapp

The module includes two Gradio web apps for testing both training and inference Ultralytics modules.

git clone git@github.com:Sinapsis-ai/sinapsis-ultralytics.git
cd sinapsis-ultralytics

docker compose -f docker/compose.yaml build

docker compose -f docker/compose_apps.yaml up sinapsis-ultralytics-inference -d

docker compose -f docker/compose_apps.yaml up sinapsis-ultralytics-train -d

docker logs -f sinapsis-ultralytics-inference

docker logs -f sinapsis-ultralytics-train

Running on local URL:  http://127.0.0.1:7860

docker compose -f docker/compose_apps.yaml down

uv sync --frozen

uv pip install sinapsis-object-detection[all] --extra-index-url https://pypi.sinapsis.tech

uv run webapps/inference_app.py

uv run webapps/training_app.py

Running on local URL:  http://127.0.0.1:7860

📙 Documentation

Documentation for this and other sinapsis packages is available on the sinapsis website

Tutorials for different projects within sinapsis are available at sinapsis tutorials page

🔍 License

This project is licensed under the AGPLv3 license, which encourages open collaboration and sharing. For more details, please refer to the LICENSE file.

For commercial use, please refer to our official Sinapsis website for information on obtaining a commercial license.