Blocco e vettorizzazione del contenuto con la competenza Azure Content Understanding

Questo articolo illustra come usare la competenza Azure Content Understanding per:

La competenza Azure Content Understanding restituisce uno o più blocchi per ogni documento. Ogni blocco contiene contenuto in formato Markdown, metadati della posizione (numeri di pagina e poligoni di delimitazione) e riferimenti facoltativi alle immagini estratte. Quando si imposta su chunkingProperties.methodsemantic, i blocchi seguono i limiti del paragrafo e dell'intestazione anziché gli intervalli di caratteri fissi. Quando si impostano modelName e modelDeployment, la skill richiama una distribuzione di completamento chat di Azure OpenAI per generare le descrizioni delle immagini incorporate. L'abilità unisce poi tali descrizioni nel contenuto del blocco.

Questo articolo utilizza i PDF di esempio del piano sanitario a scopo illustrativo. È possibile eseguire la stessa pipeline su qualsiasi origine dati supportata che espone i file in un formato supportato da Content Understanding.

Prerequisiti

• Un servizio Azure AI Search in qualsiasi area geografica supportata. Il servizio di ricerca stesso non è vincolato dall'area per questo scenario.

• Una risorsa Microsoft Foundry in un'area geografica supportata dalla funzionalità Azure Content Understanding. La descrizione dell'immagine e la suddivisione in blocchi vengono elaborate nell'area della risorsa Foundry.

• Una risorsa Microsoft Foundry collegata al set di competenze per la fatturazione. La funzionalità Azure Content Understanding viene fatturata in base ai prezzi di Azure Content Understanding.

• (Facoltativo) Una distribuzione Azure OpenAI di un modello di completamento chat (come gpt-4.1) nella stessa risorsa Foundry, utilizzata per generare descrizioni delle immagini. Obbligatorio solo se si vogliono descrizioni di immagini basate su intelligenza artificiale.

• Una distribuzione Azure OpenAI di un modello di embedding (ad esempio text-embedding-3-small), utilizzata dalla skill di embedding di Azure OpenAI per vettorizzare i segmenti.

• Contenitore Archiviazione BLOB di Azure con i file da indicizzare. Questo articolo utilizza una fonte di dati blob con l'impostazione dell'indicizzatore allowSkillsetToReadFileData (utilizzata per trasmettere il contenuto del file alla skill "Content Understanding").

Overview

L'articolo illustra la creazione di una pipeline di indicizzazione uno-a-molti. Ogni documento di origine produce più documenti di ricerca (uno per blocco):

1. L'indicizzatore legge ogni file da Archiviazione BLOB di Azure e passa il contenuto binario al set di competenze tramite /document/file_data.

2. L'abilità Azure Content Understanding utilizza la suddivisione semantica in blocchi (anteprima) per produrre text_sections. Quando modelName e modelDeployment sono impostati, genera anche descrizioni delle immagini incorporate generate dall'IA (anteprima) e le inserisce direttamente nel Markdown di ogni blocco.

3. L'abilità di embedding di Azure OpenAI viene eseguita una volta per ogni frammento e produce un vettore per il contenuto del frammento.

4. Una proiezione dell'indice scrive un documento di ricerca per ogni blocco nell'indice di destinazione, mappando il contenuto, i metadati di pagina, i riferimenti alle immagini e il vettore ai campi.

5. (Facoltativo) Un archivio di conoscenze proietta normalized_images su Archiviazione BLOB di Azure in modo che le app client possano recuperare le immagini estratte tramite URL.

Preparare i file di dati

La competenza Azure Content Understanding elabora il contenuto binario di ogni documento, quindi i file di origine devono essere in un formato supportato dalla competenza. Per l'elenco corrente, vedere i limiti del servizio Content Understanding. I formati supportati più comuni includono PDF, DOCX, XLSX, PPTX e molti formati di immagine.

Carica i tuoi file nell'origine dati supportata. È possibile usare il portale di Azure, le API REST o un Azure SDK per creare l'origine dati.

La seguente richiesta minimale crea l'origine dati utilizzata in questa guida passo passo.

POST {endpoint}/datasources?api-version=2026-08-01-preview

{
  "name": "my_blob_datasource",
  "type": "azureblob",
  "credentials": {
    "connectionString": "<your-blob-connection-string>"
  },
  "container": {
    "name": "my-container"
  }
}

Creare un indice per l'indicizzazione uno-a-molti

Ogni documento di ricerca corrisponde a un blocco prodotto dalla competenza Content Understanding. L'indice deve:

• Campo chiave (chunk_id).
• Campo padre che identifica il documento di origine da cui proviene il blocco (parent_id).
• Campi che archiviano il contenuto del blocco, i metadati della pagina e i riferimenti alle immagini.
• Un campo vettoriale per l'incorporamento dei blocchi.

