Fine-Tuning via API

Take a foundation model and make it yours — using nothing more than a JSONL file and an API call. No GPUs to manage, no infrastructure to build.

Learning Objectives

• Prepare and validate JSONL training data in the chat-completions message format
• Create and monitor fine-tuning jobs through the OpenAI API
• Understand key hyperparameters: epochs, learning rate multiplier, batch size
• Evaluate a fine-tuned model against its base model
• Manage costs, versioning, and deployment of fine-tuned models

Why API Fine-Tuning?

API-based fine-tuning lets you customise a model without managing GPUs, training frameworks, or model weights. The provider handles infrastructure; you provide the data.

When to Fine-Tune via API

JSONL Data Format

Training data must be a JSONL file (one JSON object per line). Each line contains a messages array using the chat-completions format: system, user, and assistant roles.

{"messages": [
  {"role": "system", "content": "You are a customer-support agent for Acme Corp. Always be polite and concise."},
  {"role": "user", "content": "How do I reset my password?"},
  {"role": "assistant", "content": "Go to acme.com/reset, enter your email, and follow the link sent to your inbox. The link expires in 15 minutes."}
]}
{"messages": [
  {"role": "system", "content": "You are a customer-support agent for Acme Corp. Always be polite and concise."},
  {"role": "user", "content": "What's your refund policy?"},
  {"role": "assistant", "content": "We offer full refunds within 30 days of purchase. Email billing@acme.com with your order number."}
]}

Key Rules

• Each example must include at least one user and one assistant message
• The system message is optional but should be consistent across examples
• Multi-turn conversations are supported — alternate user/assistant messages
• The model learns to produce the assistant messages; user/system messages are context

Data Validation & Quality

Garbage in, garbage out. Validating your training data is the most important step in the entire fine-tuning pipeline.

Automated Checks

• Format: Valid JSON on every line, correct messages structure, valid roles
• Token limits: Each example must fit within the model's context window (typically 4096 or 16384 tokens for fine-tuning)
• Minimum count: At least 10 examples required; 50–100+ recommended
• Duplicates: Remove exact duplicates; near-duplicates hurt generalisation

Manual Quality Checks

• Are the assistant responses what you actually want the model to produce?
• Is the style and formatting consistent across examples?
• Do examples cover the full range of expected inputs?
• Are there contradictions between examples?

Creating a Fine-Tuning Job

Two API calls: upload the file, then create the job.

from openai import OpenAI
client = OpenAI()

# Step 1: Upload the training file
file = client.files.create(
    file=open("training_data.jsonl", "rb"),
    purpose="fine-tune"
)

# Step 2: Create the fine-tuning job
job = client.fine_tuning.jobs.create(
    training_file=file.id,
    model="gpt-4o-mini-2024-07-18",
    hyperparameters={
        "n_epochs": 3,
        "learning_rate_multiplier": 1.8,
        "batch_size": 1
    },
    suffix="acme-support-v1"   # custom model name suffix
)

Provider Comparison

Hyperparameters

Three levers control how the model trains. Getting these right can mean the difference between a great model and an overfit one.

Monitoring, Evaluation & Cost

Monitoring Training

# Poll job status
job = client.fine_tuning.jobs.retrieve(job.id)
print(job.status)  # "validating_files" → "running" → "succeeded"

# Stream training events
for event in client.fine_tuning.jobs.list_events(job.id):
    print(f"[{event.created_at}] {event.message}")

Evaluating the Fine-Tuned Model

• Hold out 10–20% of your data as a validation set (pass as validation_file)
• Compare fine-tuned vs. base model on identical test prompts
• Use both automated metrics (accuracy, format compliance) and human review
• Watch for regression: fine-tuned models can lose general capabilities

Cost Management

Training cost = tokens_per_example x n_examples x n_epochs x rate. A 200-example dataset at 500 tokens each, 3 epochs = ~$0.90.

Lab & Homework