Agrupar e vetorizar conteúdo com a habilidade Azure Content Understanding

Neste artigo, você aprenderá a usar a habilidade Azure Content Understanding para:

A habilidade Azure Content Understanding retorna uma ou mais partes por documento. Cada parte contém conteúdo formatado por Markdown, metadados de localização (números de página e polígonos delimitados) e referências opcionais a imagens extraídas. Quando você define chunkingProperties.method como semantic, os blocos seguem os limites de parágrafo e título em vez de intervalos de caractere fixo. Quando você define modelName e modelDeployment, a habilidade chama uma implantação de conclusão de chat OpenAI do Azure para gerar descrições de imagens inseridas. Em seguida, a habilidade combina essas descrições ao conteúdo do segmento.

Este artigo usa os PDFs de exemplo do plano de saúde como ilustração. Você pode executar o mesmo pipeline em qualquer fonte de dados com suporte que exponha arquivos em um formato compatível com o Content Understanding.

Pré-requisitos

• Um serviço Pesquisa de IA do Azure  em qualquer região suportada. O serviço de pesquisa em si não é restrito à região para esse cenário.

• Um recurso do Microsoft Foundry em uma região com suporte para a habilidade Azure Content Understanding. A descrição da imagem e o agrupamento são processados na região do recurso do Foundry.

• Um recurso do Microsoft Foundry vinculado ao conjunto de habilidades para cobrança. A habilidade Azure Content Understanding é cobrada de acordo com os preços do Azure Content Understanding.

• (Opcional) Uma implantação do OpenAI do Azure de um modelo de conclusão de chat (como gpt-4.1) no mesmo recurso do Foundry, usada para gerar descrições de imagens. Necessário somente se você quiser descrições de imagem baseadas em IA.

• Uma implantação do OpenAI do Azure de um modelo de inserção (como text-embedding-3-small), usado pela habilidade Inserção do OpenAI do Azure para vetorizar partes.

• Um contêiner Armazenamento de Blobs do Azure com os arquivos que você deseja indexar. Este artigo usa uma fonte de dados de blob com a configuração do indexador allowSkillsetToReadFileData (usada para passar o conteúdo do arquivo para a habilidade de Compreensão de Conteúdo).

Overview

O artigo cria um pipeline de indexação de um para muitos. Cada documento de origem produz vários documentos de busca (um por bloco):

1. O indexador lê cada arquivo do Armazenamento de Blobs do Azure e passa o conteúdo binário para o conjunto de habilidades por meio de /document/file_data.

2. A habilidade Azure Content Understanding usa a segmentação semântica (versão prévia) para produzir text_sections. Quando modelName e modelDeployment são definidos, ele também produz descrições geradas por IA (versão prévia) de imagens inseridas e as inlineia no Markdown de cada parte.

3. A Azure OpenAI Embedding skill é executada uma vez para cada bloco e produz um vetor para o conteúdo do bloco.

4. Uma projeção de índice grava um documento de busca para cada bloco no índice de destino, mapeando o conteúdo, os metadados da página, as referências de imagem e o vetor para campos.

5. (Opcional) Um armazenamento de conhecimento projeta normalized_images para o Armazenamento de Blobs do Azure para que os aplicativos clientes possam recuperar as imagens extraídas por meio da URL.

Preparar arquivos de dados

A habilidade Azure Content Understanding processa o conteúdo binário de cada documento, portanto, os arquivos de origem devem estar em um formato compatível com a habilidade. Para obter a lista atual, consulte os limites do serviço de Compreensão de Conteúdo. Formatos comuns com suporte incluem PDF, DOCX, XLSX, PPTX e muitos formatos de imagem.

Carregue seus arquivos para a fonte de dados compatível. Você pode usar o portal Azure, AS APIs REST ou um SDK do Azure para criar a fonte de dados.

A solicitação mínima a seguir cria a fonte de dados usada ao longo deste passo a 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"
  }
}

Criar um índice para indexação um para muitos

Cada documento de pesquisa corresponde a uma parte produzida pela habilidade de Compreensão de Conteúdo. O índice precisa:

