tinker SDK runs on post-training after you change its import line and, if needed, its base model. The client replaces only the service calls, so your rendering, tokenization, and grading code runs unchanged, including the tinker_cookbook helpers it imports.
Requirements
- Python 3.11 or later.
- The Together Python SDK 3.3.0 or later, with the
tinkerextra. The extra installstinker0.39.0, the version the client builds on, so it replaces any othertinkerversion you already have installed. - The
tinker-cookbookpackage, if your script importstinker_cookbook. TOGETHER_API_KEYexported in your shell.- Enough credit to run your model resource for four hours, the minimum for creating one.
Swap the import
Replace thetinker import with the Together client:
tinker.types resolves to the real Tinker types, so the prompts and Datum objects your code builds pass through unchanged.
Besides the import, the only value you might need to change is the base model. Tinker and Together host different catalogs, so if your script’s model isn’t one of the supported models, switch to one that is.
When the script calls create_lora_training_client, the client provisions a model resource for the base model, waits until it’s ready, and opens a low-rank adapter (LoRA) session on it. Billing starts when the resource is ready.
The wait takes a few minutes for a small model, and longer when GPU capacity is scarce. The client keeps waiting until the resource is allocated the required GPUs, and if you interrupt it, it stops the queued resource. To set a time limit, create the resource yourself with ModelResourcesClient.create(..., ready_timeout=3600), then train on it as an existing resource. ready_timeout is in seconds, so if the resource isn’t ready within an hour, this call raises TimeoutError and stops the resource.
Run the example scripts
The post-training cookbook has three example scripts indemos/tinker-migration/. Each one is adapted from a tinker_cookbook recipe, with the import already swapped to the Together client:
grpo_gsm8k.py: A minimal group relative policy optimization (GRPO) loop on GSM8K.grpo_gsm8k_async.py: The same loop, sampling each batch while the previous one trains.sft_no_robots.py: A supervised fine-tuning (SFT) loop on No Robots.
The example scripts build their training data in Tinker’s format, with
tinker_cookbook helpers or by hand. When you write a loop on the SDK directly, build samples with every per-token array shifted to the target positions.How Tinker calls map to post-training
The client follows Tinker 0.39’s two call styles:
- In synchronous code: A call returns either a client or an
APIFuturethat you call.result()on. - Inside a running event loop: The same calls return an awaitable immediately, so you can
await service_client.create_lora_training_client(...)orawait sampling_client.sample(...). In a notebook, the calls block instead.
optim_step before you await the preceding forward_backward, the optim_step still runs second.
The deprecated _async variants still work.
Behavior differences
The client differs from Tinker in ways that can affect your results, and some differences need a change to your script.Training
- Some loss functions aren’t supported: The client supports the built-in loss functions
cross_entropy,importance_sampling,ppo,cispo, anddro. Other Tinker loss functions, such asgspoandstable_reinforce, raiseNotImplementedError. For a custom loss, pass a callable toforward_backward_custom.create_custom_lossraisesTinkerError, andLossHandlelosses raiseNotImplementedError. - Fractional weights apply to cross-entropy only: The policy-gradient loss functions accept only
0and1inweights. The client warns when it sees fractional values, and the server then fails the operation. To include or exclude tokens, usemask. droneeds abeta: Passloss_fn_config={"beta": ...}.betahas no default.- Loss inputs must be one-dimensional: A two-dimensional
loss_fn_inputstensor raisesValueError, so loss functions that need several target tokens per position, such as top-K distillation, aren’t supported. - Text input only:
model_inputmust contain only encoded text chunks. Image chunks raiseValueError. - Per-datum outputs can be skipped: As in Tinker,
forwardandforward_backwardreturn per-datum log-probabilities inloss_fn_outputs. To shrink the response and speed up the step on large batches, passreturn_loss_fn_outputs=False, an argument Tinker doesn’t accept. Either way, the total loss is inmetrics["loss:sum"]. forwardreturns zeros at unweighted positions: Positions whoseweightsare0come back as0.0inloss_fn_outputs, not as their log-probabilities. To read every position, passweightsof1everywhere.- Custom loss functions train only weighted positions:
forward_backward_customapplies your gradients only at positions whoseweightsare nonzero. A datum with noweightsgets all zeros, so it trains nothing. Passweightsof1on every position your loss reads. - A failed custom loss stops the training client: As in Tinker, if
forward_backward_customfails, the training client rejects every later training request. Unlike Tinker, the client also does this when the server fails the request. To continue, create a new training client. - Adam only: Passing an
optimizerother than Adam, oroptim_stepparameters other thanAdamParams, raisesNotImplementedError. - Module selection is fixed:
train_mlpandtrain_attncan’t be turned off, so the client warns on non-default values and ignores them.seedandtrain_unembedpass through to the session’s LoRA config. - LoRA rank is limited and alpha is fixed: The maximum rank is 64 on Qwen models and 32 on every other model. The client never sends
lora_alpha, so every session uses Together’s default of64, whatever rank you pass.
Sampling
- Sampling clients aren’t snapshots: Together samples from the most recently published weights. Once you call
save_weights_and_get_sampling_clientagain, an earlier sampling client raisesRuntimeErrorinstead of serving the old policy. Create a new sampling client after each publish. To keep a client that samples whatever weights are live, passallow_stale=Trueorkind="inflight"tosave_weights_and_get_sampling_client. - Stop sequences must be strings: Together’s sampler takes stop strings, so the client drops stop sequences given as token IDs and warns. Generation still stops at the model’s end-of-sequence token.
- Some sampling arguments are limited or unsupported:
topk_prompt_logprobsabove20raisesValueError.topk_sample_logprobs,target_prompt_logprobs,prompt_alt_tokens_k, andprompt_logprobs_last_nraiseNotImplementedError.
Checkpoints
- Checkpoint names are server-assigned: Training and inference checkpoints get a generated ID, whatever
nameyou pass. The client warns on thettl_seconds,overwrite,retry_config, andrecord_stability_infoarguments and ignores them. - Checkpoints aren’t served by path: There’s no
tinker://path to pass to an OpenAI-compatible endpoint. To call a trained model, deploy its inference checkpoint first.
Client options
- The project comes from your API key:
ServiceClientacceptsproject_idand ignores it, so every call runs in the project that yourTOGETHER_API_KEYbelongs to. The client also ignoresuser_metadata, whichServiceClientand the methods that create training clients accept. - Transport options are ignored:
ServiceClientaccepts Tinker’s HTTP options and ignores them. It warns onhttp_client,max_retries, andtimeout. Any other unknown argument raisesTypeError.
Unsupported calls
Calling a Tinker method the client doesn’t define raises anAttributeError that names the method as unsupported. These methods include:
- On
ServiceClient:create_sampling_client,get_server_capabilities, andget_telemetry. - On training clients:
get_tokenizer,get_info,load_state,load_state_with_optimizer, andsave_weights_external. - On sampling clients:
get_tokenizerandget_base_model.
tinker_cookbook.tokenizer_utils.get_tokenizer(base_model), as the example scripts do. To sample from a saved checkpoint instead of create_sampling_client, see Sample a saved checkpoint.
create_rest_client raises TinkerError, and passing weights_access_token raises NotImplementedError. To catch TinkerError, import it with from tinker import TinkerError, because together.post_training.tinker doesn’t re-export it.
Replace RestClient calls
create_rest_client isn’t available, so call the Together SDK for the run and checkpoint lookups that Tinker’s RestClient handles:
client is a together.Together client.
Clean up GPUs
Tinker’s training client has no teardown call, so the Together client registers its own cleanup, which stops the session and the model resource the client provisioned. The cleanup runs when the script exits normally, raises an uncaught exception, is interrupted withCtrl+C, or receives SIGTERM. Only SIGKILL and os._exit skip it. If either one ends the script, the resource keeps billing until it stops on its own after an hour idle.
In a long-lived process such as a notebook, the cleanup doesn’t run until the process exits. To release the GPUs as soon as training ends, call training_client.close() or use the training client as a context manager:
service_client.close("success"). The client accepts the status argument for Tinker compatibility and ignores it.
Train on an existing resource
To attach to a model resource that’s already running, pass its ID toServiceClient:
create_lora_training_client. The client opens its session on that resource. On exit, it stops the session but leaves the resource running.
model_resources_id is a Together-only argument, so a script that passes it no longer runs unchanged on Tinker.
Troubleshooting
- Creating the training client fails because the base model isn’t supported: The model ID isn’t in the post-training catalog. Pick one from Supported models.
- Sampling raises
RuntimeErrorabout a stale sampling client: The script reused a sampling client after publishing newer weights. Create a new one after eachsave_weights_and_get_sampling_clientcall, or passallow_stale=True. - Reward stays at zero: If the script’s renderer has thinking turned on, completions can use up
max_tokenson reasoning and never reach the answer. Raisemax_tokens, or use a renderer with thinking turned off. ServiceClientraisesTypeError: The script passes an argument the Together client doesn’t accept. Remove it.
Next steps
Write a training loop
Call the session operations behind the Tinker client directly from your own loop.
Supported models
Pick a base model by training mode, context length, and GPU type.
Manage checkpoints
Download the weights or resume a run from a checkpoint.