# Training concepts ## Overview Hub AI connects data preparation, model training, evaluation, and deployment. A Dataset holds samples and their annotations. A Project defines what to train and links the dataset to one or more models. A successful training run creates a new model version that can be evaluated, used to annotate more data, or converted for deployment. ## Datasets A Dataset is a team-owned collection of samples with one or more machine learning tasks. Create one from a task preset, define custom tasks, or inherit the tasks and classes from an existing project. While Hub imports data, the dataset status progresses through Pending and Running. A successful import changes it to Ready; an unsuccessful import changes it to Failed. Open the associated [job](https://docs.luxonis.com/cloud/hubai/training/jobs.md) to inspect progress or errors. ### Tasks and task names A task defines the type of prediction, its task name, and its classes. Keypoint tasks also define skeleton labels. The task name groups related annotations inside the dataset and is passed to LuxonisTrain as `task_name`; matching task names are therefore required when uploading pre-existing data. A dataset can contain several tasks. For example, the Keypoint Detection preset combines object detection with nested keypoints, while Instance Segmentation combines object detection with nested segmentation. | Task type | Annotation in Hub | Main training metric | | --- | --- | --- | | Classification | Predict a class for the image | F1 Score | | Object Detection | Predict bounding boxes | mean Average Precision (mAP) | | Semantic Segmentation | Predict polygons or masks | Jaccard Index | | Keypoint Detection | Predict a box and its skeleton keypoints | mean Average Precision Keypoints | | Instance Segmentation | Predict a box and its nested polygon | mean Average Precision (mAP) | | Optical Character Recognition (OCR) | Predict text | OCR Accuracy | For the underlying annotation structure, task names, and supported dataset parsers, see [LuxonisParser](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-parser.md). ### Classes Classes are defined separately for each task. When importing annotated data, Hub keeps only annotations whose type and class match a dataset task. It drops unmatched annotations. > **Note** > Define every class you intend to import before uploading the archive. You can add classes later, but existing classes cannot be removed from a dataset. ### Samples A sample consists of an image plus its annotations, split, annotation status, and optional tags. Samples can originate from [file uploads](https://docs.luxonis.com/cloud/hubai/training/datasets/upload.md), [Snaps](https://docs.luxonis.com/cloud/features/event-storage/snaps.md), or [model pre-annotation](https://docs.luxonis.com/cloud/hubai/training/datasets/annotate.md). ### Annotation status Annotation statuses provide an optional review workflow: `Unannotated` → `Pre-annotated` → `Annotated` → `In Review` → `Completed` * Unannotated: has no reviewed annotation work. * Pre-annotated: contains machine-generated annotations that should be reviewed. * Annotated: indicates that manual annotation work has started or changed. * In Review: is ready for a reviewer in an optional QA stage. * Completed: is finalized and approved for use by the training workflow. Editing an Unannotated or Pre-annotated sample automatically changes it to Annotated. Files imported through a regular annotated-data upload start as Completed, assuming external data has already undergone adequate QA and its annotations are correct. > **Completed samples drive readiness checks** > The train, validation, and test sizes used by run validation and dataset health count Completed samples only. Statuses are optional as a workflow, but samples must be marked Completed before they contribute to those counts. ### Splits Every sample belongs to one of three splits: * Train: teaches the model by updating its weights. * Validation: measures generalization during training and is used to select checkpoints. * Test: provides a final comparison on data that was not used to update or select the model. If a training dataset has no completed validation samples, Hub uses the training split for validation. If it has no completed test samples, Hub falls back to the validation split. An evaluation run requires completed samples in the split you explicitly select. ### Tags Tags are free-form labels for organizing samples. Use them to filter the sample grid, target model pre-annotation, or select the subset copied into a dataset version for a training run. When several tags are selected, the AND option requires all tags and the OR option accepts any selected tag. ### Versions A dataset version is a read-only snapshot created for a training run. It freezes the chosen samples and annotations so later dataset edits do not change the run's input. Enabling Version Dataset can add preparation time before training starts, but makes runs reproducible and easier to compare and analyze dataset drift over time. If the dataset has not changed since the latest version made with the same tag filter, Hub reuses that version instead of copying it again. See [Health, Splits & Versions](https://docs.luxonis.com/cloud/hubai/training/datasets/health-splits-versions.md) for the full workflow. ### Health Dataset health summarizes three checks based on completed samples: * Size: checks whether enough samples are available. * Split distribution: checks whether train, validation, and test data are reasonably balanced for their purposes. * Class distribution: checks that every class is present and flags severe imbalance. Each check is Healthy, Unhealthy, or Fail. Health is intended for user guidance and is not a training gate on its own; the run form separately validates the samples and task mapping it needs. ## Projects A Project combines a task definition, one or more linked models, and its training and evaluation runs. Creating a project from a dataset copies the dataset tasks and classes into the project. Project tasks are not modifiable after creation. ### Linked models and architectures Each project model is paired with an architecture, which determines the trainable model family and default configuration. Hub offers LuxonisTrain predefined architectures for Detection, Classification, Segmentation, Instance Segmentation, Keypoint Detection, and OCR. Available families have Light, Medium, or Heavy variants where supported; the Hub form shows only the variants currently available for the selected task. Architecture cards compare relative speed and accuracy and show estimated performance for supported RVC platforms. Light architectures generally favor speed, while heavier architectures generally favor accuracy. Every successful training run publishes a new version of its linked model. The version contains the trained artifacts and links back to the run that produced it. ### Training and evaluation runs A training run combines a project model, dataset or dataset version, checkpoint selection, and compute speed. Its output is a new model version containing an ONNX [NN Archive](https://docs.luxonis.com/software-v3/ai-inference/nn-archive.md) and a PyTorch checkpoint. An evaluation run applies an existing checkpoint to a chosen validation or test split. It records metrics and inference images but does not train weights or create another model version. Runs progress through Pending, Running, and then Completed, Failed, or Shutdown. ### Checkpoints A checkpoint stores model weights from a point in training. Hub exposes two checkpoint-selection strategies: * Metric: selects the checkpoint with the best validation value for the task's main metric. * Loss: selects the checkpoint with the lowest validation loss. Use a checkpoint to resume training, run evaluation, or pre-annotate compatible dataset samples. The checkpoint's task names and classes must match the target workflow. ### Training speed The training form shows the compute speeds available to the active team. Each option identifies its compute type and affects both duration and credit consumption. Hub shows a conservative credit estimate for the selected speed before the run is submitted. ## Credits and jobs Credits allow for training and evaluation compute. Hub reserves the estimate when a run starts, charges actual usage, and releases unused reserved credits. Learn how balances and interrupted runs work in [Credits](https://docs.luxonis.com/cloud/hubai/training/credits.md). Jobs represent background work across Hub AI, including dataset uploads and exports, version creation, pre-annotation, training, and model conversion. Monitor them from the Jobs page as described in [Jobs](https://docs.luxonis.com/cloud/hubai/training/jobs.md). ## Put the concepts together The workflow is iterative: collect samples, annotate and complete them, version the dataset, train and evaluate a model, then deploy the best model or use its checkpoint to pre-annotate the next batch. Continue with [The Hub AI workflow](https://docs.luxonis.com/cloud/hubai/training/workflow.md) for the end-to-end view.