AI Engineering Academy · Lezione

Instructor: estrazione tipizzata con Pydantic

Utilizzi la libreria instructor per modificare il client OpenAI, in modo che riprovi automaticamente e convalidi le risposte rispetto allo schema Pydantic finché l'estrazione non riesce.

Lezione 1 di 413 passaggi

Instructor: estrazione tipizzata con Pydantic è una lezione AI Engineering Academy gratuita su CoddyKit. Questa è la lezione 1 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Engineering Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Engineering Academy include 4 lezioni in totale.

Che cos'è la libreria instructor?

La libreria instructor è un wrapper leggero attorno al client OpenAI che rende affidabile l'estrazione strutturata. Invece di sperare che il modello restituisca JSON valido, instructor impone il suo schema Pydantic e riprova automaticamente se la validazione non va a buon fine. In questo modo non è necessario scrivere manualmente logiche personalizzate di parsing e retry.

Installazione di Instructor

Installi instructor con un singolo comando pip. Richiede pydantic v2 e l'SDK openai. Dopo l'installazione, applichi una patch al client OpenAI con instructor.patch() per ottenere il client potenziato che supporta il parametro response_model in ogni chiamata.

pip install instructor openai pydantic

Applicazione di patch al client OpenAI

Instructor funziona applicando una patch al client OpenAI standard. La chiamata instructor.from_openai(client) restituisce un nuovo client in cui ogni chiamata chat.completions.create accetta l'argomento keyword response_model. La chiamata API sottostante è identica: instructor aggiunge semplicemente l'imposizione dello schema.

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

Definizione dello schema Pydantic

Definisca la struttura dei dati che desidera ottenere dal modello come Pydantic BaseModel. I nomi dei campi, i tipi e le docstring vengono convertiti automaticamente nello JSON Schema inviato al modello. Utilizzi nomi di campo chiari e descrittivi, così il modello capirà cosa deve compilare. Aggiunga i validator per le regole di business.

from pydantic import BaseModel, Field
from typing import Optional

class PersonExtract(BaseModel):
    name: str = Field(description='Full name of the person')
    age: Optional[int] = Field(None, description='Age in years if mentioned')
    email: Optional[str] = Field(None, description='Email address if present')
    company: Optional[str] = Field(None, description='Company or employer')

Esecuzione di una chiamata di estrazione

Passi la classe del modello Pydantic come response_model al client con la patch. Instructor costruisce una tool call in background, il modello compila i campi e instructor deserializza il risultato in un oggetto Python tipizzato. Otterrà il completamento automatico completo nell'IDE e la sicurezza dei tipi sui dati restituiti.

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=PersonExtract,
    messages=[
        {'role': 'user', 'content': 'Alice Smith, 34, works at Acme Corp. Email: alice@acme.com'}
    ]
)
print(result.name)   # Alice Smith
print(result.email)  # alice@acme.com

Retry automatico in caso di errore di validazione

Se il modello restituisce dati che non superano la validazione Pydantic, instructor invia automaticamente l'errore di validazione al modello e gli chiede di correggere la risposta. Può configurare il numero massimo di retry con il parametro max_retries. Questo ciclo di autoriparazione elimina la maggior parte degli errori occasionali di estrazione senza richiedere codice aggiuntivo.

import instructor
from openai import OpenAI
from pydantic import BaseModel, field_validator

client = instructor.from_openai(OpenAI())

class Product(BaseModel):
    name: str
    price_usd: float

    @field_validator('price_usd')
    @classmethod
    def must_be_positive(cls, v):
        if v <= 0:
            raise ValueError('Price must be positive')
        return v

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=Product,
    max_retries=3,
    messages=[{'role': 'user', 'content': 'Widget costs $12.99'}]
)

Modelli annidati per strutture complesse

Instructor gestisce senza problemi i modelli Pydantic annidati. Può definire schemi profondamente annidati con liste, sotto-oggetti opzionali e unioni discriminate. Il modello riceve lo JSON Schema completo e deve compilare tutti i campi obbligatori, caratteristica ideale per estrarre oggetti strutturati come fatture o curriculum con più sezioni.

from pydantic import BaseModel
from typing import List

class LineItem(BaseModel):
    description: str
    quantity: int
    unit_price: float

class Invoice(BaseModel):
    vendor: str
    invoice_number: str
    total_amount: float
    line_items: List[LineItem]

result = client.chat.completions.create(
    model='gpt-4o',
    response_model=Invoice,
    messages=[{'role': 'user', 'content': invoice_text}]
)

