Compartilhar via

Configurar a vetorização integrada no Azure AI Search 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 Início Rápido: Vetorizar texto e imagens no portal do Azure.

Pré-requisitos

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 com suporte 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, frias ou geladas.
Azure Data Lake Storage (ADLS) Gen2 Essa é uma conta de Armazenamento do Azure com um namespace hierárquico habilitado. Para confirmar se você tem o Data Lake Storage, verifique a guia Propriedades na página Visão Geral .

Captura de tela de uma conta do Azure Data Lake Storage no portal do Azure.
Microsoft OneLake Essa fonte de dados se conecta a arquivos e atalhos do OneLake.

Modelos de inserção com suporte

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

Fornecedor Modelos com suporte
Recurso do Azure OpenAI1, 2 text-embedding-ada-002
text-embedding-3-small
text-embedding-3-large
Recurso do Microsoft Foundry3 Para texto e imagens: Azure Vision multimodal4

1 O endpoint do recurso do Azure OpenAI 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 instalação do recurso.

Não há suporte para 2 recursos do Azure OpenAI (com acesso a modelos de inserção) criados no portal do Foundry . Você deve criar um recurso do Azure OpenAI no portal do Azure.

3 Para fins de cobrança, você deve anexar seu recurso do Foundry ao conjunto de habilidades em seu serviço do Azure AI Search. A menos que você use uma conexão sem chave (versão prévia) para criar o conjunto de habilidades, ambos os recursos devem estar na mesma região.

4 O modelo de inserção multimodal do Azure Vision 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 strings de conexão de 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 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.

Observação

Os serviços de pesquisa gratuitos dão suporte a conexões baseadas em função com o Azure AI Search. No entanto, eles não dão suporte a identidades gerenciadas em conexões de saída com o Armazenamento do Azure ou o Azure Vision. Essa falta de suporte requer que você use a autenticação baseada em chave em conexões entre serviços de pesquisa gratuitos e outros recursos do Azure.

Para conexões mais seguras, use a camada Básica ou superior. Em seguida, você pode habilitar funções e configurar uma identidade gerenciada para acesso autorizado.

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

Dica

As etapas seguintes pressupõem que você esteja usando acesso baseado em funções para testes de conceito. Se você quiser usar a vetorização integrada para desenvolvimento de aplicativos, consulte Conectar seu aplicativo ao Azure AI Search usando identidades.

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

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

  3. Para obter o token do 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.

  1. Entre no portal do Azure e selecione sua conta de Armazenamento do Azure.

  2. No painel esquerdo, selecione Armazenamento de Dados>Contêineres.

  3. Crie um contêiner ou selecione um contêiner existente e carregue seus arquivos no contêiner.

  4. Para atribuir funções:

    1. No painel esquerdo, selecione Controle de Acesso (IAM).

    2. Selecione Adicionar>Adicionar atribuição de função.

    3. Em Funções de trabalho, selecione Leitor de dados de blobs de armazenamento e, em seguida, selecione Avançar.

    4. Em Membros, selecione Identidade Gerenciada e selecione Selecionar membros.

    5. Selecione sua assinatura e a identidade gerenciada do serviço de pesquisa.

  5. Para obter uma string de conexão:

    1. No painel esquerdo, selecione Segurança + chaves de acesso de> rede.

    2. Copie qualquer cadeia de conexão, que você especifica mais tarde em Definir variáveis.

  6. (Opcional) Sincronizar exclusões em seu contêiner com exclusões no índice de pesquisa. Para configurar o indexador para detecção de exclusão:

    1. Habilite a exclusão reversível na sua conta de armazenamento. Se você estiver usando exclusão lógica nativa, a próxima etapa não será necessária.

    2. Adicione metadados personalizados que um indexador pode verificar para determinar quais blobs estão marcados para exclusão. Dê à sua propriedade personalizada um nome descritivo. Por exemplo, você pode nomear a propriedade "IsDeleted" e defini-la como false. Repita essa etapa para cada blob no contêiner. Quando você quiser excluir o blob, altere a propriedade para true. Para obter mais informações, consulte Alterar e excluir a detecção ao indexar do Armazenamento do Azure.

