> 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.

![Project workflow with a Model stage that pre-labels items before Annotate and Review](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FblhylB8ci4Zqd0xPWMff%2Fal-workflow-model-stage.webp?alt=media)

*A Model stage named Prompt pre-labels runs before people annotate and review.*

### 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
```

{% 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](https://docs.unitlab.ai/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, queue scope, and class mappings exposed for that model.

![Model stage settings for Prompt Labelling with one text prompt per project class](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FNFIHZHvPT4NNR2rUqVU1%2Fal-model-stage-settings.webp?alt=media)
{% 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

Name an owner for failed model runs. The Model stage has no failure route to connect; a failed run is shown in the Task Queue, as described under **Monitor the run**. 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, medical, or geospatial support     |
| Output mapping    | Map every emitted class and geometry intentionally                  |
| Queue scope       | Start with a representative batch or selected queue                 |
| Success route     | Prefer human correction or review before Complete                   |
| Failure handling  | 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. If a run fails, the item either stays in the Model stage or continues to the next stage without the model’s labels, depending on the model and the item’s data type; after a timeout or a cancel it stays. An item that stays shows the status **Error** in the Task Queue; an item that continues is marked **Model failed** there. A manager can **Cancel** a run while it is running and **Retry** an item that stayed in the Model stage. For your own model, managers also see the reason the run failed.

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](https://docs.unitlab.ai/documentation/workflows/model-stages.md)
* [Queues overview](https://docs.unitlab.ai/documentation/queues/queues-overview.md)
* [Bring your own Models](https://docs.unitlab.ai/documentation/auto-labeling/bring-your-own-models.md)
* [Create a release](https://docs.unitlab.ai/documentation/releases/create-a-release.md)
