Classificare e instradare i dati usando Content Understanding

Content Understanding consente di creare flussi di lavoro di classificazione personalizzati che classificano il contenuto e lo instradano all'analizzatore corretto. Con il routing, è possibile inviare più flussi di dati attraverso la stessa pipeline e assicurarsi che i dati vengano elaborati dall'analizzatore migliore per il relativo tipo.

Questa guida illustra due passaggi:

Creare un classificatore di base che classifica i documenti in categorie personalizzate.
Classificare e instradare con analizzatori personalizzati che combinano la classificazione con l'estrazione dei campi per ogni categoria.

Prerequisiti

Per iniziare, assicurarsi di disporre delle risorse e delle autorizzazioni seguenti:

Sottoscrizione Azure. Se non si ha una sottoscrizione Azure, creare un account gratuito.
Una risorsa Microsoft Foundry nel portale di Azure creata in un'area supportata.
- Questa risorsa è elencata in Foundry>Foundry nel portale.
Configurare le distribuzioni predefinite del modello per la risorsa Content Understanding. Impostando le impostazioni predefinite, si crea una connessione ai modelli Microsoft Foundry usati per le richieste di Comprensione contenuto. Scegliere uno dei metodi seguenti:
- Portale
- API REST
1. Passare alla pagina delle impostazioni di Content Understanding.
2. Selezionare il pulsante + Aggiungi risorsa in alto a sinistra.
3. Selezionare la risorsa Foundry che si vuole usare e selezionare Avanti>Salva.
  
  Assicurarsi che la casella di controllo Abilita distribuzione automatica per i modelli necessari se non è selezionata alcuna impostazione predefinita . Questa selezione garantisce che la risorsa sia completamente configurata con i modelli necessari GPT-4.1, GPT-4.1-mini e text-embedding-3-large. Diversi analizzatori predefiniti richiedono modelli diversi.
Eseguendo questi passaggi, è possibile configurare una connessione tra i modelli Content Understanding e Foundry nella risorsa Foundry.
1. Nella risorsa Foundry, creare distribuzioni di modelli dei GPT-4.1, GPT-4.1-mini, e text-embedding-3-large. Per informazioni dettagliate su come distribuire questi modelli, vedere Creare distribuzioni di modelli nel portale di Microsoft Foundry. Diversi analizzatori predefiniti richiedono modelli diversi, quindi è necessario distribuire tutti e tre.
2. Definire le distribuzioni predefinite del modello a livello di risorsa. Prima di eseguire il comando seguente cURL , apportare le modifiche seguenti alla richiesta HTTP:
  1. Sostituire {endpoint} e {key} con i valori corrispondenti dell'istanza di Foundry nel portale di Azure.
  2. Sostituire {myGPT41Deployment}, {myGPT41MiniDeployment}e {myEmbeddingDeployment} con i nomi effettivi della distribuzione del modello dalla risorsa Foundry.
```
curl -i -X PATCH "{endpoint}/contentunderstanding/defaults?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d '{
        "modelDeployments": {
          "gpt-4.1": "{myGPT41Deployment}",
          "gpt-4.1-mini": "{myGPT41MiniDeployment}",
          "text-embedding-3-large": "{myEmbeddingDeployment}"
        }
      }'
```
cURL installato per l'ambiente di sviluppo (per la scheda API REST).

Passaggio 1: Creare un classificatore di base

Un classificatore di base classifica i documenti in categorie di contenuto personalizzate. Le categorie vengono definite con nomi e descrizioni e il servizio usa tali definizioni per classificare i file di input. Il enableSegment parametro controlla se il classificatore suddivide i file multidocumenti in segmenti o considera l'intero file come un singolo documento.

Content Understanding Studio
API REST

Passare al portale di Content Understanding Studio e accedere con le credenziali. Se si ha familiarità con l'esperienza classica Azure Document Intelligence in Foundry Tools Studio, Content Understanding estende lo stesso contenuto e l'estrazione dei campi in tutte le modalità, ovvero documento, immagine, video e audio. Selezionare l'opzione per provare la nuova esperienza Di comprensione del contenuto per accedere alle funzionalità multimodo.

Creare un progetto di classificatore

Iniziare con un nuovo progetto: selezionare Crea progetto nella home page.
Selezionare il tipo di progetto: selezionare l'opzione in Classify and route with custom categories.
Caricare i dati: caricare una parte di dati di esempio per iniziare a classificare.
Creare regole di routing: nella scheda Regole di routing selezionare Add category. Assegnare alla categoria un nome e una descrizione. Per un classificatore di base, è possibile ignorare l'assegnazione di un analizzatore specifico a ogni categoria.
Testare il flusso di lavoro di classificazione: quando le regole di routing personalizzate sono pronte per il test, selezionare Esegui analisi per visualizzare l'output delle regole sui dati.
Compilare l'analizzatore di classificazione: quando si è soddisfatti dell'output, selezionare il pulsante Compila analizzatore nella parte superiore della pagina. Assegnare un nome all'analizzatore e selezionare Salva.

Prima di eseguire uno dei comandi cURL seguenti, sostituire {endpoint} e {key} con i valori corrispondenti dell'istanza di Foundry nel portale di Azure.

Definire il classificatore

Definire contentCategories all'interno della configurazione dell'analizzatore. Ogni categoria ha un nome e una descrizione usati dal servizio per classificare i file di input.

Creare un file JSON denominato classifier.json con il contenuto seguente:

{
  "baseAnalyzerId": "prebuilt-document",
  "description": "Custom classifier for document categorization",
  "config": {
    "returnDetails": true,
    "enableSegment": true,
    "contentCategories": {
      "Loan application": {
        "description": "Documents submitted by individuals or businesses to request funding, typically including personal or business details, financial history, loan amount, purpose, and supporting documentation."
      },
      "Invoice": {
        "description": "Billing documents issued by sellers or service providers to request payment for goods or services, detailing items, prices, taxes, totals, and payment terms."
      },
      "Bank_Statement": {
        "description": "Official statements issued by banks that summarize account activity over a period, including deposits, withdrawals, fees, and balances."
      }
    }
  },
  "models": {"completion": "gpt-4.1"}
}

I campi chiave in questa definizione sono:

Campo	Descrizione
`baseAnalyzerId`	Analizzatore predefinito da estendere. Usare `prebuilt-document` per la classificazione dei documenti.
`contentCategories`	Dizionario con un massimo di 200 nomi di categoria e descrizioni.
`enableSegment`	Quando `true`, suddivide e classifica automaticamente tipi di documento diversi all'interno di un singolo file. Quando `false`, considera l'intero file come un singolo documento.

Creare il classificatore

Usare una PUT richiesta per creare il classifier analyzer.

curl -i -X PUT "{endpoint}/contentunderstanding/analyzers/{classifierId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d @classifier.json

La 201 Created risposta include un'intestazione Operation-Location con un URL che è possibile usare per tenere traccia dello stato dell'operazione di creazione asincrona.

201 Created
Operation-Location: {endpoint}/contentunderstanding/analyzers/{classifierId}/operations/{operationId}?api-version=2025-11-01

Al termine dell'operazione, un HTTP GET nell'URL del percorso dell'operazione restituisce "status": "succeeded".

curl -i -X GET "{endpoint}/contentunderstanding/analyzers/{classifierId}/operations/{operationId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Riferimento: Gli analizzatori di contenuto: creare o sostituire

Classificare un documento

Inviare un documento per la classificazione usando l'endpoint :analyze . Sostituire {classifierId} con il nome del classificatore creato.

curl -i -X POST "{endpoint}/contentunderstanding/analyzers/{classifierId}:analyze?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d '{
        "inputs": [
          {
            "url": "https://github.com/Azure-Samples/azure-ai-content-understanding-python/raw/refs/heads/main/data/mixed_financial_docs.pdf"
          }
        ]
      }'

