Skip to main content

Visual Detector

Train an object detection model using a pipeline template

Input: Images and videos

Output: Regions

A visual detector is a deep fine-tuned model that identifies and localizes objects within images and video frames. It goes beyond image classification by answering not only "What is in this image?" but also "Where is it?"

For example, it can be used to detect and locate objects such as "car", "person", or "dog" within an image, drawing a bounding box around each identified instance.

pipeline template

A pipeline template is a pre-configured workflow that defines how a model is trained, evaluated, and deployed.

It is built on top of Clarifai Pipelines, which are the underlying system that orchestrates a sequence of steps (nodes) such as data processing, training, and evaluation. The template simply provides a ready-made, opinionated setup of these pipelines for a specific use case.

Instead of building everything from scratch, a pipeline template gives you a ready-made structure with:

  • Predefined steps (e.g., data loading, preprocessing, training, evaluation)
  • Default configurations (such as model architecture and training logic)
  • Tunable parameters (hyperparameters you can adjust to fit your use case)

In practical terms, it acts as a blueprint for your training process. For example, when you select the detector-pipeline-yolof template, you're choosing:

  • A pipeline designed for object detection
  • A YOLOF-based model architecture
  • A sequence of steps already wired together using Clarifai Pipelines to train on images with bounding box annotations

You may choose a visual detector model type in cases where:

  • Accuracy takes priority — you need precise object localization rather than a fast, general-purpose solution.
  • Your data is unique — existing Clarifai models don't detect the objects in your dataset, and you need to deep fine-tune a custom model integrated into your workflows.
  • You have the right ingredients — a custom dataset with bounding box annotations, and the time and expertise to fine-tune.
tip

Visual detectors are optimized for detection and localization tasks. If you only need to identify what is in an image without locating specific objects, consider a Visual Classifier instead.

Via the UI​

Let's walk through how to create and train a visual detector model using the UI.

Step 1: Create an App​

Create an application to store and manage your model and its associated resources (such as datasets, pipelines, and deployments). You can follow this guide to set one up.

Note: When creating the application, select the default Image/Video option as the primary input type.

Step 2: Prepare Training Data​

Preparing your data is a critical step in training a model. For object detection, your dataset must include images with bounding box annotations that mark where each object of interest appears.

Make sure your dataset is:

  • Clean and accurate — free from labeling errors and imprecise bounding boxes
  • Diverse — covers different variations, scales, orientations, and backgrounds of your target objects
  • Sufficient in size — enough annotated examples for the model to learn meaningful patterns

For this example, we'll use the CPPE-5 (Consumer Protective Personal Equipment) dataset from Hugging Face, which contains images annotated with bounding boxes for medical personal protective equipment.

You can download the dataset inputs to your local machine for use in this tutorial.

objective

Based on the selected dataset, we will train a model to detect five categories of medical PPE: Coverall, Face_Shield, Gloves, Goggles, and Mask.

Step 3: Add and Annotate Inputs​

To add inputs to your app, open the collapsible left sidebar and select the Inputs option.

Click the Upload Inputs button in the upper-right corner, then use the uploader pop-up to select and upload your images. As you upload, assign them to a dataset.

Once uploaded, you'll need to annotate each image with bounding boxes. Open the collapsible left sidebar and select the Labeler option to launch the annotation tool.

For each image, draw a bounding box around every object of interest and assign the appropriate concept label:

  • Coverall
  • Face_Shield
  • Gloves
  • Goggles
  • Mask

refresh your dataset

After completing all annotations, refresh your dataset and create a new version to reflect the changes.

Step 4: Create a Cluster and Nodepool​

To run and train your model, you'll need to set up a cluster and nodepool with the appropriate compute resources.

Start by creating a cluster that supports GPU-enabled workloads, as GPUs are required for efficient training and inference of detection models.

Next, create a nodepool within the cluster and select a GPU-backed instance that matches your performance and budget needs.

Note: GPU support is essential for this tutorial. Ensure that the selected nodepool is configured with a compatible GPU instance to avoid performance issues or failed training runs.

Step 5: Choose a Training Template​

Select the Models option in your app's collapsible left sidebar. On the ensuing page for listing models, click the Add a Model button.

In the window that pops up, select the Train a Model option.

You'll be redirected to a page listing available pipeline training templates. These templates provide pre-configured workflows to help you quickly get started with different types of models.

Select the detector-pipeline-yolof template. This is a YOLOF-based object detection pipeline designed for training models on images with bounding box annotations.

Step 6: Configure Training Settings​

The ensuing page allows you to review the model training configuration and begin the training process.