Prepare 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 inserção com suporte.

O Azure AI Search dá suporte a text-embedding-ada-002, text-embedding-3-small e text-embedding-3-large. Internamente, o IA do Azure Search chama a habilidade de incorporação do Azure OpenAI para se conectar ao Azure OpenAI.

  1. Entre no portal do Azure e selecione seu recurso do Azure OpenAI.

  2. Para atribuir funções:

    1. No painel esquerdo, selecione Controle de acesso (IAM).

    2. Selecione Adicionar>Adicionar atribuição de função.

    3. Em funções de trabalho, selecione Usuário OpenAI dos Serviços Cognitivos e selecione Avançar.

    4. Em Membros, selecione Identidade Gerenciada e selecione Selecionar membros.

    5. Selecione sua assinatura e a identidade gerenciada do serviço de pesquisa.

  3. Para obter um ponto de extremidade:

    1. No painel esquerdo, selecione Gerenciamento de recursos>Chaves e ponto de extremidade.

    2. Copie o ponto de extremidade para seu recurso do Azure OpenAI. Especifique essa URL posteriormente em Definir variáveis.

  4. Para implantar um modelo de incorporação:

    1. Entre no portal do Foundry e selecione o recurso do Azure OpenAI.

    2. Implantar um modelo de incorporação compatível.

    3. Copie os nomes de implantação e modelo, que você especificar posteriormente em Definir variáveis. O nome da implantação é o nome personalizado que você escolheu, enquanto o nome do modelo é o modelo que você implantou, como text-embedding-ada-002.

Definir variáveis

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

  1. No Visual Studio Code, insira os seguintes marcadores de posição em seu 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 cadeia de conexão e o nome do contêiner que você criou em Preparar seus dados.
    ADLS Gen2 @storageConnectionString e @blobContainer A cadeia de conexão e o nome do contêiner que você criou em Preparar 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, @aoaiDeploymentName, e @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 do Azure @AiFoundryEndpoint O ponto de extremidade que você obteve em Prepare 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=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 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 indexador no Azure AI Search 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=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 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, veja Fragmentar documentos grandes para soluções de busca em vetores.

Para agrupamento de dados interno, o Azure AI Search oferece a habilidade de Divisão de Texto e a habilidade de Layout de Documento. A habilidade de divisão de texto divide o texto em frases ou páginas de um comprimento específico, enquanto a habilidade Layout do Documento divide o conteúdo com base em limites de parágrafos.

  1. Use Criar Conjunto de Habilidades 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, chame a habilidade Divisão de Texto ou a habilidade Layout de Documento. 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.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 habilidade Layout de Documento 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 pedaços

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 interna na matriz skills, chame a habilidade de inserção do Serviço OpenAI do Azure ou a habilidade de Visão do Azure. 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"
         }
       ]
     }

    Observação

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

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

  3. Se estiver usando a habilidade de inserções multimodais da Visão do Azure, anexe seu recurso da Fábrica 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ísicos em seu serviço do Azure AI Search criando um índice de vetor. 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 atribuições de mapas 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, veja 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=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 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.

    Habilidade de inserção Inserir este valor
    OpenAI do Azure O número de inserções geradas pelo seu modelo de inserção.
    Visão do 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 usa 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 do Azure OpenAI ou o vetorizador do Azure Vision 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"
          }
        }
      ]

    Observação

    O vetor do Azure Vision está em versão prévia pública. Se você quiser chamar esse vetorizador, use uma API de prévia, 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 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 Criar Indexador para definir um indexador que executa 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 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=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 vetor do Azure Vision está em versão prévia pública. Se você chamou esse vetorizador anteriormente, use uma API de visualização, como 2025-03-01-preview.

    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

  • Last updated on