Streaming parziale delle estrazioni

Per i processi di estrazione di grandi dimensioni, instructor supporta lo streaming parziale tramite instructor.Partial[YourModel]. Mentre il modello genera i token, riceve in tempo reale istanze del modello compilate parzialmente. È utile per mostrare l'avanzamento in un'interfaccia o elaborare i campi non appena arrivano, invece di attendere la risposta completa.

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

for partial in client.chat.completions.create_partial(
    model='gpt-4o-mini',
    response_model=PersonExtract,
    messages=[{'role': 'user', 'content': long_text}]
):
    print(partial.name, partial.email)

Estrazione di liste di oggetti

Quando deve estrarre più entità da un singolo documento, racchiuda il modello in List[YourModel]. Instructor gestisce lo schema dell'array JSON e deserializza ogni elemento in un oggetto Python tipizzato. Questo approccio è efficace per estrarre tutte le persone menzionate in un articolo, tutte le transazioni in un estratto conto o tutte le date in un contratto.

from pydantic import BaseModel
from typing import List

class Mention(BaseModel):
    entity: str
    entity_type: str  # PERSON, ORG, DATE, LOCATION
    context: str

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=List[Mention],
    messages=[{'role': 'user', 'content': article_text}]
)
for mention in result:
    print(f'{mention.entity} ({mention.entity_type})')

Scelta del modello giusto per l'estrazione

Non tutte le estrazioni richiedono GPT-4o. Per gli schemi semplici e piatti con meno di 10 campi, gpt-4o-mini produce risultati quasi identici a un decimo del costo. Utilizzi GPT-4o per schemi annidati complessi, documenti lunghi o casi in cui il recall è importante. Prima di scegliere un modello per la produzione, esegua sempre un benchmark su un campione dei dati reali.

# Cost comparison for 1000 extractions
# GPT-4o-mini: ~$0.002 per call = $2.00 total
# GPT-4o: ~$0.015 per call = $15.00 total
# Test both on 50 samples and compare F1 score
# before committing to the expensive model

Logging e debugging delle estrazioni

Instructor espone un sistema hooks per l'osservabilità. Registri un callback on_completion per memorizzare la risposta API grezza, l'utilizzo dei token e il numero di retry per ogni estrazione. Questo la aiuta a identificare i tipi di documento che causano più errori e a regolare di conseguenza gli schemi o i prompt.

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

@client.on('completion:response')
def log_usage(response):
    usage = response.usage
    print(f'Tokens: {usage.prompt_tokens}+{usage.completion_tokens}')

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=PersonExtract,
    messages=[{'role': 'user', 'content': text}]
)

Verifica rapida

Verifichi la comprensione della libreria instructor per l'estrazione tipizzata.

Rispondi nella lezione interattiva

Riepilogo della lezione

In questa lezione ha imparato che instructor applica una patch al client OpenAI per accettare un parametro response_model che impone gli schemi Pydantic; il retry automatico in caso di errore di validazione rende l'estrazione robusta senza dover gestire manualmente gli errori; e i modelli annidati e l'estrazione di liste consentono di analizzare documenti complessi con più entità trasformandoli in oggetti Python completamente tipizzati. Nella prossima lezione gestiremo i dati parziali e mancanti negli schemi estratti.

Gratis per iniziare

Impara Python con un tutor IA — gratis

Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.

Corsi: 30
Lezioni: 120

Inizia a imparare gratis Visualizza il corso completo

Domande Frequenti

La lezione «Instructor: estrazione tipizzata con Pydantic» è gratuita?

Sì — il testo completo di «Instructor: estrazione tipizzata con Pydantic» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Engineering Academy, passa a CoddyKit PRO. Il corso AI Engineering Academy include 4 lezioni in totale.

Cosa imparerò in «Instructor: estrazione tipizzata con Pydantic»?

Utilizzi la libreria instructor per modificare il client OpenAI, in modo che riprovi automaticamente e convalidi le risposte rispetto allo schema Pydantic finché l'estrazione non riesce. Eserciti AI Engineering Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare AI Engineering Academy?

Non è richiesta alcuna esperienza precedente. AI Engineering Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 1 di 4.

Quanto tempo richiede la lezione «Instructor: estrazione tipizzata con Pydantic»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione AI Engineering Academy?

Sì. Ogni lezione AI Engineering Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

Instructor: estrazione tipizzata con Pydantic
Gestire dati parziali e mancanti
Elaborazione batch con async e code
Evoluzione degli schemi e compatibilità con le versioni precedenti

← Torna a AI Engineering Academy