La definizione di indice seguente corrisponde al set di competenze creato nella sezione successiva.

{
  "name": "my_content_understanding_index",
  "fields": [
    {
      "name": "chunk_id",
      "type": "Edm.String",
      "key": true,
      "searchable": true,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": true,
      "facetable": false,
      "analyzer": "keyword"
    },
    {
      "name": "parent_id",
      "type": "Edm.String",
      "searchable": false,
      "filterable": true,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "title",
      "type": "Edm.String",
      "searchable": true,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "chunk",
      "type": "Edm.String",
      "searchable": true,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "page_number_from",
      "type": "Edm.Int32",
      "searchable": false,
      "filterable": true,
      "retrievable": true,
      "stored": true,
      "sortable": true,
      "facetable": false
    },
    {
      "name": "page_number_to",
      "type": "Edm.Int32",
      "searchable": false,
      "filterable": true,
      "retrievable": true,
      "stored": true,
      "sortable": true,
      "facetable": false
    },
    {
      "name": "image_path",
      "type": "Edm.String",
      "searchable": false,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "text_vector",
      "type": "Collection(Edm.Single)",
      "searchable": true,
      "retrievable": true,
      "stored": false,
      "dimensions": 1536,
      "vectorSearchProfile": "profile"
    }
  ],
  "vectorSearch": {
    "profiles": [
      {
        "name": "profile",
        "algorithm": "algorithm"
      }
    ],
    "algorithms": [
      {
        "name": "algorithm",
        "kind": "hnsw"
      }
    ]
  }
}

Definire un set di competenze per la suddivisione in blocchi semantici (anteprima) e la vettorializzazione

Una volta creato l'indice di destinazione, definisci il set di competenze che produce i frammenti, i vettori e le mappature di proiezione che lo alimentano.

Il set di competenze ha due competenze:

• La competenza Azure Content Understanding suddivide ogni documento in blocchi. Impostando chunkingProperties.method su semantic, la skill rispetterà i confini dei paragrafi e dei titoli. L'impostazione di modelName e modelDeployment consente di usare descrizioni delle immagini generate dall'intelligenza artificiale (anteprima), che la skill incorpora direttamente nel contenuto del blocco prima della vettorializzazione. Per l'elenco dei modelli di completamento della chat supportati e altri dettagli sui parametri, vedere Parametri della competenza.

• L'abilità di embedding di Azure OpenAI genera un vettore per il contenuto di ciascun blocco.

Il set di competenze usa indexProjections per associare ogni blocco a un documento di ricerca distinto. Per altre informazioni, vedere Definire una proiezione di indice.

Prima di inviare la richiesta, sostituire <subdomain> con il sottodominio OpenAI Azure, <Azure OpenAI api key> con la chiave embedding-resource e <Foundry resource key> con la chiave per la risorsa Foundry collegata al set di competenze.

POST {endpoint}/skillsets?api-version=2026-08-01-preview

