Tutorial: Vetorize a partir de um layout estruturado de documento

O Azure AI Search pode extrair e indexar texto e imagens de documentos PDF armazenados no Armazenamento de Blobs do Azure. Este tutorial mostra como criar um pipeline de indexação multimodal que agrupa dados com base na estrutura do documento e usa inserções multimodal para vetorizar texto e imagens do mesmo documento. As imagens cortadas são armazenadas em um repositório de conhecimento e o conteúdo de texto e visual são vetorizados e ingeridos em um índice pesquisável. O agrupamento é baseado no modelo de layout do Azure Document Intelligence in Foundry Tools que reconhece a estrutura de documentos.

Neste tutorial, você usará:

Um documento PDF de 36 páginas que combina conteúdo visual avançado, como gráficos, infográficos e páginas digitalizadas, com texto tradicional.
Um indexador e um conjunto de habilidades para criar um pipeline de indexação que inclui o enriquecimento de IA por meio de habilidades.
A habilidade Layout de Documento para extrair texto e imagens normalizadas com locationMetadata de vários documentos, como números de página ou regiões delimitadoras.
A habilidade de inserções multimodal do Azure Vision para vetorizar texto e imagens.
Um índice de pesquisa configurado para armazenar o conteúdo de texto e imagem extraídos. Algum conteúdo é vetorizado para pesquisa de similaridade baseada em vetor.

Prerequisites

Recurso do Microsoft Foundry. Esse recurso fornece acesso ao modelo de inserção multimodal do Azure Vision e ao modelo de Layout de Inteligência de Documento do Azure usado pelas habilidades neste tutorial. Você deve usar um recurso do Foundry para acessar o conjunto de habilidades a esses recursos.
Pesquisa de IA do Azure. Configure seu serviço de pesquisa para controle de acesso baseado em função e uma identidade gerenciada. Seu serviço deve estar na camada Básica ou superior. Este tutorial não tem suporte na camada Gratuita.
Armazenamento do Azure, usado para armazenar dados de exemplo e para criar um repositório de conhecimento.
Visual Studio Code com um cliente REST.

Limitations

A habilidade de layout de documento tem disponibilidade regional limitada. Ao criar o recurso Foundry, escolha uma região que forneça inserções multimodal. Para obter uma lista de regiões suportadas pela habilidade de layout do documento, consulte regiões suportadas pela habilidade de layout do documento.
A habilidade de inserções multimodal do Azure Vision também tem disponibilidade regional limitada. Para obter uma lista atualizada de regiões que fornecem incorporações multimodais, consulte a documentação do Azure Vision.

Preparar dados

As instruções a seguir se aplicam ao Armazenamento do Azure, que fornece os dados de exemplo e também hospeda o repositório de conhecimento. Uma identidade do serviço de pesquisa precisa de acesso de leitura ao Armazenamento do Azure para recuperar os dados de exemplo e precisa de acesso para gravação para criar o repositório de conhecimento. O serviço de pesquisa cria o contêiner para imagens cortadas durante o processamento do conjunto de habilidades, usando o nome fornecido em uma variável de ambiente.