Select Training Template​

The training template you selected previously will be displayed for you. Otherwise, you can click the Change button to change to another training pipeline.

Select Nodepool Instance​

Choose the nodepool that will be used to train your model.

Select the Choose an instance option to open a selection window, where you can pick from existing or recommended nodepools based on your training requirements.

Choose your preferred nodepool, then click Save Changes to apply your selection.

The selected nodepool will be displayed for you.

Learn more about selecting a nodepool instance here.

Set Training Settings​

Configure the training settings for your model:

  • Model ID — Set a unique ID for the model that will be created after it is trained.
  • Dataset — Select the dataset from which inputs will be used for this pipeline. For this tutorial, let's select the dataset we previously created containing the annotated PPE images.
  • Dataset Version — Select which version of the dataset to use for training. You must select a dataset first before this option becomes available.
  • Training Concepts — Select the list of concepts you want the model to detect from the existing concepts labeled with your inputs. For this tutorial, let's pick these concepts: Coverall, Face_Shield, Gloves, Goggles, and Mask.
  • Training Epochs — Set how many times the model will see the entire dataset. More epochs can lead to better accuracy but take longer. The default value is 25.

Configure Template​

Each training template includes a set of configurable hyperparameters that control how the model is trained.

You can adjust these settings based on your dataset and performance goals. However, for this tutorial, we'll use the default values provided by the detector-pipeline-yolof template.

These are the settings you can configure:

  • Batch Size — Number of samples processed per training step. Default: 32.
  • Image Size — Size (in pixels) to which input images are resized (square). Default: 512.
  • Per Item Lrate — Learning rate applied per training sample. Default: 0.00001953125.
  • Weight Decay — Regularization factor to prevent overfitting. Default: 0.01.
  • Per Item Min Lrate — Minimum learning rate per sample during training. Default: 1.5625e-8.
  • Warmup Iters — Number of initial iterations used to gradually increase the learning rate. Default: 5.
  • Warmup Ratio — Starting ratio of the learning rate during warmup. Default: 0.0001.
  • Flip Probability — Chance of randomly flipping images during training (data augmentation). Default: 0.5.
  • Flip Direction — Direction used when flipping images. Default: horizontal.
  • Pretrained Weights — Source of initial model weights for transfer learning. Default: ImageNet-1k.
  • Seed — Random seed used to initialize training (set -1 for random behavior). Default: -1.

Step 7: Train the Model​​

After configuring the training settings, click the Train Model button to start training your model using the selected pipeline.

You'll be redirected to the Pipeline Version Runs page, where you can monitor the training job in real time and track how the pipeline executes.

On this page, you can:

  • Monitor run status — Track the current state of the pipeline:
    • RUNNING: The training job is in progress. While the job is running, you can pause or stop it.
    • COMPLETED: The training finished successfully
    • FAILED: The training did not complete successfully (check logs for details)
  • View run details — See key information such as the start time and total run duration.
  • Inspect infrastructure — View where the job is running, including the cloud provider, region, compute instance type, and allocated resources.
  • Follow pipeline execution — The training runs as an Argo Workflow, which breaks the process into steps. You can track the step-by-step execution of the pipeline in real time.
  • Explore logs and nodes — The logs panel displays detailed, JSON-like output, including a list of nodes (pipeline steps such as data loading, training, and evaluation). Each node includes metadata like its ID, type (e.g., Steps, Pod), and current status.
  • Reload logs — Click the Reload button to refresh and view the latest logs.
  • Run a new job — Click Run Pipeline Version to launch another training run. You'll be prompted to select a cluster and nodepool before starting.

Step 8: Use the Model​​

Once your model has been trained successfully, you can start using it for predictions.

To access it, go to the Models section from the left sidebar and select your model from the list. This opens the models listing page.

Click the listed model to open its individual page.

Next, click the Deploy Model button to create a deployment. This sets up the compute resources needed to run inference.

After deployment, click the Try Model button in the upper-right corner to open the Playground, where you can submit inputs and get predictions.

For this tutorial, uploading an image will return detected objects with bounding boxes drawn around each identified item — labeled with their concept such as Coverall, Gloves, or Mask — along with their prediction probabilities.

That's it!

Via the CLI​

note

Quick Start​

The detector-pipeline-yolof-quick-start template lets you train a test visual detection model with minimal setup. It uses a YOLOF-based object detector pre-configured with a public dataset, so you can run an end-to-end training pipeline immediately — no data preparation required.

Step 1: Perform Prerequisites

