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

Neste artigo, você aprenderá a usar um conjunto de habilidades para agrupar e vetorizar o conteúdo de uma fonte de dados com suporte. O conjunto de habilidades chama a habilidade Divisão de Texto ou habilidade Layout de Documento para fragmentação e uma habilidade de incorporação que é anexada a um modelo de incorporação suportado para vetorização de fragmentos. Você também aprenderá a armazenar o conteúdo em partes e vetorizado em um índice de vetor.

Este artigo descreve o fluxo de trabalho de ponta a ponta para vetorização integrada usando REST. Para obter instruções baseadas em portal, consulte Quickstart: Vectorize texto e imagens no portal Azure.

Pré-requisitos

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

• Um serviço Pesquisa de IA do Azure . Recomendamos a camada Básica ou superior.

• Uma fonte de dados com suporte.

• Um modelo de inserção com suporte.

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

• Visual Studio Code com a extensão cliente REST.

Fontes de dados com suporte

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

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

Modelos de inserção com suporte

Use um dos seguintes modelos de inserção para vetorização integrada. As instruções de implantação são fornecidas em uma seção posterior.

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

² recursos Azure OpenAI (com acesso a modelos de embedding) criados no portal Microsoft Foundry não têm suporte. Você deve criar um recurso Azure OpenAI no portal do Azure.

³ Para fins de cobrança, você deve anexar seu recurso Microsoft Foundry ao seu conjunto de habilidades do Pesquisa de IA do Azure . A menos que você use uma conexão sem chave para criar o conjunto de habilidades, ambos os recursos devem estar na mesma região.

⁴ O modelo de inserção multimodal da Visão Azure está disponível em regiões selecionadas.

Acesso baseado em função

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 as conexões do Pesquisa de IA do Azure  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 as funções e configure uma identidade gerenciada atribuída pelo sistema.

2. Em sua plataforma de fonte de dados e no provedor de modelo de inserção, 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 inserção.

Obter informações de conexão para Pesquisa de IA do Azure 

Nesta seção, você recuperará o endpoint e o token do Microsoft Entra para o seu serviço Pesquisa de IA do Azure . Ambos os valores são necessários para estabelecer conexões em solicitações REST.

1. Acesse o serviço de pesquisa no Azure portal.

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

3. Para obter o token Microsoft Entra, execute o seguinte comando em seu sistema local. Esta etapa requer a conclusão do Início Rápido: Conectar sem chaves.

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

Preparar seus dados

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

Preparar seu modelo de inserção

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

Definir variáveis

Nesta seção, você especifica as informações de conexão para seu serviço Pesquisa de IA do Azure , sua fonte de dados suportada e seu modelo de incorporação suportado.

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

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

2. Substitua @baseUrl pelo ponto de extremidade de pesquisa e @token pelo token Microsoft Entra obtido em Obter informações de conexão para a Pesquisa de IA do Azure.

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

   Fonte de dados	Variáveis	Insira essas informações
   Armazenamento de Blobs do Azure	@storageConnectionString e @blobContainer	A string de conexão e o nome do contêiner que você criou em Prepare seus dados.
   ADLS Gen2	@storageConnectionString e @blobContainer	A string de conexão e o nome do contêiner que você criou em Prepare seus dados.
   OneLake	@workspaceId e @lakehouseId	Os IDs do espaço de trabalho e do lakehouse que você obteve em Preparar dados.

4. Dependendo do provedor de modelo de inserção, adicione as variáveis a seguir.

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

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

   ### List existing indexes by name
   GET {{baseUrl}}/indexes?api-version=2026-04-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 estiver 200 OK, você estará pronto para continuar.

Conectar-se aos seus dados

Nesta seção, você se conectará a uma fonte de dados com suporte para indexação baseada em indexador. Um indexer em Pesquisa de IA do Azure  requer uma fonte de dados que especifica o tipo, as credenciais e o contêiner.

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

   ### Create a data source
   POST {{baseUrl}}/datasources?api-version=2026-04-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 como 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 para ResourceId={{workspaceId}} .container.name{{lakehouseId}}

Criar um conjunto de habilidades

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

Chame uma habilidade interna para fragmentar seu conteúdo

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

Para a fragmentação interna de dados, o Pesquisa de IA do Azure  oferece a habilidade Divisão de Texto e a habilidade Compreensão de Conteúdo do Azure. A habilidade Text Split divide o texto em frases ou páginas com um comprimento específico, enquanto a habilidade Azure Content Understanding realiza a segmentação semântica com reconhecimento de layout que respeita os limites dos parágrafos.