• Um campo de chave (chunk_id).
• Um campo pai que identifica de qual documento de origem a parte veio (parent_id).
• Campos que armazenam o conteúdo da parte, os metadados de página e as referências de imagem.
• Um campo de vetor para a inserção de partes.

A definição de índice a seguir corresponde ao conjunto de habilidades que você cria na próxima seção.

{
  "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"
      }
    ]
  }
}

Definir um conjunto de habilidades para agrupamento semântico (versão prévia) e vetorização

Com o índice de destino definido, defina o conjunto de habilidades que produz os fragmentos, vetores e mapeamentos de projeção que o alimentam.

O conjunto de competências tem duas habilidades:

• A habilidade Azure Content Understanding agrupa cada documento. Definir chunkingProperties.method como semantic faz com que a habilidade respeite os limites entre parágrafos e cabeçalhos. Definir modelName e modelDeployment habilita descrições de imagem geradas por IA (visualização prévia), que a habilidade insere diretamente no conteúdo do bloco antes da vetorização. Para obter a lista de modelos de conclusão de chat compatíveis e outros detalhes dos parâmetros, consulte Skill parameters.

• A habilidade Azure OpenAI Embedding gera um vetor para o conteúdo de cada bloco.

O conjunto de habilidades usa indexProjections para mapear cada bloco para um documento de busca separado. Para obter mais informações, veja Definir uma projeção de índice.

Antes de enviar a solicitação, substitua <subdomain> pelo subdomínio Azure OpenAI, <Azure OpenAI api key> pela chave de recurso de inserção e <Foundry resource key> com a chave do recurso Foundry anexada ao conjunto de habilidades.

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"
    }
  }
}

Para obter a referência completa do parâmetro, os valores com suporte e as regras de validação para a habilidade de Compreensão de Conteúdo, consulte Azure habilidade de Compreensão de Conteúdo.

Configurar e executar o indexador

Crie e execute um indexador que lê da sua fonte de dados, chama o conjunto de habilidades e projeta os fragmentos no índice. Defina allowSkillsetToReadFileData como true para que a habilidade de Compreensão de Conteúdo receba o conteúdo do arquivo e defina parsingMode como default.

Você não precisa de outputFieldMappings neste cenário. O bloco indexProjections no conjunto de habilidades já mapeia cada bloco para os campos do índice de destino.

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 o indexador é executado, a habilidade Content Understanding usa segmentação semântica (versão prévia), opcionalmente gera descrições de imagens com IA (versão prévia) e grava um documento de pesquisa para cada segmento no índice.

Verificar o status do indexador

Antes de consultar, confirme se a execução do indexador foi concluída:

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

Verifique se lastResult.status é success. Se for transientFailure com itemsProcessed maior que 0, a execução será um sucesso parcial e você ainda poderá consultar as partes preenchidas. Para obter mais informações, consulte Monitorar o status do indexador.

Verificar os resultados

Consulte o índice para verificar se as partes contêm o conteúdo esperado e que a pesquisa de vetor funciona conforme o esperado. Use o Gerenciador de Pesquisa ou qualquer ferramenta que envie solicitações HTTP.

A solicitação a seguir executa uma consulta híbrida (pesquisa por palavra-chave em chunk e uma consulta vetorial em text_vector) para confirmar que tanto o texto segmentado quanto os embeddings foram populados.

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"
}

Uma resposta bem-sucedida é semelhante à seguinte (cortada para fins de brevidade):

{
  "@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
    }
  ]
}

A resposta inclui:

• chunk: O conteúdo em Markdown de cada segmento. Quando você configura modelName e modelDeploymentas descrições de imagem geradas por IA (versão prévia) aparecem embutidas no Markdown.
• page_number_from e page_number_to: o intervalo de páginas que gerou o bloco.
• image_path: O caminho para a imagem extraída com o segmento ou, quando um segmento abrange várias imagens, uma lista de caminhos separados por ponto e vírgula. A forma exata depende se uma projeção de arquivo do repositório de conhecimento está configurada. Sem uma projeção de arquivo, o caminho é o formulário curto mostrado no exemplo (figures/3). Em uma projeção de arquivo, o caminho corresponde ao caminho relativo da imagem no repositório de conhecimento. Para disponibilizar essas imagens para aplicativos cliente, consulte (Opcional) Imagens do projeto para recuperação.

