Criar uma consulta vetorial no Pesquisa de IA do Azure

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

Campos de vetores de consulta
Consultar múltiplos campos vetoriais ao mesmo tempo
Definir pesos vetoriais
Consulta com vetorização integrada
Defina limiares para excluir resultados com pontuação baixa (pré-visualização)

Este artigo utiliza REST como ilustração. Depois de compreender 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 incluindo consultas vetoriais.

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 nível.
Um índice vetorial. Verifique se há uma vectorSearch secção no seu índice para confirmar a sua presença.
Opcionalmente, adicione um vetorizador ao seu índice para conversão integrada de texto para vetor ou imagem para vetor durante as consultas.
Visual Studio Code com um cliente REST e dados de amostra se quiseres executar estes exemplos sozinho. Para começar com o cliente REST, consulte Quickstart: Pesquisa em texto completo usando REST.

Converter uma entrada de cadeia de consulta num vetor

Para consultar um campo vetorial, a própria consulta deve ser um vetor.

Uma abordagem para converter a cadeia de consulta de texto de um utilizador na sua representação vetorial é chamar uma biblioteca ou API de embedding no código da sua aplicação. Como boa prática, utilize sempre os mesmos modelos de embedding usados para gerar embeddings nos documentos fonte. Pode encontrar exemplos de código que mostram como gerar embeddings no repositório azure-search-vector-samples.

Uma segunda abordagem é usar a vetorização integrada, agora geralmente disponível, para que o Pesquisa de IA do Azure possa gerir as entradas e saídas da vetorização da consulta.

Aqui está um exemplo de API REST de uma cadeia de consulta submetida a uma implementação de um modelo de embedding do Azure OpenAI:

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 é de 202 para uma chamada bem-sucedida ao modelo implantado.

O campo embedding no corpo da resposta é a representação vetorial da cadeia input de consulta. Para efeitos de teste, copiarias o valor do embedding array num vectorQueries.vector pedido de consulta, usando a sintaxe mostrada nas secções seguintes.

A resposta real a esta chamada POST ao modelo implementado 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
    }
}

Nesta abordagem, o código da sua aplicação é responsável por se ligar a um modelo, gerar embeddings e tratar da resposta.

Pedido de consulta vetorial

Esta secção mostra-lhe a estrutura básica de uma consulta vetorial. Pode usar o portal Azure, APIs REST ou os SDKs do Azure para formular uma consulta vetorial.

Se está a migrar a partir de 2023-07-01-Preview, há alterações urgentes. Para mais informações, consulte Atualizar para a API REST mais recente.

A versão estável suporta:

vectorQueries é o construto para a pesquisa vetorial.
vectorQueries.kind define para vector um array vetorial ou text se a entrada for uma cadeia e se tiveres um vetorizador.
vectorQueries.vector é a consulta (uma representação vetorial de texto ou imagem).
vectorQueries.exhaustive (opcional) invoca KNN exaustivo durante a consulta, mesmo que o campo esteja 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 vetorial incluída nas operações de pesquisa. Para mais informações, veja Ponderação vetorial.
vectorQueries.k é o número de correspondências a retornar.

No exemplo seguinte, o vetor é uma representação desta cadeia: "what Azure services support full text search". A consulta dirige-se ao contentVector campo e devolve k os resultados. O vetor real tem 1.536 embeddings, que são cortados neste exemplo para maior 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 pré-visualização do Search - POST. Suporta a mesma sintaxe de consulta vetorial de 2025-09-01, mas tem parâmetros extra para pesquisa híbrida e limiares mínimos para excluir resultados mais fracos.

Esta pré-visualização suporta:

threshold para excluir resultados com pontuação baixa.
hybridSearch.MaxTextRecallSize para mais controlo sobre as entradas de 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 a consulta vetorial

No serviço Pesquisa de IA do Azure, as respostas à query consistem de todos os campos retrievable por defeito. No entanto, é comum limitar os resultados de pesquisa a um subconjunto de retrievable campos, listando-os numa select declaração.

Numa consulta vetorial, considere cuidadosamente se precisa de vetorizar campos numa resposta. Os campos vetoriais não são legíveis por humanos, por isso, se estiveres a enviar uma resposta para uma página web, deves escolher campos não vetoriais que representem o resultado. Por exemplo, se a consulta for executada contra contentVector, pode devolver content em vez disso.

Se quiser campos vetoriais no resultado, aqui está um exemplo da estrutura de resposta. contentVector é um array de cadeias de embeddings, que são cortadas neste exemplo para legibilidade. 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, assumindo que existam pelo menos k documentos, mesmo que alguns documentos tenham pouca semelhança. Isto deve-se ao facto de o algoritmo encontrar quaisquer k vizinhos mais próximos ao vetor de consulta.
O algoritmo de pesquisa vetorial determina o @search.score.
Os campos nos resultados de pesquisa são todos retrievable campos ou campos dentro de uma cláusula select. Durante a execução de consultas vetoriais, a correspondência é feita apenas com dados vetoriais. No entanto, uma resposta pode incluir qualquer retrievable campo num índice. Como não existe uma funcionalidade para decodificar um resultado de campo vetorial, a inclusão de campos de texto não vetoriais é útil para os seus valores legíveis por humanos.