La risposta include un'intestazione Operation-Location . Usare tale URL per recuperare i risultati dell'analisi.

Ottenere i risultati della classificazione

curl -i -X GET "{Operation-Location}" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Una risposta positiva restituisce "status": "Succeeded" con i risultati della classificazione nell'oggetto result. Ogni segmento include un category, un startPageNumber e un endPageNumber.

Riferimento: Risultati dell'analizzatore - Ottenere

Eseguire la pulizia

Eliminare il classificatore quando hai finito.

curl -i -X DELETE "{endpoint}/contentunderstanding/analyzers/{classifierId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Passaggio 2: Classificare e instradare con analizzatori personalizzati

Per andare oltre la classificazione di base, è possibile instradare ogni categoria a un analizzatore specifico per l'estrazione dei campi. Questo approccio combina la classificazione con l'estrazione dei dati in una singola pipeline: il classificatore identifica il tipo di documento e quindi lo indirizza all'analizzatore corretto, che estrae i campi personalizzati per tale categoria.

Content Understanding Studio
API REST

Per indirizzare correttamente i dati, creare analizzatori personalizzati per ogni categoria. Per altre informazioni sulla creazione di analizzatori personalizzati, vedere Creare e migliorare l'analizzatore personalizzato in Content Understanding Studio.

Creare analizzatori personalizzati prima: creare analizzatori personalizzati per ogni tipo di documento che vuoi instradare. Ad esempio, creare un analizzatore personalizzato per le applicazioni di prestito con uno schema di estrazione dei campi specifico per quel tipo di documento.
Creare o aggiornare le regole di routing: nella scheda Regole di routing selezionare Add category. Assegnare alla categoria un nome e una descrizione e selezionare un analizzatore per corrispondere a tale route. Lo strumento consente di visualizzare in anteprima lo schema per ogni analizzatore per assicurarsi di avere quello corretto.
Testare il flusso di lavoro di classificazione: selezionare Esegui analisi per visualizzare l'output delle regole sui dati. È possibile caricare dati di esempio aggiuntivi per i test per verificare le prestazioni con più regole diverse.
Compilare l'analizzatore di classificazione: quando si è soddisfatti dell'output, selezionare il pulsante Compila analizzatore nella parte superiore della pagina. Assegnare un nome all'analizzatore e selezionare Salva.
Usare l'analizzatore di classificazione: ora è disponibile un endpoint analizzatore che è possibile usare nella propria applicazione tramite l'API REST.

Creare un analizzatore personalizzato per una categoria

Creare prima di tutto un analizzatore personalizzato che estrae campi specifici di una categoria di documenti. Questo esempio definisce un analizzatore per applicazioni di prestiti con estrazione dei dati.

Creare un file JSON denominato loan-analyzer.json con il contenuto seguente:

{
  "baseAnalyzerId": "prebuilt-document",
  "description": "Loan application analyzer - extracts key information from loan applications",
  "config": {
    "returnDetails": true,
    "enableLayout": true,
    "enableFormula": false,
    "estimateFieldSourceAndConfidence": true
  },
  "fieldSchema": {
    "fields": {
      "ApplicationDate": {
        "type": "date",
        "method": "generate",
        "description": "The date when the loan application was submitted."
      },
      "ApplicantName": {
        "type": "string",
        "method": "generate",
        "description": "Full name of the loan applicant or company."
      },
      "LoanAmountRequested": {
        "type": "number",
        "method": "generate",
        "description": "The total loan amount requested by the applicant."
      },
      "LoanPurpose": {
        "type": "string",
        "method": "generate",
        "description": "The stated purpose or reason for the loan."
      },
      "Summary": {
        "type": "string",
        "method": "generate",
        "description": "A brief summary overview of the loan application details."
      }
    }
  },
  "models": {"completion": "gpt-4.1"}
}