Baixe o seguinte pdf de exemplo: sustainable-ai-pdf
No Armazenamento do Azure, crie um novo contêiner chamado sustainable-ai-pdf.
Carregue o arquivo de dados de exemplo.
Crie atribuições de função e especifique uma identidade gerenciada em uma cadeia de conexão:
1. Atribua o Leitor de Dados do Blob de Armazenamento para a recuperação de dados pelo indexador. Atribua Colaborador de Dados de Blob de Armazenamento e Colaborador de Dados de Tabela de Armazenamento para criar e carregar o repositório de conhecimento. Você pode usar uma identidade gerenciada atribuída pelo sistema ou uma identidade gerenciada atribuída pelo usuário para sua atribuição de função de serviço de pesquisa.
2. Para conexões feitas usando uma identidade gerenciada atribuída pelo sistema, obtenha uma cadeia de conexão que contenha um ResourceId, sem chave de conta ou senha. O ResourceId deve incluir a ID da assinatura da conta de armazenamento, o grupo de recursos da conta de armazenamento e o nome da conta de armazenamento. A cadeia de conexão é semelhante ao seguinte exemplo:
```
"credentials" : { 
    "connectionString" : "ResourceId=/subscriptions/00000000-0000-0000-0000-00000000/resourceGroups/MY-DEMO-RESOURCE-GROUP/providers/Microsoft.Storage/storageAccounts/MY-DEMO-STORAGE-ACCOUNT/;" 
}
```
3. Para conexões feitas usando uma identidade gerenciada atribuída pelo usuário, obtenha uma cadeia de conexão que contenha um ResourceId, sem chave de conta ou senha. O ResourceId deve incluir a ID da assinatura da conta de armazenamento, o grupo de recursos da conta de armazenamento e o nome da conta de armazenamento. Forneça uma identidade usando a sintaxe mostrada no exemplo a seguir. Defina userAssignedIdentity como a identidade gerenciada atribuída pelo usuário. A cadeia de conexão é semelhante ao seguinte exemplo:
```
"credentials" : { 
    "connectionString" : "ResourceId=/subscriptions/00000000-0000-0000-0000-00000000/resourceGroups/MY-DEMO-RESOURCE-GROUP/providers/Microsoft.Storage/storageAccounts/MY-DEMO-STORAGE-ACCOUNT/;" 
},
"identity" : { 
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity" : "/subscriptions/00000000-0000-0000-0000-00000000/resourcegroups/MY-DEMO-RESOURCE-GROUP/providers/Microsoft.ManagedIdentity/userAssignedIdentities/MY-DEMO-USER-MANAGED-IDENTITY" 
}
```

Preparar modelos

Esse tutorial pressupõe que você tenha um recurso do Foundry existente por meio do qual a habilidade chama o modelo de incorporação multimodal da Visão do Azure 4.0. O serviço de pesquisa se conecta ao modelo durante o processamento do conjunto de habilidades usando sua identidade gerenciada. Esta seção fornece diretrizes e links para atribuir funções para acesso autorizado.

A mesma atribuição de função também é usada para acessar o modelo de layout do Azure Document Intelligence por meio de um recurso do Foundry.

Entre no portal do Azure (não no portal do Foundry) e localize o recurso Foundry. Verifique se ele está em uma região que fornece a API multimodal 4.0 e o modelo de layout do Azure Document Intelligence.
Selecione Controle de acesso (IAM) .
Selecione Adicionar e, em seguida, Adicionar atribuição de função.
Pesquise Usuário dos Serviços Cognitivos e, em seguida, selecione.
Escolha Identidade Gerenciada e depois atribua a Identidade Gerenciada do Serviço de Pesquisa.

Configure seu arquivo REST

Para este tutorial, o cliente REST local precisa de um ponto de extremidade e uma chave de API para se conectar ao Azure AI Search. Você pode obter esses valores no portal do Azure. Para obter métodos de conexão alternativos, consulte Conectar-se a um serviço de pesquisa.

Para conexões autenticadas que ocorrem durante o processamento do indexador e do conjunto de habilidades, o serviço de pesquisa usa as atribuições de função definidas anteriormente.

Inicie o Visual Studio Code e crie um arquivo.
Forneça valores para variáveis usadas na solicitação. Para @storageConnection, verifique se a cadeia de conexão não tem um ponto e vírgula ou aspas no final. Para @imageProjectionContainer, forneça um nome de contêiner exclusivo no armazenamento de blobs. O Azure AI Search cria esse contêiner para você durante o processamento de habilidades.
```
@searchUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@searchApiKey = PUT-YOUR-ADMIN-API-KEY-HERE
@storageConnection = PUT-YOUR-STORAGE-CONNECTION-STRING-HERE
@cognitiveServicesUrl = PUT-YOUR-AZURE-AI-FOUNDARY-ENDPOINT-HERE
@modelVersion = 2023-04-15
@imageProjectionContainer=sustainable-ai-pdf-images
```
Salve o arquivo usando uma extensão de nome de arquivo .rest ou .http. Para obter ajuda com o cliente REST, consulte Início Rápido: Pesquisa de texto completo usando REST.

Para obter a URL do endpoint e a chave de API do Azure AI Search:

