Criar uma consulta vetorial no Azure AI Search
No Azure AI Search, se você tiver um índice de vetor, este artigo explica como:
Este artigo usa REST para ilustração. Para exemplos de código em outros idiomas, consulte o repositório GitHub azure-search-vector-samples para obter soluções de ponta a ponta que incluem consultas vetoriais.
Você também pode usar o explorador de Pesquisa no portal do Azure se configurar um vetorizador que converte cadeias de caracteres em incorporações.
Pré-requisitos
Azure AI Search, em qualquer região e em qualquer camada.
Um índice vetorial no Azure AI Search. Verifique se há uma
vectorSearchseção no seu índice para confirmar um índice vetorial.Código do Visual Studio com um cliente REST e dados de exemplo se você quiser executar esses exemplos por conta própria. Para começar a usar o cliente REST, consulte Guia de início rápido: Azure AI Search usando REST.
Converter uma entrada de cadeia de caracteres de consulta em um vetor
Para consultar um campo vetorial, a própria consulta deve ser um vetor.
Uma abordagem para converter a cadeia de caracteres de consulta de texto de um usuário em sua representação vetorial é chamar uma biblioteca de incorporação ou API no código do aplicativo. Como prática recomendada, use sempre os mesmos modelos de incorporação usados para gerar incorporações nos documentos de origem. Você pode encontrar exemplos de código mostrando como gerar incorporações no repositório azure-search-vector-samples.
Uma segunda abordagem é usar a vetorização integrada, atualmente em visualização pública, para que o Azure AI Search manipule suas entradas e saídas de vetorização de consulta.
Aqui está um exemplo de API REST de uma cadeia de caracteres de consulta enviada para uma implantação de um modelo de incorporação 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 é 202 para uma chamada bem-sucedida para o modelo implantado.
O campo "incorporação" no corpo da resposta é a representação vetorial da cadeia de caracteres de consulta "input". Para fins de teste, você copiaria o valor da matriz "embedding" em "vectorQueries.vetor" em uma solicitação de consulta, usando a sintaxe mostrada nas próximas seções.
A resposta real para esta chamada POST para o modelo implantado inclui 1536 incorporações, cortadas aqui apenas para os primeiros vetores para legibilidade.
{
"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 incorporações e manipular a resposta.
Solicitação de consulta vetorial
Esta seção mostra a estrutura básica de uma consulta vetorial. Você pode usar o portal do Azure, APIs REST ou os SDKs do Azure para formular uma consulta vetorial. Se você estiver migrando de 2023-07-01-Preview, há alterações de quebra. Consulte Atualizar para a API REST mais recente para obter detalhes.
2023-11-01 é a versão estável da API REST para Search POST. Esta versão suporta:
vectorQueriesé a construção para pesquisa vetorial.kindDefina comovectorEspecifica que a consulta é uma matriz vetorial.vectoré consulta (uma representação vetorial de texto ou imagem).exhaustive(opcional) invoca KNN exaustivo no momento da consulta, mesmo que o campo esteja indexado para HNSW.
No exemplo a seguir, o vetor é uma representação dessa cadeia de caracteres: "quais serviços do Azure dão suporte à pesquisa de texto completo". A consulta destina-se ao contentVector campo. A consulta retorna k resultados. O vetor real tem 1536 incorporações, por isso é cortado neste exemplo para legibilidade.
POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2023-11-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",
"k": 5
}
]
}
Resposta de consulta vetorial
No Azure AI Search, as respostas da consulta consistem em todos os retrievable campos 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 vetorial, considere cuidadosamente se você precisa vetar campos em uma resposta. Os campos vetoriais não são legíveis por humanos, portanto, se você estiver enviando uma resposta para uma página da Web, deverá escolher campos não vetoriais que sejam representativos do resultado. Por exemplo, se a consulta for executada contra contentVector, você poderá retornar content em vez disso.
Se você quiser campos vetoriais no resultado, aqui está um exemplo da estrutura de resposta. contentVector é uma matriz de cadeia de caracteres de incorporações, cortada aqui para brevidade. A pontuação da 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 principais:
kdetermina quantos resultados do vizinho mais próximo são retornados, neste caso, três. As consultas vetoriais sempre retornamkresultados, supondo que pelo menoskos documentos existam, mesmo que haja documentos com pouca semelhança, porque o algoritmo encontra oskvizinhos mais próximos do vetor de consulta.O
@search.scoreé determinado pelo algoritmo de pesquisa vetorial.Os campos nos resultados da pesquisa são todos os
retrievablecampos ou campos de umaselectcláusula. Durante a execução da consulta vetorial, a correspondência é feita apenas em dados vetoriais. No entanto, uma resposta pode incluir qualquerretrievablecampo em um índice. Como não há nenhuma facilidade para decodificar um resultado de campo vetorial, a inclusão de campos de texto não vetoriais é útil para seus valores legíveis por humanos.
Consulta vetorial com filtro
Uma solicitação de consulta pode incluir uma consulta vetorial e uma expressão de filtro. Os filtros aplicam-se a filterable campos não vetoriais, um campo de cadeia de caracteres ou numéricos, e são úteis para incluir ou excluir documentos de pesquisa com base em critérios de filtro. Embora um campo vetorial não seja filtrável em si, os filtros podem ser aplicados a outros campos no mesmo índice.
Você pode aplicar filtros como critérios de exclusão antes da execução da consulta ou após a execução da consulta para filtrar os resultados da pesquisa. Para obter uma comparação de cada modo e o desempenho esperado com base no tamanho do índice, consulte Filtros em consultas vetoriais.
Gorjeta
Se você não tiver campos de origem com texto ou valores numéricos, verifique se há metadados do documento, como as propriedades LastModified ou CreatedBy, que podem ser úteis em um filtro de metadados.
2023-11-01 é a versão estável para esta API. Dispõe de:
vectorFilterModepara os modos de filtragem pré-filtro (padrão) ou pós-filtro.filterfornece os critérios.
No exemplo a seguir, o vetor é uma representação dessa cadeia de caracteres de consulta: "quais serviços do Azure oferecem suporte à pesquisa de texto completo". A consulta destina-se ao contentVector campo. O vetor real tem 1536 incorporações, por isso é cortado neste exemplo para legibilidade.
Os critérios de filtro são aplicados a um campo de texto filtrável (category neste exemplo) antes que o mecanismo de pesquisa execute a consulta vetorial.
POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2023-11-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
"count": true,
"select": "title, content, category",
"filter": "category eq 'Databases'",
"vectorFilterMode": "preFilter",
"vectorQueries": [
{
"kind": "vector",
"vector": [
-0.009154141,
0.018708462,
. . .
-0.02178128,
-0.00086512347
],
"exhaustive": true,
"fields": "contentVector",
"k": 5
}
]
}
Vários campos vetoriais
Você pode definir a propriedade "vectorQueries.fields" como vários campos vetoriais. A consulta vetorial é executada em relação a cada campo vetorial fornecido na fields lista. Ao consultar vários campos vetoriais, verifique se cada um contém incorporações do mesmo modelo de incorporação e se a consulta também é gerada a partir do mesmo modelo de incorporação.
POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2023-11-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 vetoriais
A pesquisa vetorial de várias consultas envia várias consultas em vários campos vetoriais no seu índice de pesquisa. Um exemplo comum dessa solicitação de consulta é ao usar modelos como CLIP para uma pesquisa vetorial multimodal onde o mesmo modelo pode vetorizar conteúdo de imagem e texto.
O exemplo de consulta a seguir procura semelhança em ambos e myImageVectormyTextVector, mas envia duas incorporações de consulta diferentes, respectivamente, cada uma sendo executada em paralelo. Esta consulta produz um resultado que é pontuado usando Reciprocal Rank Fusion (RRF).
vectorQueriesfornece uma matriz de consultas vetoriais.vectorContém os vetores de imagem e de texto no índice de pesquisa. Cada instância é uma consulta separada.fieldsEspecifica qual campo de vetor segmentar.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 resultados da pesquisa incluiriam uma combinação de texto e imagens, supondo que seu índice de pesquisa inclua um campo para o arquivo de imagem (um índice de pesquisa não armazena imagens).
Consulta com vetorização integrada (visualização)
Esta seção mostra uma consulta vetorial que invoca o novo recurso de visualização de vetorização integrada que converte uma consulta de texto em um vetor. Use a API REST 2023-10-01-Preview e APIs REST de visualização mais recentes ou um pacote beta atualizado do SDK do Azure.
Um pré-requisito é um índice de pesquisa com um vetorizador configurado e atribuído a um campo vetorial. O vetorizador fornece informações de conexão para um modelo de incorporação usado no momento da consulta. Verifique a definição do índice para uma especificação de vetorizadores.
As consultas fornecem cadeias de texto em vez de vetores:
kinddeve ser definido comotext.textdeve ter uma cadeia de caracteres de texto. É passado para o vetorizador atribuído ao campo vetorial.fieldsé o campo vetorial a pesquisar.
Aqui está um exemplo simples de uma consulta vetorizada no momento da consulta. A cadeia de caracteres de texto é vetorizada e, em seguida, usada para consultar o campo descriptionVector.
POST https://{{search-service}}.search.windows.net/indexes/{{index}}/docs/search?api-version=2024-05-01-preview
{
"select": "title, genre, description",
"vectorQueries": [
{
"kind": "text",
"text": "mystery novel set in London",
"fields": "descriptionVector",
"k": 5
}
]
}
Aqui está uma consulta híbrida usando vetorização integrada de consultas de texto. Esta consulta inclui vários campos vetoriais de consulta, vários campos não vetoriais, um filtro e classificação semântica. Novamente, as diferenças são a kind de consulta vetorial e a text cadeia de caracteres em vez de um vectorarquivo .
Neste exemplo, o mecanismo de pesquisa faz três chamadas de vetorização para os vetorizadores atribuídos a descriptionVector, synopsisVectore authorBioVector no índice. Os vetores resultantes são usados para recuperar documentos em seus respetivos campos. O motor de busca também executa uma pesquisa por palavra-chave na consulta, "romance de mistério ambientado search em Londres".
POST https://{{search-service}}.search.windows.net/indexes/{{index}}/docs/search?api-version=2024-05-01-preview
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": 5
},
{
"kind": "text"
"text": "living english author",
"fields": "authorBioVector",
"k": 5
}
]
}
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, mas apenas sobre os resultados que estão mais alinhados semanticamente com o "search":"mystery novel set in London"searchFields .
Nota
Os vetorizadores são usados durante a indexação e consulta. Se você não precisar de fragmentação e vetorização de dados no índice, poderá ignorar etapas como a criação de um indexador, conjunto de habilidades e fonte de dados. Nesse cenário, o vetorizador é usado somente no momento da consulta para converter uma cadeia de caracteres de texto em uma incorporação.
Número de resultados classificados em uma resposta de consulta vetorial
Uma consulta vetorial especifica o k parâmetro, que determina quantas correspondências são retornadas nos resultados. O motor de busca devolve k sempre 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 estiver familiarizado com a pesquisa de texto completo, sabe que espera zero resultados se o índice não contiver um termo ou frase. No entanto, na pesquisa vetorial, a operação de pesquisa está identificando os vizinhos mais próximos e sempre retornará k resultados, mesmo que os vizinhos mais próximos não sejam tão semelhantes. Assim, é 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 semelhança pior, mas ainda são os vetores "mais próximos" se não houver nada mais próximo. Como tal, 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 inclua pesquisa de texto completo pode atenuar esse problema. Outra atenuação é definir um limite mínimo na pontuação de pesquisa, mas apenas 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 RRF são muito menores e voláteis.
Os parâmetros de consulta que afetam a contagem de resultados incluem:
"k": nResultados para consultas somente vetoriais"top": nResultados para consultas híbridas que incluem um parâmetro de "pesquisa"
Tanto "k" como "top" são opcionais. Não especificado, o número padrão de resultados em uma resposta é 50. Você pode definir "top" e "skip" para a página através de mais resultados ou alterar o padrão.
Algoritmos de classificação usados em uma consulta vetorial
A classificação dos resultados é calculada por:
- Métrica de semelhança
- Reciprocal Rank Fusion (RRF) se houver vários conjuntos de resultados de pesquisa.
Métrica de semelhança
A métrica de similaridade especificada na seção de índice vectorSearch para uma consulta somente vetor. Os valores válidos são cosine, euclideane dotProduct.
Os modelos de incorporação do Azure OpenAI usam semelhança cosseno, portanto, se você estiver usando modelos de incorporação do Azure OpenAI, cosine é a métrica recomendada. Outras métricas de classificação suportadas incluem euclidean e dotProduct.
Usando RRF
Vários conjuntos são criados se a consulta tiver como alvo vários campos vetoriais, executar várias consultas vetoriais em paralelo ou se a consulta 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 ter como destino um índice de vetor interno. Assim, para vários campos vetoriais e várias consultas vetoriais, o mecanismo de pesquisa gera várias consultas que visam os respetivos í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 Reciprocal Rank Fusion (RRF).
Definir limites para excluir resultados de baixa pontuação (visualização)
Como a pesquisa de vizinhos mais próximos sempre retorna os vizinhos solicitados k , é possível obter várias correspondências de pontuação baixa como parte do cumprimento do k requisito de número nos resultados da pesquisa.
Usando as APIs REST 2024-05-01-preview, agora você pode adicionar um threshold parâmetro de consulta para excluir resultados de pesquisa de baixa pontuação com base em uma pontuação mínima. A filtragem ocorre antes da fusão dos resultados de diferentes conjuntos de recordação.
Neste exemplo, todas as correspondências com pontuação inferior a 0,8 são excluídas dos resultados da pesquisa vetorial, mesmo que o número de resultados seja inferior ka .
POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2024-05-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
}
}
]
}
MaxTextSizeRecall para pesquisa híbrida (visualização)
As consultas vetoriais são frequentemente usadas em construções híbridas que incluem campos não vetoriais. Se você descobrir que os resultados classificados como BM25 estão mais ou menos representados em uma consulta híbrida, poderá definir maxTextRecallSize para aumentar ou diminuir os resultados classificados como BM25 fornecidos para a classificação híbrida.
Você só pode definir essa propriedade em solicitações híbridas que incluem componentes "search" e "vectorQueries".
Para obter mais informações, consulte Definir maxTextRecallSize - Criar uma consulta híbrida.
Ponderação vetorial (pré-visualização)
Adicione um weight parâmetro de consulta para especificar o peso relativo de cada consulta vetorial 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 da parte vetorial 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 para calcular as pontuações de fusão de classificação recíproca de cada documento. O cálculo é multiplicador do weight valor em relação à pontuação de classificação do documento dentro do seu respetivo conjunto de resultados.
O exemplo a seguir é uma consulta híbrida com duas cadeias de caracteres 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.
As consultas de texto não têm parâmetros de peso, mas você pode aumentar ou diminuir sua importância definindo maxTextRecallSize.
POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2024-05-01-Preview
{
"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"
}
Próximos passos
Como próxima etapa, revise exemplos de código de consulta vetorial em Python, C# ou JavaScript.
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários