Train your first model

You will train a model on 10 support tickets and download the result, a Model Version. A Model Version is the set of files a completed Training Run produces.

Commands print IDs that you paste into later commands. Values that differ on your account appear here as … or YOUR_…: IDs, timestamps, token counts, charges, and project counts.

Before you start

You need:

• A supported standalone CLI system: macOS or glibc Linux on ARM64 or x64. Native Windows and musl Linux releases are not available yet. The CLI includes its runtime; see CLI installation.
• An API key. Open https://console.toloka.ai, go to Company → API Keys, press Generate API Key, and copy the key. The key is shown once.
• A funded team balance. The balance pays for the Training Run. See Manage your team and balance to top up.
• A browser signed in to the web app at https://platform.toloka.ai. You create the dataset there.

Step 1 — Install the CLI and sign in

Install the stable CLI and sign in:

curl -fsSL https://platform.toloka.ai/cli/install.sh | sh
toloka version --json
toloka login
toloka whoami

Training requires stable CLI 0.2.0 or newer. The standalone CLI includes its runtime, so this tutorial needs neither Bun nor an SDK project dependency. For version pins, updates, PATH fixes, and migration, see Updates and migration from Bun global installs. There is no toloka update command; rerun the installer for an immediate update.

login prompts for the API key without echoing it and saves it only after authentication succeeds. Treat the key like a password. whoami shows the selected platform and a masked key.

Step 2 — Find your team ID

Open https://platform.toloka.ai in the browser and sign in. The address bar then reads https://platform.toloka.ai/teams/YOUR_TEAM_ID/projects. Copy the team ID: the part of the address between /teams/ and /projects.

Note

If the app shows a team chooser first, choose your team; the address bar then shows the ID. If you land in the older workspace, follow Step 1 of Get your first labeled dataset to switch.

Step 3 — Create the project

A project holds the dataset, the Training, and the resulting Model. Billing goes to your team balance.

Open a new, empty folder in your terminal. Create a project named First training:

toloka project create first-training --name "First training" --team-id YOUR_TEAM_ID
# Created project pp.… as first-training.
toloka project current
# Project:  pp.… (alias first-training, from toloka.json; registry current is first-training)

project create selects the project and writes a toloka.json file in this folder. Run the rest of the tutorial from this folder.

Step 4 — Save the training data

A dataset is a collection of items. Each line of the file becomes one item. The CLI calls items rows. Each row below is one chat with a support ticket and its label.

Save these 10 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"}]}

Each final assistant turn contains the label question, complaint, or praise. Keep all 10 rows in one file. Without a separate validation dataset, the run holds out 10% of these rows automatically.

Check the file has 10 lines:

wc -l support-tickets.jsonl
#       10 support-tickets.jsonl

Step 5 — Create and upload the dataset

Print the project’s web address and open it in the browser:

toloka project url
# https://platform.toloka.ai/teams/YOUR_TEAM_ID/projects/pp.…

Create the dataset in the web app first. The CLI uploads rows into an existing dataset; it does not create one from this folder. Open Datasets in the sidebar and click the plus button.

The plus button creates a dataset named New Dataset. Open the ⋯ menu on the dataset header, click Rename dataset, enter support-tickets, and confirm.

Upload the file and list the datasets:

toloka dataset upload support-tickets ./support-tickets.jsonl
# Uploaded 10 rows to dataset support-tickets.
toloka dataset list
# support-tickets  ds.…

The upload command may also list the fields it found in the file. Run it once: uploads append, so a second run adds the 10 rows again. Copy the ds.… dataset ID from the list line; a tab separates the name and the ID.

Step 6 — Create the Training

A Base model is the catalog model your Training starts from. List the available Base models:

toloka base-model list
# ID          NAME        PROVIDER  UPSTREAM MODEL                      REVISION      UPSTREAM SNAPSHOT
# qwen3-4b    Qwen3 4B    Qwen      Qwen/Qwen3-4B-Instruct-2507         cdbee75f17c0  https://huggingface.co/Qwen/Qwen3-4B-Instruct-2507/tree/cdbee75f17c01a7cc42f958dc650907174af0554
# qwen3-8b    Qwen3 8B    Qwen      Qwen/Qwen3-8B                       b968826d9c46  https://huggingface.co/Qwen/Qwen3-8B/tree/b968826d9c46dd6066d109eabc6255188de91218
# qwen3-32b   Qwen3 32B   Qwen      Qwen/Qwen3-32B                      9216db5781bf  https://huggingface.co/Qwen/Qwen3-32B/tree/9216db5781bf21249d130ec9da846c4624c16137
# qwen3-235b  Qwen3 235B  Qwen      Qwen/Qwen3-235B-A22B-Instruct-2507  ac9c66cc9b46  https://huggingface.co/Qwen/Qwen3-235B-A22B-Instruct-2507/tree/ac9c66cc9b46af7306746a9250f23d47083d689e