Múltiplos campos vetoriais

Podes definir a vectorQueries.fields propriedade para múltiplos campos vetoriais. A consulta vetorial é executada contra cada campo vetorial que forneces na fields lista. Pode especificar até 10 campos.

Ao consultar múltiplos campos vetoriais, certifique-se de que cada um contém embeddings do mesmo modelo de embedding. A consulta deve também ser gerada a partir do mesmo modelo de embedding.

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

Múltiplas consultas vetoriais

A pesquisa vetorial multi-consulta envia várias consultas através de vários campos vetoriais no seu índice de pesquisa. Este tipo de consulta é comumente usado em modelos como o CLIP para pesquisa multimodal, onde o mesmo modelo pode vetorizar tanto texto como imagens.

O exemplo seguinte procura similaridade em ambos myImageVector e myTextVector, mas envia dois embeddings de consulta respetivos, cada um executando em paralelo. O resultado desta consulta é pontuado usando fusão recíproca de ranking (RRF).

vectorQueries fornece um array de consultas vetoriais.
vector contém os vetores de imagem e de texto no índice de pesquisa. Cada instância é uma consulta separada.
fields especifica qual campo vetorial a direcionar.
k é o número de correspondências com vizinhos mais próximos a incluir 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 conseguem armazenar imagens. Assumindo que o seu índice inclui um campo para o ficheiro de imagem, os resultados da pesquisa incluirão uma combinação de texto e imagens.

Consulta com vetorização integrada

Esta secção mostra uma consulta vetorial que invoca a vetorização integrada para converter uma consulta de texto ou imagem num vetor. Recomendamos os pacotes estáveis 2025-09-01 REST API, Explorador de Pesquisa ou SDK do Azure mais recentes para esta funcionalidade.

Um pré-requisito é um índice de pesquisa que tenha um vetorizador configurado e atribuído a um campo vetorial. O vetorizador fornece informação de ligação a um modelo de embedding utilizado no momento da consulta.

Portal do Azure
API REST

O Explorador de Pesquisa suporta vetorização integrada no momento da consulta. Se o seu índice contiver campos vetoriais e tiver um vetorizador, pode usar a conversão incorporada de texto para vetor.

Vá ao seu serviço de pesquisa no portal Azure.
No menu da esquerda, selecione Gestão de Pesquisa>Índices e depois selecione o seu índice.
Selecione a aba Perfis Vetoriais para confirmar que possui um vetorizador.
Selecione o separador Pesquisa do Explorador. Usando a vista de consulta predefinida, pode inserir uma cadeia de texto na barra de pesquisa. O vetorizador incorporado converte a sua string num vetor, realiza a pesquisa e devolve os resultados.

Em alternativa, pode selecionar Visualizar>vista JSON para visualizar ou modificar a consulta. Se houver vetores presentes, o Explorador de Pesquisa configura automaticamente uma consulta vetorial. Pode usar a vista JSON para selecionar campos para usar na pesquisa e resposta, adicionar filtros e construir consultas mais avançadas, como consultas híbridas. Para ver um exemplo em JSON, selecione o separador da API REST nesta secção.

Use Index - GET para devolver a definição do índice e verificar a presença de uma configuração vetorizadora. Procure vectorizers na definição do seu índice. Deve especificar um modelo de embedding implementado.
Use Search - POST para o pedido de consulta.
- kind deve ser definido para text.
- text Deve ter uma cadeia de texto. É passado para o vetorizador atribuído ao campo vetorial.
- fields é o campo vetorial a pesquisar.
- k é o número de correspondências vetoriais a retornar.

Aqui está um exemplo simples de uma consulta vetorizada no momento da consulta. A cadeia de texto é vetorizada e depois 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 utiliza vetorização integrada para consultas de texto. Esta consulta inclui múltiplos campos de vetores de consulta, múltiplos campos não vetoriais, um filtro e uma classificação semântica. Mais uma vez, as diferenças são o kind de consulta vetorial e a text cadeia em vez de vector.

Neste exemplo, o motor de busca faz três chamadas de vetorização aos vetorizadores atribuídos a descriptionVector, synopsisVector, e authorBioVector no índice. Os vetores resultantes são usados para obter documentos em relação aos seus respetivos campos. O motor de busca também executa uma pesquisa 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 usares a classificação semântica com vetores, define k para 50. O ranker semântico usa até 50 partidas como entrada. Especificar menos de 50 priva os modelos semânticos de classificação das entradas necessárias.

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

Nota

A vetorização ocorre durante a indexação e a consulta. Se não precisares de fragmentação de dados e vetorização no índice, podes saltar passos como criar um indexador, conjunto de competências e fonte de dados. Neste fluxo de trabalho, a vetorização é usada apenas no momento da consulta para converter uma cadeia de texto ou uma imagem numa incorporação. Pode definir um vetorizador no índice de pesquisa para este passo.

