Criar uma consulta de vetor no Pesquisa de IA do Azure

Se você tiver um índice vector em Pesquisa de IA do Azure , este artigo explica como:

Campos de vetor de consulta
Consultar vários campos de vetor ao mesmo tempo
Definir pesos de vetor
Consulta com vetorização integrada
Definir limites para excluir resultados de baixa pontuação (versão prévia)

Este artigo usa REST para ilustração. Depois de entender o fluxo de trabalho básico, continue com os exemplos de código SDK do Azure no repositório azure-search-vector-samples, que fornece soluções de ponta a ponta que incluem consultas vetoriais.

Você também pode usar Search Explorer no portal Azure.

Pré-requisitos

Um serviço Pesquisa de IA do Azure em qualquer região e em qualquer camada.
Um índice de vetor. Verifique se há uma vectorSearch seção em seu índice para confirmar sua presença.
Opcionalmente, adicione um vetor de vetorização ao seu índice para vetorização integrada de texto para vetor ou de imagem para vetor durante consultas.
Visual Studio Code com um cliente REST e dados de exemplo se quiser executar esses exemplos por conta própria. Para começar a usar o cliente REST, consulte Início Rápido: Pesquisa de texto completo usando REST.

Converter uma entrada de cadeia de caracteres de consulta em um vetor

Para consultar um campo de vetor, a consulta em si deve ser um vetor.

Uma abordagem para converter a cadeia de caracteres de consulta de texto de um usuário em sua representação de vetor é chamar uma biblioteca de inserção ou API no código do aplicativo. Como prática recomendada, sempre use os mesmos modelos de inserção usados para gerar inserções nos documentos de origem. Você pode encontrar exemplos de código mostrando como gerar embeddings no repositório azure-search-vector-samples.

Uma segunda abordagem é usar a vetorização integrada, agora disponível para o público em geral, para que o Pesquisa de IA do Azure lide com as entradas e saídas de vetorização da sua consulta.

Aqui está um exemplo de API REST de uma cadeia de caracteres de consulta enviada a uma implantação de um modelo de inserção do OpenAI do Azure:

POST https://{{openai-service-name}}.openai.azure.com/openai/deployments/{{openai-deployment-name}}/embeddings?api-version={{openai-api-version}}
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "input": "what azure services support generative AI'"
}

A resposta esperada é 202 para uma chamada bem-sucedida para o modelo implantado.

O embedding campo no corpo da resposta é a representação de vetor da cadeia de caracteres inputde consulta. Para fins de teste, você copiaria o valor da embedding matriz em vectorQueries.vector uma solicitação de consulta, usando a sintaxe mostrada nas próximas seções.

A resposta real a esta chamada POST para o modelo implantado inclui 1.536 embeddings. Para legibilidade, este exemplo mostra apenas os primeiros vetores.

{
    "object": "list",
    "data": [
        {
            "object": "embedding",
            "index": 0,
            "embedding": [
                -0.009171937,
                0.018715322,
                ...
                -0.0016804502
            ]
        }
    ],
    "model": "ada",
    "usage": {
        "prompt_tokens": 7,
        "total_tokens": 7
    }
}

Nessa abordagem, o código do aplicativo é responsável por se conectar a um modelo, gerar inserções e lidar com a resposta.

Solicitação de consulta de vetor

Esta seção mostra a estrutura básica de uma consulta de vetor. Você pode usar o portal Azure, AS APIs REST ou o SDKs do Azure para formular uma consulta de vetor.

Se você estiver migrando de 2023-07-01-Preview, haverá alterações significativas. Para obter mais informações, consulte Atualizar para a API REST mais recente.

A versão estável dá suporte a:

vectorQueries é o constructo para pesquisa de vetor.
vectorQueries.kind definido como vector para uma matriz de vetores ou text se a entrada for uma string e se você tiver um vetorizador.
vectorQueries.vector é a consulta (uma representação de vetor de texto ou uma imagem).
vectorQueries.exhaustive (opcional) invoca KNN exaustivo no momento da consulta, mesmo que o campo seja indexado para HNSW.
vectorQueries.fields (opcional) direciona campos específicos para execução de consulta (até 10 por consulta).
vectorQueries.weight (opcional) especifica o peso relativo de cada consulta de vetor incluída nas operações de pesquisa. Para obter mais informações, consulte a ponderação do vetor.
vectorQueries.k é o número de correspondências a serem retornadas.

