Estrarre contenuto da un documento significa quasi sempre tre cose in fila: leggere i caratteri (OCR), capire come sono disposti (layout), tirarne fuori i valori che servono (field extraction). Su Azure li offrono due servizi, Azure Document Intelligence in Foundry Tools e Azure Content Understanding in Foundry Tools, e la domanda ricorrente è quale dei due prendi davanti a un certo documento.

Document Intelligence: Read, Layout, prebuilt, custom

Read è l’OCR: testo stampato e manoscritto, righe e parole, rilevamento della lingua. Layout aggiunge la struttura (tabelle multipagina con celle unite, selection mark, section heading, header e footer, ordine di lettura) ed emette direttamente Markdown. I prebuilt di dominio hanno uno schema già definito: prebuilt-invoice restituisce VendorName, InvoiceId, InvoiceDate, le righe di dettaglio, SubTotal, TotalTax e InvoiceTotal; ci sono anche receipt e ID document, con le cautele sui dati personali.

Quando nessun prebuilt copre il documento si addestra un custom model. Il custom template vale per moduli davvero templated: training rapido con pochi campioni, ma dipendente dalla posizione dei campi, e un fornitore che sposta una colonna lo rompe. Il custom neural regge layout variabili e testo non strutturato, al prezzo di un training più lungo e di una copertura linguistica diversa. Accanto c’è il custom classifier, che riconosce e separa i documenti dentro un file che ne contiene molti.

Le add-on capability di analyzeDocument (highResolution, formulas, styleFont, barcodes, languages, keyValuePairs, searchablePdf) non sono attive di default: vanno chieste e si fatturano a parte. I queryFields estendono a runtime lo schema di un prebuilt senza training: la scorciatoia quando mancano due campi su venti. E la coppia accuracy contro confidence: l’accuracy la restituisce il training di un custom model, la confidence il risultato dell’analisi, ed è sulla seconda che si costruisce la soglia di human-in-the-loop.

Content Understanding: analyzer, fieldSchema e i tre metodi

Content Understanding è multimodale: documenti, immagini, audio e video passano dalla stessa API. L’unità di lavoro è l’analyzer, che parte da un baseAnalyzerId e vi aggiunge configurazione e schema. I prebuilt sono organizzati per scopo: content extraction (prebuilt-read, prebuilt-layout), base per modalità (prebuilt-document, prebuilt-image, prebuilt-audio, prebuilt-video), per il RAG (prebuilt-documentSearch, prebuilt-imageSearch) e di dominio (prebuilt-invoice, prebuilt-idDocument, prebuilt-contract).

La parte distintiva è il fieldSchema. Ogni campo ha un tipo (string, number, boolean, date, object, array), una description e un method, e i metodi sono tre: extract copia un valore presente nel documento, classify sceglie fra categorie che hai descritto, generate produce un valore che nel documento non c’è, come un riassunto. Sceglierne uno sbagliato è l’errore più comune: chiedere extract di un totale da calcolare non funziona. E la description non è documentazione, è un mini-prompt: riscriverla è la prima leva sulla qualità.

analyzer = {
  "baseAnalyzerId": "prebuilt-document",
  "config": {"enableOcr": True, "enableLayout": True,
             "tableFormat": "markdown",
             "estimateFieldSourceAndConfidence": True},
  "fieldSchema": {"fields": {
      "numero": {"type": "string", "method": "extract",
                 "description": "Numero del contratto, in alto a destra"},
      "tipo": {"type": "string", "method": "classify",
               "description": "Fornitura, manutenzione o consulenza"},
      "sintesi": {"type": "string", "method": "generate",
                  "description": "Obblighi del fornitore, in due frasi"}
  }}
}

Il ciclo di chiamata è asincrono: una PUT per creare l’analyzer, una POST con il suffisso :analyze per inviare il file, header Operation-Location e polling; per file piccoli esistono operazioni sincrone di Read e Layout, in preview. Nella configurazione stanno anche enableFormula, enableBarcode, enableSegment e locales, e i modelli generativi dell’analyzer si mappano sui deployment Foundry della risorsa. Per i file misti c’è il classifier, che categorizza, splitta e instrada ogni parte all’analyzer giusto; l’operazione :copy duplica un analyzer fra risorse, per promuovere da sviluppo a produzione o congelare una definizione.

Markdown e rappresentazioni pulite per RAG e agenti

Il formato dell’output non è un dettaglio estetico. Un JSON di parole con coordinate serve a un’applicazione che deve compilare campi; a un modello che deve ragionare serve Markdown, perché heading, tabelle e figure diventano struttura e permettono un chunking che segue le sezioni. È la rappresentazione pulita e ancorata che il dominio chiede: si analizza una volta, e da lì nascono l’indice e il contesto degli agenti.

L’ancoraggio arriva da estimateFieldSourceAndConfidence: ogni campo torna con origine e confidence, e sono quei dati a diventare citazioni e soglie di revisione umana. Lato agenti, Content Understanding può fare da context provider di Microsoft Agent Framework per analizzare gli allegati di una conversazione, invece di dare il PDF grezzo al modello.

C’è infine l’agentic mode, in preview: si attiva mettendo agentic nel campo workflow e serve quando l’estrazione richiede ragionamento multistep, calcoli o validazioni incrociate. Usa il livello di contextualization advanced, quindi costa di più, vale solo per gli analyzer di documento, accetta un file per richiesta e non supporta il method extract. Sostituisce la pro mode, ritirata.

Quando l’uno e quando l’altro

Document Intelligence conviene con tipi di documento pochi e noti, volumi alti e un insieme di campi deterministico e ripetibile, coperto da un prebuilt o da un custom addestrato su campioni etichettati. Content Understanding conviene con più modalità, con uno schema descritto in linguaggio naturale senza etichettare nulla, con campi generativi o classificazioni, e quando l’obiettivo è RAG e agenti. Un’avvertenza: portale Foundry e Studio dedicato non espongono le stesse versioni di API né gli stessi prebuilt.

Da ricordare per l’esame

  • Read fa OCR, Layout aggiunge struttura e Markdown, i prebuilt di dominio hanno campi fissi; custom template per moduli a posizione fissa, custom neural per layout variabili, custom classifier per separare documenti dentro un solo file.
  • queryFields estende lo schema di un prebuilt a runtime senza training; le add-on capability vanno chieste esplicitamente e si pagano.
  • Accuracy riguarda il training di un custom model, confidence il risultato dell’analisi: la soglia di revisione umana sta sulla confidence.
  • Nel fieldSchema di Content Understanding il method è la scelta chiave: extract per un valore presente, classify per una categoria, generate per un valore da produrre. La description fa da prompt.
  • Il Markdown è la rappresentazione da preferire per RAG e agenti, e estimateFieldSourceAndConfidence lo rende citabile e verificabile.