> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.toloka.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Fine-tune a model

> Sign in, load labeled conversations, create an SFT Training, review the cost, and start one Training Run.

Adapt a catalog Base model to labeled conversations with `toloka`. A **Training** is an editable project draft. A **Training Run** is one billed execution. The first Training Run creates the output Model; a completed run publishes an immutable LoRA adapter Model Version.

> [!NOTE]
>
> To work with a coding agent, run `claude -p "Let's fine-tune a model. Follow https://platform.toloka.ai/agents/fine-tuning.md"` or give the same runbook URL to another agent.

Copy IDs from command output into later commands.

## Before you start

You need:

* macOS or Linux on ARM64 or x64. The installer uses compatible Bun or a standalone executable; standalone Linux downloads require glibc.
* A Toloka account on a team. Browser sign-in needs no API key. Noninteractive automation can use an API key from the Business Console.
* A funded team balance. Cost estimation is free; starting a Training Run places a hold up to the printed maximum charge.
* Labeled conversations. Use the sample below, or prepare your own with [Prepare training data](https://docs.platform.toloka.ai/docs/train/guides/prepare-training-data.md).

For prompt compression rather than weight adaptation, use [Compress a prompt with gisting](https://docs.platform.toloka.ai/docs/train/guides/gist.md).

## Step 1 — Install and sign in

```sh theme={null}
curl -fsSL https://platform.toloka.ai/cli/install.sh | sh
toloka version --json
toloka login
toloka whoami
```

Use the latest CLI release. This workflow does not import the TypeScript SDK and needs no project runtime. Rerun the installer for an immediate update; there is no `toloka update` command. See [CLI](https://docs.platform.toloka.ai/docs/cli.md) for installation modes, `PATH` fixes, and noninteractive authentication.

`login` opens the Toloka sign-in page in your browser. `whoami` prints the platform URL, account, selected project, and reachable project count.

## Step 2 — Create or select a project

The Training, datasets, billing, and output Model belong to one project.

```sh theme={null}
toloka project list
toloka project create fine-tuning --name "Support ticket SFT"
toloka project current
```

If you belong to more than one team, pass `--team-id`. To reuse an existing project:

```sh theme={null}
toloka project add support-sft pp.YOUR_PROJECT_ID
toloka project switch support-sft
```

## Step 3 — Put labeled conversations in a dataset

Each JSONL row is one chat. At least one turn must be `user`, and the last turn must be `assistant` with the output the model should learn.

Save these rows as `support-tickets.jsonl`:

```json theme={null}
{"messages":[{"role":"user","content":"Hi, how do I reset my password? I can't find the option anywhere."},{"role":"assistant","content":"question"}]}
{"messages":[{"role":"user","content":"This is the third time my order arrived damaged. I'm furious."},{"role":"assistant","content":"complaint"}]}
{"messages":[{"role":"user","content":"Just wanted to say your support team was incredibly helpful today, thank you!"},{"role":"assistant","content":"praise"}]}
{"messages":[{"role":"user","content":"What are your business hours on weekends?"},{"role":"assistant","content":"question"}]}
{"messages":[{"role":"user","content":"The app keeps crashing every time I open the checkout page. Please fix this."},{"role":"assistant","content":"complaint"}]}
{"messages":[{"role":"user","content":"Amazing product, it has saved me hours every week. Great job!"},{"role":"assistant","content":"praise"}]}
{"messages":[{"role":"user","content":"Can I change the shipping address after placing an order?"},{"role":"assistant","content":"question"}]}
{"messages":[{"role":"user","content":"I was charged twice for the same subscription and nobody is responding."},{"role":"assistant","content":"complaint"}]}
{"messages":[{"role":"user","content":"Do you offer student discounts?"},{"role":"assistant","content":"question"}]}
{"messages":[{"role":"user","content":"The new dashboard update is fantastic, much easier to use now."},{"role":"assistant","content":"praise"}]}
```

Keep the rows in one file. The Training command will give this new dataset an 80% train, 10% validation, 10% test split and freeze it in a slice. These 10 rows yield 8 training rows, 1 validation row, and 1 test row.

Create an empty dataset, upload the rows once, and list its ID:

```sh theme={null}
toloka dataset create support-tickets
toloka dataset upload support-tickets ./support-tickets.jsonl
toloka dataset list
```

The upload prints `Uploaded 10 rows to dataset support-tickets.` Uploads append, so repeating it adds the same rows again. Copy the `ds.…` ID from `dataset list`.

## Step 4 — Choose a Base model

```sh theme={null}
toloka base-model list
```

SFT supports `qwen3-4b`, `qwen3-8b`, `qwen3-32b`, and `qwen3-235b`. This guide uses `qwen3-8b`. Pass the printed ID to `--base-model`.

To continue training an existing adapter, use a LoRA adapter Model Version from the same project instead. Find its ID with:

```sh theme={null}
toloka model versions "Your model name"
```

A full-weight Model Version cannot be a source. See [Base models](https://docs.platform.toloka.ai/docs/train/reference/base-models.md#model-sources).

## Step 5 — Create the Training draft

SFT is the default method, so do not pass `--method`:

```sh theme={null}
toloka training create "Support ticket SFT" \
  --base-model qwen3-8b \
  --dataset ds.YOUR_DATASET_ID
```

The command freezes a slice named after the Training and prints `Created training trg.…`. To use an existing ready slice, pass `--slice <id>` instead of `--dataset`; see [Dataset selections](https://docs.platform.toloka.ai/docs/train/reference/settings.md#dataset-selections). Copy that Training ID.

To warm-start from an adapter, pass `--model-version` instead of `--base-model`:

```sh theme={null}
toloka training create "Support ticket SFT v2" \
  --model-version mdv.YOUR_VERSION_ID \
  --dataset ds.YOUR_DATASET_ID
```

The output Model is still new; the source Model Version is its training parent.

Inspect the draft:

```sh theme={null}
toloka training get trg.YOUR_TRAINING_ID
```

**Method** is `Supervised fine-tuning (SFT)`. **Output Model** is `-` until the first Training Run is created, even if that run later blocks or fails before publishing a version.

Optional SFT settings are `--lora-rank`, `--epochs`, `--learning-rate`, `--batch-size`, and `--max-sequence-length`. See [Training settings](https://docs.platform.toloka.ai/docs/train/reference/settings.md) for accepted values and defaults.

## Step 6 — Review the cost

```sh theme={null}
toloka training cost trg.YOUR_TRAINING_ID --json > estimate.json
```

Open `estimate.json`, require `status: "ready"`, and review the training rows, tokens, maximum GPU seconds, `maximumCharge`, and fingerprint. With the 10-row example and default split, expect 8 training rows and 1 validation row; 1 test row stays out of learning. Keep this file for the run command. If validation blocks the estimate, the command exits with code 1 and lists every issue. Fix them and calculate again.

> [!WARNING]
>
> Starting the Training Run places a hold for the saved estimate's maximum charge. Do not continue until you accept that amount. If the saved estimate is rejected or expires, calculate and review a new one before retrying.

See [Training cost](https://docs.platform.toloka.ai/docs/train/concepts/cost.md) for the estimate, minimum charge, hold, settlement, and no-charge cases.

## Step 7 — Start the Training Run

```sh theme={null}
toloka training run trg.YOUR_TRAINING_ID --estimate-file estimate.json
```

The command uses the saved estimate and `Support ticket SFT` as the Model Version name. Copy the `trn.…` Training Run ID. Omitting `--estimate-file` would calculate a new estimate instead of using the one you reviewed.

```sh theme={null}
toloka training status trn.YOUR_RUN_ID
toloka training logs trn.YOUR_RUN_ID
toloka training metrics trn.YOUR_RUN_ID
```

Status normally moves from `queued` to `running` to `completed`. While status is `running`, **Progress** shows the current phase. Progress `queued` or `pending` means the job is waiting for GPU capacity.

A Training Run can train longer than estimated. It stays `running`, its charge remains capped at the approved maximum, and it publishes when complete. Do not start a duplicate because the first Training Run is slower than estimated.

`training metrics` lists each metric's latest value. Use `--key train/loss` for one metric's point history and `--resolution` to request 2–500 points; the default is 200. The CLI reports when a history was thinned or trimmed.

If status is `blocked` with reason `funds`, add funds and run:

```sh theme={null}
toloka training resume trn.YOUR_RUN_ID
```

See [Training errors](https://docs.platform.toloka.ai/docs/train/reference/errors.md#blocked-training-runs) for payment and billing-review blocks.

## Step 8 — Use the trained model

When status is `completed`, inspect the Training and list its Model Versions:

```sh theme={null}
toloka training get trg.YOUR_TRAINING_ID
toloka model versions mdl.YOUR_MODEL_ID
```

Copy the `mdv.…` Model Version ID and download it:

```sh theme={null}
toloka model version download mdv.YOUR_VERSION_ID --out ./support-ticket-sft
```

The directory contains `adapter_model.safetensors`, `adapter_config.json`, and any additional validated JSON files. The CLI verifies file sizes and SHA-256 hashes.

The result is a LoRA adapter, not a hosted endpoint. Use it with its matching Base model. The Model Version records the Base model ID; upstream repository and revision belong to the catalog entry. See [Pinned revisions and lineage](https://docs.platform.toloka.ai/docs/train/reference/base-models.md#pinned-revisions-and-lineage) before serving the adapter.

## If something fails

Use [Training errors](https://docs.platform.toloka.ai/docs/train/reference/errors.md) to search exact CLI messages, blocked estimate issues, Training Run states, and terminal error codes.

## Related

* [Train your first model](https://docs.platform.toloka.ai/docs/train/get-started/first-trained-model.md)
* [Compress a prompt with gisting](https://docs.platform.toloka.ai/docs/train/guides/gist.md)
* [Prepare training data](https://docs.platform.toloka.ai/docs/train/guides/prepare-training-data.md)
* [How Training works](https://docs.platform.toloka.ai/docs/train/concepts/how-training-works.md)
* [CLI](https://docs.platform.toloka.ai/docs/cli.md)
* [Label, train, and evaluate](https://docs.platform.toloka.ai/docs/workflows/label-train-evaluate.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.