No exemplo a seguir, o vetor é uma representação dessa cadeia de caracteres: "what Azure services support full text search". A consulta tem como destino o contentVector campo e retorna k resultados. O vetor real tem 1.536 inserções, que são cortadas neste exemplo para legibilidade.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2025-09-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "count": true,
    "select": "title, content, category",
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "exhaustive": true,
            "fields": "contentVector",
            "weight": 0.5,
            "k": 5
        }
    ]
}

2025-11-01-preview é a versão mais recente da API de versão prévia do Search – POST. Ele dá suporte à mesma sintaxe de consulta vetor que 2025-09-01, mas tem parâmetros extras para pesquisa híbrida e limites mínimos para excluir resultados mais fracos.

Esta versão prévia dá suporte a:

threshold para excluir resultados de baixa pontuação.
hybridSearch.MaxTextRecallSize para obter mais controle sobre as entradas para uma consulta híbrida.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "count": true,
    "select": "title, content, category",
    "hybridSearch": {
        "maxTextRecallSize": 100,
        "countAndFacetMode": "countAllResults"
        }
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "contentVector",
            "k": 5,
            "exhaustive": true,
            "weight": 2,
            "threshold": {
                "kind": "vectorSimilarity",
                "value": 0.8
            },

        }
    ]
}

Resposta de consulta de vetor

Em Pesquisa de IA do Azure , as respostas de consulta consistem em todos os campos retrievable por padrão. No entanto, é comum limitar os resultados da pesquisa a um subconjunto de retrievable campos listando-os em uma select instrução.

Em uma consulta de vetor, considere cuidadosamente se você precisa de campos vetoriais na resposta. Os campos de vetor não são legíveis por humanos, portanto, se você estiver enviando uma resposta por push para uma página da Web, deverá escolher campos não vetoriais que representem o resultado. Por exemplo, se a consulta for executada em contentVector, você poderá retornar content em vez disso.

Se você quiser campos de vetor no resultado, aqui está um exemplo da estrutura de resposta. contentVector é uma matriz de strings de embeddings, que são truncadas neste exemplo para facilitar a leitura. A pontuação de pesquisa indica relevância. Outros campos não vetoriais são incluídos para contexto.

{
    "@odata.count": 3,
    "value": [
        {
            "@search.score": 0.80025613,
            "title": "Azure Search",
            "category": "AI + Machine Learning",
            "contentVector": [
                -0.0018343845,
                0.017952163,
                0.0025753193,
                ...
            ]
        },
        {
            "@search.score": 0.78856903,
            "title": "Azure Application Insights",
            "category": "Management + Governance",
            "contentVector": [
                -0.016821077,
                0.0037742127,
                0.016136652,
                ...
            ]
        },
        {
            "@search.score": 0.78650564,
            "title": "Azure Media Services",
            "category": "Media",
            "contentVector": [
                -0.025449317,
                0.0038463024,
                -0.02488436,
                ...
            ]
        }
    ]
}

Pontos-chave:

k determina quantos resultados vizinhos mais próximos são retornados, neste caso, três. Consultas vetoriais sempre retornam k resultados, supondo que pelo menos k documentos existam, mesmo que alguns documentos tenham pouca similaridade. Isso ocorre porque o algoritmo localiza os k vizinhos mais próximos do vetor de consulta.
O algoritmo de pesquisa de vetor determina o @search.score.
Os campos nos resultados da pesquisa são todos campos do tipo retrievable ou campos em uma cláusula select. Durante a execução da consulta vetor, a correspondência é feita apenas em dados de vetor. No entanto, uma resposta pode incluir qualquer retrievable campo em um índice. Como não há nenhuma facilidade para decodificar um resultado de campo de vetor, a inclusão de campos de texto não vetor é útil para seus valores legíveis por humanos.

Vários campos de vetor

Você pode definir a vectorQueries.fields propriedade como vários campos de vetor. A consulta de vetor é executada em cada campo de vetor que você fornece na lista fields. Você pode especificar até 10 campos.

