Prompt optimization con DSPy: dai prompt ai programmi

Informazioni verificate il 15 ottobre 2026 sulla documentazione corrente di DSPy, su PyPI e sul listino dei modelli Google. Su PyPI è disponibile DSPy 3.4.1, pubblicato il 12 ottobre 2026, che richiede Python dalla versione 3.10 inclusa alla 3.16 esclusa. Il pacchetto da installare è dspy. Metadati del pacchetto su PyPI.

Cos'è DSPy e che cosa significa compilare un programma?

DSPy è un framework Python open source che permette di definire le attività di un modello linguistico come programmi, per poi migliorarne i prompt o, con ottimizzatori specifici, i pesi del modello. La sua promessa concreta è ottenere miglioramenti ripetibili rispetto ai criteri di successo stabiliti da chi lo usa. Non promette che il primo prompt generato sarà migliore di uno scritto con cura. Panoramica di DSPy.

Si può pensare alle prove di uno spettacolo. La signature è la consegna, il modulo stabilisce come eseguirla e la metrica è il criterio di giudizio. L'ottimizzatore modifica qualcosa, osserva il risultato e conserva le modifiche utili. Senza un criterio di giudizio, si possono provare varianti all'infinito senza sapere se qualcosa è davvero migliorato.

Le signature definiscono il compito

Una signature dichiara gli input, gli output e le istruzioni dell'attività. "ticket -> category" indica che in ingresso arriva un ticket e in uscita viene restituita una categoria. Una signature definita come classe può aggiungere campi tipizzati e una docstring che spiega il compito. La scelta dei campi resta determinante: un ottimizzatore non può rimediare a una definizione aziendale ambigua di «urgente». Documentazione delle signature.

I moduli DSPy stabiliscono come eseguirlo

Un modulo implementa una strategia per svolgere il compito. dspy.Predict è il componente di base per le predizioni. dspy.ChainOfThought aggiunge un campo di ragionamento prima della risposta. dspy.ReAct supporta un ciclo che alterna ragionamento e uso di strumenti. Quando un singolo passaggio del modello non basta, è possibile comporre più moduli in Python. Documentazione dei moduli.

Per smistare i ticket di assistenza, conviene partire da Predict. Aggiungere un ciclo di uso degli strumenti per classificare un messaggio breve introduce complessità prima ancora di averne dimostrato la necessità.

La compilazione è una procedura di ottimizzazione

Un ottimizzatore modifica parti selezionate del programma usando esempi e una metrica. Nell'ottimizzazione dei prompt, .compile() restituisce un programma con istruzioni riviste o dimostrazioni, cioè esempi inclusi nel prompt. Non trasforma l'applicazione in un eseguibile nativo e non elimina le successive chiamate al modello. Per addestrare i pesi occorre scegliere un ottimizzatore dedicato. Guida alla scelta dell'ottimizzatore.

Tutorial DSPy: l'esempio minimo della documentazione corrente

Il programma introduttivo della documentazione corrente genera un haiku. Questo piccolo esempio permette di capire l'interfaccia senza coinvolgere database, strumenti o una ricerca di ottimizzazione.

Installare la versione verificata nel proprio ambiente Python:

python -m pip install 'dspy[litellm]==3.4.1'

Impostare la variabile d'ambiente GEMINI_API_KEY con una chiave API Google Gemini valida. Salvare questo codice come first_dspy.py, quindi eseguire python first_dspy.py:

import os
import dspy

lm = dspy.LM(
    "gemini/gemini-2.5-flash-lite",
    api_key=os.environ["GEMINI_API_KEY"],
    engine="litellm",
)
dspy.configure(lm=lm)

haiku_signature = "subject -> haiku"
haiku_generator = dspy.Predict(haiku_signature)
result = haiku_generator(subject="computer science")
print(result.haiku)

Le ultime quattro righe sono il primo programma della documentazione corrente. La configurazione segue lo schema di configurazione dei modelli di DSPy, sostituendo il modello con Google Gemini 2.5 Flash-Lite per usare un unico modello economico nell'esperimento che segue. La stringa del provider segue l'integrazione Gemini di LiteLLM; l'indicazione esplicita del backend è supportata dall'API LM di DSPy.

DSPy costruisce un prompt a partire dalla signature, lo invia al modello configurato e interpreta il campo haiku restituito. È un esempio di inferenza, non un'esecuzione di ottimizzazione. Non si promette una poesia specifica né un miglioramento della qualità.

Prompt optimization con DSPy: serve una metrica

