Fragmente e vetorize conteúdo com a competência Azure Content Understanding

Neste artigo, aprende a usar a competência Azure Compreensão de Conteúdo para:

A capacidade Azure Content Understanding devolve um ou mais segmentos por documento. Cada bloco contém conteúdo formatado em Markdown, metadados de localização (números de página e polígonos delimitadores) e referências opcionais a imagens extraídas. Quando defines chunkingProperties.method para semantic, os blocos seguem limites de parágrafo e cabeçalho em vez de intervalos fixos de caracteres. Quando defines modelName e modelDeployment, a habilidade chama uma implementação Azure OpenAI chat-completion para gerar descrições de imagens incorporadas. A competência incorpora então essas descrições no conteúdo do segmento.

Este artigo utiliza os PDFs exemplo de planos de saúde para ilustração. Pode executar o mesmo pipeline contra qualquer fonte de dados suportada que exponha ficheiros num formato suportado pelo 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 está limitado por região para este cenário.

• Um recurso Microsoft Foundry numa região apoiado pela competência Azure Content Understanding. A descrição da imagem e a divisão em blocos são processadas na região do recurso Foundry.

• Um recurso do Microsoft Foundry associado ao conjunto de competências para faturação. A função Azure Content Understanding é cobrada de acordo com os preços do Azure Content Understanding.

• (Opcional) Uma implementação Azure OpenAI de um modelo de conclusão de chat (como gpt-4.1) no mesmo recurso Foundry, usado para gerar descrições de imagens. Só é obrigatório se quiseres descrições de imagens baseadas em IA.

• Uma implementação do Azure OpenAI de um modelo de incorporação (como text-embedding-3-small), utilizada pela competência Azure OpenAI Embedding para vetorizar segmentos.

• Um contentor Armazenamento de Blobs do Azure com os ficheiros que queres indexar. Este artigo utiliza uma fonte de dados blob com a allowSkillsetToReadFileData definição do indexador (usada para passar conteúdo do ficheiro à competência de Compreensão de Conteúdo).

Overview

O artigo implementa um processo de indexação um-para-muitos. Cada documento fonte produz múltiplos documentos de pesquisa (um por bloco):

1. O indexador lê cada ficheiro a partir de Armazenamento de Blobs do Azure e passa o conteúdo binário para o conjunto de competências através de /document/file_data.

2. A habilidade de Compreensão de Conteúdo do Azure utiliza fragmentação semântica (pré-visualização) para produzir text_sections. Quando modelName e modelDeployment estão definidos, também produz descrições geradas por IA (pré-visualização) de imagens embutidas e integra-as no Markdown de cada bloco.

3. A habilidade Azure OpenAI Embedding executa-se uma vez por bloco e produz um vetor para o conteúdo do bloco.

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

5. (Opcional) Um knowledge store projeta normalized_images para Armazenamento de Blobs do Azure para que as aplicações clientes possam recuperar as imagens extraídas por URL.

Preparar arquivos de dados

A competência Azure Content Understanding processa o conteúdo binário de cada documento, pelo que os ficheiros fonte devem estar num formato que a competência suporte. Para a lista atual, consulte os limites do serviço de Compreensão de Conteúdo. Os formatos mais comuns suportados incluem PDF, DOCX, XLSX, PPTX e muitos formatos de imagem.

Carregue os seus ficheiros para a fonte de dados suportada. Pode usar o portal Azure, APIs REST ou um SDK do Azure para criar a fonte de dados.

O pedido mínimo seguinte cria a fonte de dados utilizada ao longo deste walkthrough.

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 uma indexação de um-para-muitos

Cada documento de pesquisa corresponde a um bloco produzido pela competência de Compreensão de Conteúdo. O índice precisa:

• Um campo de chave (chunk_id).
• Um campo pai que identifica de que documento fonte veio o bloco (parent_id).
• Campos que armazenam o conteúdo do bloco, metadados da página e referências de imagens.
• Um campo vetorial para a imersão de blocos.

A definição de índice seguinte corresponde ao conjunto de competências que cria na secção seguinte.

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

Defina um conjunto de competências para segmentação semântica (versão preliminar) e vetorização

Com o índice de destino definido, defina o conjunto de competências que produz os segmentos, vetores e mapeamentos de projeção que o alimentam.

O conjunto de competências tem duas competências:

• A capacidade Azure Content Understanding segmenta cada documento. Definir chunkingProperties.method para semantic faz com que a habilidade respeite os limites de parágrafos e títulos. Definir modelName e modelDeployment ativa descrições de imagens geradas por IA (pré-visualização), que a aptidão insere diretamente no conteúdo do bloco antes da vetorização. Para a lista de modelos de conclusão de chat suportados e outros detalhes de parâmetros, consulte Parâmetros de Competência.

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

O conjunto de competências utiliza indexProjections para mapear cada segmento para um documento de pesquisa separado. Para obter mais informações, consulte Definir uma projeção de índice.

Antes de enviares o pedido, substitui <subdomain> pelo teu subdomínio Azure OpenAI, <Azure OpenAI api key> pela chave de embedding-resource e <Foundry resource key> pela chave para o recurso Foundry associado ao conjunto de competências.

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 a referência completa dos parâmetros, valores suportados e regras de validação para a competência de Compreensão de Conteúdo, consulte Azure Competência de Compreensão de Conteúdo.