Ao consultar vários campos de vetor, verifique se cada um contém inserções do mesmo modelo de inserção. A consulta também deve ser gerada do mesmo modelo de inserção.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2025-09-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "count": true,
    "select": "title, content, category",
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "exhaustive": true,
            "fields": "contentVector, titleVector",
            "k": 5
        }
    ]
}

Várias consultas de vetor

A busca em vetores de várias consultas envia várias consultas em vários campos de vetor no índice de pesquisa. Esse tipo de consulta é comumente usado com modelos como CLIP para pesquisa multimodal, em que o mesmo modelo pode vetorizar texto e imagens.

O exemplo de consulta a seguir busca similaridade em myImageVector e myTextVector, mas envia dois embeddings de consulta respectivos, cada um sendo executado em paralelo. O resultado desta consulta é pontuado usando a fusão de classificação recíproca (RRF).

vectorQueries fornece uma matriz de consultas de vetor.
vector contém os vetores de imagem e vetores de texto no índice de pesquisa. Cada instância é uma consulta separada.
fields especifica qual campo de vetor será direcionado.
k é o número de correspondências vizinhas mais próximas a serem incluídas nos resultados.

{
    "count": true,
    "select": "title, content, category",
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "myimagevector",
            "k": 5
        },
        {
            "kind": "vector"
            "vector": [
                -0.002222222,
                0.018708462,
                -0.013770515,
            . . .
            ],
            "fields": "mytextvector",
            "k": 5
        }
    ]
}

Os índices de pesquisa não podem armazenar imagens. Supondo que seu índice inclua um campo para o arquivo de imagem, os resultados da pesquisa incluiriam uma combinação de texto e imagens.

Consulta com vetorização integrada

Esta seção mostra uma consulta de vetor que invoca a vetorização integrada para converter uma consulta de texto ou imagem em um vetor. Recomendamos a API REST estável 2025-09-01, o Search Explorer ou os pacotes SDK do Azure mais recentes para esse recurso.

Um pré-requisito é um índice de pesquisa que tem um vetorizador configurado e atribuído a um campo vetorial. O vetorizador fornece informações de conexão para um modelo de inserção usado no momento da consulta.

Portal do Azure
REST API

O Gerenciador de Pesquisa dá suporte à vetorização integrada no momento da consulta. Se o índice contiver campos vetoriais e tiver um vetorizador, você poderá usar a conversão interna de texto para vetor.

Acesse o serviço de pesquisa no Azure portal.
No menu à esquerda, selecione Gerenciamento de Pesquisa>Índices e, em seguida, selecione seu índice.
Selecione a guia Perfis de Vetor para confirmar se você tem um vetorizador.
Selecione a guia Gerenciador de Pesquisa . Usando o modo de exibição de consulta padrão, você pode inserir uma cadeia de caracteres de texto na barra de pesquisa. O vetorizar interno integra sua string em um vetor, executa a pesquisa e retorna resultados.

Como alternativa, você pode selecionar Exibir> exibiçãoJSON para exibir ou modificar a consulta. Se os vetores estiverem presentes, o Gerenciador de Pesquisa configurará uma consulta vetor automaticamente. Você pode usar a exibição JSON para selecionar campos para uso na pesquisa e resposta, adicionar filtros e construir consultas mais avançadas, como consultas híbridas. Para ver um exemplo JSON, selecione a guia API REST nesta seção.

Use Index – GET para retornar a definição de índice e verificar a presença de uma configuração de vetorizador. Procure por vectorizers em sua definição de índice. É necessário especificar um modelo de embedding implantado.
Use Pesquisa – POST para a solicitação de consulta.
- kind deve ser definido como text.
- text deve ter uma cadeia de caracteres de texto. Isso é passado para o vetorizador atribuído ao campo de vetor.
- fields é o campo de vetor a ser pesquisado.
- k é o número de correspondências de vetor a serem retornadas.

Aqui está um exemplo simples de uma consulta que é vetorizada no momento da consulta. A cadeia de caracteres de texto é vetorizada e usada para consultar o descriptionVector campo.

