Implementation:Togethercomputer Together python FineTuning Create

Attribute	Value
Implementation Name	FineTuning_Create
Type	API Method
Source	src/together/resources/finetune.py:L335-539
Domain	MLOps, Fine_Tuning
Repository	togethercomputer/together-python
Last Updated	2026-02-15 16:00 GMT

API Signature

class FineTuning:
    def create(
        self,
        *,
        training_file: str,
        model: str | None = None,
        n_epochs: int = 1,
        validation_file: str | None = "",
        n_evals: int | None = 0,
        n_checkpoints: int | None = 1,
        batch_size: int | Literal["max"] = "max",
        learning_rate: float | None = 0.00001,
        lr_scheduler_type: Literal["linear", "cosine"] = "cosine",
        min_lr_ratio: float = 0.0,
        scheduler_num_cycles: float = 0.5,
        warmup_ratio: float = 0.0,
        max_grad_norm: float = 1.0,
        weight_decay: float = 0.0,
        lora: bool = True,
        lora_r: int | None = None,
        lora_dropout: float | None = 0,
        lora_alpha: float | None = None,
        lora_trainable_modules: str | None = "all-linear",
        train_vision: bool = False,
        suffix: str | None = None,
        wandb_api_key: str | None = None,
        wandb_base_url: str | None = None,
        wandb_project_name: str | None = None,
        wandb_name: str | None = None,
        verbose: bool = False,
        model_limits: FinetuneTrainingLimits | None = None,
        train_on_inputs: bool | Literal["auto"] | None = None,
        training_method: str = "sft",
        dpo_beta: float | None = None,
        dpo_normalize_logratios_by_length: bool = False,
        rpo_alpha: float | None = None,
        simpo_gamma: float | None = None,
        from_checkpoint: str | None = None,
        from_hf_model: str | None = None,
        hf_model_revision: str | None = None,
        hf_api_token: str | None = None,
        hf_output_repo_name: str | None = None,
    ) -> FinetuneResponse:

Import

from together import Together

client = Together()
response = client.fine_tuning.create(...)

I/O Contract

Inputs

Parameter	Type	Default	Description
`training_file`	`str`	(required)	File ID of the uploaded training file (from `Files.upload()`).
`model`	None	`None`	Base model name to fine-tune. Either `model` or `from_checkpoint` must be specified.
`n_epochs`	`int`	`1`	Number of training epochs.
`validation_file`	None	`""`	File ID of an uploaded validation file.
`n_evals`	None	`0`	Number of evaluation loops during training.
`n_checkpoints`	None	`1`	Number of checkpoints to save during training.
`batch_size`	Literal["max"]	`"max"`	Training batch size. `"max"` uses the maximum allowed for the model.
`learning_rate`	None	`0.00001`	Learning rate (1e-5).
`lr_scheduler_type`	`Literal["linear", "cosine"]`	`"cosine"`	Learning rate scheduler type.
`min_lr_ratio`	`float`	`0.0`	Minimum learning rate ratio (must be in [0, 1]).
`scheduler_num_cycles`	`float`	`0.5`	Number of cycles for cosine scheduler (must be > 0).
`warmup_ratio`	`float`	`0.0`	Warmup ratio for the LR scheduler (must be in [0, 1]).
`max_grad_norm`	`float`	`1.0`	Maximum gradient norm for clipping. Set to 0 to disable.
`weight_decay`	`float`	`0.0`	Weight decay (must be >= 0).
`lora`	`bool`	`True`	Whether to use LoRA adapters.
`lora_r`	None	`None`	LoRA rank. Defaults to the model's maximum rank when `None`.
`lora_dropout`	None	`0`	LoRA dropout rate (must be in [0, 1)).
`lora_alpha`	None	`None`	LoRA alpha scaling. Defaults to `2 * lora_r` when `None`.
`lora_trainable_modules`	None	`"all-linear"`	Which modules to apply LoRA to.
`train_vision`	`bool`	`False`	Whether to train the vision encoder (multimodal models only).
`suffix`	None	`None`	Up to 40-character suffix for the fine-tuned model name.
`wandb_api_key`	None	`None`	Weights & Biases API key.
`wandb_base_url`	None	`None`	Weights & Biases base URL.
`wandb_project_name`	None	`None`	Weights & Biases project name.
`wandb_name`	None	`None`	Weights & Biases run name.
`verbose`	`bool`	`False`	Whether to print job parameters before submission.
`model_limits`	None	`None`	Pre-fetched model limits. Fetched automatically if `None`.
`train_on_inputs`	Literal["auto"] \| None	`None`	Whether to mask user messages/prompts during loss computation. Defaults to `"auto"` for SFT. Only valid for SFT.
`training_method`	`str`	`"sft"`	Training method: `"sft"` or `"dpo"`.
`dpo_beta`	None	`None`	DPO beta regularization parameter. Only valid for DPO.
`dpo_normalize_logratios_by_length`	`bool`	`False`	Whether to normalize log-ratios by sample length. Only valid for DPO.
`rpo_alpha`	None	`None`	RPO alpha to include NLL in DPO loss (must be >= 0). Only valid for DPO.
`simpo_gamma`	None	`None`	SimPO gamma parameter (must be >= 0). Enables reference-free DPO. Only valid for DPO.
`from_checkpoint`	None	`None`	Checkpoint identifier to continue training from (format: `{JOB_ID}:{STEP}`).
`from_hf_model`	None	`None`	Hugging Face Hub repo for starting weights. Requires `model`.
`hf_model_revision`	None	`None`	Specific revision of the HF model (defaults to latest main).
`hf_api_token`	None	`None`	Hugging Face Hub API token.
`hf_output_repo_name`	None	`None`	HF repo to push the fine-tuned model to.

