Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Estrazione Strutturata di Entità

Lezione 13 di 16 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Estrazione Strutturata di Entità
  2. Pipeline di Estrazione di Base
  3. Esempio 1: Estrazione da Curriculum Vitae
  4. Esempio 2: Estrazione da Email Commerciale
  5. Estrazione in Batch
  6. Valutazione della Qualità dell’Estrazione
  7. Costruisci il Tuo Riferimento Prima di Ottimizzare
  8. Punti chiave

Lezione aggiornata il 3 novembre 2026 sulla base della documentazione OpenAI: temperature e top_p sono accettati solo con uno sforzo di ragionamento pari a none, mentre i modelli GPT-5.6 ragionano per impostazione predefinita (medium). Le chiamate che impostano questi parametri devono quindi specificare reasoning={"effort": "none"} (API Responses) o reasoning_effort="none" (Chat Completions). Fonti: Using GPT-6 · GPT-5.6 Terra.

Estrazione Strutturata di Entità

L’estrazione strutturata di entità è uno dei casi d’uso più richiesti in produzione: trasformare testo libero (email, documenti, pagine web) in dati che la tua applicazione possa effettivamente utilizzare. Combinando l’Output Strutturato con prompt specializzati, puoi costruire pipeline di estrazione affidabili senza dover addestrare un modello NER dedicato.

Pipeline di Estrazione di Base

L’intera specificità dell’estrazione risiede nel prompt di sistema della funzione sottostante, e merita una stretta attenzione. Qui si sovrappongono tre istruzioni: estrai solo ciò che è presente, usa null per i dati mancanti e non inferire mai informazioni non menzionate esplicitamente.

Quell’ultima frase è la più importante nella pratica. Se lasciato a se stesso, un modello riempirà felicemente un numero SIRET plausibile o indovinerà una città da un prefisso telefonico, con le migliori intenzioni. Per un’estrazione destinata a un sistema aziendale, questa solerzia è un grave difetto: una volta che i dati sono nel database, non c’è modo di distinguere ciò che è stato letto da ciò che è stato ipotizzato. Impostare temperature a 0.0 serve allo stesso scopo: tra due esecuzioni dello stesso documento, vuoi lo stesso output, se non altro per riprodurre un incidente.

import json
from openai import OpenAI

client = OpenAI()

def extract_entities(text: str, schema: dict,
                     instructions: str = "") -> dict:
    """Estrae entità strutturate da testo libero."""
    system = (
        "You are a specialized entity extractor. "
        "Extract ONLY information present in the text. "
        "If information is missing, use null. "
        "NEVER infer information not explicitly mentioned."
    )
    if instructions:
        system += f"\n\nAdditional instructions: {instructions}"

    response = client.responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperature requires effort none
        instructions=system,
        input=f"Text to analyze:\n\n{text}",
        text={
            "format": {
                "type": "json_schema",
                "name": "extraction",
                "schema": schema,
                "strict": True
            }
        },
        temperature=0.0
    )
    return json.loads(response.output_text)

Esempio 1: Estrazione da Curriculum Vitae

Un CV è un terreno di prova eccellente perché combina sezioni stabili con un layout completamente libero. Lo schema sottostante raggruppa i dettagli di contatto in un oggetto identity dove quasi ogni campo è nullable: un candidato potrebbe non fornire un numero di telefono e rendere quel campo obbligatorio inviterebbe essenzialmente il modello a inventarne uno.

Le competenze non sono semplici stringhe ma oggetti con tre attributi, il che ti permette di preservare il livello dichiarato e categorizzare ogni competenza. Senza queste enum, “Scrum” e “Python” finirebbero affiancati nella stessa lista piatta, inutili per un filtro che cerca di isolare i linguaggi. Nota anche il campo end_date nelle esperienze, che è nullable mentre start_date non lo è: è così che codifichi una posizione attuale senza inventare convenzioni fatte in casa come “present” o “9999”. Sul CV di test, questa sottigliezza si manifesta sulla riga di TechCorp.

resume_schema = {
    "type": "object",
    "properties": {
        "identity": {
            "type": "object",
            "properties": {
                "full_name": {"type": "string"},
                "email": {"type": ["string", "null"]},
                "phone": {"type": ["string", "null"]},
                "location": {"type": ["string", "null"]},
                "linkedin": {"type": ["string", "null"]}
            },
            "required": ["full_name", "email", "phone",
                          "location", "linkedin"],
            "additionalProperties": False
        },
        "current_title": {"type": ["string", "null"]},
        "years_experience": {"type": ["integer", "null"]},
        "skills": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "level": {
                        "type": "string",
                        "enum": ["beginner", "intermediate",
                                 "advanced", "expert"]
                    },
                    "category": {
                        "type": "string",
                        "enum": ["language", "framework", "tool",
                                 "methodology", "soft_skill"]
                    }
                },
                "required": ["name", "level", "category"],
                "additionalProperties": False
            }
        },
        "experiences": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "company": {"type": "string"},
                    "title": {"type": "string"},
                    "start_date": {"type": "string"},
                    "end_date": {"type": ["string", "null"]},
                    "description": {"type": "string"}
                },
                "required": ["company", "title", "start_date",
                              "end_date", "description"],
                "additionalProperties": False
            }
        },
        "education": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "institution": {"type": "string"},
                    "degree": {"type": "string"},
                    "year": {"type": ["string", "null"]}
                },
                "required": ["institution", "degree", "year"],
                "additionalProperties": False
            }
        },
        "languages": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "language": {"type": "string"},
                    "level": {
                        "type": "string",
                        "enum": ["a1", "a2", "b1", "b2",
                                 "c1", "c2", "native"]
                    }
                },
                "required": ["language", "level"],
                "additionalProperties": False
            }
        }
    },
    "required": ["identity", "current_title", "years_experience",
                  "skills", "experiences", "education", "languages"],
    "additionalProperties": False
}

resume_text = """
Marie Dupont - Senior Full Stack Developer
Email: [email protected] | Tel: +33 6 12 34 56 78
Paris, France | linkedin.com/in/mariedupont

8 years of experience in web development.

Skills: Python (expert), TypeScript (advanced), React (advanced),
Django (expert), PostgreSQL (advanced), Docker (intermediate),
Scrum (advanced)

Experience:
- TechCorp (2022-present): Lead Full Stack Developer
  Principal architect of a B2B SaaS platform, team of 6 devs.
- StartupAI (2019-2022): Senior Developer
  Development of ML APIs in Python/FastAPI.

Education:
- EPITECH Paris, Master in Computer Science (2017)

Languages: French (native), English (C1), Spanish (B1)
"""

result = extract_entities(resume_text, resume_schema)

Esempio 2: Estrazione da Email Commerciale

Il secondo esempio cambia natura: non stiamo più solo copiando informazioni, stiamo chiedendo al modello di interpretare. intent e urgency sono giudizi: nessuna frase nell’email dice “questa è una richiesta di preventivo, alta priorità”. Questo è esattamente ciò che una classica pipeline di estrazione basata su regole o espressioni regolari non può fare, ed è esattamente ciò che giustifica l’uso di un LLM qui piuttosto che altrove.

Il resto dello schema torna a fatti verificabili: prodotti menzionati, importi con il loro contesto, date e il loro significato, azioni richieste. Il campo summary chiude l’oggetto e serve all’umano che esaminerà la coda, non al codice. Un punto di vigilanza con questo schema misto: un errore di giudizio su urgency non invalida gli importi, ma può accadere il contrario, perché un modello che fraintende l’intento a volte legge il resto attraverso quel malinteso. Se la classificazione è critica per il tuo routing, separala in una chiamata dedicata.

email_schema = {
    "type": "object",
    "properties": {
        "intent": {
            "type": "string",
            "enum": ["quote_request", "complaint", "information",
                     "order", "partnership", "other"]
        },
        "urgency": {
            "type": "string",
            "enum": ["critical", "high", "normal", "low"]
        },
        "sender": {
            "type": "object",
            "properties": {
                "name": {"type": ["string", "null"]},
                "company": {"type": ["string", "null"]},
                "email": {"type": ["string", "null"]}
            },
            "required": ["name", "company", "email"],
            "additionalProperties": False
        },
        "mentioned_products": {
            "type": "array",
            "items": {"type": "string"}
        },
        "mentioned_amounts": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "value": {"type": "number"},
                    "currency": {"type": "string"},
                    "context": {"type": "string"}
                },
                "required": ["value", "currency", "context"],
                "additionalProperties": False
            }
        },
        "key_dates": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "date": {"type": "string"},
                    "significance": {"type": "string"}
                },
                "required": ["date", "significance"],
                "additionalProperties": False
            }
        },
        "required_actions": {
            "type": "array",
            "items": {"type": "string"}
        },
        "summary": {"type": "string"}
    },
    "required": ["intent", "urgency", "sender",
                  "mentioned_products", "mentioned_amounts",
                  "key_dates", "required_actions", "summary"],
    "additionalProperties": False
}

Estrazione in Batch

Per elaborare grandi volumi, parallelizza le tue estrazioni. Un ciclo sequenziale su mille documenti passa la maggior parte del tempo ad aspettare la rete; con asyncio, queste attese si sovrappongono e il batch viene elaborato in una frazione del tempo.

Il semaforo non è un dettaglio decorativo. Senza di esso, lanciare mille task contemporaneamente saturerà la tua quota e attiverà errori di rate limit che costano più in retry di quanto risparmino in velocità. Imposta il valore max_concurrent osservando i tuoi limiti, con dieci come punto di partenza prudente. Nota anche return_exceptions=True: impedisce a un singolo documento malformato di far crashare l’intero batch, lasciandoti il compito di smistare i fallimenti successivamente.

import asyncio
from openai import AsyncOpenAI

async_client = AsyncOpenAI()

async def extract_batch(texts: list[str], schema: dict,
                          max_concurrent: int = 10) -> list[dict]:
    """Estrazione parallela con controllo della concorrenza."""
    semaphore = asyncio.Semaphore(max_concurrent)

    async def extract_one(text: str) -> dict:
        async with semaphore:
            response = await async_client.responses.create(
                model="gpt-5.6-terra",
                reasoning={"effort": "none"},  # temperature requires effort none
                instructions="Extract entities from the provided text. "
                             "Use null for missing fields.",
                input=text,
                text={
                    "format": {
                        "type": "json_schema",
                        "name": "extraction",
                        "schema": schema,
                        "strict": True
                    }
                },
                temperature=0.0
            )
            return json.loads(response.output_text)

    tasks = [extract_one(t) for t in texts]
    return await asyncio.gather(*tasks, return_exceptions=True)

Valutazione della Qualità dell’Estrazione

Una pipeline di estrazione senza un set di test annotato è una pipeline la cui affidabilità nessuno conosce, e l’impressione lasciata da tre esempi letti a mano si rivela quasi sempre troppo ottimistica. La funzione sottostante confronta un’estrazione ottenuta campo per campo contro un riferimento stabilito manualmente, restituendo la precisione complessiva insieme a una ripartizione delle discrepanze.

Questa ripartizione è la parte utile: gli errori non sono quasi mai distribuiti uniformemente. Un campo concentra i problemi—spesso una data ambigua, un livello di competenza implicito o una categoria mal definita—e una singola frase aggiunta al prompt di sistema lo risolve. Senza questa misurazione, staresti modificando il prompt a caso, rischiando possibilmente di peggiorare un campo che già funzionava.

def evaluate_extraction(expected: dict, obtained: dict,
                       fields: list[str]) -> dict:
    """Confronta l'estrazione ottenuta con il riferimento."""
    correct = 0
    total = len(fields)
    errors = []

    for field in fields:
        val_expected = expected.get(field)
        val_obtained = obtained.get(field)

        if val_expected == val_obtained:
            correct += 1
        else:
            errors.append({
                "field": field,
                "expected": val_expected,
                "obtained": val_obtained
            })

    return {
        "precision": correct / total if total > 0 else 0,
        "correct": correct,
        "total": total,
        "errors": errors
    }

Costruisci il Tuo Riferimento Prima di Ottimizzare

Scegli un tipo di documento dal tuo dominio—contratti, fatture, report—e definisci uno schema di estrazione di almeno dieci campi, mescolando deliberatamente campi facili con altri che sai essere ambigui. Assembla cinque documenti di esempio con le loro estrazioni attese, scritte a mano: questo passaggio è noioso, richiede un’ora, ed è ciò che dà valore a tutto il lavoro successivo.

Poi esegui la pipeline, misura la precisione e leggi la lista degli errori campo per campo. Il campo più difettoso ti dirà cosa correggere nel prompt; una seconda misurazione ti dirà se la correzione ha effettivamente aiutato—o se ha degradato un altro campo nel processo, cosa che accade più spesso di quanto pensi non appena un’istruzione aggiuntiva sposta l’attenzione del modello.

Punti chiave

  • L’estrazione strutturata sostituisce i modelli NER dedicati per la maggior parte dei casi d’uso
  • Usa temperature=0.0 per massimizzare la coerenza
  • Rendi i campi opzionali nullable piuttosto che opzionali
  • Parallelizza con asyncio per grandi volumi
  • Valuta sistematicamente la qualità con un set di test annotato
  • Le istruzioni del prompt di sistema guidano il contenuto, lo schema vincola la struttura