POST https://{{search-service}}.search.windows.net/indexes/{{index}}/docs/search?api-version=2025-09-01
{
    "select": "title, genre, description",
    "vectorQueries": [
        {
            "kind": "text",
            "text": "mystery novel set in London",
            "fields": "descriptionVector",
            "k": 5
        }
    ]
}

Aqui está uma consulta híbrida que usa a vetorização integrada para consultas de texto. Essa consulta inclui vários campos de vetor de consulta, vários campos não vetoriais, um filtro e uma classificação semântica. Novamente, as diferenças são o kind da consulta vetor e a cadeia de caracteres text em vez de um vector.

Neste exemplo, o mecanismo de pesquisa faz três chamadas de vetorização para os vetorizadores atribuídos a descriptionVector, synopsisVector e authorBioVector no índice. Os vetores resultantes são usados para recuperar documentos nos respectivos campos. O mecanismo de busca também realiza uma busca por palavra-chave na search consulta, que é "mystery novel set in London".

POST https://{{search-service}}.search.windows.net/indexes/{{index}}/docs/search?api-version=2025-09-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "search":"mystery novel set in London", 
    "searchFields":"description, synopsis", 
    "semanticConfiguration":"my-semantic-config", 
    "queryType":"semantic",
    "select": "title, author, synopsis",
    "filter": "genre eq 'mystery'",
    "vectorFilterMode": "postFilter",
    "vectorQueries": [
        {
            "kind": "text",
            "text": "mystery novel set in London",
            "fields": "descriptionVector, synopsisVector",
            "k": 50
        },
        {
            "kind": "text"
            "text": "living english author",
            "fields": "authorBioVector",
            "k": 50
        }
    ]
}

Sempre que você usar a classificação semântica com vetores, defina k como 50. O classificador semântico usa até 50 resultados de correspondência como entrada. Especificar menos de 50 priva os modelos de classificação semântica de entradas necessárias.

Os resultados pontuados de todas as quatro consultas são fundidos usando a classificação RRF. A classificação semântica secundária é invocada sobre os resultados de pesquisa fundidos apenas no searchFields impulsionando os resultados que estão mais alinhados semanticamente ao "search":"mystery novel set in London".

Nota

A vetorização ocorre durante a indexação e a consulta. Se você não precisar de agrupamento de dados e vetorização no índice, poderá ignorar etapas como a criação de um indexador, um conjunto de habilidades e uma fonte de dados. Nesse fluxo de trabalho, a vetorização é usada somente no momento da consulta para converter uma cadeia de caracteres de texto ou uma imagem em uma inserção. Você pode definir um vetorizador no índice de pesquisa para esta etapa.

Número de resultados classificados em uma resposta de consulta de vetor

Uma consulta vetor especifica o k parâmetro, que determina quantas correspondências são retornadas nos resultados. O mecanismo de pesquisa sempre retorna k o número de correspondências. Se k for maior que o número de documentos no índice, o número de documentos determinará o limite superior do que pode ser retornado.

Se você estiver familiarizado com a pesquisa de texto completo, você saberá esperar zero resultados se o índice não contiver um termo ou frase. No entanto, na pesquisa de vetor, a operação de pesquisa identifica vizinhos mais próximos e sempre retorna k resultados, mesmo que os vizinhos mais próximos não sejam semelhantes. É possível obter resultados para consultas sem sentido ou fora do tópico, especialmente se você não estiver usando prompts para definir limites. Resultados menos relevantes têm uma pontuação de similaridade pior, mas ainda são os vetores "mais próximos" se não houver nada mais próximo. Portanto, uma resposta sem resultados significativos ainda pode retornar k resultados, mas a pontuação de similaridade de cada resultado seria baixa.

Uma abordagem híbrida que inclui a pesquisa de texto completo pode atenuar esse problema. Outra solução é definir um limite mínimo na pontuação de pesquisa, mas somente se a consulta for uma consulta de vetor único pura. As consultas híbridas não são propícias a limites mínimos porque os intervalos de RRF são muito menores e mais voláteis.

Os parâmetros de consulta que afetam a contagem de resultados incluem:

"k": n resultados para consultas somente de vetor.
"top": n resultados de consultas híbridas que incluem um search parâmetro.

Ambos k e top são opcionais. Quando não especificado, o número padrão de resultados em uma resposta é 50. Você pode definir top e skip para navegar por mais resultados ou alterar a configuração padrão.

