Configurar vetorização integrada na Pesquisa de IA do Azure usando REST

Neste artigo, você aprenderá a usar um conjunto de habilidades para fragmentar e vetorizar conteúdo de uma fonte de dados suportada. A coleção de habilidades chama a habilidade Divisão de Texto ou habilidade de Layout de Documento para a fragmentação e uma habilidade de incorporação anexada a um modelo de incorporação suportado para vetorização de segmentos. Você também aprende a armazenar o conteúdo em partes e vetorizado em um índice vetorial.

Este artigo descreve o fluxo de trabalho de ponta a ponta para vetorização integrada usando REST. Para obter instruções baseadas no portal, consulte Guia de início rápido: vetorizar texto e imagens no portal do Azure.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.

• Um serviço Azure AI Search. Recomendamos a camada Básica ou superior.

• Uma fonte de dados suportada.

• Um modelo de incorporação compatível.

• Conclusão do Início Rápido: Conexão sem chaves e Configurar uma identidade gerida atribuída pelo sistema. Embora você possa usar a autenticação baseada em chave para operações de plano de dados, este artigo assume funções e identidades gerenciadas, que são mais seguras.

• Código do Visual Studio com um cliente REST.

Fontes de dados suportadas

A vetorização integrada funciona com todas as fontes de dados suportadas. No entanto, este artigo se concentra nas fontes de dados mais comumente usadas, que são descritas na tabela a seguir.

Fonte de dados suportada	Descrição
Armazenamento de Blobs do Azure	Esta fonte de dados funciona com blobs e tabelas. Você deve usar uma conta padrão de desempenho (uso geral v2). As camadas de acesso podem ser quentes, frescas ou frias.
Azure Data Lake Storage (ADLS) Gen2	Esta é uma conta de Armazenamento do Azure com um namespace hierárquico habilitado. Para confirmar que você tem o Armazenamento Data Lake, verifique a guia Propriedades na página Visão geral .
Microsoft OneLake	Essa fonte de dados se conecta a arquivos e atalhos do OneLake.

Modelos de incorporação suportados

Para vetorização integrada, use um dos seguintes modelos de incorporação em uma plataforma de IA do Azure. As instruções de implantação são fornecidas em uma seção posterior.

¹ O endpoint do seu recurso OpenAI do Azure deve ter um subdomínio personalizado, como https://my-unique-name.openai.azure.com. Se você criou seu recurso no portal do Azure, esse subdomínio foi gerado automaticamente durante a configuração do recurso.

² recursos Azure OpenAI (com acesso a modelos de embedding) que foram criados no portal Foundry não são suportados. Você deve criar um recurso do Azure OpenAI no portal do Azure.

³ Para efeitos de faturação, deve associar o seu recurso Foundry ao conjunto de competências do seu serviço Azure AI Search. A menos que você use uma conexão sem chave (visualização) para criar o conjunto de habilidades, ambos os recursos devem estar na mesma região.

⁴ O modelo de embedding multimodal Azure Vision está disponível em regiões selecionadas.

Acesso baseado em funções

Você pode usar o Microsoft Entra ID com atribuições de função ou autenticação baseada em chave com cadeias de conexão com acesso total. Para conexões do Azure AI Search com outros recursos, recomendamos atribuições de função.

Para configurar o acesso baseado em função para vetorização integrada:

1. No serviço de pesquisa, habilite funções e configure uma identidade gerenciada atribuída ao sistema.

2. Em sua plataforma de fonte de dados e provedor de modelo incorporado, crie atribuições de função que permitam que seu serviço de pesquisa acesse dados e modelos. Consulte Preparar seus dados e Preparar seu modelo de incorporação.

Obter informações de conexão para o Azure AI Search

Nesta seção, você recupera o ponto de extremidade e o token do Microsoft Entra para seu serviço Azure AI Search. Ambos os valores são necessários para estabelecer conexões em solicitações REST .

1. Entre no portal do Azure e selecione seu serviço Azure AI Search.

2. Para obter o endpoint de pesquisa, copie o link na página Visão geral. Um exemplo de ponto de extremidade de pesquisa é https://my-service.search.windows.net.

3. Para obter o seu token Microsoft Entra, execute o seguinte comando no seu sistema local. Esta etapa requer a conclusão do Guia de início rápido: conectar-se sem chaves.

   az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
   

Prepare os seus dados

Nesta seção, você prepara seus dados para vetorização integrada carregando arquivos para uma fonte de dados suportada, atribuindo funções e obtendo informações de conexão.

Prepare o seu modelo de incorporação

Nesta seção, você prepara seu recurso de IA do Azure para vetorização integrada atribuindo funções, obtendo um ponto de extremidade e implantando um modelo de incorporação com suporte.

Definir variáveis

Nesta seção, você especifica as informações de conexão para seu serviço Azure AI Search, sua fonte de dados com suporte e seu modelo de incorporação com suporte.

1. No Visual Studio Code, cole os seguintes espaços reservados no seu arquivo .rest ou .http.

   @baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
   @token = PUT-YOUR-MICROSOFT-ENTRA-TOKEN-HERE
   

2. Substitua @baseUrl pelo endpoint de pesquisa e @token pelo token Microsoft Entra obtido em Obter informações de conexão para o Azure AI Search.

3. Dependendo da fonte de dados, adicione as seguintes variáveis.

   Fonte de dados	Variáveis	Insira estas informações
   Armazenamento de Blobs do Azure	@storageConnectionString e @blobContainer	A cadeia de conexão e o nome do contêiner criado em Preparar seus dados.
   ADLS Gen2	@storageConnectionString e @blobContainer	A cadeia de conexão e o nome do contêiner criado em Preparar seus dados.
   OneLake	@workspaceId e @lakehouseId	Os identificadores de espaço de trabalho e lakehouse obtidos em Prepare os seus dados.

4. Dependendo do seu provedor de modelo de incorporação, adicione as seguintes variáveis.

   Provedor de modelo de integração	Variáveis	Insira estas informações
   Azure OpenAI	@aoaiEndpoint, @aoaiDeploymentNamee @aoaiModelName	O ponto de extremidade, o nome da implantação e o nome do modelo obtidos em Preparar seu modelo de incorporação.
   Azure Vision	@AiFoundryEndpoint	O ponto de extremidade que obteve em Preparar o seu modelo de incorporação.

5. Para verificar as variáveis, envie a seguinte solicitação.

   ### List existing indexes by name
   GET {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   

   Uma resposta deve aparecer em um painel adjacente. Se você tiver índices existentes, eles serão listados. Caso contrário, a lista estará vazia. Se o código HTTP for 200 OK, você está pronto para continuar.

Conectar aos seus dados

Nesta seção, você se conecta a uma fonte de dados com suporte para indexação baseada em indexador. Um indexador no Azure AI Search requer uma fonte de dados que especifique o tipo, as credenciais e o contêiner.

1. Use Criar Fonte de Dados para definir uma fonte de dados que forneça informações de conexão durante a indexação.

   ### Create a data source
   POST {{baseUrl}}/datasources?api-version=2025-09-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-data-source",
       "type": "azureblob",
       "subtype": null,
       "credentials": {
           "connectionString": "{{storageConnectionString}}"
       },
       "container": {
           "name": "{{blobContainer}}",
           "query": null
       },
       "dataChangeDetectionPolicy": null,
       "dataDeletionDetectionPolicy": null
     }
   

2. Defina type para sua fonte de dados: azureblob ou adlsgen2.

3. Para criar a fonte de dados, selecione Enviar solicitação.

4. Se você estiver usando o OneLake, defina credentials.connectionString como ResourceId={{workspaceId}} e container.name para {{lakehouseId}}.

Criar um conjunto de competências

Nesta seção, você cria um conjunto de habilidades que chama uma habilidade interna para fragmentar seu conteúdo e uma habilidade de incorporação para criar representações vetoriais das partes. O conjunto de habilidades é executado durante a indexação em uma seção posterior.

Chame uma habilidade integrada para fragmentar seu conteúdo

Particionar seu conteúdo em partes ajuda você a atender aos requisitos do seu modelo de incorporação e evita a perda de dados devido ao truncamento. Para obter mais informações sobre fragmentação, consulte Fragmentar documentos grandes para soluções de pesquisa vetorial.

Para fragmentação de dados interna, a Pesquisa de IA do Azure oferece a habilidade Divisão de Texto e a habilidade Layout de Documento. A habilidade Divisão de Texto divide o texto em frases ou páginas de um determinado comprimento, enquanto a habilidade Layout de Documento divide o conteúdo com base nos limites de parágrafo.

1. Use Create Skillset para definir um conjunto de habilidades.

   ### Create a skillset
   POST {{baseUrl}}/skillsets?api-version=2025-09-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-skillset",
       "skills": []
     }
   

2. Na matriz skills, invoque a funcionalidade de Divisão de Texto ou a funcionalidade de Layout de Documento. Você pode colar uma das seguintes definições.

       "skills": [
        {
          "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
          "name": "my-text-split-skill",
          "textSplitMode": "pages",
          "maximumPageLength": 2000,
          "pageOverlapLength": 500,
          "maximumPagesToTake": 0,
          "unit": "characters",
          "defaultLanguageCode": "en",
          "inputs": [
           {
             "name": "text",
             "source": "/document/text",
             "inputs": []
           }
          ],
          "outputs": [
           {
             "name": "textItems"
           }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Util.DocumentIntelligenceLayoutSkill",
          "name": "my-document-layout-skill",
          "context": "/document",
          "outputMode": "oneToMany",
          "markdownHeaderDepth": "h3",
          "inputs": [
           {
             "name": "file_data",
             "source": "/document/file_data"
           }
          ],
          "outputs": [
           {
             "name": "markdown_document"
           }
          ]
        }
       ]
   

   Observação

   A funcionalidade de Layout de Documentos está em visualização pública. Se você quiser chamar essa habilidade, use uma API de visualização, como 2025-03-01-preview.

Chame uma habilidade de incorporação para vetorizar os segmentos

Para vetorizar seu conteúdo fragmentado, o conjunto de habilidades precisa de uma habilidade de incorporação que aponte para um modelo de incorporação suportado.

1. Depois da habilidade de chunking incorporada no skills array, chame a habilidade Azure OpenAI Embedding ou a habilidade Azure Vision. Você pode colar uma das seguintes definições.

        {
          "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
          "resourceUri": "{{aoaiEndpoint}}",
          "deploymentId": "{{aoaiDeploymentName}}",
          "modelName": "{{aoaiModelName}}",
          "dimensions": 1536,
          "inputs": [
            {
              "name": "text",
              "source": "/document/text"
            }
          ],
          "outputs": [
            {
              "name": "embedding"
            }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Vision.VectorizeSkill",
          "context": "/document",
          "modelVersion": "2023-04-15", 
          "inputs": [
            {
              "name": "url",
              "source": "/document/metadata_storage_path"
            },
            {
              "name": "queryString",
              "source": "/document/metadata_storage_sas_token"
            }
          ],
          "outputs": [
            {
              "name": "vector"
            }
          ]
        }
   

   Observação

   A competência de embeddings multimodais do Azure Vision está em versão preliminar pública. Se pretender chamar esta habilidade, utilize a API de pré-visualização mais recente.

2. Se você estiver usando a habilidade de incorporação do Azure OpenAI, defina dimensions o número de incorporações geradas pelo seu modelo de incorporação.

3. Se estiver a usar a habilidade de embeddings multimodal do Azure Vision, anexe o seu recurso Foundry depois do skills array. Este anexo destina-se a efeitos de faturação.

       "skills": [ ... ],
       "cognitiveServices": {
         "@odata.type": "#Microsoft.Azure.Search.AIServicesByIdentity",
         "subdomainUrl": "{{AiFoundryEndpoint}}"
        }
   

4. Para criar o conjunto de habilidades, selecione Enviar solicitação.

Criar um índice de vetores

Nesta seção, você configura estruturas de dados físicas em seu serviço Azure AI Search criando um índice vetorial. O esquema de um índice vetorial requer o seguinte:

• Nome
• Campo chave (string)
• Um ou mais campos vetoriais
• Configuração vetorial

Os campos vetoriais armazenam representações numéricas de seus dados em partes. Eles devem ser pesquisáveis e recuperáveis, mas não podem ser filtráveis, facetáveis ou ordenáveis. Eles também não podem ter analisadores, normalizadores ou atribuições de mapas de sinônimos.

Além dos campos vetoriais, o índice de exemplo nas etapas a seguir contém campos não vetoriais para conteúdo legível por humanos. É comum incluir equivalentes em texto simples do conteúdo que você deseja vetorizar. Para obter mais informações, consulte Criar um índice vetorial.

1. Use Create Index para definir o esquema de um índice vetorial.

   ### Create a vector index
   POST {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-vector-index",
       "fields": [],
       "vectorSearch": []
     }
   

2. Adicione uma configuração de pesquisa vetorial à vectorSearch seção.

       "vectorSearch": {
         "algorithms": [
           {
             "name": "hnsw-algorithm",
             "kind": "hnsw",
             "hnswParameters": {
               "m": 4,
               "efConstruction": 400,
               "efSearch": 100,
               "metric": "cosine"
             }
           }
         ],
         "profiles": [
           {
             "name": "vector-profile-hnsw",
             "algorithm": "hnsw-algorithm",
           }
         ]
       }
   

   vectorSearch.algorithms Especifica o algoritmo usado para indexar e consultar campos vetoriais, enquanto vectorSearch.profiles vincula a configuração do algoritmo a um perfil que você pode atribuir a campos vetoriais.

3. Dependendo do seu modelo de embedding, atualize vectorSearch.algorithms.metric. Os valores válidos para métricas de distância são cosine, dotproduct, euclideane hamming.

4. Adicione campos às fields matrizes. Inclua um campo chave para identificação de documentos, campos não vetoriais para conteúdo legível por pessoas e campos vetoriais para incorporações.

       "fields": [
         {
           "name": "id",
           "type": "Edm.String",
           "key": true,
           "filterable": true
         },
         {
           "name": "title",
           "type": "Edm.String",
            "searchable": true,
            "filterable": true,
            "sortable": true,
            "retrievable": true
         },
         {
           "name": "titleVector",
           "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": false,
            "stored": true,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-hnsw"
         },
         {
           "name": "content",
           "type": "Edm.String",
            "searchable": true,
            "retrievable": true
         },
         {
           "name": "contentVector",
           "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": false,
            "stored": false,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-hnsw"
         }
       ]
   

5. Dependendo da sua habilidade de incorporação, defina dimensions para cada campo vetorial com o seguinte valor.

   Habilidade de incorporação	Insira este valor
   Azure OpenAI	O número de incorporações geradas pelo seu modelo de incorporação.
   Azure Vision	1024

Adicionar um vetorizador ao índice

Nesta seção, você habilita a vetorização no momento da consulta definindo um vetorizador em seu índice. O vetorizador usa o modelo de incorporação que indexa seus dados para decodificar uma cadeia de caracteres de pesquisa ou imagem em um vetor para pesquisa vetorial.

1. Adicione o vectorizador Azure OpenAI ou o vectorizador Azure Vision após vectorSearch.profiles. Você pode colar uma das seguintes definições.

         "profiles": [ ... ],
         "vectorizers": [
           {
             "name": "my-openai-vectorizer",
             "kind": "azureOpenAI",
             "azureOpenAIParameters": {
               "resourceUri": "{{aoaiEndpoint}}",
               "deploymentId": "{{aoaiDeploymentName}}",
               "modelName": "{{aoaiModelName}}"
             }
           },
           {
             "name": "my-ai-services-vision-vectorizer",
             "kind": "aiServicesVision",
             "aiServicesVisionParameters": {
               "resourceUri": "{{AiFoundryEndpoint}}",
               "modelVersion": "2023-04-15"
             }
           }
         ]
   

   Observação

   O vectorizador Azure Vision está em pré-visualização pública. Se você quiser chamar esse vetorizador, use uma API de visualização, como 2025-03-01-preview.

2. Especifique seu vetorizador em vectorSearch.profiles.

         "profiles": [
           {
             "name": "vector-profile-hnsw",
             "algorithm": "hnsw-algorithm",
             "vectorizer": "my-openai-vectorizer"
           }
         ]
   

3. Para criar o índice vetorial, selecione Enviar solicitação.

Criar um indexador

Nesta seção, você cria um indexador para conduzir todo o pipeline de vetorização, desde a recuperação de dados até a execução do conjunto de habilidades e a indexação. Recomendamos que execute o indexador de acordo com um cronograma para processar alterações ou documentos que foram perdidos devido à retenção.

1. Use Create Indexer para definir um indexador que execute o pipeline de vetorização.

   ### Create an indexer
   POST {{baseUrl}}/indexers?api-version=2025-09-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-indexer",
       "dataSourceName": "my-data-source",
       "targetIndexName": "my-vector-index",
       "skillsetName": "my-skillset",
       "schedule": {
         "interval": "PT2H"
       },
       "parameters": {
         "batchSize": null,
         "maxFailedItems": null,
         "maxFailedItemsPerBatch": null
       }
     }
   

2. Para criar o indexador, selecione Enviar solicitação.

Executar uma consulta vetorial para confirmar a indexação

Nesta seção, você verifica se o conteúdo foi indexado com êxito criando uma consulta vetorial. Como você configurou um vetorizador em uma seção anterior, o mecanismo de pesquisa pode decodificar texto sem formatação ou uma imagem em um vetor para execução de consulta.

1. Use Documents - Search Post para definir uma consulta vetorizada no momento da consulta.

   ### Run a vector query
   POST {{baseUrl}}/indexes('my-vector-index')/docs/search.post.search?api-version=2025-09-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "count": true,
       "select": "title, content",
       "vectorQueries": [
           {
             "kind": "text",
             "text": "a sample text string for integrated vectorization",
             "fields": "titleVector, contentVector",
             "k": "3"
           }
       ]
     }
   

   Observação

   O vectorizador Azure Vision está em pré-visualização pública. Se você chamou esse vetorizador anteriormente, use uma API de visualização, como 2025-03-01-preview.

   Para consultas que invocam vetorização integrada, kind deve ser definido como text, e text deve especificar uma cadeia de caracteres de texto. Esta cadeia de caracteres é passada para o vetorizador atribuído ao campo vetorial. Para obter mais informações, consulte Consulta com vetorização integrada.

2. Para executar a consulta vetorial, selecione Enviar solicitação.

Conteúdo relacionado

• Vetorização integrada na Pesquisa de IA do Azure
• Guia de início rápido: vetorizar texto e imagens no portal do Azure
• Exemplo de Python para vetorização integrada