Entre no portal do Azure, navegue até a página Visão geral do serviço de pesquisa e copie a URL. Um exemplo de endpoint pode ter a seguinte aparência: https://mydemo.search.windows.net.
Em Configurações>Chaves, copie uma chave de administrador. As chaves de administrador são usadas para adicionar, modificar e excluir objetos. Há duas chaves de administrador intercambiáveis. Copie uma delas.

Criar uma fonte de dados

Criar fonte de dados (REST) cria uma conexão de fonte de dados que especifica quais dados indexar.

### Create a data source using system-assigned managed identities
POST {{searchUrl}}/datasources?api-version=2025-11-01-preview   HTTP/1.1
  Content-Type: application/json
  api-key: {{searchApiKey}}

  {
    "name": "doc-intelligence-multimodal-embedding-ds",
    "description": "A data source to store multimodal documents",
    "type": "azureblob",
    "subtype": null,
    "credentials":{
      "connectionString":"{{storageConnection}}"
    },
    "container": {
      "name": "sustainable-ai-pdf",
      "query": null
    },
    "dataChangeDetectionPolicy": null,
    "dataDeletionDetectionPolicy": null,
    "encryptionKey": null,
    "identity": null
  }

Enviar a solicitação. A resposta deve ser semelhante a:

HTTP/1.1 201 Created
Transfer-Encoding: chunked
Content-Type: application/json; odata.metadata=minimal; odata.streaming=true; charset=utf-8
Location: https://<YOUR-SEARCH-SERVICE-NAME>.search.windows-int.net:443/datasources('doc-extraction-multimodal-embedding-ds')?api-version=2025-11-01-preview -Preview
Server: Microsoft-IIS/10.0
Strict-Transport-Security: max-age=2592000, max-age=15724800; includeSubDomains
Preference-Applied: odata.include-annotations="*"
OData-Version: 4.0
request-id: 4eb8bcc3-27b5-44af-834e-295ed078e8ed
elapsed-time: 346
Date: Sat, 26 Apr 2025 21:25:24 GMT
Connection: close

{
  "name": "doc-extraction-multimodal-embedding-ds",
  "description": null,
  "type": "azureblob",
  "subtype": null,
  "indexerPermissionOptions": [],
  "credentials": {
    "connectionString": null
  },
  "container": {
    "name": "sustainable-ai-pdf",
    "query": null
  },
  "dataChangeDetectionPolicy": null,
  "dataDeletionDetectionPolicy": null,
  "encryptionKey": null,
  "identity": null
}

Crie um índice

Criar índice (REST) cria um índice de pesquisa em seu serviço de pesquisa. Um índice especifica todos os parâmetros e seus atributos.

Para JSON aninhado, os campos de índice devem ser idênticos aos campos de origem. Atualmente, o Azure AI Search não dá suporte a mapeamentos de campo para JSON aninhado, portanto, os nomes de campo e os tipos de dados devem corresponder completamente. O índice a seguir se alinha aos elementos JSON no conteúdo bruto.

### Create an index
POST {{searchUrl}}/indexes?api-version=2025-11-01-preview   HTTP/1.1
  Content-Type: application/json
  api-key: {{searchApiKey}}

