Skip to main content
The Together Python SDK includes a Tinker-compatible client, so a training loop written against the 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 tinker extra. The extra installs tinker 0.39.0, the version the client builds on, so it replaces any other tinker version you already have installed.
  • The tinker-cookbook package, if your script imports tinker_cookbook.
  • TOGETHER_API_KEY exported in your shell.
  • Enough credit to run your model resource for four hours, the minimum for creating one.
Install the packages and export your API key:

Swap the import

Replace the tinker 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 in demos/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.
From the root of a cookbook checkout, install the Tinker dependencies and run a short smoke test:
Each script also runs on Tinker when you switch the import back, so you can compare training curves across both backends.
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 APIFuture that 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(...) or await sampling_client.sample(...). In a notebook, the calls block instead.
A training client sends its requests to the server in the order you call them, so if you call 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, and dro. Other Tinker loss functions, such as gspo and stable_reinforce, raise NotImplementedError. For a custom loss, pass a callable to forward_backward_custom. create_custom_loss raises TinkerError, and LossHandle losses raise NotImplementedError.
  • Fractional weights apply to cross-entropy only: The policy-gradient loss functions accept only 0 and 1 in weights. The client warns when it sees fractional values, and the server then fails the operation. To include or exclude tokens, use mask.
  • dro needs a beta: Pass loss_fn_config={"beta": ...}. beta has no default.
  • Loss inputs must be one-dimensional: A two-dimensional loss_fn_inputs tensor raises ValueError, so loss functions that need several target tokens per position, such as top-K distillation, aren’t supported.
  • Text input only: model_input must contain only encoded text chunks. Image chunks raise ValueError.
  • Per-datum outputs can be skipped: As in Tinker, forward and forward_backward return per-datum log-probabilities in loss_fn_outputs. To shrink the response and speed up the step on large batches, pass return_loss_fn_outputs=False, an argument Tinker doesn’t accept. Either way, the total loss is in metrics["loss:sum"].
  • forward returns zeros at unweighted positions: Positions whose weights are 0 come back as 0.0 in loss_fn_outputs, not as their log-probabilities. To read every position, pass weights of 1 everywhere.
  • Custom loss functions train only weighted positions: forward_backward_custom applies your gradients only at positions whose weights are nonzero. A datum with no weights gets all zeros, so it trains nothing. Pass weights of 1 on every position your loss reads.
  • A failed custom loss stops the training client: As in Tinker, if forward_backward_custom fails, 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 optimizer other than Adam, or optim_step parameters other than AdamParams, raises NotImplementedError.
  • Module selection is fixed: train_mlp and train_attn can’t be turned off, so the client warns on non-default values and ignores them. seed and train_unembed pass 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 of 64, 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_client again, an earlier sampling client raises RuntimeError instead of serving the old policy. Create a new sampling client after each publish. To keep a client that samples whatever weights are live, pass allow_stale=True or kind="inflight" to save_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_logprobs above 20 raises ValueError. topk_sample_logprobs, target_prompt_logprobs, prompt_alt_tokens_k, and prompt_logprobs_last_n raise NotImplementedError.

Checkpoints

  • Checkpoint names are server-assigned: Training and inference checkpoints get a generated ID, whatever name you pass. The client warns on the ttl_seconds, overwrite, retry_config, and record_stability_info arguments 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: ServiceClient accepts project_id and ignores it, so every call runs in the project that your TOGETHER_API_KEY belongs to. The client also ignores user_metadata, which ServiceClient and the methods that create training clients accept.
  • Transport options are ignored: ServiceClient accepts Tinker’s HTTP options and ignores them. It warns on http_client, max_retries, and timeout. Any other unknown argument raises TypeError.

Unsupported calls

Calling a Tinker method the client doesn’t define raises an AttributeError that names the method as unsupported. These methods include:
  • On ServiceClient: create_sampling_client, get_server_capabilities, and get_telemetry.
  • On training clients: get_tokenizer, get_info, load_state, load_state_with_optimizer, and save_weights_external.
  • On sampling clients: get_tokenizer and get_base_model.
To get a tokenizer, call 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 with Ctrl+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:
To close every training client that a service client created, use the service client as a context manager, or call 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 to ServiceClient:
The resource must be LoRA-enabled and serve the same base model you pass to 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 RuntimeError about a stale sampling client: The script reused a sampling client after publishing newer weights. Create a new one after each save_weights_and_get_sampling_client call, or pass allow_stale=True.
  • Reward stays at zero: If the script’s renderer has thinking turned on, completions can use up max_tokens on reasoning and never reach the answer. Raise max_tokens, or use a renderer with thinking turned off.
  • ServiceClient raises TypeError: 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.