Avviare il Fine-Tuning tramite API
In questa pagina
Aggiornamento del 2 novembre 2026 — Disponibilità del fine-tuning. Il servizio di fine-tuning self-service di OpenAI sta venendo gradualmente dismesso: dal 7 maggio 2026, le organizzazioni che non hanno mai eseguito un job di fine-tuning non possono più crearne uno; dal 2 luglio, devi aver utilizzato un modello sottoposto a fine-tuning negli ultimi 60 giorni; e a partire dal 6 gennaio 2027, nessun cliente potrà avviare nuovi job. I modelli già addestrati rimangono utilizzabili fino al pensionamento del loro modello base. Questo corso rimane utile per comprendere e sfruttare un modello esistente; per i nuovi progetti, dai priorità al prompt engineering, al RAG e alle valutazioni.
Panoramica del processo
I tuoi dati sono pronti, convalidati e suddivisi in set di addestramento e di validazione. La fase effettiva di addestramento si riduce a tre passaggi: caricare il file dei dati, creare un job di fine-tuning e attendere il completamento dell’addestramento. Tutto avviene tramite l’SDK Python ufficiale e vedrai che il codice richiede circa una trentina di righe: la maggior parte del lavoro è stata svolta a monte.
Installazione e configurazione dell’SDK
Il client viene istanziato senza argomenti: legge automaticamente la variabile d’ambiente OPENAI_API_KEY.
# Installazione
# pip install openai
from openai import OpenAI
# Il client utilizza automaticamente la variabile d'ambiente OPENAI_API_KEY
client = OpenAI()
Assicurati che questa variabile sia impostata prima di eseguire lo script, altrimenti l’istanziazione fallirà alla prima richiesta. In produzione, non inserire mai la tua chiave direttamente nel codice: una chiave scritta in testo semplice finisce nella cronologia di Git e rimuoverla successivamente costa molto di più rispetto al leggerla dall’ambiente fin dal primo giorno.
Caricamento dei file
Il caricamento utilizza purpose="fine-tune", il che indica a OpenAI che il file è destinato all’addestramento e attiva i controlli di formato corrispondenti. Carica subito anche il file di validazione: tecnicamente è opzionale, ma senza di esso l’addestramento procede alla cieca, poiché nessuna perdita di validazione segnalerà l’overfitting durante l’esecuzione del job.
# Caricamento del file di addestramento
training_file = client.files.create(
file=open("training_data.jsonl", "rb"),
purpose="fine-tune"
)
print(f"ID file: {training_file.id}")
print(f"Stato: {training_file.status}")
# Opzionale: caricamento del file di validazione
validation_file = client.files.create(
file=open("validation_data.jsonl", "rb"),
purpose="fine-tune"
)
print(f"ID validazione: {validation_file.id}")
Il file attraversa una fase di elaborazione lato OpenAI. Attendi che lo stato sia processed prima di avviare il job: un job creato su un file ancora in elaborazione fallirà e perderai alcuni minuti a cercare una causa inesistente nel tuo JSONL.
Creazione del job di fine-tuning
job = client.fine_tuning.jobs.create(
training_file=training_file.id,
validation_file=validation_file.id, # opzionale ma consigliato
model="gpt-5.6-luna", # oppure "gpt-5.6-luna"
suffix="my-assistant-v1" # suffisso per identificare il tuo modello
)
print(f"ID job: {job.id}")
print(f"Stato: {job.status}")
print(f"Modello base: {job.model}")
Il parametro suffix viene aggiunto al nome del tuo modello sottoposto a fine-tuning: con "my-assistant-v1", il modello risultante si chiamerà ft:gpt-5.6-luna:your-org::my-assistant-v1:xxxxxxxx. Prendi l’abitudine di inserire qui il caso d’uso e un numero di versione. Il giorno in cui tre modelli coesisteranno nel tuo account, sarà l’unico modo per sapere quale fa cosa senza aprire la console.
Monitoraggio dell’avanzamento
Un job attraversa diversi stati in sequenza e retrieve ti fornisce quello corrente in qualsiasi momento.
# Ottenere lo stato del job
job = client.fine_tuning.jobs.retrieve(job.id)
print(f"Stato: {job.status}")
# Stati possibili: validating_files, queued, running, succeeded, failed, cancelled
Lo stato da solo rimane laconico. Gli eventi, invece, raccontano la storia: convalida dei file, avvio, avanzamento passo dopo passo, fine.
# Visualizzare gli eventi del job
events = client.fine_tuning.jobs.list_events(
fine_tuning_job_id=job.id,
limit=20
)
for event in events.data:
print(f"[{event.created_at}] {event.message}")
Invece di chiamare manualmente retrieve ogni cinque minuti, racchiudi l’attesa in un ciclo che restituisce il controllo non appena il job raggiunge uno stato terminale. Nota che i tre casi di uscita sono gestiti separatamente: un job annullato non è un job fallito e vorrai distinguerli nei tuoi log.
import time
def track_job(client: OpenAI, job_id: str, interval: int = 30):
"""Monitora un job di fine-tuning fino al completamento."""
while True:
job = client.fine_tuning.jobs.retrieve(job_id)
print(f"Stato: {job.status}")
if job.status == "succeeded":
print(f"Modello fine-tuned: {job.fine_tuned_model}")
return job
if job.status == "failed":
print(f"Fallimento: {job.error}")
return job
if job.status == "cancelled":
print("Job annullato.")
return job
time.sleep(interval)
# Utilizzo
final_job = track_job(client, job.id)
Utilizzo del modello sottoposto a fine-tuning
Una volta completato correttamente il job, il tuo modello viene chiamato esattamente come un modello standard. Cambia solo il valore passato a model, il che significa che passare al tuo modello personalizzato si riduce, in un’applicazione esistente, a modificare una variabile di configurazione.
response = client.responses.create(
model=final_job.fine_tuned_model, # es. "ft:gpt-5.6-luna:org::suffix:xxxxxxxx"
input="Ciao, ho un problema con il mio ordine."
)
print(response.output_text)
Gestione dei tuoi job
Due chiamate sono sufficienti per amministrare tutto: elencare ciò che esiste e interrompere ciò che è in esecuzione. L’annullamento è utile non appena il monitoraggio mostra che l’addestramento sta andando fuori controllo: non ha senso pagare per token di un job che sai già produrrà un modello scadente.
# Elencare tutti i tuoi job di fine-tuning
jobs = client.fine_tuning.jobs.list(limit=10)
for j in jobs.data:
print(f"{j.id} | {j.status} | {j.model} | {j.fine_tuned_model}")
# Annullare un job in esecuzione
client.fine_tuning.jobs.cancel(job.id)
Costi e durata
L’addestramento viene fatturato in base al numero di token elaborati. La durata, invece, dipende dalle dimensioni dei tuoi dati e dal numero di epoche.
| Dimensione del dataset | Durata dell’addestramento |
|---|---|
| 50 esempi | Alcuni minuti |
| 500 esempi | Da 15 a 30 minuti |
| 5.000 esempi | Da 1 a 2 ore |
Questi ordini di grandezza servono principalmente a dimensionare il tuo ciclo di lavoro: con pochi minuti per esecuzione, iteri nella stessa sessione; con due ore, pianifichi. I prezzi esatti variano in base al modello scelto; consulta la pagina dei prezzi di OpenAI per le tariffe attuali.
Punti chiave
- Il flusso di lavoro è: carica file, crea job, attendi, usa il modello
- Aggiungi un
suffixdescrittivo per identificare facilmente i tuoi modelli - Usa sempre un file di validazione per valutare la qualità
- Il modello sottoposto a fine-tuning viene utilizzato esattamente come il modello base tramite API
- Conserva gli ID dei job e dei modelli: ti serviranno per il versioning