Fine-tune a model

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.

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.

For prompt compression rather than weight adaptation, use Compress a prompt with gisting.

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

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:

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:

{"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:

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

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:

toloka model versions "Your model name"

A full-weight Model Version cannot be a source. See Base models.

Step 5 — Create the Training draft

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

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. Copy that Training ID. To warm-start from an adapter, pass --model-version instead of --base-model:

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:

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 for accepted values and defaults.

Step 6 — Review the cost

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.

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 for the estimate, minimum charge, hold, settlement, and no-charge cases.

Step 7 — Start the Training Run

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.

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:

toloka training resume trn.YOUR_RUN_ID

See Training errors for payment and billing-review blocks.

Step 8 — Use the trained model

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

toloka training get trg.YOUR_TRAINING_ID
toloka model versions mdl.YOUR_MODEL_ID

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

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 before serving the adapter.

If something fails

Use Training errors to search exact CLI messages, blocked estimate issues, Training Run states, and terminal error codes.

Start

Data Labeling

Train

Workflows

Admin

Before you start

Step 2 — Create or select a project

Step 3 — Put labeled conversations in a dataset

Step 4 — Choose a Base model

Step 5 — Create the Training draft

Step 6 — Review the cost

Step 7 — Start the Training Run

Step 8 — Use the trained model

If something fails

​Before you start

​Step 1 — Install and sign in

​Step 2 — Create or select a project

​Step 3 — Put labeled conversations in a dataset

​Step 4 — Choose a Base model

​Step 5 — Create the Training draft

​Step 6 — Review the cost

​Step 7 — Start the Training Run

​Step 8 — Use the trained model

​If something fails

​Related

Before you start

Step 1 — Install and sign in

Step 2 — Create or select a project

Step 3 — Put labeled conversations in a dataset

Step 4 — Choose a Base model

Step 5 — Create the Training draft

Step 6 — Review the cost

Step 7 — Start the Training Run

Step 8 — Use the trained model

If something fails

Related