> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/documentation/auto-labeling/batch-auto-labeling.md).

# Batch Auto-Labeling

Run models at scale with workflow Model stages, human correction routes, queues, monitoring, and failure recovery.

Batch Auto-Labeling moves model inference from an annotator’s current item into a repeatable project workflow. Unitlab uses a **Model stage** to run the selected model, save its predictions into annotation history, and route the item to human annotation, review, another automated stage, or a terminal state.

![Unitlab workflow canvas with the Model stage available](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2F47ytYTxtSrCEgrclkdIQ%2Fauto-labeling-model-workflow.webp?alt=media)

### Recommended production pattern

{% code collapsedlinecount="10" %}

```mermaid
flowchart LR
  P["Project"] --> M["Model stage"]
  M --> A["Annotate / correction"]
  A --> R["Review"]
  R -->|Approve| C["Complete"]
  R -->|Reject| A
  M -->|Failure| E["Visible error state"]
```

{% endcode %}

A reliable first rollout uses **Model → Annotate → Review**. Direct Model → Review routing is appropriate only after the model is calibrated on the target domain and the review team can detect systematic errors.

### Before you start

* A project with representative data and an approved ontology.
* A public or private AI model whose input and output contract matches the data.
* A class mapping from model outputs to ontology classes.
* Defined thresholds, failure ownership, and human acceptance criteria.
* Permission to edit and apply the project workflow.

### Configure batch auto-labeling

{% stepper %}
{% step %}

#### Select or integrate the model

Open **Public AI Models** or **My AI Models**. Confirm running state, supported data, output geometry, version, and owner. See [Bring your own Models](/documentation/auto-labeling/bring-your-own-models.md) for private endpoints.
{% endstep %}

{% step %}

#### Open the project workflow

From the project, open **Workflows**. Start from the project’s current graph or an approved reusable workflow.
{% endstep %}

{% step %}

#### Add a Model stage

Place **Model** after Project or another intended entry stage. Configure the model, generic data type, threshold controls, queue scope, and class mappings exposed for that model.
{% endstep %}

{% step %}

#### Add human control

Route successful predictions to **Annotate** for correction or **Review** for acceptance. Configure a rejection path back to the appropriate correction stage.
{% endstep %}

{% step %}

#### Define failure handling

Ensure model failures remain visible in an Error state with a named owner. Do not route an empty or malformed response directly to Complete.
{% endstep %}

{% step %}

#### Save and apply

Validate graph reachability and apply the workflow. Review the impact before replacing an active project workflow with items already in flight.
{% endstep %}

{% step %}

#### Add the batch population

Upload or attach the intended data. Each item enters the workflow and is dispatched when it reaches the Model stage.
{% endstep %}

{% step %}

#### Monitor and review

Use project queues and status filters to inspect Processing, Error, Annotate, Review, and Complete populations. Measure human correction before increasing volume.
{% endstep %}
{% endstepper %}

### Model-stage configuration

| Decision          | Production guidance                                                 |
| ----------------- | ------------------------------------------------------------------- |
| Model and version | Pin the approved integration and record its owner                   |
| Input data        | Match image, video, audio, text, or medical support                 |
| Output mapping    | Map every emitted class and geometry intentionally                  |
| Threshold         | Calibrate on the target domain; do not copy a generic default       |
| Queue scope       | Start with a representative batch or selected queue                 |
| Success route     | Prefer human correction or review before Complete                   |
| Failure route     | Keep failures visible and recoverable                               |
| Change control    | Re-test after endpoint, model, prompt, mapping, or ontology changes |

### Monitor the run

A Model-stage item shows **Processing** while inference runs. Successful predictions are saved as normal annotation history and advance through the configured route. A failed item moves to an explicit error state.

Track at least:

* total items entering the Model stage;
* completed, processing, and failed counts;
* empty-output rate;
* per-class proposal count;
* correction and deletion rate;
* reviewer rejection rate;
* latency and timeout rate;
* model and ontology version.

{% hint style="warning" %}
Batch throughput is not quality. Approve scale only after the correction rate, missed-instance rate, and failure behavior are stable on representative data.
{% endhint %}

### Safe rollout

| Phase            | Scope                     | Exit criterion                                             |
| ---------------- | ------------------------- | ---------------------------------------------------------- |
| Contract test    | A few known items         | Request, response, mapping, and failure states are valid   |
| Calibration      | Representative cohort     | Threshold and class behavior are acceptable                |
| Controlled batch | One queue or source slice | Human correction is stable and failures are owned          |
| Production       | Approved population       | Monitoring, review, rollback, and provenance are operating |

### Recovery

* Fix the model endpoint or mapping before retrying failed items.
* Inspect remote state before repeating a mutation to avoid duplicate work.
* Re-run only the affected cohort when possible.
* If a workflow change would reset in-flight work, review the impact count and schedule the change.
* Preserve model version and correction evidence in the release record.

### Related guides

* [Model stages](/documentation/workflows/model-stages.md)
* [Queues overview](/documentation/queues/queues-overview.md)
* [Bring your own Models](/documentation/auto-labeling/bring-your-own-models.md)
* [Create a release](/documentation/releases/create-a-release.md)