Senza una metrica, l'ottimizzazione non ha un significato misurabile. Una metrica è una funzione che trasforma una predizione in un punteggio. Per lo smistamento dei ticket, può confrontare la categoria prevista con un'etichetta approvata da una persona. Per una risposta generata, la correttezza può richiedere una griglia di valutazione o una verifica eseguibile. L'interfaccia delle metriche di DSPy accetta la funzione di valutazione definita dall'utente; il framework non decide quali risultati debba premiare l'azienda. Metriche e valutazione.

Ecco perché conta avere un piccolo insieme di esempi etichettati per la valutazione. Se cambiare «sii conciso» in «rispondi brevemente» è diventato frustrante, conviene raccogliere gli errori reali: una richiesta di rimborso inviata all'assistenza tecnica, un problema di accesso scambiato per una questione di fatturazione o un messaggio che contiene due richieste. Il risultato atteso va etichettato prima di guardare l'output di un nuovo prompt.

Per un primo progetto pilota, usare 60 esempi distinti, suddivisi deliberatamente in 20 esempi di addestramento, 20 di validazione e 20 di test finale. Sono dimensioni proposte per l'esperimento, non requisiti di DSPy né una prova di affidabilità in produzione.

• Gli esempi di addestramento forniscono il materiale da cui l'ottimizzatore può apprendere.
• Gli esempi di validazione aiutano a confrontare le versioni e a prendere decisioni durante lo sviluppo.
• Gli esempi di test finale restano intatti finché non vengono fissati il programma candidato e le regole di valutazione.

I ticket correlati dello stesso cliente o dello stesso incidente devono restare nello stesso sottoinsieme. Altrimenti, esempi quasi duplicati possono far sembrare il prompt ottimizzato più capace di generalizzare di quanto sia davvero. Includere gli errori rari ma rilevanti, evitando di riempire ogni sottoinsieme di soli casi facili.

L'affermazione «senza una metrica» richiede una precisazione. È possibile eseguire un programma DSPy non ottimizzato senza definirne una, e LabeledFewShot può aggiungere esempi senza valutarli. Si tratta di configurazione, non della prova che una modifica abbia migliorato i risultati del compito. Inoltre, non tutte le attività richiedono una risposta di riferimento scritta a mano: il segnale può arrivare da una verifica eseguibile della correttezza. Per la classificazione in ambito aziendale, le etichette approvate sono di solito il punto di partenza più chiaro. Baseline few-shot.

Gli ottimizzatori DSPy nella documentazione corrente

Conviene iniziare dall'ottimizzatore più semplice che affronti un errore identificabile. Ampliare la ricerca è utile solo se la metrica sa distinguere i candidati migliori da quelli peggiori.

L'attuale indice delle API degli ottimizzatori elenca esattamente queste voci: BetterTogether, BootstrapFewShot, BootstrapFewShotWithRandomSearch, BootstrapFinetune, BootstrapRS, COPRO, Ensemble, GEPA, InferRules, KNN, KNNFewShot, LabeledFewShot, MIPROv2 e SIMBA.

Non sono tutti algoritmi di ricerca indipendenti. BootstrapRS è un alias di BootstrapFewShotWithRandomSearch; KNN è il componente di recupero degli esempi usato da KNNFewShot. La guida corrente alla scelta cita anche AvatarOptimizer per i programmi di tipo agentico, sebbene non compaia in quell'indice delle API. Dettagli della famiglia di ottimizzatori, guida alla scelta.

MIPROv2 propone istruzioni e usa l'ottimizzazione bayesiana, un metodo di ricerca guidato dai punteggi precedenti, per esplorare combinazioni di istruzioni e dimostrazioni. SIMBA lavora su minibatch e propone regole o dimostrazioni. Sono approcci diversi, non versioni di BootstrapFewShot con un altro nome. API di MIPROv2, API di SIMBA.

GEPA usa un modello di riflessione per leggere il feedback delle esecuzioni e proporre modifiche alle istruzioni. Un punteggio accompagnato da una spiegazione precisa, come «le richieste di rimborso vanno alla fatturazione anche quando citano una funzione non funzionante», fornisce un segnale più utile di un semplice punteggio di insuccesso. La documentazione dettagliata ammette metriche esclusivamente numeriche, ma spiega che in questo modo si perde il feedback più ricco. Come funziona GEPA.

Definire i limiti della prima ottimizzazione

È più facile tenere il conto delle esecuzioni in un piccolo esperimento con BootstrapFewShot che in una ricerca di istruzioni senza limiti prestabiliti. Il progetto seguente usa un solo modulo Predict, una metrica deterministica sulle etichette e lo stesso modello per l'insegnamento e la predizione.

BootstrapFewShot in DSPy: un esperimento volutamente ridotto