Before getting started, make sure you've completed the following setup:

  • Install the Clarifai package:
pip install --upgrade clarifai
clarifai login
  • Select an instance type for running your pipeline — such as g6e.xlarge.

Step 2: Initialize a Pipeline from a Template

Initialize a new pipeline using the quick-start template, then navigate into the generated directory:

clarifai pipeline init --template=detector-pipeline-yolof-quick-start
cd detector-pipeline-yolof-quick-start

Step 3: Upload and Run the Pipeline

Upload the pipeline configuration and execute the training job:

clarifai pipeline upload

Note: This will automatically create an app called pipeline-app and upload the pipeline to it.

clarifai pipeline run --instance=g6e.xlarge

Step 4: Monitor Your Pipeline

Once the pipeline runs, it automatically loads the dataset, trains a YOLOF-based object detector, and produces a test model ready for use.

To access your pipeline, open your app's sidebar and select Pipelines; to view your trained model, select Models.


Let's walk through how to use the Clarifai CLI to build and train a visual detection model using your own custom dataset.

Step 1: Install Clarifai and Authenticate​

Start by installing the latest version of the clarifai Python package. This also includes the Clarifai CLI, which we'll use to run and manage the training pipeline.

pip install --upgrade clarifai

Then, authenticate your connection to Clarifai:

clarifai login

The CLI will prompt you for your Personal Access Token (PAT). It will auto-detect your user ID and save everything locally.

Note: You can obtain a PAT by opening Settings in the platform's collapsible left sidebar, selecting Secrets, and then creating a new token or copying an existing one.

Step 2: Create an App​

Create an app to store and manage your model and its associated resources (such as datasets, pipelines, and deployments).

clarifai app create your-app-id
Example Output
[INFO] 14:40:29.196099 App with ID 'my-vis-detector' is created:
code: SUCCESS
description: "Ok"
req_id: "sdk-python-12.4.0-1b1aa61784ee447e80653686a5da546f"
 |  thread=8485281984
App 'my-vis-detector' created successfully.

Step 3: Prepare Training Data​

As mentioned previously, high-quality, well-structured data is critical for training an accurate and reliable model.

For object detection, your dataset must include images with bounding box annotations. Each annotation marks the location of an object in the image and assigns it a concept label.

For this example, we'll use a public dataset of annotated images available here.

Objective

Using this dataset, we'll train a model to detect and localize the following object categories: dog, cat, person, and car.

You can clone the repository containing the dataset, then use the Clarifai Python SDK to upload the dataset to your app.

import os
from clarifai.datasets.upload.utils import load_module_dataloader
from clarifai.client.app import App

# Construct the path to the dataset folder
module_path = os.path.join(os.getcwd().split('/models/model_train')[0], 'examples/datasets/upload/image_detection')

# Load the dataloader module using the provided function from your module
detection_dataloader = load_module_dataloader(module_path)

# Initialize Clarifai App
app = App(app_id="YOUR_APP_ID_HERE", user_id="YOUR_USER_ID_HERE")

# Create a Clarifai dataset with the specified dataset_id
dataset = app.create_dataset(dataset_id="image_dataset")

# Upload the dataset using the provided dataloader and get the upload status
dataset.upload_dataset(dataloader=detection_dataloader, get_upload_status=True)
Example Output
[INFO] 15:47:57.287614
Dataset created
code: SUCCESS
description: "Ok"
req_id: "sdk-python-12.4.0-c8985fc62a4840399cbe3b5af908ed8a"
 |  thread=8485281984
[INFO] 15:47:57.294167 Getting dataset upload status... |  thread=8485281984
[INFO] 15:48:01.211582
Dataset Version created
code: SUCCESS
description: "Ok"
req_id: "sdk-python-12.4.0-fd7e961f305e49b7939065578f3f127b"
 |  thread=8485281984
Uploading Dataset: 100%|██████████████████████████████████████████████████████| 1/1 [04:43<00:00, 283.41s/it]
[INFO] 15:52:44.652318 Getting dataset upload status... |  thread=8485281984
[INFO] 15:52:44.923118
Dataset Version created
code: SUCCESS
description: "Ok"
req_id: "sdk-python-12.4.0-ff64897b59814a0aaf6e578fb06b7e8a"
 |  thread=8485281984