(Opcional) Imagens do projeto para recuperação

Os valores image_path armazenados no índice são ponteiros para a árvore de enriquecimento da habilidade, não URLs recuperáveis diretamente. Para recuperar imagens, projete normalized_images no Armazenamento de Blobs do Azure usando um knowledge store e, em seguida, obtenha uma URL de blob junto com cada bloco.

Esta etapa é opcional. Adicione-o somente se o aplicativo cliente precisar exibir ou baixar as imagens extraídas.

Adicione a propriedade a seguir ao conteúdo do conjunto de habilidades da seção anterior. A solicitação do conjunto de habilidades usa api-version=2026-08-01-preview.

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

Depois que o indexador é executado, cada blob no extracted-images contêiner corresponde a um normalized_images elemento. A URL do blob tem o formulário https://<storage-account>.blob.core.windows.net/<container>/<imagePath>, em que <imagePath> corresponde ao valor armazenado no image_path campo.

Para ver o esquema completo, incluindo tipos de projeção adicionais (tables e objects) e opções de autenticação, consulte "Projeções" do Knowledge store no Pesquisa de IA do Azure .

Limpar os recursos

Quando terminar, exclua o indexador, o conjunto de habilidades e o índice para evitar cobranças da Compreensão de Conteúdo e do OpenAI do Azure. Os arquivos de origem no Armazenamento de Blobs do Azure e no próprio recurso foundry permanecem até que você os exclua.

Solução de problemas

Se o indexador falhar ou retornar resultados inesperados, verifique as causas comuns a seguir.

A validação do conjunto de habilidades falha com erro 400

A habilidade retorna um 400 Skill validation failed erro quando as combinações de parâmetros entram em conflito. Causas comuns:

• modelName é definido sem modelDeployment, ou vice-versa. Ambos devem ser definidos juntos.
• method é semantic (versão prévia) e overlapLength é maior que 0. overlapLength Defina 0 ou omita-o.
• method e unit não são um par com suporte. Use fixedSize com characters ou semantic com tokens.

A autorização falha no recurso Foundry

Se a habilidade retornar 401 ou 403 ao chamar o recurso Foundry, verifique se:

• O bloco cognitiveServices no conjunto de habilidades aponta para o recurso Foundry correto.
• A identidade usada pelo serviço de pesquisa tem a função necessária no recurso Foundry. Para configurações de identidade gerenciada, consulte Anexe um recurso faturável a um conjunto de habilidades em Pesquisa de IA do Azure .

text_sections está vazio

Se os documentos indexados não tiverem partes, verifique se:

• Há suporte para o formato de arquivo. Para obter a lista, consulte formatos de arquivo com suporte.
• O recurso Foundry está em uma região com suporte.
• PDFs protegidos por senha são desbloqueados antes da indexação.

Descrições de imagem (versão prévia) estão ausentes

Se os blocos não incluírem descrições inline de imagens, verifique se:

• Ambos modelName e modelDeployment estão definidos no conjunto de habilidades.
• O modelo de conclusão de chat em modelName está implantado no mesmo recurso do Foundry referenciado no conjunto de habilidades.
• A implantação tem cota de TPM ou RPM suficiente para o volume do documento.

O indexador atinge o tempo limite em documentos grandes

O Content Understanding impõe um tempo limite de processamento por documento. Se PDFs grandes falharem:

• Divida o documento de origem em arquivos menores antes da indexação.
• Reduza batchSize para que 1 cada documento seja processado de forma independente.

Para obter os limites de dados completos da habilidade Azure Content Understanding, consulte Data limits.

Conteúdo relacionado

• habilidade de Compreensão de Conteúdo do Azure
• Habilidade de incorporação do Azure OpenAI
• Pesquisa multimodal no Pesquisa de IA do Azure 
• Definir uma projeção de índice para indexação pai-filho
• Dividir documentos grandes em blocos para RAG e busca vetorial