Preparare train.jsonl, validation.jsonl e test.jsonl, ciascuno con 20 ticket distinti ed etichettati da persone. Ogni riga è un oggetto JSON con text e label; le etichette ammesse sono billing, technical, account e other. Per esempio, una richiesta di modifica dell'indirizzo di fatturazione potrebbe avere l'etichetta billing. Servono esempi propri, non l'output del generatore di haiku.

Salvare questo script separato come optimize_tickets.py ed eseguirlo dopo aver impostato la stessa chiave API:

import json
import os
from typing import Literal
import dspy

lm = dspy.LM(
    "gemini/gemini-2.5-flash-lite",
    api_key=os.environ["GEMINI_API_KEY"],
    engine="litellm",
    cache=False,
)
dspy.configure(lm=lm)

class RouteTicket(dspy.Signature):
    """Choose the support queue responsible for the ticket's main request."""
    text: str = dspy.InputField()
    label: Literal["billing", "technical", "account", "other"] = (
        dspy.OutputField()
    )

def load_examples(path):
    with open(path, encoding="utf-8") as source:
        rows = [json.loads(line) for line in source if line.strip()]
    assert len(rows) == 20
    return [dspy.Example(**row).with_inputs("text") for row in rows]

train = load_examples("train.jsonl")
validation = load_examples("validation.jsonl")
test = load_examples("test.jsonl")
assert len({e.text for e in train + validation + test}) == 60

def correct_label(example, prediction, trace=None):
    return prediction.label == example.label

program = dspy.Predict(RouteTicket)
evaluate = dspy.Evaluate(
    devset=validation, metric=correct_label, num_threads=1
)
print("Baseline validation:", evaluate(program).score)

optimizer = dspy.BootstrapFewShot(
    metric=correct_label,
    max_bootstrapped_demos=4,
    max_labeled_demos=0,
    max_rounds=1,
)
optimized = optimizer.compile(program, trainset=train)
print("Optimized validation:", evaluate(optimized).score)

# Freeze this candidate before opening the final test results.
final_test = dspy.Evaluate(
    devset=test, metric=correct_label, num_threads=1
)
print("Baseline final test:", final_test(program).score)
print("Optimized final test:", final_test(optimized).score)
optimized.save("candidate_ticket_router.json")

È un adattamento che usa il costruttore documentato di BootstrapFewShot e l'interfaccia di valutazione, non un benchmark di cui si rivendicano i risultati. Richiede fino a quattro dimostrazioni riuscite, consente un tentativo di bootstrap per ciascun esempio di addestramento e non aggiunge dimostrazioni etichettate grezze. Il file salvato è un candidato da esaminare, non un rilascio automatico in produzione.

Il conto delle esecuzioni previste è il seguente:

• Baseline sul set di validazione: 20 esecuzioni del programma.
• Bootstrap sul set di addestramento: fino a 20 esecuzioni del modello insegnante, anche meno se si ottengono prima abbastanza dimostrazioni valide.
• Programma ottimizzato sul set di validazione: 20 esecuzioni del programma.
• Entrambe le versioni sul set di test finale: 40 esecuzioni del programma.

In totale, fino a 100 esecuzioni a un solo passaggio, valutazione inclusa; la sola compilazione ne richiede al massimo 20. Con una richiesta al modello riuscita per ogni esecuzione, senza tentativi ripetuti né procedure di ripiego per il parsing, si arriva al massimo a 100 chiamate al modello che svolge il compito. La precedente verifica di funzionamento con l'haiku è separata. Un LLM usato come giudice, un ciclo agentico, tentativi ripetuti o un ulteriore tentativo di ottimizzazione cambiano il totale.

Al prezzo di listino Google per il testo nella modalità Standard a pagamento di Gemini 2.5 Flash-Lite, pari a $0.10 per milione di token di input e $0.40 per milione di token di output, 100 chiamate con una media ipotizzata di 1,000 token di input e 100 token di output costano $0.014: 100,000 ÷ 1,000,000 × $0.10 + 10,000 ÷ 1,000,000 × $0.40. Listino Google.

È un calcolo relativo al solo modello, non una fattura misurata né un tetto di spesa. L'ipotesi sui token di input deve includere la formattazione di DSPy e le dimostrazioni aggiunte; ticket più lunghi, output più estesi e ragionamento fatturabile aumentano l'importo. La stima non include sconti per elaborazione batch o cache. Per la contabilità fa fede il consumo effettivo registrato dal provider.

DSPy, prompt scritti a mano e fine-tuning: quando scegliere ciascuno