Use qwen3-4b, the smallest Base model.

A Training is an editable draft that records the Base model, dataset, and training settings. Create one named First training:

toloka training create "First training" \
  --base-model qwen3-4b \
  --dataset ds.YOUR_DATASET_ID
# Created training trg.…
toloka training get trg.YOUR_TRAINING_ID
# ID            trg.…
# Project       pp.…
# Method        Supervised fine-tuning (SFT)
# Output Model  -
# Archived at   -
# Created at    …
# Updated at    …

Copy the trg.… Training ID. Supervised fine-tuning is the default method. The - means no Training Run exists yet. The first run creates the Model.

Step 7 — Review the cost estimate

A cost estimate is free. It checks the Training inputs and shows the maximum charge, the most the run can cost.

Calculate it:

toloka training cost trg.YOUR_TRAINING_ID
# Training             trg.…
# Training rows        10
# Training tokens      …
# Maximum GPU seconds  …
# Maximum charge       $… USD
# Fingerprint          …

The Training rows line confirms that all 10 rows are ready. The Fingerprint line identifies this estimate. You do not need it in this tutorial.

If the estimate is blocked, the command exits with code 1 and prints Training cannot run with these inputs: followed by one - <message> line per problem. Fix each. Then calculate the cost again.

Caution

Starting the next command places a hold for the maximum charge on the team balance. When the run ends, the platform charges only for the GPU seconds used, capped at the maximum charge, and returns the rest of the hold. If the run fails because of the platform, nothing is charged and the whole hold is returned.

Step 8 — Start and watch the Training Run

A Training Run is one billed execution of the Training. Start it:

toloka training run trg.YOUR_TRAINING_ID
# ID                      trn.…
# Training                trg.…
# Status                  queued
# Blocked reason          -
# Message                 -
# Error code              -
# Billing status          pending
# Charged amount          -
# Progress                -
# Model Version name      First training
# Model Version revision  -
# Future Model Version    mdv.…
# Maximum charge          $… USD
# Created at              …

The command calculates a fresh ready estimate. It names the future Model Version First training. Copy the trn.… Training Run ID.

Follow the logs until the run completes, then check the status:

toloka training logs trn.YOUR_RUN_ID --follow
# …
toloka training status trn.YOUR_RUN_ID
# ID                      trn.…
# Training                trg.…
# Status                  completed
# Blocked reason          -
# Message                 -
# Error code              -
# Billing status          settled
# Charged amount          $… USD
# Progress                -
# Model Version name      First training
# Model Version revision  1
# Future Model Version    mdv.…
# Maximum charge          $… USD
# Created at              …

The status moves from queued to running to completed. --follow prints log lines until the run completes. While the run is running, toloka training status shows what it is doing in the Progress row. Status completed with revision 1 means the Model Version is published. Charged amount is what the run cost; it is at most the maximum charge.

If the status is blocked and the blocked reason is funds, the team balance cannot cover the hold. Top up the balance, then run toloka training resume trn.YOUR_RUN_ID. Nothing is charged if the run stops before training starts.

Step 9 — Download the Model Version

toloka training run created a Model for this Training. A Model is a named container for Model Versions. The completed run published revision 1 into it. Both take the Training’s name, First training.

List the versions by the Model’s name:

toloka model versions "First training"
# REVISION  NAME            ID     CREATED AT
# 1         First training  mdv.…  …

Copy the mdv.… ID and download the files:

toloka model version download mdv.YOUR_VERSION_ID --out ./first-training-model
# Downloaded Model Version mdv.… revision 1 to /…/first-training-model

The folder holds adapter_model.safetensors and adapter_config.json. The run may add other .json files. Together they form a LoRA adapter: a small set of extra weights that the Qwen3 4B Base model loads on top of its own.

The platform does not host or serve the model. To test it, deploy it. You can use our partner, Nebius.

You trained and downloaded your first Model Version.

Next steps

• Training — how Trainings, cost estimates, Training Runs, and Model Versions fit together
• Fine-tune a model — the same commands for your own data, with the error table
• Compress a prompt with gisting — the other Training method
• Create and manage datasets — the Datasets page in the web app
• CLI — every command, flag, and sign-in option