0
# Fine-tuning
1

2
Custom model training with supervised fine-tuning and direct preference optimization. Create specialized models tailored to specific domains, tasks, or behavioral requirements with comprehensive job management and model downloading capabilities.
3

4
## Capabilities
5

6
### Create Fine-tuning Job
7

8
Start a fine-tuning job with custom training configuration.
9

10
```python { .api }
11
def create(
12
    training_file: str,
13
    model: str,
14
    n_epochs: Optional[int] = None,
15
    n_checkpoints: Optional[int] = None,
16
    batch_size: Optional[Union[str, int]] = None,
17
    learning_rate: Optional[float] = None,
18
    suffix: Optional[str] = None,
19
    wandb_api_key: Optional[str] = None,
20
    training_type: Optional[str] = None,
21
    **kwargs
22
) -> FinetuneResponse:
23
    """
24
    Create a fine-tuning job.
25

26
    Args:
27
        training_file: ID of uploaded training file
28
        model: Base model to fine-tune
29
        n_epochs: Number of training epochs
30
        n_checkpoints: Number of checkpoints to save
31
        batch_size: Batch size ('max' or integer)
32
        learning_rate: Learning rate for training
33
        suffix: Custom suffix for model name
34
        wandb_api_key: Weights & Biases API key for tracking
35
        training_type: Type of training ('FullTrainingType' or 'LoRATrainingType')
36

37
    Returns:
38
        FinetuneResponse with job information
39
    """
40
```
41

42
### List Fine-tuning Jobs
43

44
List all fine-tuning jobs with status and metadata.
45

46
```python { .api }
47
def list() -> FinetuneList:
48
    """
49
    List all fine-tuning jobs.
50

51
    Returns:
52
        FinetuneList containing job information
53
    """
54
```
55

56
### Retrieve Fine-tuning Job
57

58
Get detailed information about a specific fine-tuning job.
59

60
```python { .api }
61
def retrieve(id: str) -> FinetuneResponse:
62
    """
63
    Retrieve fine-tuning job details.
64

65
    Args:
66
        id: Fine-tuning job ID
67

68
    Returns:
69
        FinetuneResponse with job details
70
    """
71
```
72

73
### Cancel Fine-tuning Job
74

75
Cancel a running fine-tuning job.
76

77
```python { .api }
78
def cancel(id: str) -> FinetuneResponse:
79
    """
80
    Cancel a fine-tuning job.
81

82
    Args:
83
        id: Fine-tuning job ID
84

85
    Returns:
86
        FinetuneResponse with updated job status
87
    """
88
```
89

90
### List Job Events
91

92
Get training progress events and logs for a fine-tuning job.
93

94
```python { .api }
95
def list_events(id: str) -> FinetuneListEvents:
96
    """
97
    List events for a fine-tuning job.
98

99
    Args:
100
        id: Fine-tuning job ID
101

102
    Returns:
103
        FinetuneListEvents with training logs
104
    """
105
```
106

107
### Download Fine-tuned Model
108

109
Download trained model weights and artifacts.
110

111
```python { .api }
112
def download(
113
    id: str,
114
    checkpoint: Optional[str] = None,
115
    output: Optional[str] = None
116
) -> FinetuneDownloadResult:
117
    """
118
    Download fine-tuned model or checkpoint.
119

120
    Args:
121
        id: Fine-tuning job ID
122
        checkpoint: Specific checkpoint to download
123
        output: Output directory path
124

125
    Returns:
126
        FinetuneDownloadResult with download information
127
    """
128
```
129

130
### Async Fine-tuning Operations
131

132
All fine-tuning operations support asynchronous execution.
133

134
```python { .api }
135
async def create(training_file: str, model: str, **kwargs) -> FinetuneResponse: ...
136
async def list() -> FinetuneList: ...
137
async def retrieve(id: str) -> FinetuneResponse: ...
138
async def cancel(id: str) -> FinetuneResponse: ...
139
async def list_events(id: str) -> FinetuneListEvents: ...
140
async def download(id: str, **kwargs) -> FinetuneDownloadResult: ...
141
```
142

143
## Usage Examples
144

145
### Basic Fine-tuning
146

147
```python
148
from together import Together
149

150
client = Together()
151

152
# First, upload training data
153
training_file = client.files.upload(
154
    file="training_data.jsonl",
155
    purpose="fine-tune"
156
)
157

158
# Create fine-tuning job
159
finetune_job = client.fine_tuning.create(
160
    training_file=training_file.id,
161
    model="meta-llama/Llama-3.2-3B-Instruct",
162
    n_epochs=3,
163
    n_checkpoints=1,
164
    batch_size="max",
165
    learning_rate=1e-5,
166
    suffix="my-custom-model"
167
)
168

169
print(f"Fine-tuning job created: {finetune_job.id}")
170
print(f"Status: {finetune_job.status}")
171
print(f"Model name: {finetune_job.fine_tuned_model}")
172
```
173

174
### Advanced Fine-tuning Configuration
175

