sinapsis-ultralytics 0.1.0

Package to build computer vision applications based on the Ultralytics library

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

🚀 Features

Templates Supported

• UltralyticsTrain: Template for training Ultralytics models.
• UltralyticsVal: Template for validating Ultralytics models.
• UltralyticsPredict: Template for generating inference predictions with trained models.
• UltralyticsExport: Template for exporting models to deployment-ready format.

🌍 General Attributes

All templates share the following attributes:

• model_class (Literal["YOLO", "YOLOWorld", "SAM", "FastSAM", "NAS", "RTDETR"], required): The Ultralytics model class name.
• model (str | Path, required): The model name or model path to be loaded.
• task (Literal["classify", "detect", "segment", "pose", "obb"], required): The task to be performed by the specified model.
• verbose (bool, optional): Whether to print verbose logs. Defaults to False.
• working_dir (str | Path, optional): The working directory for ultralytics. Ultralytics default models are downloaded to this directory. Defaults to SINAPSIS_CACHE_DIR/ultralytics.
• datasets_dir (str | Path, optional): The directory where the datasets are located. Ultralytics datasets ar downloaded to this directory. Defaults to working_dir/datasets.
• runs_dir (str | Path, optional): The directory where the training experiment artifacts are saved. Defaults to working_dir/runs.
• checkpoint_path (str | Path, optional): Optional explicit path to a checkpoint (pre-trained) model. Defaults to None.

Specific Attributes

There are some attributes specific to the templates used:

• UltralyticsTrain has one additional attribute:
  • training_params (dict, 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 has one additional attribute:
  • validation_params (dict, 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 has two additional attributes:
  • predict_params (dict, 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 (bool, optional): Whether to use the available detections as prompts for SAM model. Defaults to False.
• UltralyticsExport has one additional attribute:
  • export_params (dict, 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.

[!TIP] Use CLI command sinapsis info --all-template-names to show a list with all the available Template names installed with Sinapsis Ultralytics.

[!TIP] Use CLI command sinapsis info --example-template-config TEMPLATE_NAME to produce an example Agent config for the Template specified in TEMPLATE_NAME.

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.

Config

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.

[!IMPORTANT] The FolderImageDatasetCV2, BBoxDrawer and ImageSaver templates correspond to the sinapsis-data-readers, sinapsis-data-visualization and sinapsis-data-writers packages respectively. If you want to use the example, please make sure you install these packages.

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.

[!IMPORTANT] To run the app you first need to clone this repository:

git clone [e-mail]:Sinapsis-ai/sinapsis-ultralytics.git
cd sinapsis-ultralytics

[!NOTE] If you'd like to enable external app sharing in Gradio, export GRADIO_SHARE_APP=True

🐳 Docker

IMPORTANT This docker image depends on the sinapsis-nvidia:base image. Please refer to the official sinapsis instructions to Build with Docker.

1. Build the sinapsis-ultralytics image:

docker compose -f docker/compose.yaml build

2. Start the app container:

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

NOTE: if resources are not enough to test all tasks, please stop and restart the app.

NOTE : to start the inference app, change the service to sinapsis-ultralytics-inference

3. Check the status:

docker logs -f sinapsis-ultralytics-train

4. The logs will display the URL to access the webapp, e.g.:

NOTE: The url can be different, check the output of logs

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

5. To stop the app:

docker compose -f docker/compose_apps.yaml down

💻 UV

To run the webapp using the uv package manager, please:

1. Create the virtual environment and sync the dependencies:

uv sync --frozen

2. Install the wheel:

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

3. Run the webapp:

uv run webapps/training_app.py

Or, if you wish to try the inference app instead:

uv run webapps/inference_app.py

4. The terminal will display the URL to access the webapp, e.g.:

NOTE: The url can be different, check the output of the terminal

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.