Número de resultados classificados numa resposta vetorial a uma consulta

Uma consulta vetorial especifica o k parâmetro, que determina quantas correspondências são devolvidas nos resultados. O motor de busca devolve sempre k o número de correspondências. Se k for maior do que o número de documentos no índice, o número de documentos determina o limite superior do que pode ser devolvido.

Se está familiarizado com a pesquisa em texto completo, sabe que deve esperar zero resultados se o índice não contiver um termo ou frase. No entanto, na pesquisa vetorial, a operação de pesquisa identifica os vizinhos mais próximos e devolve k sempre os resultados, mesmo que os vizinhos mais próximos não sejam assim tão semelhantes. É possível obter resultados para consultas sem sentido ou fora do tópico, especialmente se não estiveres a usar prompts para definir limites. Resultados menos relevantes têm uma pontuação de semelhança inferior, mas continuam a ser os vetores "mais próximos" se não houver nada mais próximo. Portanto, uma resposta sem resultados significativos pode ainda devolver k resultados, mas a pontuação de semelhança de cada resultado seria baixa.

Uma abordagem híbrida que inclua pesquisa em texto completo pode mitigar este problema. Outra solução é definir um limiar mínimo na pontuação de pesquisa, mas apenas se a consulta for puramente de um único vetor. As consultas híbridas não são propícias a limiares mínimos porque os intervalos dos RRF são muito mais pequenos e voláteis.

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

"k": n resultados para consultas apenas vetoriais.
"top": n resultados para 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 numa resposta é 50. Pode definir top e skip para navegar por mais resultados ou alterar a predefinição.

Algoritmos de classificação usados numa consulta vetorial

A classificação dos resultados é calculada por:

A métrica de semelhança.
RRF se existirem vários conjuntos de resultados de pesquisa.

Métrica de similaridade

A métrica de similaridade especificada na secção de índice vectorSearch para uma consulta apenas vetorial. Os valores válidos são cosine, euclidean, e dotProduct.

Os modelos de embedding da Azure OpenAI usam similaridade cosseno, por isso, se estiver a usar modelos de embedding da Azure OpenAI, cosine é a métrica recomendada. Outras métricas de classificação suportadas incluem euclidean e dotProduct.

RRF

Múltiplos conjuntos são criados se a consulta visar múltiplos campos vetoriais, executar múltiplas consultas vetoriais em paralelo, ou for um híbrido de pesquisa vetorial e de texto completo, com ou sem classificação semântica.

Durante a execução da consulta, uma consulta vetorial só pode direcionar um índice vetorial interno. Para múltiplos campos vetoriais e múltiplas consultas vetoriais, o motor de busca gera múltiplas consultas que visam os respetivos índices vetoriais de cada campo. A saída é um conjunto de resultados ordenados para cada consulta, que são fundidos usando RRF. Para mais informações, veja Pontuação de Relevância usando Fusão de Classificação Recíproca.

Ponderação vetorial

Adicione um weight parâmetro de consulta para especificar o peso relativo de cada consulta vetorial incluída nas operações de pesquisa. Este valor é usado ao combinar os resultados de múltiplas listas de classificação produzidas por duas ou mais consultas vetoriais no mesmo pedido, ou da parte vetorial de uma consulta híbrida.

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

Os pesos são usados no cálculo das pontuações RRF de cada documento. O cálculo é um multiplicador do valor weight em relação à pontuação do ranking do documento dentro do respetivo conjunto de resultados.

O exemplo seguinte é uma consulta híbrida com duas cadeias de consulta vetorial e uma cadeia de texto. Os pesos são atribuídos às consultas vetoriais. A primeira consulta tem 0,5 ou metade do peso, reduzindo a sua importância no pedido. A segunda consulta vetorial é 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 vetorial aplica-se apenas a vetores. A consulta de texto neste exemplo, "hello world", tem um peso neutro implícito de 1.0. No entanto, numa consulta híbrida, pode aumentar ou diminuir a importância dos campos de texto definindo maxTextRecallSize.

Defina limiares para excluir resultados com pontuação baixa (pré-visualização)

Como a pesquisa por vizinhos mais próximos devolve sempre os vizinhos solicitados k , é possível obter múltiplas correspondências de baixa pontuação como parte do cumprimento do k requisito de número nos resultados da pesquisa. Para excluir resultados de pesquisa com pontuação baixa, pode adicionar um threshold parâmetro de consulta que filtra os resultados com base numa pontuação mínima. A filtragem ocorre antes de fundir os resultados de diferentes conjuntos de recuperação.

Este parâmetro está em pré-visualização. Recomendamos a versão mais recente de pré-visualização do Documents - Search Post (API REST).

Neste exemplo, todas as correspondências com pontuação inferior a 0,8 são excluídas dos resultados de pesquisa por vetor, mesmo que o número de resultados seja inferior a 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óximos passos

Como passo seguinte, reveja exemplos de código de consulta vetorial em Python, C# ou JavaScript.

Comentários

Esta página foi útil?

Last updated on 2026-04-30