> For the complete documentation index, see [llms.txt](https://docs.biodock.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.biodock.ai/projects-and-models/training-a-model.md).

# Training a model

*What you'll get: how to start a training run, what each setting on the **Configure and submit** page does, how to check the new version, and how to activate it and use it for analysis.*

Every training run creates a new version of your model. It never overwrites an earlier version.

## Before you start

* At least one tile must be marked **Fully labeled**. Only fully labeled (and corrected) tiles are used for training. See [Labeling tools](https://docs.biodock.ai/projects-and-models/labeling-tools.md#fully-labeled-tiles).
* Only a project owner can start a training run.
* Training needs free storage for the finished model, and it uses credits. See [Credits, storage and limits](https://docs.biodock.ai/account/credits-storage-and-limits.md).

## Start a training run

<figure><img src="https://3806122466-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk3DfNQKoMy1JXdaDLvpG%2Fuploads%2Fgit-blob-0d010c33b4c714c0d7df1abeb480be3181da6816%2Fdocs-training-start-training.gif?alt=media" alt="Click Train, click Get started, click Customize under the tile count and drag the slider from 18 to 15, type a description, click Start training, a v1 row with the status Training appears under Current versions"><figcaption><p><strong>Train</strong> → <strong>Get started</strong> → <strong>Customize</strong> the test tiles → <strong>Start training</strong>.</p></figcaption></figure>

1. Open the training page. Either open your project and click **Continue training**, or click **Train** in the top bar of the labeling screen.
2. Under **Train a new model**, click **Get started**. If it is greyed out, the card says why: usually no tile is marked **Fully labeled** yet.
3. The **Configure and submit** page opens. Check the settings below. For a first model, the defaults are good.
4. Optionally, type a note in **Add a description** so you can tell versions apart later.
5. Click **Start training**.

The new version appears under **Current versions** with the status **Training**. If someone starts the same training twice, for example from another tab, Biodock refuses the second one.

<figure><img src="https://3806122466-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk3DfNQKoMy1JXdaDLvpG%2Fuploads%2Fgit-blob-be867e6c78acd909a1f02ebe2dd07f92a11a9083%2Fdocs-training-configure-and-submit.png?alt=media" alt="The Configure and submit page with one size group card, the tile count with Customize, the transforms line, Classes in this group, and Add a description on the right"><figcaption><p>The <strong>Configure and submit</strong> page.</p></figcaption></figure>

## The training settings

Each size group in your project has its own card under **Choose size groups and classes**, with its own copy of these settings. A size group with no fully labeled tiles can't be included.

### Test tiles

The card reads "Using N/N fully labeled tiles for training". By default every fully labeled tile is used for training.

To hold some tiles back as a test, click **Customize** next to that line and move the slider. The card then says how many tiles will be used to test your model. Test tiles are never trained on, so they show how the model does on images it has not seen. Biodock picks them at random. Each size group you retrain needs at least one training tile.

In your first few rounds, use all your tiles for training. Hold a few back once the model starts to look good, so the test score means something.

### Image transforms

The card says how many transforms will apply to the size group. Click **Customize** next to it. The window asks "Are your images still valid if they are:" flipped, rotated or scaled. For cells under a microscope, the answer is almost always yes. Switch a flip to **No** only if direction matters in your sample, such as tissue with a fixed top and bottom. Then click **Save**.

### Advanced settings

Click **Advanced settings** on the card:

* **Data transformations**: **Apply contrast normalization** (on by default) evens out dim and bright areas. **Remove color** makes the images greyscale; use it when colour means nothing in your images.
* **Model architecture**: the type of AI model. The one marked **Recommended** is selected by default and is the right choice for almost everyone. Some architectures can be exported but not activated or used for analysis in Biodock; the app tells you when a version is export-only.

### Classes in this group

Tick the classes to include. A class you leave out is not learned, so the model will not output it.

### Retrain

If a size group already has a trained version, you can turn **Retrain** off to reuse that group's model from an earlier version. Pick it under **Choose trained version**. Leave **Retrain** on to train the group again from all its tiles.

### Errors and recommendations

If Biodock finds a problem with your labels, an **Errors and recommendations** box appears on the right. An error must be fixed before you can train. A recommendation is advice only.

### Size group hierarchy and channels

* **Size group hierarchy** appears when the project has more than one size group. See [Configuring your model](https://docs.biodock.ai/projects-and-models/configuring-your-model.md#size-group-hierarchy).
* **Channel settings for training** shows the channels the model will see. To change them, see [Project settings](https://docs.biodock.ai/projects-and-models/project-settings.md#channels).

## While it trains

Click **View details** on the version to follow it. It says **Spinning up** while Biodock starts a machine, then **Training** with a percentage and an estimate. You don't need to keep the page open: Biodock emails you when the model has finished training.

The status on the version row can be:

* **Training** (with a percentage once it has started)
* **Active**: trained and ready to use
* **In review** or **Changes requested**
* **Failed**: the training did not finish

## Check the new version

When training finishes, click **View** on the version under **Current versions**. Or open the project, go to **Active models** or **All models**, and click the version.

<figure><img src="https://3806122466-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk3DfNQKoMy1JXdaDLvpG%2Fuploads%2Fgit-blob-7359aa6ddce98971e4af0093fcfd855804080a20%2Fdocs-training-version-overview.png?alt=media" alt="A model version page showing the status Active, the version number, the description, Use for analysis and Deactivate on the right, and the sidebar with Overview, Performance, Data and Configuration"><figcaption><p>A version's page: <strong>Use for analysis</strong> and <strong>Deactivate</strong> on the right, its sections in the sidebar.</p></figcaption></figure>

The version page has these sections:

* **Overview**: the status, who trained it and when, and its description. Click the description to change it.
* **Performance**: **Predictions** shows the model's outlines next to your labels, and **Training statistics** shows the scores. See [Evaluating performance](https://docs.biodock.ai/projects-and-models/evaluating-performance.md).
* **Data**: **Training details** lists what the model was trained on: tiles, train and test split, labels, classes, architecture, tile size, and the transforms used.
* **Configuration** (active versions only): **Metrics**, **Class hierarchy**, **Size group hierarchy** and **Class transforms**. See [Configuring your model](https://docs.biodock.ai/projects-and-models/configuring-your-model.md).

**Evaluate**, next to a version on the training page, opens the labeling screen so you can try the model on new tiles with [AI Prelabel](https://docs.biodock.ai/projects-and-models/labeling-tools.md#ai-prelabel).

## Activate, deactivate and use a model

A version is **Active** as soon as training succeeds. An active version can be picked when you start an analysis. Export-only versions finish inactive and can't be activated.

To manage a version, open the project's **Active models** or **All models** tab and click **Manage** on its row:

* **Use for analysis**: opens **New analysis** with this version selected. See [Running an analysis](https://docs.biodock.ai/analysis-and-results/running-an-analysis.md).
* **View details**: opens the version page.
* **Edit description**.

Project owners also see:

* **Deactivate model**: removes the version from the analysis page. Nothing is deleted, and analyses you already ran keep their results.
* **Activate model**: brings an inactive version back.
* **Publish to the community** (active versions): see [Public AI models](https://docs.biodock.ai/projects-and-models/public-ai-models.md).
* **Delete model**.

The version page also has **Use for analysis** and **Deactivate** buttons at the top right.

If a project has several active versions, deactivate the ones you no longer want so nobody runs them by mistake.

## Next steps

* [Evaluating performance](https://docs.biodock.ai/projects-and-models/evaluating-performance.md): read the scores.
* [Configuring your model](https://docs.biodock.ai/projects-and-models/configuring-your-model.md): change the threshold, metrics and hierarchies without retraining.
* [Correcting results to improve your model](https://docs.biodock.ai/analysis-and-results/correcting-results-to-improve-your-model.md): add new images and train again.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.biodock.ai/projects-and-models/training-a-model.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