[INFO] 15:52:45.112250 Crunching the dataset metrics. Please wait... |  thread=8485281984
╭───────────────────────────────────────────────────  Dataset Upload Summary ────────────────────────────────────────────────────╮
│ Inputs Progress:      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% │
│ Annotations Progress: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% │
│ ┏━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓                                                                                │
│ ┃ dataset_id    ┃ user_id ┃ app_id            ┃                                                                                │
│ ┡━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩                                                                                │
│ │ image_dataset │ alfrick │ my-vis-detector   │                                                                                │
│ └───────────────┴─────────┴───────────────────┘                                                                                │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────  Dataset Metrics Comparison ──────────────────────────────────────────────────╮
│                          Local Dataset                                                Uploaded Dataset                         │
│ ┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ │
│ ┃ Inputs Count ┃ Annotations Count                            ┃┃ Inputs Count ┃ Annotations Count                            ┃ │
│ ┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │
│ │ 200          │ {'concepts': 0, 'bboxes': 847, 'polygons': 0} ││ 200          │ {'concepts': 0, 'bboxes': 847, 'polygons': 0} │ │
│ └──────────────┴──────────────────────────────────────────────┘└──────────────┴──────────────────────────────────────────────┘ │
│                                                                                                                                │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Note: Once your dataset is successfully uploaded, navigate to the platform UI and record the dataset_id and dataset_version_id. You'll need these values when running the training pipeline.

Step 4: Set Up Compute​

You can run your pipeline using either on-demand instance compute or a managed cluster and nodepool.

Option A: Select an Instance Type​

You can run your pipeline directly on on-demand compute by specifying an instance with the --instance flag (see example below). This removes the need to create and manage a cluster and nodepool.

With this approach, compute is automatically provisioned — or reused if available — so you can focus on running your pipeline rather than managing infrastructure.

See the available instance types to choose one that best matches your workload and performance requirements.

Option B: Create a Cluster and Nodepool​

To train your model via the CLI with managed infrastructure, you'll need to provision compute resources by creating a cluster and a nodepool.

Start by defining a YAML configuration file for your compute cluster. Ensure the configuration supports GPU workloads, as GPUs are required for efficient training and inference of detection models.

Here is an example cluster config file:

compute_cluster:
  id: "visual-compute-cluster"
  description: "My AWS compute cluster"
  cloud_provider:
    id: "aws"
  region: "us-east-1"
  managed_by: "clarifai"
  cluster_type: "dedicated"
  visibility:
    gettable: 10

Then run the following command, pointing to your config file:

    clarifai computecluster create \
      your_compute_cluster_id \
      --config your_compute_cluster_config_filepath
Example Output
clarifai computecluster create \
      visual-compute-cluster \
      --config compute.yaml
[INFO] 16:04:56.120016 Compute Cluster with ID 'visual-compute-cluster' is created:
code: SUCCESS
description: "Ok"
req_id: "sdk-python-12.4.0-8233ec6fcf154467857f61d19d175023"
 |  thread=8485281984

Next, define a nodepool within your cluster. This is where you specify the actual compute instances used for training. Be sure to choose a GPU-enabled instance that aligns with your performance and cost requirements.

Note: GPU support is essential for this tutorial. Without a compatible GPU instance, training may be significantly slower or fail altogether.

Here is an example nodepool config file:

nodepool:
  id: "visual-nodepool"
  compute_cluster:
    id: "visual-compute-cluster"
  description: "GPU nodepool for training workloads"
  instance_types:
    - id: "g5.2xlarge"
      compute_info:
        cpu_limit: "8"
        cpu_memory: "28Gi"
        accelerator_type:
          - "a10"
        num_accelerators: 1
        accelerator_memory: "40Gi"
  node_capacity_type:
    capacity_types:
      - 1
  min_instances: 0
  max_instances: 1

Then run the following command, pointing to your config file:

    clarifai nodepool create \
      your_compute_cluster_id \
      your_nodepool_id \
      --config your_nodepool_config_filepath
Example Output
clarifai nodepool create \
      visual-compute-cluster \
      visual-nodepool \
      --config nodepool.yaml
[INFO] 16:12:23.712709 Nodepool with ID 'visual-nodepool' is created:
code: SUCCESS
description: "Ok"
req_id: "sdk-python-12.4.0-db3e87045f87426395a777c157daf5a2"
 |  thread=8485281984

Step 5: Initialize a Pipeline from a Template​

The detector-pipeline-yolof template lets you quickly set up a visual detection pipeline using a preconfigured YOLOF-based object detector — so you can focus on training rather than setup.

tip

To view all the available predefined templates, run:

clarifai pipelinetemplate list
Example Output
clarifai pipelinetemplate list
NAME                                      TYPE
classifier-pipeline-resnet                classifier
classifier-pipeline-resnet-quick-start    classifier
detector-pipeline-dfine                   detector
detector-pipeline-eval-yolof-quick-start  detector
detector-pipeline-yolof                   detector
detector-pipeline-yolof-quick-start       detector
lora-pipeline-unsloth-quick-start         lora