Algoritmos de classificação usados em uma consulta de vetor

A classificação dos resultados é computada por:

A métrica de similaridade.
RRF se houver vários conjuntos de resultados da pesquisa.

Métrica de similaridade

A métrica de similaridade especificada na seção de índice vectorSearch para uma consulta somente de vetor. Os valores válidos são cosine, euclideane dotProduct.

Os modelos de inserção do OpenAI do Azure usam a similaridade de cosseno. Portanto, se você estiver usando os modelos de inserção do OpenAI do Azure, cosine será a métrica recomendada. Outras métricas de classificação com suporte incluem euclidean e dotProduct.

RRF

Vários conjuntos são criados se a consulta destina-se a vários campos de vetor, executa várias consultas vetoriais em paralelo ou é um híbrido de vetor e pesquisa de texto completo, com ou sem classificação semântica.

Durante a execução da consulta, uma consulta vetor só pode ser direcionada a um índice de vetor interno. Para vários campos de vetor e várias consultas de vetor, o mecanismo de pesquisa gera várias consultas direcionadas aos respectivos índices vetoriais de cada campo. A saída é um conjunto de resultados classificados para cada consulta, que são fundidos usando RRF. Para obter mais informações, consulte Pontuação de relevância usando a fusão de classificação recíproca.

Ponderação de vetor

Adicione um weight parâmetro de consulta para especificar o peso relativo de cada consulta vetor incluída nas operações de pesquisa. Esse valor é usado ao combinar os resultados de várias listas de classificação produzidas por duas ou mais consultas vetoriais na mesma solicitação ou na parte vetor de uma consulta híbrida.

O padrão é 1,0 e o valor deve ser um número positivo maior que zero.

Os pesos são usados ao calcular as pontuações RRF de cada documento. O cálculo é feito multiplicando o valor weight contra a pontuação de classificação do documento dentro de seu respectivo conjunto de resultados.

O exemplo a seguir é uma consulta híbrida com duas cadeias de caracteres de consulta de vetor e uma cadeia de caracteres de texto. Os pesos são atribuídos às consultas vetoriais. A primeira consulta é 0,5 ou metade do peso, reduzindo a importância dela na solicitação. A segunda consulta de vetor é duas vezes mais importante.

POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2025-09-01

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my_first_vector_field", 
          "k": 10, 
          "weight": 0.5 
        },
        { 
          "kind": "vector", 
          "vector": [4.0, 5.0, 6.0], 
          "fields": "my_second_vector_field", 
          "k": 10, 
          "weight": 2.0
        } 
      ], 
      "search": "hello world" 
    }

A ponderação de vetor se aplica somente a vetores. A consulta de texto neste exemplo "hello world"tem um peso neutro implícito de 1,0. No entanto, em uma consulta híbrida, você pode aumentar ou diminuir a importância dos campos de texto definindo maxTextRecallSize.

Definir limites para excluir resultados de baixa pontuação (versão prévia)

Como a pesquisa por vizinho mais próximo sempre retorna os vizinhos k solicitados, é possível obter várias correspondências de baixa pontuação como parte do atendimento ao requisito de número k nos resultados da pesquisa. Para excluir os resultados da pesquisa de baixa pontuação, você pode adicionar um threshold parâmetro de consulta que filtra os resultados com base em uma pontuação mínima. A filtragem ocorre antes de fundir resultados de diferentes conjuntos de recall.

Esse parâmetro está em versão prévia. Recomendamos a versão prévia mais recente da API REST ( Documents – Search Post ).

Neste exemplo, todas as correspondências que pontuam abaixo de 0,8 são excluídas dos resultados da pesquisa de vetor, mesmo que o número de resultados fique abaixo k.

POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2025-11-01-preview 
    Content-Type: application/json 
    api-key: [admin key] 

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my-cosine-field", 
          "threshold": { 
            "kind": "vectorSimilarity", 
            "value": 0.8 
          } 
        }
      ]
    }

Próximas etapas

Como próxima etapa, examine exemplos de código de consulta vetor em Python, C# ou JavaScript.

Comentários

Esta página foi útil?

Last updated on 2026-04-30