1. Use Criar Conjunto de Habilidades para definir um conjunto de habilidades.

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

2. Na matriz skills, chame a habilidade Divisão de Texto ou a habilidade Compreensão de Conteúdo do Azure. Você pode colar uma das definições a seguir.

       "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.ContentUnderstandingSkill",
          "name": "my-content-understanding-skill",
          "context": "/document",
          "chunkingProperties": {
            "method": "semantic",
            "unit": "tokens",
            "maximumLength": 500
          },
          "inputs": [
           {
             "name": "file_data",
             "source": "/document/file_data"
           }
          ],
          "outputs": [
           {
             "name": "text_sections",
             "targetName": "text_sections"
           }
          ]
        }
       ]
   

Chamar uma habilidade de incorporação para vetorizar os fragmentos

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 compatível.

1. Após a habilidade de divisão em blocos integrada na matriz skills, chame a habilidade de embeddings do OpenAI do Azure ou a habilidade de embeddings multimodais do Visão do Azure (versão prévia). Você pode colar uma das definições a seguir.

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

   Nota

   A habilidade de inserções multimodal do Azure Vision está em versão prévia. Se você quiser chamar essa habilidade, use a versão mais recente da API de visualização.

2. Se você estiver usando a habilidade Azure OpenAI Embedding, defina dimensions para o número de embeddings gerados pelo seu modelo de embedding.

3. Se você estiver usando a habilidade de incorporações multimodais do Azure Vision, anexe seu recurso Microsoft Foundry após a matriz skills. Esse anexo é para fins de cobrança.

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

Nesta seção, você configurará estruturas de dados físicas em seu serviço Pesquisa de IA do Azure  criando um índice vector. O esquema de um índice de vetor requer o seguinte:

• Nome
• Campo de chave (cadeia de caracteres)
• Um ou mais campos de vetor
• Configuração do vetor

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

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

1. Use Criar Índice para definir o esquema de um índice de vetor.

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

2. Adicione uma configuração de pesquisa de vetor à 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 de vetor, enquanto vectorSearch.profiles vincula a configuração de algoritmo a um perfil que você pode atribuir a campos de vetor.

3. Dependendo do seu modelo de inserção, atualize vectorSearch.algorithms.metric. Os valores válidos para métricas de distância são cosine, dotproducte euclideanhamming.

4. Adicione campos às fields matrizes. Inclua um campo de chave para identificação de documentos, campos não vetoriais para conteúdo legível por humanos e campos de vetor para inserçõ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 habilidade de inserção, defina dimensions para cada campo de vetor com o valor a seguir.

   Incorporar habilidade	Insira esse valor
   OpenAI do Azure	O número de inserções geradas pelo seu modelo de inserção.
   Visão Azure	1024

Adicionar um vetorizador ao índice

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

1. Adicione o vetorizador Azure OpenAI ou o vetorizador de Visão Azure (versão prévia) após vectorSearch.profiles. Você pode colar uma das definições a seguir.

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

   Nota

   O vetorizador Azure Vision está em versão prévia. Se você quiser chamar esse vetorizador, use a versão mais recente da API de visualização.

2. Especifique seu vetorizador em vectorSearch.profiles.

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

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

Criar um indexador

Nesta seção, você criará um indexador para conduzir todo o pipeline de vetorização, desde a recuperação de dados até a execução do conjunto de habilidades até a indexação. Recomendamos que você execute o indexador em uma programação para processar alterações ou documentos que foram perdidos devido à limitação.

1. Use Create Indexer para definir um indexador que irá executar o fluxo de vetorização.

   ### Create an indexer
   POST {{baseUrl}}/indexers?api-version=2026-04-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 de vetor para confirmar a indexação

Nesta seção, você verifica se o conteúdo foi indexado com êxito criando uma consulta de vetor. Como você configurou um vetor 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 Documentos - Pesquisar postagem para definir uma consulta que é vetorizada no momento da consulta.

   ### Run a vector query
   POST {{baseUrl}}/indexes('my-vector-index')/docs/search.post.search?api-version=2026-04-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"
           }
       ]
     }
   

   Nota

   O vetorizador Azure Vision está em versão prévia. Se você quiser chamar esse vetorizador, use a versão mais recente da API de visualização.

   Para consultas que invocam a vetorização integrada, kind deve ser definido como text, e text deve especificar uma cadeia de caracteres de texto. Essa 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 de vetor, selecione Enviar solicitação.

Conteúdo relacionado

• Inserção de vetor integrado no Pesquisa de IA do Azure 
• Quickstart: pesquisa de vetor no portal Azure
• Python exemplo de vetorização integrada