{
    "name": "doc-intelligence-multimodal-embedding-index",
    "fields": [
        {
            "name": "content_id",
            "type": "Edm.String",
            "retrievable": true,
            "key": true,
            "analyzer": "keyword"
        },
        {
            "name": "text_document_id",
            "type": "Edm.String",
            "searchable": false,
            "filterable": true,
            "retrievable": true,
            "stored": true,
            "sortable": false,
            "facetable": false
        },          
        {
            "name": "document_title",
            "type": "Edm.String",
            "searchable": true
        },
        {
            "name": "image_document_id",
            "type": "Edm.String",
            "filterable": true,
            "retrievable": true
        },
        {
            "name": "content_text",
            "type": "Edm.String",
            "searchable": true,
            "retrievable": true
        },
        {
            "name": "content_embedding",
            "type": "Collection(Edm.Single)",
            "dimensions": 1024,
            "searchable": true,
            "retrievable": true,
            "vectorSearchProfile": "hnsw"
        },
        {
            "name": "content_path",
            "type": "Edm.String",
            "searchable": false,
            "retrievable": true
        },
        {
            "name": "offset",
            "type": "Edm.String",
            "searchable": false,
            "retrievable": true
        },
        {
            "name": "location_metadata",
            "type": "Edm.ComplexType",
            "fields": [
                {
                "name": "page_number",
                "type": "Edm.Int32",
                "searchable": false,
                "retrievable": true
                },
                {
                "name": "bounding_polygons",
                "type": "Edm.String",
                "searchable": false,
                "retrievable": true,
                "filterable": false,
                "sortable": false,
                "facetable": false
                }
            ]
        }         
    ],
    "vectorSearch": {
        "profiles": [
            {
                "name": "hnsw",
                "algorithm": "defaulthnsw",
                "vectorizer": "demo-vectorizer"
            }
        ],
        "algorithms": [
            {
                "name": "defaulthnsw",
                "kind": "hnsw",
                "hnswParameters": {
                    "m": 4,
                    "efConstruction": 400,
                    "metric": "cosine"
                }
            }
        ],
        "vectorizers": [
            {
                "name": "demo-vectorizer",
                "kind": "aiServicesVision",
                "aiServicesVisionParameters": {
                    "resourceUri": "{{cognitiveServicesUrl}}",
                    "authIdentity": null,
                    "modelVersion": "{{modelVersion}}"
                }
            }
        ]     
    },
    "semantic": {
        "defaultConfiguration": "semanticconfig",
        "configurations": [
            {
                "name": "semanticconfig",
                "prioritizedFields": {
                    "titleField": {
                        "fieldName": "document_title"
                    },
                    "prioritizedContentFields": [
                    ],
                    "prioritizedKeywordsFields": []
                }
            }
        ]
    }
}

Pontos principais:

As inserções de texto e imagem são armazenadas no content_embedding campo e devem ser configuradas com dimensões apropriadas, como 1024, e um perfil de pesquisa de vetor.
location_metadata captura metadados de polígono delimitador e número de página para cada parte de texto e imagem normalizada, permitindo pesquisa espacial precisa ou sobreposições de interface do usuário.
Para obter mais informações sobre a pesquisa de vetor, consulte Vectors no Azure AI Search.
Para obter mais informações sobre classificação semântica, consulte Classificação semântica no Azure AI Search.

Criar um conjunto de habilidades

Criar conjunto de habilidades (REST) cria um conjunto de habilidades em seu serviço de pesquisa. Um conjunto de habilidades define as operações que agrupam e inserem conteúdo antes da indexação. Esse conjunto de habilidades usa a habilidade layout do documento para extrair texto e imagens, preservando metadados de localização que são úteis para citações em aplicativos RAG. Ele usa a habilidade de inserções multimodal do Azure Vision para vetorizar o conteúdo de imagem e texto.

### Create a skillset
POST {{searchUrl}}/skillsets?api-version=2025-11-01-preview   HTTP/1.1
  Content-Type: application/json
  api-key: {{searchApiKey}}