Found 7 template(s) total
Available types: classifier, detector, lora

Run the following command to initialize a pipeline from the template:

clarifai pipeline init \
  --app_id your_app_id \
  --user_id your_user_id \
  --template detector-pipeline-yolof \
  --set dataset_id=image_dataset \
  --set dataset_version_id=dataset_version_id \
  --set concepts='["dog","cat","person","car"]'

Where:

ParameterDescription
--app_idThe ID of the app where the pipeline will be created
--user_idYour Clarifai user ID
--templateThe pipeline template to use. Here, we use detector-pipeline-yolof
--set dataset_idThe ID of the dataset to use for training
--set dataset_version_idThe specific dataset version to use for training
--set conceptsA JSON array of the concept labels the model will be trained to detect
Example Output
clarifai pipeline init \
  --app_id my-vis-detector \
  --user_id alfrick \
  --template detector-pipeline-yolof \
  --set dataset_id=image_dataset \
  --set dataset_version_id=b7c12e3f901a4d85a3bb67e2f10cd94a \
  --set concepts='["dog","cat","person","car"]'
Using template: detector-pipeline-yolof

Template Type: detector
Steps:
Parameters: 18 required

Creating pipeline 'detector-pipeline-yolof' from template 'detector-pipeline-yolof'...

Template Parameters (default values):
  user_id                     : <YOUR_USER_ID>
  app_id                      : <YOUR_APP_ID>
  model_id                    : test_model
  dataset_id                  : <YOUR_DATASET_ID>
  dataset_version_id          :
  concepts                    : ["dog","cat","person","car"]
  num_epochs                  : 200
  batch_size                  : 32
  image_size                  : 512
  per_item_lrate              : 1.953125e-05
  weight_decay                : 0.01
  per_item_min_lrate          : 1.5625e-08
  warmup_iters                : 5
  warmup_ratio                : 0.0001
  flip_probability            : 0.5
  flip_direction              : horizontal
  pretrained_weights          : ImageNet-1k
  seed                        : -1

Pipeline initialization complete in /Users/macbookpro/Desktop/detector/detector-pipeline-yolof

Next steps:
1. Review and customize the generated pipeline steps
2. Add any additional dependencies to requirements.txt files
3. Run 'clarifai pipeline upload /Users/macbookpro/Desktop/detector/detector-pipeline-yolof/config.yaml' to upload your pipeline
4. Use 'clarifai pipeline run --config /Users/macbookpro/Desktop/detector/detector-pipeline-yolof/config.yaml [--set key=value]' to execute your pipeline

Once executed, the command creates a new project directory named after the template, preloaded with all necessary configuration files.

Before running any subsequent clarifai pipeline ... commands, navigate into the generated directory — these commands rely on the local config.yaml and config-lock.yaml files:

cd detector-pipeline-yolof

Note: You can optionally review the generated pipeline steps and tailor them to your use case. If needed, you can also adjust the default parameters and add any additional dependencies to the requirements.txt files to support your pipeline.

Override Defaults at Initialization

You can optionally customize the pipeline during setup — for example, by specifying a different user/app, assigning a custom pipeline ID, or adjusting model parameters:

  clarifai pipeline init --template=detector-pipeline-yolof \
  --user_id your_custom_user_id \
  --app_id your_custom_app_id \
  --set id=your_custom_pipeline_id \
  --set num_epochs=20

Step 6: Upload Your Pipeline​

Once your pipeline is initialized and configured, the next step is to upload it and trigger the training job.

Make sure you're inside the generated pipeline directory, then run:

