# Training and evaluation runs

## Overview

A Hub AI project links a fixed task definition to one or more models. Training runs update model weights and publish model
versions; evaluation runs measure an existing checkpoint on a selected split without changing it.

This guide uses the `Warehouse Pallets` object-detection dataset to create a Detection (Light) model, train it, and evaluate the
selected checkpoint on the test split.

> **Note**
> Prepare a dataset with completed training samples first. Project task names and types must match the dataset, and every project class must exist in the corresponding dataset task.

## Create a project

Open [Luxonis Hub](https://hub.luxonis.com/ai/projects), select Projects, and click Add Project. Enter a descriptive project name.

Select the source Dataset to copy its task names, types, and classes into the project. Review the task definition carefully
because project tasks are read-only after creation.

Enter the linked model name, such as `pallet-detector`, then choose a compatible architecture such as Detection (Light). Review
the architecture card's relative speed, accuracy, and supported-platform statistics, add an optional description, and click Add.

> **Project creation produces a model**
> When a project is created, a new model is inherently created and linked to it with the given name. This is where any trained model artifacts will be stored for this particular project. Every project has a distinct model.

Architecture options are based on LuxonisTrain predefined models. Light variants generally favor throughput, while heavier
variants generally favor accuracy. The exact choices depend on the project task.

## Start a training run

Open the project and click New Training Run. Give the run a name that identifies its data and experiment, such as
`pallet-detection-medium`.

Choose the compatible Dataset. Leave Version Dataset enabled to create a read-only snapshot, and optionally select tags with an
AND or OR filter. If you do not create a new version, select an existing Dataset Version or the latest working dataset.

Select the linked Model and choose the checkpoint strategy:

 * Metric: retains the checkpoint with the best validation value for the task's main metric.
 * Loss: retains the checkpoint with the lowest validation loss.

To continue training existing weights, select a compatible Model Checkpoint from an earlier run. Leave it empty to start from the
architecture's initial weights.

> **Reuse a checkpoint in another project**
> To continue training in a new project, download the first project's PyTorch checkpoint and upload it to the model linked to the new project. You can upload a checkpoint from local LuxonisTrain training the same way. Compatible checkpoints then appear under Model Checkpoint when you create a run.

Choose from the training speeds available to your team, review the compute type and conservative credit estimate shown for the
selection, and click Add. Hub reserves the estimate and queues the versioning and training work.

After submission, the run summary records the selected speed alongside the linked dataset version, epochs, batch size, and
checkpoint settings. The completed example below used Medium training speed.

The run progresses from Pending to Running, then to Completed, Failed, or Shutdown. Open the run to inspect metadata, logs,
credits used, metrics, curves, and any inference images that were logged.

A completed training run publishes a new version of the linked model and exposes it from the run page.

The project table's Main Metric column provides a quick way to compare runs. Detailed metrics, curves, and inference images help
explain why one run performs differently from another.

## Start an evaluation run

Evaluation applies a saved checkpoint to a validation or test split. It produces metrics and inference images, but no new model
weights or version.

From the project, click New Evaluation Run and enter a name, such as `pallet-detection-test`.

Select Validation or Testing, then choose the dataset and optional dataset version. The chosen split must contain completed
samples.

Choose the linked model and the required Model Checkpoint, review the estimated credits, and submit the run. When it completes,
open the result to inspect its metrics, inference images, and logs.

## Review run results

Training and evaluation results combine summary metrics, per-epoch curves, logs, and inference images. Use them together: a single
high metric is useful for comparison, while curves and visual predictions help reveal overfitting, underfitting, and data
problems.

> **Note**
> Compare runs only when their task, evaluation split, and dataset version are equivalent. A result on different data is not a like-for-like model comparison.

Open a completed training or evaluation run and find Metrics. The table groups values by task and shows the available Training,
Validation, and Testing results.

Use Show Additional Metrics to inspect secondary and per-class values. The project page also surfaces each run's Main Metric for
quick comparison.

On a training run, compare the training and validation curves across epochs. Lower loss is better. For the main metric, higher is
generally better; a model is learning and generalizing when both curves improve without a sustained gap.

Use the Inference Images epoch control to compare predictions during training. Ground truth appears alongside the model prediction
so you can spot missed objects, incorrect classes, loose localization, or systematic labeling problems that a summary metric can
hide.

## Main metrics

The main metric depends on the project's task:

| Task | Main metric | What it summarizes |
| --- | --- | --- |
| Classification | F1 Score | Balance between precision and recall |
| Object Detection | mean Average Precision (mAP) | Detection quality across confidence and overlap thresholds |
| Semantic Segmentation | Jaccard Index | Overlap between predicted and ground-truth masks |
| Instance Segmentation | mean Average Precision (mAP) | Instance detection and mask quality |
| Keypoint Detection | mean Average Precision Keypoints | Keypoint localization quality across examples |
| OCR | OCR Accuracy | Correctness of recognized text |

For metric definitions and evaluation configuration, see [LuxonisTrain
evaluation](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-train/evaluation.md).

## Additional metrics

Depending on the task, Show Additional Metrics can include:

 * `mAP50` and `mAP75`, which evaluate detections at different intersection-over-union thresholds;
 * precision and recall, which expose the tradeoff between false positives and missed positives;
 * per-class results, which reveal weak classes hidden by an aggregate;
 * segmentation overlap measures such as mean intersection over union and Dice;
 * keypoint metrics based on object-keypoint similarity;
 * task-specific accuracy or recall values.

Metric names and available values vary by task and configuration. Treat a metric as comparable only when it was calculated the
same way.

## Recognize common curve patterns

| Pattern | Likely interpretation | Next action |
| --- | --- | --- |
| Training and validation loss fall together; both main metrics rise | Learning is progressing and generalization is stable |
Evaluate the selected checkpoint on held-out test data |
| Training improves while validation stalls or degrades | Overfitting to the training split | Add varied data, improve splits or
augmentation, or stop earlier |
| Both losses remain high and metrics remain low | Underfitting, insufficient training, or a task/data mismatch | Inspect
annotations, architecture capacity, configuration, and run duration |
| One class is much weaker than the aggregate | Class imbalance, label inconsistency, or harder examples | Inspect per-class data
and collect or correct representative samples |
| Metrics look good but predictions are visibly wrong | Leakage, an unsuitable metric, or annotation quality problems | Audit
splits and ground truth before promoting the model |

Validation metrics are used to select the Metric checkpoint. The test split should remain a final check rather than becoming
another tuning target.

## Choose a model for deployment

Use the project Main Metric to shortlist comparable runs, then confirm the choice with curves, per-class results, inference
images, and a dedicated test evaluation. On the produced model version, add a meaningful tag such as `candidate` or `production`
so applications and teammates can identify the selected artifact.

Tags can move between versions within a model, which supports a stable promotion label while preserving immutable version history.
Continue with [The Hub AI workflow](https://docs.luxonis.com/cloud/hubai/training/workflow.md) to connect model selection to
deployment and the next data cycle.

## Run controls and outputs

Use the controls in the run-page header to manage or reuse the run:

| Action | Result |
| --- | --- |
| Stop Training Run | Stops active compute and changes the run to Shutdown; the best checkpoint produced so far is retained |
| Edit and Rerun | Opens a new run form populated from the selected run so you start from the same parameters a previous run used
while tweaking the experiment |
| Download Model | Downloads the model artifact produced by the run |
| Deploy | Opens the produced model version's conversion workflow for a target RVC platform |
| Resume from checkpoint | Select the run's PyTorch checkpoint as Model Checkpoint in a new training run |

> **Training produces two model instances**
> A successful training run creates a model version containing an ONNX NN Archive for inference and a PyTorch checkpoint for resuming training, evaluation, and model pre-annotation. Evaluation runs record results only. See [Model Registry concepts](https://docs.luxonis.com/cloud/hubai/model-registry/concepts.md) for the model hierarchy.

The Version and Start Training Run job coordinates dataset versioning, export, training, output validation, and model
registration. Use the [Jobs](https://docs.luxonis.com/cloud/hubai/training/jobs.md) page when a run remains pending or a
preparation step fails.