DSPy è utile quando serve un metodo ripetibile per migliorare un programma dai risultati misurabili. Un prompt scritto a mano va mantenuto quando soddisfa già i requisiti del compito. Il fine-tuning va considerato quando ci sono prove che modificare i prompt non sia sufficiente e addestrare un modello sia compatibile con i vincoli di distribuzione.

Queste tecniche sono compatibili. DSPy include BootstrapFinetune e BetterTogether combina l'ottimizzazione dei prompt con quella dei pesi. La differenza pratica sta in ciò che si modifica e si mantiene, non nel nome che sembra più avanzato. Ottimizzazione di prompt e pesi.

Il punto di svolta è operativo: se ogni cambio di modello o nuovo caso di errore costringe uno sviluppatore a modificare manualmente più prompt, un ciclo di ottimizzazione basato su punteggi diventa interessante. Se un prompt breve supera già i criteri di accettazione, sostituirlo con un framework non offre un vantaggio dimostrato.

Chi dovrebbe provarlo, chi aspettare e chi farne a meno?

Per gli sviluppatori, è il momento di agire quando esistono un compito ripetuto, una baseline funzionante ed errori rappresentativi. Lo smistamento dei ticket e l'estrazione strutturata sono buoni punti di partenza perché gli output attesi si possono verificare. Meglio ottimizzare un piccolo componente prima di ampliare il sistema. Il limite di DSPy è la qualità dell'obiettivo: può selezionare un candidato con un punteggio più alto anche quando la metrica premia il comportamento sbagliato.

I responsabili operativi devono definire le etichette e la priorità degli errori. Per un responsabile dell'assistenza, smistare male un incidente che impedisce l'accesso all'account può essere molto più grave che sbagliare una normale domanda sulla fatturazione. Se il punteggio tratta i due errori allo stesso modo, l'ottimizzazione può contraddire le sue priorità. Questa regola va chiarita prima di chiedere a uno sviluppatore di migliorare il punteggio.

Chi decide l'acquisto dovrebbe chiedere prove su esempi mai visti durante lo sviluppo. Occorre sapere quale baseline è stata usata per il confronto, quali casi sono peggiorati, cosa include ora il programma in esecuzione e se il flusso rispetta ancora i requisiti di latenza. Il nome di un ottimizzatore non è una prova sufficiente per l'accettazione. La recensione di Promptfoo pubblicata sul sito è una lettura complementare per i team che stanno organizzando il lavoro di valutazione.

Un team aziendale dovrebbe fare a meno di DSPy per la scrittura occasionale di testi, le ricerche una tantum o i flussi che cambiano prima di poter raccogliere abbastanza esempi. Lo stesso vale se nessuno può mantenere il codice Python o concordare un criterio di valutazione. Un buon prompt, una checklist e una revisione umana possono essere una soluzione più proporzionata. Meglio aspettare quando il vero problema sono dati di partenza mancanti o un processo non definito: ottimizzare la formulazione non risolve nessuna delle due carenze.

Quali promesse su DSPy sono esagerate?

«Programmare invece di scrivere prompt» non fa sparire i prompt. DSPy li crea e li gestisce; sono ancora le persone a definire il compito, valutare gli errori e decidere se il risultato è accettabile.

«Compilare» non significa che il modello abbia imparato in modo permanente. Con gli ottimizzatori dei prompt, ciò che si apprende e si conserva sono istruzioni o dimostrazioni. Il modello viene comunque chiamato durante l'inferenza e le dimostrazioni occupano spazio nel prompt. Lo stato appreso può essere salvato in JSON e caricato in un nuovo programma. Salvataggio e caricamento.

«Ottimizzazione automatica» non significa miglioramento garantito. Il confronto utile è con l'approccio già in uso, su input mai visti durante lo sviluppo. Un punteggio di sviluppo più alto può riflettere overfitting, un giudice permissivo o un dataset che non include gli errori più costosi.

E le chiamate alla metrica non sono le chiamate al provider. Il parametro max_metric_calls di GEPA limita le invocazioni della funzione di valutazione; anche la riflessione chiama un modello e il programma valutato può a sua volta effettuare più richieste. Le impostazioni auto non corrispondono a un importo di fattura universale. Controlli del budget di GEPA.

Le domande degli sviluppatori su DSPy

Da dove cominciare

Lunedì, scegliere un errore ricorrente nello smistamento dei ticket o nell'estrazione e chiedere al responsabile del processo di etichettare esempi rappresentativi. Fissare una baseline, definire un criterio di valutazione ed eseguire un esperimento con limiti prestabiliti. Esaminare le risposte cambiate prima di approvare il candidato. Se non si riesce a definire il punteggio, il prossimo lavoro utile è concordare la regola aziendale.

Ricevi nella newsletter guide pratiche all'ingegneria dell'IA.