clarifai pipeline upload
Example Output
cd detector-pipeline-yolof
((venv) ) (base) macbookpro@macs-MacBook-Pro detector-pipeline-yolof %     clarifai pipeline upload
[INFO] 16:32:35.454197 Starting pipeline upload from config: ./config.yaml |  thread=8485281984
[INFO] 16:32:37.865166 Using existing app 'my-vis-detector' |  thread=8485281984
[INFO] 16:32:37.873317 No step_directories specified, but all templateRefs have versions. Skipping pipeline step upload (reusing existing step versions). |  thread=8485281984
[INFO] 16:32:37.873399 No pipeline step versions for lockfile |  thread=8485281984
[WARNING] 16:32:37.877711 Could not find version for step: detector-pipeline-yolof-ps |  thread=8485281984
[INFO] 16:32:37.880190 Creating pipeline detector-pipeline-yolof... |  thread=8485281984
[WARNING] 16:32:37.884322 Could not find version for step: detector-pipeline-yolof-ps |  thread=8485281984
[INFO] 16:32:41.966172 Successfully created pipeline detector-pipeline-yolof |  thread=8485281984
[INFO] 16:32:41.966564 Pipeline ID: detector-pipeline-yolof |  thread=8485281984
[INFO] 16:32:41.966635 Pipeline version ID: a91d3f7c2b4e41e8b6c053a8d17f29be |  thread=8485281984
[INFO] 16:32:41.987219 Generated lockfile: /Users/macbookpro/Desktop/detector/detector-pipeline-yolof/config-lock.yaml |  thread=8485281984
[INFO] 16:32:41.987555 Pipeline upload completed successfully with lockfile! |  thread=8485281984

The above command will register the pipeline in your app, upload all associated configuration files, and prepare the pipeline for execution.

Step 7: Run the Pipeline​

You can run your pipeline using either on-demand instance compute or a preconfigured cluster and nodepool.

Option A: Run on On-Demand Instance Compute​

Instead of relying on an existing nodepool and compute cluster, you can automatically provision or reuse compute at runtime by specifying an instance type:

clarifai pipeline run --instance=g6e.xlarge

This approach removes the need to manage infrastructure, making it ideal for quick experiments or simplified workflows.

Override Parameters at Runtime

To modify pipeline parameters at run time, pass one or more --set key=value flags:

clarifai pipeline run \
  --instance=g6e.xlarge \
  --set num_epochs=20 \
  --set batch_size=32

Option B: Run on Cluster and Nodepool​

If you've already set up a compute cluster and nodepool, you can run the pipeline by explicitly targeting those resources:

    clarifai pipeline run \
      --nodepool_id=your_nodepool_id \
      --compute_cluster_id=your_compute_cluster_id
Example Output
clarifai pipeline run \
      --nodepool_id=visual-nodepool \
      --compute_cluster_id=visual-compute-cluster
Found config-lock.yaml, using it as default config source
[INFO] 16:38:26.555009 Starting pipeline run for pipeline detector-pipeline-yolof |  thread=8485281984
[INFO] 16:38:29.834776 Pipeline version run created with ID: 7f4d1a9cb23e4058aad87e1b5c63f921 |  thread=8485281984

[INFO] 16:42:49.830451 Pipeline run status: 64001 (JOB_RUNNING) |  thread=8485281984
[INFO] 16:42:49.830541 Pipeline run in progress: 64001 (JOB_RUNNING) |  thread=8485281984
[INFO] 16:43:00.628789 Pipeline run monitoring... (elapsed 270.8s) |  thread=8485281984
[INFO] 16:43:00.629355 Pipeline run status: 64001 (JOB_RUNNING) |  thread=8485281984
[INFO] 16:43:11.350856 [LOG] time="2026-04-23T13:40:25.268Z" level=info msg="Starting Workflow Executor" version=v3.7.9
/opt/conda/lib/python3.11/site-packages/torch/cuda/__init__.py:61: FutureWarning: The pynvml package is deprecated. Please install nvidia-ml-py instead. If you did not install pynvml directly, please report this to the maintainers of the package that installed pynvml for you.
  import pynvml  # type: ignore[import] |  thread=8485281984
[INFO] 16:44:05.154017 [LOG] /opt/conda/lib/python3.11/site-packages/mmengine/optim/optimizer/zero_optimizer.py:11: DeprecationWarning: `TorchScript` support for functional optimizers is deprecated and will be removed in a future PyTorch release. Consider using the `torch.compile` optimizer instead.
  from torch.distributed.optim import \