{
  "name": "doc-intelligence-multimodal-embedding-skillset",
  "description": "A sample skillset for multimodal using multimodal embedding",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Util.DocumentIntelligenceLayoutSkill",
      "name": "document-layout-skill",
      "description": "Azure Document Intelligence skill for document cracking",
      "context": "/document",
      "outputMode": "oneToMany",
      "outputFormat": "text",
      "extractionOptions": ["images", "locationMetadata"],
      "chunkingProperties": {     
          "unit": "characters",
          "maximumLength": 2000, 
          "overlapLength": 200
      },
      "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.Vision.VectorizeSkill", 
      "name": "text-embedding-skill",
      "description": "Vision Vectorization skill for text",
      "context": "/document/text_sections/*", 
      "modelVersion": "2023-04-15", 
      "inputs": [ 
        { 
          "name": "text", 
          "source": "/document/text_sections/*/content" 
        } 
      ], 
      "outputs": [ 
        { 
          "name": "vector",
          "targetName": "text_vector"
        } 
      ] 
    },    
    { 
      "@odata.type": "#Microsoft.Skills.Vision.VectorizeSkill", 
      "name": "image-embedding-skill",
      "description": "Vision Vectorization skill for images",
      "context": "/document/normalized_images/*", 
      "modelVersion": "2023-04-15", 
      "inputs": [ 
        { 
          "name": "image", 
          "source": "/document/normalized_images/*" 
        } 
      ], 
      "outputs": [ 
        { 
          "name": "vector",
          "targetName": "image_vector"
        } 
      ] 
    },
    {
      "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
      "name": "shaper-skill",
      "context": "/document/normalized_images/*",
      "inputs": [
        {
          "name": "normalized_images",
          "source": "/document/normalized_images/*",
          "inputs": []
        },
        {
          "name": "imagePath",
          "source": "='my_container_name/'+$(/document/normalized_images/*/imagePath)",
          "inputs": []
        }
      ],
      "outputs": [
        {
          "name": "output",
          "targetName": "new_normalized_images"
        }
      ]
    }      
  ], 
   "indexProjections": {
      "selectors": [
        {
          "targetIndexName": "doc-intelligence-multimodal-embedding-index",
          "parentKeyFieldName": "text_document_id",
          "sourceContext": "/document/text_sections/*",
          "mappings": [    
            {
            "name": "content_embedding",
            "source": "/document/text_sections/*/text_vector"
            },                      
            {
              "name": "content_text",
              "source": "/document/text_sections/*/content"
            },
            {
              "name": "location_metadata",
              "source": "/document/text_sections/*/locationMetadata"
            },                
            {
              "name": "document_title",
              "source": "/document/document_title"
            }   
          ]
        },        
        {
          "targetIndexName": "{{index}}",
          "parentKeyFieldName": "image_document_id",
          "sourceContext": "/document/normalized_images/*",
          "mappings": [    
            {
            "name": "content_embedding",
            "source": "/document/normalized_images/*/image_vector"
            },                                           
            {
              "name": "content_path",
              "source": "/document/normalized_images/*/new_normalized_images/imagePath"
            },                    
            {
              "name": "document_title",
              "source": "/document/document_title"
            },
            {
              "name": "location_metadata",
              "source": "/document/normalized_images/*/locationMetadata"
            }             
          ]
        }
      ],
      "parameters": {
        "projectionMode": "skipIndexingParentDocuments"
      }
  },
  "cognitiveServices": {
    "@odata.type": "#Microsoft.Azure.Search.AIServicesByIdentity",
    "subdomainUrl": "{{cognitiveServicesUrl}}",
    "identity": null
  },
  "knowledgeStore": {
    "storageConnectionString": "",
    "identity": null,
    "projections": [
      {
        "files": [
          {
            "storageContainer": "{{imageProjectionContainer}}",
            "source": "/document/normalized_images/*"
          }
        ]
      }
    ]
  }
}

Esse conjunto de habilidades extrai texto e imagens, vetoriza ambos e formata os metadados de imagem para projeção no índice.

Pontos principais:

