Azure Content Understanding in Foundry Tools è il servizio multimodale che trasforma contenuto non strutturato — documenti, immagini, audio, video — in dati strutturati. Nel dominio computer vision serve a estrarre caratteristiche visive secondo uno schema che decidi tu e a interpretare i video segmento per segmento. Chiude l’unità la parte scomoda: il visivo è pericoloso in modi che un filtro testuale non vede.

L’analyzer è l’unità di configurazione

Tutto passa da un analyzer, un oggetto JSON con quattro parti: identità (analyzerId, description, baseAnalyzerId), models con i nomi dei modelli Foundry, config con le opzioni di elaborazione e fieldSchema con i campi da estrarre. I custom analyzer si derivano solo da quattro base analyzer: prebuilt-document, prebuilt-image, prebuilt-audio, prebuilt-video.

Per le immagini c’è un’asimmetria da memorizzare: gli image analyzer supportano una sola opzione di config, returnDetails. Non esistono interruttori tipo “estrai i colori” o “trova i difetti”: le caratteristiche visive si dichiarano nel fieldSchema, e la description di ogni campo funziona da mini-prompt che guida il modello, quindi scriverla bene è il vero lavoro di tuning. Ogni campo ha un type fra string, number, boolean, date, object e array, e un method: extract prende il valore così come compare, generate lo produce interpretando, classify lo assegna da un insieme chiuso dichiarato con enum.

{
  "baseAnalyzerId": "prebuilt-image",
  "fieldSchema": { "fields": {
    "difetto": { "type": "string", "method": "classify",
                 "enum": ["graffio", "crepa", "nessuno"],
                 "description": "Anomalia visibile sul pezzo" }
  } }
}

Per indicizzare immagini in un flusso RAG c’è prebuilt-imageSearch, che genera una descrizione di un paragrafo pronta per il vector store. Un limite dichiarato: gli image analyzer non sono ottimizzati quando l’analisi si basa sul testo stampato, dove conviene uno schema di document field extraction.

Video: due fasi e una segmentazione che decidi tu

L’analisi video lavora in due passaggi. La content extraction produce la spina dorsale: trascrizione WebVTT con diarizzazione, keyframe, cambi di inquadratura. La field extraction ci passa sopra un modello generativo che descrive le scene, riempie i campi personalizzati e produce la segmentazione. Con returnDetails a true tornano i timestamp di frase e gli stacchi di camera.

La segmentazione si governa con enableSegment. A false il video è un unico segmento: giusto per un controllo di conformità che cerca un problema ovunque nel filmato. A true si descrive in linguaggio naturale, dentro contentCategories, come spezzare il video — per esempio “ogni servizio distinto di un telegiornale”. Per il video si definisce una sola content category, e la segmentazione consuma token anche senza campi dichiarati. Per l’ingestione RAG c’è prebuilt-videoSearch, che restituisce Markdown con trascrizione e keyframe per segmento.

I limiti tecnici spiegano i falsi negativi: circa un fotogramma al secondo, frame ridimensionati a 512 pixel per lato, solo il parlato trascritto.

Standard e agentic: quando serve la pipeline che ragiona

Qui la terminologia vecchia inganna. La “pro mode” esisteva solo nella API 2025-05-01-preview, che è ritirata. Il suo posto è preso dall’agentic mode, disponibile con 2026-06-01-preview e attivato impostando config.workflow su "agentic" alla creazione dell’analyzer; il servizio risolve poi il valore in una forma versionata come agentic.2026-06-01-preview. Lasciare "default" fa scegliere al servizio fra standard e advanced.

La scelta è di costo e latenza. L’estrazione single-task standard basta quando il valore sta in un punto preciso. L’agentic mode serve quando la risposta va costruita da indizi sparsi: ragionamento multistep, calcoli su valori non dichiarati, validazione di coerenza, interpretazione di tabelle e figure complesse. In cambio usa la tariffa advanced e impiega più tempo; la documentazione consiglia almeno 400.000 TPM sul deployment per evitare errori 429. Contano anche i limiti della preview: un solo file per richiesta, solo document analyzer, campi extract non supportati.

Difendere il visivo: filtri, iniezione e regole di policy

Per classificare contenuto visivo non ammesso ci sono due superfici. I guardrail di Foundry applicano le quattro categorie di danno — hate, sexual, violence, self-harm — con quattro livelli di severità (safe, low, medium, high) sia al testo sia alle immagini, su input e output; il livello safe è annotato ma mai bloccato. Fuori da una chiamata al modello, l’API image:analyze di Content Safety accetta l’immagine in base64 o come blob URL e restituisce le stesse categorie con outputType uguale a FourSeverityLevels e severità 0, 2, 4 e 6.

L’iniezione indiretta tramite testo stampato in un’immagine è il rischio meno intuitivo: un’istruzione scritta su un cartello o in uno screenshot non esiste come testo finché qualcuno non la estrae, quindi nessun filtro testuale la vede a monte, ma un modello multimodale la legge e può eseguirla. Prompt Shields distingue i user prompt attack, scansionati sull’input utente, dai document attack, scansionati sull’input utente e sulla tool response, con annotazioni detected e filtered. Lo Spotlighting, in preview e disattivo di default, marca i documenti come meno affidabili codificandoli in base-64: aumenta i token e vale solo via Chat Completions. La regola applicativa è una: il testo estratto da un’immagine è dato, mai istruzione.

Simboli vietati, uso del marchio e contenuto inappropriato diventano campi classify con enum chiuso, più revisione umana dove l’impatto è alto. Per la provenienza c’è Content Provenance Detection: verifica manifest C2PA firmati e watermark invisibili, rileva solo contenuti generati da sistemi AI Microsoft, fino a 100 MB, e l’assenza di segnale non prova che il contenuto non sia AI.

Da ricordare per l’esame

  • Gli image analyzer supportano solo returnDetails: le caratteristiche visive si dichiarano nel fieldSchema, dove la description agisce da mini-prompt.
  • method vale extract (valore così com’è), generate (interpretato) o classify (scelto da un enum).
  • Sul video, enableSegment a false è un unico segmento; a true segue le contentCategories, una sola per video. Circa 1 fps, frame a 512 pixel, solo parlato.
  • La pro mode è ritirata con la API 2025-05-01-preview: oggi è agentic mode, tariffa advanced, un file per richiesta, solo document analyzer.
  • Guardrail su testo e immagini: safe/low/medium/high; l’API image di Content Safety restituisce 0, 2, 4, 6. Il testo dentro un’immagine è prompt injection indiretta: trattalo come dato non fidato.