Configurar e executar o indexador

Crie e execute um indexador que leia da sua fonte de dados, chame o conjunto de competências e projete blocos no índice. Defina allowSkillsetToReadFileData para true que a habilidade de Compreensão de Conteúdo receba o conteúdo do ficheiro, e defina parsingMode para default.

Neste cenário, não é preciso outputFieldMappings . O bloco indexProjections no conjunto de competências já mapeia cada segmento 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 competência Content Understanding utiliza fragmentação semântica (em pré-visualização), gera opcionalmente descrições de imagens baseadas em IA (em pré-visualização) e grava um documento de pesquisa por fragmento no índice.

Verificar o estado do indexador

Antes de consultares, confirma que a execução do indexador terminou:

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 é parcialmente bem-sucedida, e ainda podes consultar os chunks preenchidos. Para mais informações, consulte Monitorizar o estado do indexador.

Verificar resultados

Consulta o índice para verificar se os chunks contêm o conteúdo esperado e que a pesquisa vetorial funciona como esperado. Usa o Explorador de Pesquisa ou qualquer ferramenta que envie pedidos HTTP.

O pedido seguinte executa uma consulta híbrida (pesquisa por palavras-chave em chunk e consulta vetorial contra text_vector) para confirmar que tanto o texto em blocos como as embeddings estão preenchidos.

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 assemelha-se ao seguinte (cortado para 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 Markdown de cada bloco. Quando configuras modelName e modelDeployment, as descrições de imagens geradas por IA (pré-visualização) aparecem em linha dentro do Markdown.
• page_number_from e page_number_to: O intervalo de páginas que originou o fragmento.
• image_path: O caminho para a imagem extraído com o bloco ou, quando um bloco abrange várias imagens, uma lista de caminhos separada por ponto e vírgula. A forma exata depende ou não de uma projeção de ficheiro de armazenamento de conhecimento estar configurada. Sem uma projeção de ficheiro, o caminho é a forma curta mostrada no exemplo (figures/3). Numa projeção de ficheiro, o caminho corresponde ao caminho relativo da imagem no arquivo de conhecimento. Para disponibilizar estas imagens às aplicações cliente, consulte (Opcional) Imagens do projeto para obtenção.

(Opcional) Imagens do Project para recuperação

Os image_path valores armazenados no índice são apontadores para a árvore de enriquecimento da competência, não URLs diretamente recuperáveis. Para recuperar imagens, projete normalized_images para o Armazenamento de Blobs do Azure utilizando um arquivo de conhecimento e, em seguida, derive o URL do blob juntamente com cada fragmento.

Esta etapa é opcional. Adiciona-a apenas se a tua aplicação cliente precisar de mostrar ou descarregar as imagens extraídas.

Adicione a seguinte propriedade ao conjunto de competências da secção anterior. O pedido de conjunto de aptidões utiliza api-version=2026-08-01-preview.

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

Após a execução do indexador, cada blob no extracted-images contentor corresponde a um normalized_images elemento. A URL do blob tem o formulário https://<storage-account>.blob.core.windows.net/<container>/<imagePath>, onde <imagePath> corresponde ao valor armazenado no image_path campo.

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

Limpeza de recursos

Quando terminares, elimina o indexador, o conjunto de competências e o índice para deixares de incorrer em custos do Content Understanding e do Azure OpenAI. Os ficheiros de origem no Armazenamento de Blobs do Azure e no próprio recurso do Foundry permanecem até os eliminar.

Troubleshooting

Se o indexador falhar ou devolver resultados inesperados, verifique as seguintes causas comuns.

A validação do conjunto de competências falha com o erro 400

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

• modelName está definido sem modelDeployment, ou vice-versa. Ambos devem ser definidos em conjunto.
• method é semantic (pré-visualização) e overlapLength é maior que 0. Defina overlapLength como 0 ou omita-o.
• method e unit não formam um par suportado. Usar fixedSize com characters ou semantic com tokens.

A autorização falha no recurso Foundry

Se a competência devolver um erro 401 ou 403 ao chamar o recurso Foundry, verifique se:

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

text_sections é vazio

Se os documentos indexados não tiverem blocos, verifique que:

• O formato de ficheiro é suportado. Para a lista, veja Formatos de ficheiro suportados.
• O recurso Foundry encontra-se numa região suportada.
• Os PDFs protegidos por palavra-passe são desbloqueados antes de serem indexados.

As descrições das imagens (pré-visualização) estão em falta

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

• Tanto modelName como modelDeployment estão definidos no conjunto de competências.
• O modelo de conclusão de conversa em modelName está implementado no mesmo recurso do Foundry ao qual o conjunto de competências faz referência.
• A implementação tem uma quota suficiente de TPM ou RPM para o volume do seu documento.

O indexador expira ao processar documentos grandes

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

• Divide o documento de origem em ficheiros mais pequenos antes de indexar.
• Reduza batchSize para 1 que cada documento seja processado de forma independente.

Para os limites completos de dados da competência Azure Compreensão de Conteúdo, veja Limites de dados.

Conteúdo relacionado

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