Crea l'analizzatore personalizzato con una PUT richiesta:

curl -i -X PUT "{endpoint}/contentunderstanding/analyzers/{loanAnalyzerId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d @loan-analyzer.json

Eseguire il polling dell'URL Operation-Location dall'intestazione della risposta finché lo stato diventa "succeeded".

Riferimento: Gli analizzatori di contenuto: creare o sostituire

Definire il classificatore avanzato con il routing

Creare un classificatore che instrada ogni categoria a un analizzatore specifico. Usare il campo analyzerId in ogni categoria per puntare all'analizzatore che gestisce tale categoria.

Creare un file JSON denominato enhanced-classifier.json con il contenuto seguente. Sostituire {loanAnalyzerId} con l'ID analizzatore usato nel passaggio precedente.

{
  "baseAnalyzerId": "prebuilt-document",
  "description": "Enhanced classifier with custom loan analyzer",
  "config": {
    "returnDetails": true,
    "enableSegment": true,
    "contentCategories": {
      "Loan application": {
        "description": "Documents submitted by individuals or businesses to request funding, typically including personal or business details, financial history, loan amount, purpose, and supporting documentation.",
        "analyzerId": "{loanAnalyzerId}"
      },
      "Invoice": {
        "description": "Billing documents issued by sellers or service providers to request payment for goods or services, detailing items, prices, taxes, totals, and payment terms."
      },
      "Bank_Statement": {
        "description": "Official statements issued by banks that summarize account activity over a period, including deposits, withdrawals, fees, and balances."
      }
    }
  },
  "models": {"completion": "gpt-4.1"}
}

La differenza principale rispetto a un classificatore di base è la analyzerId proprietà nella Loan application categoria . Questo indica al servizio di indirizzare i documenti classificati come domande di prestito verso l'analizzatore personalizzato per l'estrazione dei campi. Le categorie senza analyzerId sono classificate ma non sono indirizzate a un analizzatore specifico.

Creare il classificatore avanzato

curl -i -X PUT "{endpoint}/contentunderstanding/analyzers/{enhancedClassifierId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d @enhanced-classifier.json

Eseguire il polling dell'URL Operation-Location dall'intestazione della risposta finché lo stato diventa "succeeded".

Analizzare un documento con il classificatore avanzato

curl -i -X POST "{endpoint}/contentunderstanding/analyzers/{enhancedClassifierId}:analyze?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d '{
        "inputs": [
          {
            "url": "https://github.com/Azure-Samples/azure-ai-content-understanding-python/raw/refs/heads/main/data/mixed_financial_docs.pdf"
          }
        ]
      }'

Ottenere risultati di classificazione avanzati

Usare l'URL Operation-Location dall'intestazione della risposta per recuperare i risultati.

curl -i -X GET "{Operation-Location}" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Una risposta con esito positivo restituisce "status": "Succeeded" risultati di classificazione insieme ai campi estratti. I documenti indirizzati all'analizzatore di prestiti personalizzato includono valori di campo estratti, ad esempio ApplicantName, LoanAmountRequested, e LoanPurpose nell'oggetto fields per tale segmento.

Riferimento: Risultati dell'analizzatore - Ottenere

Eseguire la pulizia

Eliminare gli analizzatori al termine.

curl -i -X DELETE "{endpoint}/contentunderstanding/analyzers/{enhancedClassifierId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}"

curl -i -X DELETE "{endpoint}/contentunderstanding/analyzers/{loanAnalyzerId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Suggerimento

Per un notebook Python end-to-end, vedere l'esempio di classificatore su GitHub.

Passaggi successivi

Scopri di più sulle migliori pratiche per Azure Content Understanding in Foundry Tools.
Seguire l'esercitazione per creare un analizzatore personalizzato usando le API REST.
Esplorare i concetti del classificatore per scenari avanzati.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-04-29