Migrate from Tinker

​

Requirements

• Python 3.11 or later.
• The Together Python SDK 2.41.0 or later, with the tinker extra. The extra installs tinker 0.23.1, the version the client builds on, so it replaces a newer tinker you already have installed.
• The tinker-cookbook package, if your script imports tinker_cookbook.
• TOGETHER_API_KEY exported in your shell.
• A credit balance of at least $100, the minimum for creating a model resource.

pip install -U "together[tinker]>=2.41.0" tinker-cookbook
export TOGETHER_API_KEY=<your_key>

​

Swap the import

-import tinker
+import together.post_training.tinker as tinker

​

Run the example scripts

import together.post_training.tinker as tinker

• grpo_gsm8k.py: A minimal GRPO loop on GSM8K.
• grpo_gsm8k_async.py: The same loop, sampling each batch while the previous one trains.
• sft_no_robots.py: Supervised fine-tuning on No Robots.

uv sync --locked --group tinker
uv run python demos/tinker-migration/grpo_gsm8k.py --batch-size 8 --group-size 4 --max-steps 3

​

How Tinker calls map to post-training

​

Behavior differences

• Sampling clients aren’t snapshots: Together samples from the most recently published weights. After a later save_weights_and_get_sampling_client call, an earlier sampling client raises RuntimeError instead of serving the old policy. Create a new sampling client after each publish, or pass allow_stale=True to keep a client that samples whatever weights are live.
• 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.
• forward_backward returns no per-datum outputs by default: Its loss_fn_outputs list is empty unless you pass return_loss_fn_outputs=True, an argument Tinker doesn’t accept. Scripts that read log-probabilities from it, such as the tinker_cookbook recipe sl_loop.py, need that argument or a separate forward call. The total loss is in metrics["loss:sum"].
• 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.
• 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.
• 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, and retry_config arguments and ignores them.
• 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.
• 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.
• Text input only: model_input must contain only encoded text chunks. Image chunks raise ValueError.
• 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.
• dro needs a beta: Pass loss_fn_config={"beta": ...}. The loss function has no default.
• LoRA rank and alpha: 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 arguments: topk_prompt_logprobs above 20 raises ValueError.
• 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. See Deploy a checkpoint.
• The project comes from your API key: ServiceClient accepts project_id and user_metadata and ignores them. Every call runs in the project that your TOGETHER_API_KEY belongs to.
• 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.
• Some calls aren’t available: create_rest_client raises TinkerError from the tinker package, and passing weights_access_token raises NotImplementedError. To catch the error, import it with from tinker import TinkerError, because together.post_training.tinker doesn’t re-export it. The client doesn’t define create_sampling_client, get_tokenizer, get_info, get_base_model, get_telemetry, load_state, load_state_with_optimizer, or get_server_capabilities, so calls to them raise AttributeError. Sampling clients don’t define get_tokenizer or get_base_model either. ServiceClient also has no close and isn’t a context manager, so close the training client instead, as in Clean up GPUs. 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.

​

Replace RestClient calls

​

Clean up GPUs

import together.post_training.tinker as tinker

service_client = tinker.ServiceClient()
with service_client.create_lora_training_client(
    base_model="Qwen/Qwen3.8-27B", rank=32
) as training_client:
    ...  # your training loop

​

Train on an existing resource

service_client = tinker.ServiceClient(
    model_resources_id="your_model_resources_id"
)

​

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