Output

Returns a FinetuneResponse object with fields including:

Field	Type	Description
`id`	`str`	Fine-tuning job ID (starts with `"ft-"`).
`status`	`str`	Job status (e.g., `"pending"`, `"running"`, `"completed"`).
`model`	`str`	Base model name.
`training_file`	`str`	Training file ID.
`output_name`	`str`	Name of the output fine-tuned model.

Validation Errors

The method raises ValueError for invalid parameter combinations:

Both model and from_checkpoint specified (or neither).
from_checkpoint used together with from_hf_model.
from_hf_model specified without model.
LoRA not supported for the selected model.
lora_dropout outside [0, 1) range.
batch_size exceeding model limits.
warmup_ratio outside [0, 1] range.
training_method not in {"sft", "dpo"}.
DPO-specific parameters used with SFT, or train_on_inputs used with DPO.
train_vision=True on a non-multimodal model.

Code Reference

The method at src/together/resources/finetune.py:L335-539 performs these steps:

Fetch model limits -- If model_limits is not provided, calls self.get_model_limits(model=model_name) to retrieve model-specific training constraints from the API.
Build request -- Delegates to create_finetune_request() (L56-294) which validates all parameters, constructs the FinetuneRequest payload including LR scheduler configuration, training type (LoRA or Full), training method (SFT or DPO), and multimodal parameters.
Price estimation -- Calls self.estimate_price() to check if the user has sufficient credits (skipped for checkpoint/HF model continuations).
Submit request -- Posts to the fine-tunes API endpoint.
Return response -- Parses and returns the FinetuneResponse.

Usage Examples

Basic SFT with LoRA

from together import Together

client = Together()

response = client.fine_tuning.create(
    training_file="file-abc123",
    model="meta-llama/Meta-Llama-3.1-8B-Instruct",
    n_epochs=3,
    learning_rate=2e-5,
    lora=True,
    lora_r=16,
)
print(f"Job ID: {response.id}")
print(f"Status: {response.status}")

Full Training (No LoRA)

from together import Together

client = Together()

response = client.fine_tuning.create(
    training_file="file-abc123",
    model="meta-llama/Meta-Llama-3.1-8B-Instruct",
    n_epochs=1,
    lora=False,
    batch_size=4,
    learning_rate=1e-5,
)
print(f"Job ID: {response.id}")

DPO Training

from together import Together

client = Together()

response = client.fine_tuning.create(
    training_file="file-dpo456",
    model="meta-llama/Meta-Llama-3.1-8B-Instruct",
    training_method="dpo",
    dpo_beta=0.1,
    n_epochs=2,
    lora=True,
)
print(f"Job ID: {response.id}")

Continue from Checkpoint

from together import Together

client = Together()

response = client.fine_tuning.create(
    training_file="file-abc123",
    from_checkpoint="ft-12345678-abcd-1234-efgh-123456789012:100",
    n_epochs=1,
)
print(f"Job ID: {response.id}")

Fine-Tune from Hugging Face Model with W&B Logging

from together import Together

client = Together()

response = client.fine_tuning.create(
    training_file="file-abc123",
    model="meta-llama/Meta-Llama-3.1-8B-Instruct",
    from_hf_model="my-org/my-custom-llama",
    hf_api_token="hf_...",
    wandb_api_key="your-wandb-key",
    wandb_project_name="llama-finetune",
    wandb_name="run-001",
    n_epochs=3,
    lr_scheduler_type="cosine",
    warmup_ratio=0.1,
    suffix="my-model-v1",
    verbose=True,
)
print(f"Job ID: {response.id}")
print(f"Output model: {response.output_name}")

With Validation File and Multiple Checkpoints

from together import Together

client = Together()

response = client.fine_tuning.create(
    training_file="file-abc123",
    validation_file="file-val789",
    model="meta-llama/Meta-Llama-3.1-8B-Instruct",
    n_epochs=5,
    n_evals=10,
    n_checkpoints=3,
    lora=True,
    lora_r=32,
    lora_alpha=64,
)
print(f"Job ID: {response.id}")

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment