Tinker: training and inference
Tinker gives you token-level control of hosted fine-tuning: you build the
Datums, you own the chat template, you hold the exact prompt and completion
token ids on both sides. That is the reason to use it — a training run stays
auditable, because the tokens the policy was updated on are tokens you can point
at — and it is also why there is more to get right than with a hosted
fine-tuning button. This skill is the map.
Do this first, in any new Tinker project
Create the pricing file. Prices next to the training script get read before a
550B RL run is launched; prices in a browser tab do not.
python <skill>/scripts/tinker_pricing.py init --out <project dir>
That writes TINKER_PRICING.md — the full catalogue, what each operation
meters, and the pre-launch checklist. It is a snapshot: verify against the
live catalogue at https://tinker-docs.thinkingmachines.ai/tinker/models/, and
regenerate with --force when it moves. Then:
export TINKER_API_KEY="..." # console.tinker.ai
uv pip install tinker
Where to go
Runnable templates
Copy into the project and replace the marked function:
| script | replace |
|---|
scripts/tinker_sft.py | load_dataset() — everything else (Datum construction, loss masking, before/after eval, checkpointing) is the part that is easy to get subtly wrong |
scripts/tinker_rl.py | TASKS, render_prompt(), reward() |
scripts/tinker_infer.py | nothing — CLI, both the SDK and HTTP routes |
scripts/tinker_pricing.py | nothing — catalogue, init, and the cost estimator |
The API in one screen
import tinker
from tinker import types
service_client = tinker.ServiceClient() # reads TINKER_API_KEY
training_client = service_client.create_lora_training_client(
base_model="Qwen/Qwen3-8B", rank=32)
tokenizer = training_client.get_tokenizer()
# SFT ---------------------------------------------------------------------
result = training_client.forward_backward(batch, loss_fn="cross_entropy").result()
training_client.optim_step(types.AdamParams(learning_rate=1e-4)).result()
# RL ----------------------------------------------------------------------
sampler = training_client.save_weights_and_get_sampling_client(name=f"iter-{it}")
resp = sampler.sample(prompt=types.ModelInput.from_ints(prompt_tokens),
num_samples=8,
sampling_params=types.SamplingParams(
max_tokens=4096, temperature=1.0,
stop=STOP_STRINGS, seed=seed)).result()
training_client.forward_backward(rl_data, loss_fn="importance_sampling").result()
training_client.optim_step(types.AdamParams(learning_rate=1e-4)).result()
# checkpoints -------------------------------------------------------------
training_client.save_state(name="iter-40") # -> weights/… resumable
training_client.save_weights_for_sampler(name="final") # -> sampler_weights/… servable
Every call returns a future; .result() blocks, and an _async variant exists
for each. Loss functions: cross_entropy (SFT), importance_sampling (RL
default), ppo, cispo, dro, or your own via forward_backward_custom_async.
Things that are true and easy to miss
Two checkpoint types, not interchangeable. save_weights_for_sampler →
sampler_weights/… is servable and downloadable. save_state → weights/…
carries optimizer state and is for resuming. The download endpoint rejects the
latter with a 400. Save both.
The context window is part of the model id. openai/gpt-oss-120b is 32K;
openai/gpt-oss-120b:peft:131072 is a different model at 128K and ~2.4× the
prefill price. Assert your configured window against
get_server_capabilities() at startup — configured above the served limit means
episodes die on BadRequestError mid-run, and they die in whichever arm has
longer conversations, which silently unbalances an A/B.
Prompt format is a contract that outlives the run. A checkpoint SFT'd on raw
text must be prompted as raw text forever after; wrapping it in a chat template
it never saw looks exactly like a fine-tune that did nothing. Record the format
next to the checkpoint path.
In RL, everything except the policy must be constant inside a group. The
advantage is a within-group difference, so a simulated user sampling at
temperature injects noise straight into the gradient and attributes it to the
policy. Measured in the reference project: at user temperature 0.5, two runs of
the same configuration differed by as much as the effect under study.
Evaluate the base model before training it. If it sits at a floor on your
task, every rollout in every group ties, every advantage is zero, and no
gradient ever flows — and no ablation you run against it can resolve anything.
Reasoning tokens count against max_tokens. A model that spends its budget
inside <think> emits neither a reply nor a tool call, which is not a valid
message. Budget 4096, not 1024, and add a truncation retry.
Do the multiplication before launching. RL cost is
iterations × tasks_per_iter × group_size × turns. Every one of those is a flag
someone bumps on its own:
python scripts/tinker_pricing.py estimate-rl --model openai/gpt-oss-120b \
--iterations 10 --tasks-per-iter 8 --group-size 8 \
--turns 20 --avg-prompt 8000 --avg-completion 400
Recording the run
Tinker keeps almost nothing locally — a hosted run UUID and that is it. Anything
you want to inspect later has to be written by you.
Use the companion research-observability skill. It was built against this
stack: run.sample() takes Tinker's prompt and completion token ids directly, so
the trace records exactly the tokens the policy was updated on, and its viewers
and cost report work on the result unchanged. That skill records the loop; this
one runs it.
Links