O campo content_text é preenchido com texto extraído e dividido em partes usando a Habilidade de Layout do Documento
content_path contém o caminho relativo para o arquivo de imagem dentro do contêiner de projeção de imagem designado. Esse campo é gerado somente para imagens extraídas de documentos quando extractOption é definido como ["images", "locationMetadata"] ou ["images"], e pode ser mapeado a partir do documento enriquecido do campo de origem /document/normalized_images/*/imagePath.
A habilidade de inserção multimodal do Azure Vision permite a inserção de dados textuais e visuais usando o mesmo tipo de habilidade, diferenciado por entrada (texto versus imagem). Para obter mais informações, consulte a habilidade de inserções multimodal do Azure Vision.

Criar e executar um indexador

Criar Indexador cria um indexador em seu serviço de pesquisa. Um indexador se conecta à fonte de dados, carrega dados, executa um conjunto de habilidades e indexa os dados enriquecidos.

### Create and run an indexer
POST {{searchUrl}}/indexers?api-version=2025-11-01-preview   HTTP/1.1
  Content-Type: application/json
  api-key: {{searchApiKey}}

{
  "dataSourceName": "doc-intelligence-multimodal-embedding-ds",
  "targetIndexName": "doc-intelligence-multimodal-embedding-index",
  "skillsetName": "doc-intelligence-multimodal-embedding-skillset",
  "parameters": {
    "maxFailedItems": -1,
    "maxFailedItemsPerBatch": 0,
    "batchSize": 1,
    "configuration": {
      "allowSkillsetToReadFileData": true
    }
  },
  "fieldMappings": [
    {
      "sourceFieldName": "metadata_storage_name",
      "targetFieldName": "document_title"
    }
  ],
  "outputFieldMappings": []
}

Executar consultas

Você poderá iniciar a pesquisa assim que o primeiro documento for carregado.

### Query the index
POST {{searchUrl}}/indexes/doc-intelligence-multimodal-embedding-index/docs/search?api-version=2025-11-01-preview   HTTP/1.1
  Content-Type: application/json
  api-key: {{searchApiKey}}
  
  {
    "search": "*",
    "count": true
  }

Enviar a solicitação. Essa é uma consulta de pesquisa de texto completo não especificada que retorna todos os campos marcados como recuperáveis no índice, juntamente com uma contagem de documentos. A resposta deve ser semelhante a:

{
  "@odata.count": 100,
  "@search.nextPageParameters": {
    "search": "*",
    "count": true,
    "skip": 50
  },
  "value": [
  ],
  "@odata.nextLink": "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/doc-intelligence-multimodal-embedding-index/docs/search?api-version=2025-11-01-preview "
}

100 documentos são retornados na resposta.

Para filtros, você também pode usar operadores lógicos (e, ou não) e operadores de comparação (eq, ne, gt, lt, ge, le). Comparações de cadeia de caracteres diferenciam maiúsculas de minúsculas. Para obter mais informações e exemplos, consulte exemplos de consultas de pesquisa simples.

Note

O parâmetro $filter só funciona em campos que foram marcados como filtráveis durante a criação do índice.

### Query for only images
POST {{searchUrl}}/indexes/doc-intelligence-multimodal-embedding-index/docs/search?api-version=2025-11-01-preview   HTTP/1.1
  Content-Type: application/json
  api-key: {{searchApiKey}}
  
  {
    "search": "*",
    "count": true,
    "filter": "image_document_id ne null"
  }

### Query for text or images with content related to energy, returning the id, parent document, and text (only populated for text chunks), and the content path where the image is saved in the knowledge store (only populated for images)
POST {{searchUrl}}/indexes/doc-intelligence-multimodal-embedding-index/docs/search?api-version=2025-11-01-preview   HTTP/1.1
  Content-Type: application/json
  api-key: {{searchApiKey}}
  
  {
    "search": "energy",
    "count": true,
    "select": "content_id, document_title, content_text, content_path"
  }

Redefina e execute novamente

Os indexadores podem ser redefinidos para limpar o histórico de execução, o que permite uma nova execução completa. As solicitações POST a seguir são para redefinição, seguidas de nova execução.

### Reset the indexer
POST {{searchUrl}}/indexers/doc-intelligence-multimodal-embedding-indexer/reset?api-version=2025-11-01-preview   HTTP/1.1
  api-key: {{searchApiKey}}

### Run the indexer
POST {{searchUrl}}/indexers/doc-intelligence-multimodal-embedding-indexer/run?api-version=2025-11-01-preview   HTTP/1.1
  api-key: {{searchApiKey}}

### Check indexer status 
GET {{searchUrl}}/indexers/doc-intelligence-multimodal-embedding-indexer/status?api-version=2025-11-01-preview   HTTP/1.1
  api-key: {{searchApiKey}}

Limpar os recursos

Quando você está trabalhando em sua própria assinatura, no final de um projeto, é uma boa ideia remover os recursos que já não são necessários. Recursos deixados em execução podem custar dinheiro. Você pode excluir recursos individualmente ou excluir o grupo de recursos para excluir todo o conjunto de recursos.

Você pode usar o portal do Azure para excluir índices, indexadores e fontes de dados.

Consulte também

Agora que você está familiarizado com uma implementação de exemplo de um cenário de indexação multimodal, confira:

Comentários

Esta página foi útil?

Last updated on 2025-11-18