176
```python
177
# Create fine-tuning job with advanced settings
178
finetune_job = client.fine_tuning.create(
179
    training_file=training_file.id,
180
    model="meta-llama/Llama-3.2-3B-Instruct",
181
    n_epochs=5,
182
    n_checkpoints=3,
183
    batch_size=16,
184
    learning_rate=5e-6,
185
    suffix="domain-specialist",
186
    wandb_api_key="your-wandb-api-key",  # For experiment tracking
187
    training_type="FullTrainingType"  # Full model training vs LoRA
188
)
189

190
print(f"Advanced fine-tuning job: {finetune_job.id}")
191
print(f"Training type: {finetune_job.training_type}")
192
print(f"Hyperparameters: {finetune_job.hyperparameters}")
193
```
194

195
### Monitor Fine-tuning Progress
196

197
```python
198
import time
199

200
def monitor_finetune_job(client: Together, job_id: str):
201
    """Monitor fine-tuning job progress."""
202
    
203
    while True:
204
        job = client.fine_tuning.retrieve(job_id)
205
        print(f"Status: {job.status}")
206
        
207
        if job.status == "succeeded":
208
            print(f"Fine-tuning completed!")
209
            print(f"Fine-tuned model: {job.fine_tuned_model}")
210
            break
211
        elif job.status == "failed":
212
            print(f"Fine-tuning failed: {job.error}")
213
            break
214
        elif job.status == "cancelled":
215
            print("Fine-tuning was cancelled")
216
            break
217
        
218
        # Get latest events
219
        events = client.fine_tuning.list_events(job_id)
220
        if events.data:
221
            latest_event = events.data[-1]
222
            print(f"Latest: {latest_event.message}")
223
        
224
        time.sleep(30)  # Check every 30 seconds
225

226
# Monitor the job
227
monitor_finetune_job(client, finetune_job.id)
228
```
229

230
### List and Manage Jobs
231

232
```python
233
# List all fine-tuning jobs
234
jobs = client.fine_tuning.list()
235

236
print(f"Total fine-tuning jobs: {len(jobs.data)}")
237

238
for job in jobs.data:
239
    print(f"ID: {job.id}")
240
    print(f"Model: {job.model}")
241
    print(f"Status: {job.status}")
242
    print(f"Created: {job.created_at}")
243
    if job.fine_tuned_model:
244
        print(f"Fine-tuned model: {job.fine_tuned_model}")
245
    print("---")
246

247
# Find specific jobs
248
running_jobs = [job for job in jobs.data if job.status == "running"]
249
completed_jobs = [job for job in jobs.data if job.status == "succeeded"]
250

251
print(f"Running jobs: {len(running_jobs)}")
252
print(f"Completed jobs: {len(completed_jobs)}")
253
```
254

255
### Download Trained Model
256

257
```python
258
# Download the fine-tuned model
259
job_id = "ft-c66a5c18-1d6d-43c9-94bd-32d756425b4b"
260

261
download_result = client.fine_tuning.download(
262
    id=job_id,
263
    output="./my-finetuned-model"
264
)
265

266
print(f"Model downloaded to: {download_result.output_path}")
267
print(f"Files downloaded: {download_result.files}")
268

269
# Download specific checkpoint
270
checkpoint_result = client.fine_tuning.download(
271
    id=job_id,
272
    checkpoint="checkpoint-1000",
273
    output="./checkpoint-1000"
274
)
275

276
print(f"Checkpoint downloaded: {checkpoint_result.checkpoint}")
277
```
278

279
### Training Data Preparation
280

281
```python
282
import json
283

284
def prepare_conversation_data(conversations: list, output_file: str):
285
    """Prepare conversation data for fine-tuning."""
286
    
287
    training_examples = []
288
    
289
    for conversation in conversations:
290
        # Format for instruction fine-tuning
291
        example = {
292
            "messages": conversation["messages"],
293
            "model": "meta-llama/Llama-3.2-3B-Instruct"
294
        }
295
        training_examples.append(example)
296
    
297
    # Write JSONL format
298
    with open(output_file, 'w') as f:
299
        for example in training_examples:
300
            f.write(json.dumps(example) + '\n')
301
    
302
    print(f"Prepared {len(training_examples)} training examples")
303
    return output_file
304

305
def prepare_completion_data(prompts_and_completions: list, output_file: str):
306
    """Prepare prompt-completion pairs for fine-tuning."""
307
    
308
    training_examples = []
309
    
310
    for prompt, completion in prompts_and_completions:
311
        example = {
312
            "prompt": prompt,
313
            "completion": completion
314
        }
315
        training_examples.append(example)
316
    
317
    with open(output_file, 'w') as f:
318
        for example in training_examples:
319
            f.write(json.dumps(example) + '\n')
320
    
321
    print(f"Prepared {len(training_examples)} prompt-completion pairs")
322
    return output_file
323

324
# Example usage
325
conversation_data = [
326
    {
327
        "messages": [
328
            {"role": "user", "content": "Explain quantum computing"},
329
            {"role": "assistant", "content": "Quantum computing leverages quantum mechanics..."}
330
        ]
331
    },
332
    {
333
        "messages": [
334
            {"role": "user", "content": "What is machine learning?"},
335
            {"role": "assistant", "content": "Machine learning is a subset of AI..."}
336
        ]
337
    }
338
]
339

340
training_file = prepare_conversation_data(conversation_data, "custom_training.jsonl")
341
```
342