{
  "name": "my_content_understanding_skillset",
  "description": "Semantic chunking, image descriptions, and vectorization with the Azure Content Understanding skill",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Util.ContentUnderstandingSkill",
      "name": "my_content_understanding_skill",
      "context": "/document",
      "modelName": "gpt-4.1",
      "modelDeployment": "my-gpt-4-1-deployment",
      "chunkingProperties": {
        "method": "semantic",
        "unit": "tokens",
        "maximumLength": 500
      },
      "extractionOptions": ["images", "locationMetadata"],
      "inputs": [
        {
          "name": "file_data",
          "source": "/document/file_data"
        }
      ],
      "outputs": [
        {
          "name": "text_sections",
          "targetName": "text_sections"
        },
        {
          "name": "normalized_images",
          "targetName": "normalized_images"
        }
      ]
    },
    {
      "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
      "name": "my_azure_openai_embedding_skill",
      "context": "/document/text_sections/*",
      "inputs": [
        {
          "name": "text",
          "source": "/document/text_sections/*/content"
        }
      ],
      "outputs": [
        {
          "name": "embedding",
          "targetName": "text_vector"
        }
      ],
      "resourceUri": "https://<subdomain>.openai.azure.com",
      "deploymentId": "text-embedding-3-small",
      "modelName": "text-embedding-3-small",
      "apiKey": "<Azure OpenAI api key>"
    }
  ],
  "cognitiveServices": {
    "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
    "key": "<Foundry resource key>"
  },
  "indexProjections": {
    "selectors": [
      {
        "targetIndexName": "my_content_understanding_index",
        "parentKeyFieldName": "parent_id",
        "sourceContext": "/document/text_sections/*",
        "mappings": [
          {
            "name": "chunk",
            "source": "/document/text_sections/*/content"
          },
          {
            "name": "text_vector",
            "source": "/document/text_sections/*/text_vector"
          },
          {
            "name": "page_number_from",
            "source": "/document/text_sections/*/locationMetadata/pageNumberFrom"
          },
          {
            "name": "page_number_to",
            "source": "/document/text_sections/*/locationMetadata/pageNumberTo"
          },
          {
            "name": "image_path",
            "source": "/document/text_sections/*/imagePath"
          },
          {
            "name": "title",
            "source": "/document/metadata_storage_name"
          }
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

Per il riferimento completo dei parametri, i valori supportati e le regole di convalida per la skill Content Understanding, vedere skill Azure Content Understanding.

Configurare ed eseguire l'indicizzatore

Crea ed esegui un indicizzatore che legga dalla tua fonte di dati, richiami il set di competenze e inserisca i blocchi nell'indice. Impostare allowSkillsetToReadFileData su true in modo che la funzionalità Content Understanding riceva il contenuto del file e impostare parsingMode su default.

Non è necessario outputFieldMappings in questo scenario. Il blocco indexProjections dello skillset mappa già ogni segmento ai campi dell'indice di destinazione.

POST {endpoint}/indexers?api-version=2026-08-01-preview

{
  "name": "my_content_understanding_indexer",
  "dataSourceName": "my_blob_datasource",
  "targetIndexName": "my_content_understanding_index",
  "skillsetName": "my_content_understanding_skillset",
  "parameters": {
    "batchSize": 1,
    "configuration": {
      "dataToExtract": "contentAndMetadata",
      "parsingMode": "default",
      "allowSkillsetToReadFileData": true
    }
  },
  "fieldMappings": [],
  "outputFieldMappings": []
}

Quando l'indicizzatore viene eseguito, la competenza Content Understanding usa la suddivisione in blocchi semantici (anteprima), facoltativamente genera descrizioni di immagini basate su intelligenza artificiale (anteprima) e scrive un documento di ricerca per ogni blocco nell'indice.

Controllare lo stato dell'indicizzatore

Prima di eseguire una query, verificare che l'esecuzione dell'indicizzatore sia stata completata:

GET {endpoint}/indexers/my_content_understanding_indexer/status?api-version=2026-08-01-preview

Verificare che lastResult.status sia success. Se è pari a transientFailure e itemsProcessed è superiore a 0, l'esecuzione è considerata un successo parziale ed è comunque possibile interrogare i blocchi popolati. Per altre informazioni, vedere Monitorare lo stato dell'indicizzatore.

Verificare i risultati

Eseguire una query sull'indice per verificare che i blocchi contengano il contenuto previsto e che la ricerca vettoriale funzioni come previsto. Usare Esplora ricerche o qualsiasi strumento che invia richieste HTTP.

La richiesta seguente esegue una query ibrida (ricerca di parole chiave su chunk e una query vettoriale su text_vector) per confermare che siano stati popolati sia il testo suddiviso in blocchi sia gli embedding.

POST /indexes/my_content_understanding_index/docs/search?api-version=2026-08-01-preview
{
  "search": "copay for in-network providers",
  "count": true,
  "searchMode": "all",
  "vectorQueries": [
    {
      "kind": "text",
      "text": "copay for in-network providers",
      "fields": "text_vector"
    }
  ],
  "select": "chunk, title, page_number_from, page_number_to, image_path"
}

Una risposta con esito positivo è simile alla seguente (tagliata per brevità):

{
  "@odata.count": 2,
  "value": [
    {
      "@search.score": 0.0317,
      "chunk": "## Cost sharing\n\nFor in-network providers, the copay is $20 per visit...\n\n![Chart: Copay comparison across plans](figures/3)",
      "title": "Northwind_Standard_Benefits_Details.pdf",
      "page_number_from": 4,
      "page_number_to": 4,
      "image_path": "figures/3"
    },
    {
      "@search.score": 0.0289,
      "chunk": "### Out-of-network providers\n\nWhen you visit a provider that isn't in the Northwind network, the copay is $40 per visit...",
      "title": "Northwind_Standard_Benefits_Details.pdf",
      "page_number_from": 5,
      "page_number_to": 6,
      "image_path": null
    }
  ]
}

La risposta include:

• chunk: contenuto Markdown di ogni blocco. Quando si configura modelName e modelDeployment, le descrizioni delle immagini generate dall'intelligenza artificiale (anteprima) vengono visualizzate inline all'interno di Markdown.
• page_number_from e page_number_to: intervallo di pagine che ha prodotto il blocco.
• image_path: percorso dell'immagine estratta con il blocco o, quando un blocco si estende su più immagini, un elenco di percorsi separati da punto e virgola. La forma esatta dipende dal fatto che sia stata configurata o meno una proiezione del file dell'archivio di conoscenza. Senza una proiezione di file, il percorso è la forma breve illustrata nell'esempio (figures/3). In una proiezione di file, il percorso è il percorso relativo dell'immagine nell'archivio delle conoscenze. Per rendere queste immagini disponibili alle app client, vedere (Facoltativo) Immagini del progetto per il recupero.

(Facoltativo) Immagini del progetto per il recupero

I valori image_path memorizzati nell'indice sono puntatori all'interno dell'albero di arricchimento della skill, non URL recuperabili direttamente. Per recuperare le immagini, proietta normalized_images su Archiviazione BLOB di Azure utilizzando un archivio di conoscenze, quindi genera un URL del blob per ciascun blocco.

Questo passaggio è facoltativo. Aggiungerlo solo se l'app client deve visualizzare o scaricare le immagini estratte.

Aggiungere la proprietà seguente al payload del set di competenze della sezione precedente. La richiesta dell'insieme di competenze utilizza api-version=2026-08-01-preview.

"knowledgeStore": {
  "storageConnectionString": "<your-azure-storage-connection-string>",
  "projections": [
    {
      "files": [
        {
          "storageContainer": "extracted-images",
          "source": "/document/normalized_images/*"
        }
      ],
      "tables": [],
      "objects": []
    }
  ]
}

Dopo l'esecuzione dell'indicizzatore, ogni blob nel contenitore extracted-images corrisponde a un elemento normalized_images. L'URL del BLOB ha il formato https://<storage-account>.blob.core.windows.net/<container>/<imagePath>, dove <imagePath> corrisponde al valore archiviato nel image_path campo .

Per lo schema completo, inclusi i tipi di proiezione aggiuntivi (tables e objects) e le opzioni di autenticazione, vedere Knowledge store "projections" in Azure AI Search.

Pulire le risorse

Quando hai finito, elimina l'indicizzatore, il set di competenze e l'indice per evitare ulteriori addebiti per Content Understanding e Azure OpenAI. I file di origine in Archiviazione BLOB di Azure e la risorsa Foundry rimangono finché non vengono eliminati.

Risoluzione dei problemi

Se l'indicizzatore ha esito negativo o restituisce risultati imprevisti, controllare le cause comuni seguenti.

La convalida delle competenze non va a buon fine con codice 400

L'abilità restituisce l'errore 400 Skill validation failed quando le combinazioni di parametri sono incompatibili. Cause comuni:

• modelName è impostato senza modelDeployment, o viceversa. Entrambi devono essere impostati insieme.
• method è semantic (anteprima) ed overlapLength è maggiore di 0. Impostare overlapLength su 0 o ometterlo.
• method e unit non sono una coppia supportata. Usare fixedSize con characters o semantic con tokens.

Autorizzazione non riuscita per la risorsa Foundry

Se l'abilità restituisce 401 o 403 quando chiama la risorsa Foundry, verificare che:

• Il blocco cognitiveServices nello skillset fa riferimento alla risorsa Foundry corretta.
• L'identità usata dal servizio di ricerca ha il ruolo necessario nella risorsa Foundry. Per le configurazioni con identità gestita, vedere Collegare una risorsa fatturabile a un set di competenze in Azure AI Search.

text_sections è vuoto

Se i documenti indicizzati non hanno blocchi, verificare che:

• Il formato di file è supportato. Per l'elenco, vedere Formati di file supportati.
• La risorsa Foundry si trova in un'area supportata.
• I PDF protetti da password vengono sbloccati prima dell'indicizzazione.

Descrizioni delle immagini (anteprima) mancanti

Se i blocchi non includono descrizioni di immagini inline, verificare che:

• Sia modelName che modelDeployment sono inclusi nel set di competenze.
• Il modello di completamento della chat in modelName viene distribuito nella stessa risorsa Foundry a cui fa riferimento il set di competenze.
• L'implementazione dispone di una quota TPM o RPM sufficiente per il volume dei tuoi documenti.

L'indicizzatore va in timeout con documenti di grandi dimensioni

Content Understanding applica un timeout di elaborazione per documento. Se i FILE PDF di grandi dimensioni hanno esito negativo:

• Suddividere il documento di origine in file più piccoli prima dell'indicizzazione.
• Ridurre batchSize in 1 modo che ogni documento venga elaborato in modo indipendente.

Per i limiti completi relativi ai dati della skill Azure Content Understanding, vedere Limiti dei dati.

Contenuti correlati

• Abilità Azure Content Understanding
• Competenza di incorporamento di OpenAI di Azure
• Ricerca multimodale in Azure AI Search
• Definire una proiezione di indice per l'indicizzazione padre-figlio
• Suddividi documenti di grandi dimensioni per RAG e ricerca vettoriale