Pydantic + OpenAI: output strutturati dagli LLM senza parsing manuale

I Structured Outputs di OpenAI garantiscono che il modello restituisca un JSON conforme a uno schema grazie al constrained decoding, ma lato Python resta comunque una stringa da parsare, con tipi da validare e campi da gestire. L’articolo di Maria Mouschoutzi su Towards Data Science mostra come Pydantic colmi questo gap, diventando lo strato di definizione dello schema tra il codice Python e l’API OpenAI.

Da dizionario a oggetto tipizzato

Pydantic è una libreria di data validation basata sulle type annotation: si definisce la forma dei dati come una classe Python e ogni valore in ingresso viene validato. Con l’approccio classico a Function Calling si scrive lo schema come dizionario grezzo e si fa json.loads sul risultato, con il rischio di KeyError o di un campo age che arriva come stringa invece che come intero. Passando invece la classe Pydantic a response_format e usando il metodo .parse() del SDK OpenAI, si ottiene un vero oggetto Python, con tutti i campi tipizzati e validati e accesso in dot-notation. Lo JSON Schema richiesto dall’API viene generato dietro le quinte dal modello Pydantic, senza scriverlo a mano.

Nested, validazione e refusal

Il vantaggio si vede soprattutto con le strutture annidate: definire un modello Address dentro ContactInfo è naturale in Pydantic, mentre lo JSON Schema equivalente sarebbe scomodo da scrivere. Con Field si aggiungono vincoli espliciti, come ge=1, le=5 su un rating o max_length=200 su un summary, e le description fungono da istruzioni per il modello su cosa mettere in ciascun campo. Il metodo .parse() gestisce inoltre i refusal: se il modello rifiuta una richiesta, il campo parsed è None e refusal contiene il motivo, aspetto rilevante per app in produzione dove non si può prevedere cosa chiederà l’utente.

L’esempio conclusivo è una pipeline di document information extraction su annunci di lavoro: input non strutturato, schema di output ben definito (con un modello annidato SalaryRange e campi Optional che defaultano a None) e un risultato tipizzato pronto per essere inserito in un database o passato allo step successivo senza elaborazione aggiuntiva.

• Structured Outputs garantisce JSON conforme allo schema, ma resta una stringa; Pydantic restituisce un oggetto Python tipizzato e validato.
• Il metodo .parse() del SDK OpenAI genera lo schema, imposta strict: True e gestisce anche i refusal del modello.
• L’accoppiata funziona bene su nested data, vincoli con Field ed estrazione documentale, casi tipici delle app LLM in produzione.

Fonte: Pydantic + OpenAI: The Cleanest Way to Get Structured Outputs from LLMs — https://towardsdatascience.com/pydantic-openai-the-cleanest-way-to-get-structured-outputs-from-llms/