INFO:root:Starting MMDetection YOLOF training pipeline
{"msg": "Downloading to /tmp/pretrain_checkpoints/yolof_r50_c5_8x8_1x_coco_20210425_024427-8e864411.pth", "@timestamp": "2026-04-23T13:43:02.414665Z", "filename": "artifact_version.py", "stack_info": null, "lineno": 503, "level": "info"}
INFO:clarifai:Downloading to /tmp/pretrain_checkpoints/yolof_r50_c5_8x8_1x_coco_20210425_024427-8e864411.pth
Downloading: 100%|██████████| 145M/145M [00:03<00:00, 46.2MB/s]
INFO:root:Downloaded checkpoint to /tmp/pretrain_checkpoints/yolof_r50_c5_8x8_1x_coco_20210425_024427-8e864411.pth
INFO:root:
INFO:root:================================================================================
INFO:root:STEP 1: Downloading Dataset from Clarifai API
INFO:root:================================================================================
INFO:model.1.dataset_helpers:Downloaded 200/200 images
INFO:model.1.dataset_helpers:Successfully downloaded 200 images with 847 bounding box annotations
INFO:root:
INFO:root:================================================================================
INFO:root:STEP 2: Converting Dataset to COCO Detection Format
INFO:root:================================================================================
INFO:model.1.dataset_helpers:Concept mapping: {'dog': 0, 'cat': 1, 'person': 2, 'car': 3}
INFO:model.1.dataset_helpers:Conversion complete! Images saved: 200, annotations: 847
INFO:root:
INFO:root:================================================================================
INFO:root:STEP 3: Training YOLOF Detector
INFO:root:================================================================================
04/23 13:47:11 - mmengine - INFO - Epoch(train)  [1][  10/200]  lr: 1.9531e-05  eta: 2:14:07  time: 0.7823  data_time: 0.0412  memory: 8341  loss: 3.8821  loss_cls: 1.2341  loss_bbox: 2.6480
04/23 13:47:19 - mmengine - INFO - Epoch(train)  [1][  20/200]  lr: 1.9531e-05  eta: 2:08:32  time: 0.7651  data_time: 0.0387  memory: 8341  loss: 3.5124  loss_cls: 1.1032  loss_bbox: 2.4092

The above command launches the pipeline on your specified cluster and nodepool, ensuring it uses the configured GPU-backed resources.

Once triggered, the pipeline runs end-to-end — loading the dataset, training the YOLOF-based model, and producing a model ready for evaluation and further use.

Step 8: Monitor Your Pipeline​

To monitor your pipeline, open your app's collapsible sidebar and select Pipelines. From there, navigate to the Pipeline Version Runs page, where you can track execution progress, view logs, and manage runs for a specific pipeline version — as illustrated above.

To access the trained model, go to Models in the sidebar.

You can also monitor the pipeline directly from the CLI:

clarifai pipelinerun monitor pipeline_version_run_id
Example Output
clarifai pipelinerun monitor 7f4d1a9cb23e4058aad87e1b5c63f921
[INFO] 16:56:38.058412 Loading parameters from config-lock.yaml |  thread=8485281984
[INFO] 16:56:38.288422 Monitoring existing pipeline run with ID: 7f4d1a9cb23e4058aad87e1b5c63f921 |  thread=8485281984
[INFO] 16:56:42.025675 [LOG] time="2026-04-23T13:40:25.268Z" level=info msg="Starting Workflow Executor" version=v3.7.9
/opt/conda/lib/python3.11/site-packages/torch/cuda/__init__.py:61: FutureWarning: The pynvml package is deprecated. Please install nvidia-ml-py instead. If you did not install pynvml directly, please report this to the maintainers of the package that installed pynvml for you.
  import pynvml  # type: ignore[import] |  thread=8485281984
INFO:root:Starting MMDetection YOLOF training pipeline

04/23 13:47:11 - mmengine - INFO -
------------------------------------------------------------
System environment:
    sys.platform: linux
    Python: 3.11.10 | packaged by conda-forge
    CUDA available: True
    GPU 0: NVIDIA A10G
    PyTorch: 2.5.1+cu124
------------------------------------------------------------

04/23 14:12:44 - mmengine - INFO - Epoch(train) [50][ 200/200]  lr: 1.9531e-05  eta: 1:03:21  loss: 1.9843  loss_cls: 0.6124  loss_bbox: 1.3719
04/23 14:38:01 - mmengine - INFO - Epoch(train) [100][ 200/200]  lr: 9.7656e-07  eta: 0:31:14  loss: 1.2107  loss_cls: 0.3891  loss_bbox: 0.8216
04/23 15:03:18 - mmengine - INFO - Epoch(train) [150][ 200/200]  lr: 1.5625e-08  eta: 0:04:11  loss: 0.9432  loss_cls: 0.2973  loss_bbox: 0.6459
04/23 15:08:29 - mmengine - INFO - Epoch(train) [200][ 200/200]  lr: 1.5625e-08  eta: 0:00:00  loss: 0.8761  loss_cls: 0.2714  loss_bbox: 0.6047
INFO:root:Training complete. Uploading model to Clarifai...
{"msg": "Model uploaded successfully", "@timestamp": "2026-04-23T15:09:14.221Z", "level": "info"}
[INFO] 17:09:18.442217 Pipeline run status: 64002 (JOB_COMPLETED) |  thread=8485281984
[INFO] 17:09:18.442338 Pipeline run completed successfully |  thread=8485281984