343
### Complete Fine-tuning Workflow
344

345
```python
346
def complete_finetuning_workflow(
347
    client: Together,
348
    training_data_file: str,
349
    base_model: str,
350
    job_name: str
351
):
352
    """Complete workflow from data upload to model deployment."""
353
    
354
    # Step 1: Upload training data
355
    print("1. Uploading training data...")
356
    training_file = client.files.upload(
357
        file=training_data_file,
358
        purpose="fine-tune"
359
    )
360
    print(f"   Uploaded: {training_file.id}")
361
    
362
    # Step 2: Create fine-tuning job
363
    print("2. Creating fine-tuning job...")
364
    job = client.fine_tuning.create(
365
        training_file=training_file.id,
366
        model=base_model,
367
        n_epochs=3,
368
        batch_size="max",
369
        learning_rate=1e-5,
370
        suffix=job_name
371
    )
372
    print(f"   Job created: {job.id}")
373
    
374
    # Step 3: Monitor progress
375
    print("3. Monitoring progress...")
376
    while True:
377
        job_status = client.fine_tuning.retrieve(job.id)
378
        print(f"   Status: {job_status.status}")
379
        
380
        if job_status.status == "succeeded":
381
            print(f"   ✅ Fine-tuning completed!")
382
            print(f"   Model: {job_status.fine_tuned_model}")
383
            break
384
        elif job_status.status in ["failed", "cancelled"]:
385
            print(f"   ❌ Fine-tuning {job_status.status}")
386
            return None
387
        
388
        time.sleep(60)  # Check every minute
389
    
390
    # Step 4: Download model (optional)
391
    print("4. Downloading model...")
392
    download_result = client.fine_tuning.download(
393
        id=job.id,
394
        output=f"./models/{job_name}"
395
    )
396
    print(f"   Downloaded to: {download_result.output_path}")
397
    
398
    return job_status.fine_tuned_model
399

400
# Run complete workflow
401
model_id = complete_finetuning_workflow(
402
    client=client,
403
    training_data_file="domain_specific_data.jsonl",
404
    base_model="meta-llama/Llama-3.2-3B-Instruct",
405
    job_name="domain-expert"
406
)
407

408
if model_id:
409
    print(f"Ready to use model: {model_id}")
410
```
411

412
## Types
413

414
### Request Types
415

416
```python { .api }
417
class FinetuneRequest:
418
    training_file: str
419
    model: str
420
    n_epochs: Optional[int] = None
421
    n_checkpoints: Optional[int] = None
422
    batch_size: Optional[Union[str, int]] = None
423
    learning_rate: Optional[float] = None
424
    suffix: Optional[str] = None
425
    wandb_api_key: Optional[str] = None
426
    training_type: Optional[str] = None
427
```
428

429
### Response Types
430

431
```python { .api }
432
class FinetuneResponse:
433
    id: str
434
    object: str
435
    model: str
436
    created_at: int
437
    finished_at: Optional[int]
438
    fine_tuned_model: Optional[str]
439
    status: str
440
    trained_tokens: Optional[int]
441
    training_file: str
442
    validation_file: Optional[str]
443
    hyperparameters: dict
444
    error: Optional[str]
445
    training_type: Optional[str]
446

447
class FinetuneList:
448
    object: str
449
    data: List[FinetuneResponse]
450

451
class FinetuneListEvents:
452
    object: str
453
    data: List[FinetuneEvent]
454

455
class FinetuneEvent:
456
    object: str
457
    created_at: int
458
    level: str
459
    message: str
460

461
class FinetuneDownloadResult:
462
    id: str
463
    output_path: str
464
    checkpoint: Optional[str]
465
    files: List[str]
466
```
467

468
### Training Configuration Types
469

470
```python { .api }
471
class TrainingType:
472
    """Base training type configuration"""
473
    pass
474

475
class FullTrainingType(TrainingType):
476
    """Full model fine-tuning configuration"""
477
    type: Literal["FullTrainingType"]
478

479
class LoRATrainingType(TrainingType):
480
    """LoRA (Low-Rank Adaptation) training configuration"""
481
    type: Literal["LoRATrainingType"]
482
    lora_r: Optional[int] = None
483
    lora_alpha: Optional[int] = None
484
    lora_dropout: Optional[float] = None
485

486
class TrainingMethodSFT:
487
    """Supervised Fine-Tuning method"""
488
    type: Literal["SFT"]
489

490
class TrainingMethodDPO:
491
    """Direct Preference Optimization method"""
492
    type: Literal["DPO"]
493
    beta: Optional[float] = None
494
    reference_model: Optional[str] = None
495
```