Step 9: Use Your Model​

Once training is complete, your model is ready for use.

Start by creating a deployment to make it available for inference.

clarifai model deploy \
  --model-url clarifai_model_url \
  --instance g5.2xlarge
Example Output
 clarifai model deploy \
  --model-url https://clarifai.com/alfrick/my-vis-detector/models/test_model \
  --instance g5.2xlarge

── Deploy ────────────────────────────────────────────────
  Model:            alfrick/my-vis-detector/models/test_model
  Version:          d4f7a2c19b3e4e81b0d966e22a74cd38
  Instance:         g5.2xlarge
  Cloud:            aws / us-east-1
  Creating compute cluster 'deploy-cc-aws-us-east-1'...
  Creating nodepool 'deploy-np-g5-2xlarge'...
  Deploying to nodepool 'deploy-np-g5-2xlarge'...
  Deployment 'deploy-test_model-8ae43c' created

── Monitor ───────────────────────────────────────────────
  [warning] Scheduling: Waiting for node to become available...
  [event  ] Scaling: Waiting for cluster to scale up...
  [event  ] TriggeredScaleUp: pod triggered scale-up: [{eks-cl-7a5f623ab5cd4dc8e44f34abe7ad1d3c-18cedd59-a1...
  [event  ] FilteringSucceed: find fit node(ip-10-7-91-93.ec2.internal), 0 nodes not fit, 1 nodes fit
  [event  ] BindingSucceed: Successfully binding node [ip-10-7-91-93.ec2.internal] to prod-alfrick/runner...
  [event  ] Scheduled: Pod scheduled on node
  [event  ] Pulling image: Pulling model image...
  [event  ] Image pulled: Model image pulled
  [event  ] Starting: Container created
  [event  ] Running: Container started
  [warning] Health check: Health check failed, waiting...
  Pod started (281s). Waiting for model to be ready...

── Startup Logs ──────────────────────────────────────────
  INFO:model:Inference took 412.37 ms
{"msg": "model_predict | 200 OK | 428.91ms | req_id=sdk-python-12.4.0-****2d80ab68b692", "@timestamp": "2026-04-23T14:31:03.846492Z", "stack_info": null, "level": "info"}

── Deployed (pod pending) ────────────────────────────────

  Model:            https://clarifai.com/alfrick/my-vis-detector/models/test_model
  Version:          d4f7a2c19b3e4e81b0d966e22a74cd38
  Deployment:       deploy-test_model-8ae43c
  Instance:         g5.2xlarge
  Cloud:            AWS / us-east-1

── Next Steps ────────────────────────────────────────────
  Events:           clarifai model logs --deployment "deploy-test_model-8ae43c" --log-type events
  Status:           clarifai model status --deployment "deploy-test_model-8ae43c"
  Predict:          clarifai model predict alfrick/my-vis-detector/models/test_model --deployment deploy-test_model-8ae43c --url https://samples.clarifai.com/featured-models/image-general-horses.jpg
  Playground:       https://clarifai.com/playground?model=test_model__d4f7a2c19b3e4e81b0d966e22a74cd38&user_id=alfrick&app_id=my-vis-detector
  Undeploy:         clarifai model undeploy --deployment "deploy-test_model-8ae43c"

Then, use the generated deployment ID to run predictions on new data.

clarifai model predict \
  clarifai_model_url \
  --url https://samples.clarifai.com/featured-models/image-general-horses.jpg \
  --deployment deployment_id
Example Output
 clarifai model predict https://clarifai.com/alfrick/my-vis-detector/models/test_model --url https://samples.clarifai.com/featured-models/image-general-horses.jpg --deployment deploy-test_model-8ae43c

[Region(id='a1b2c3', bounding_box=BoundingBox(top_row=0.1423, left_col=0.0831, bottom_row=0.8912, right_col=0.4762), data=Data(concepts=[Concept(id='2', name='person', value=0.9734832048416138)])), Region(id='d4e5f6', bounding_box=BoundingBox(top_row=0.2187, left_col=0.5103, bottom_row=0.9341, right_col=0.9814), data=Data(concepts=[Concept(id='2', name='person', value=0.9512304067611694)])), Region(id='g7h8i9', bounding_box=BoundingBox(top_row=0.3054, left_col=0.1927, bottom_row=0.7683, right_col=0.6341), data=Data(concepts=[Concept(id='3', name='car', value=0.8823491930961609)]))]
© 2026 Clarifai, Inc. All rights reserved