Criar uma consulta vetorial no Azure AI Search

No Azure AI Search, se você tiver um índice de vetor, este artigo explica como:

• Campos de vetor de consulta.
• Consulte vários campos vetoriais de uma só vez.
• Defina pesos vetoriais.
• Consulta com vetorização integrada.
• Defina limites para excluir resultados de baixa pontuação (visualização).

Este artigo usa REST para ilustração. Depois de entender o fluxo de trabalho básico, continue com os exemplos de código do 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 o Gerenciador de Pesquisa no portal do Azure.

Pré-requisitos

• Um serviço Azure AI Search em qualquer região e em qualquer camada.

• Um índice vetorial. Verifique se há uma vectorSearch seção no seu índice para confirmar sua presença.

• Opcionalmente, adicione um vetorizador ao seu índice para conversão interna de texto para vetor ou de imagem para vetor durante as consultas.

• 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: pesquisa de texto completo 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 vetorização integrada, agora disponível em geral, 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 embedding campo no corpo da resposta é a representação vetorial da cadeia de caracteres de consulta input. Para fins de teste, copiaria o valor do array embedding para a vectorQueries.vector numa 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 incorporações. Para facilitar a leitura, 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 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. Para obter mais informações, consulte Atualizar para a API REST mais recente.

2024-07-01

2024-07-01 é a versão estável da API REST do Search POST. Esta versão suporta:

• vectorQueries é a construção para pesquisa vetorial.
• vectorQueries.kind Defina como vector para uma matriz vetorial ou text se a entrada for uma cadeia de caracteres e se você tiver um vetorizador.
• vectorQueries.vector é a consulta (uma representação vetorial de texto ou imagem).
• vectorQueries.exhaustive (opcional) invoca KNN exaustivo no momento da consulta, mesmo que o campo esteja indexado para HNSW.
• vectorQueries.fields (opcional) destina-se a campos específicos para execução de consultas (até 10 por consulta).
• vectorQueries.weight (opcional) especifica o peso relativo de cada consulta vetorial incluída nas operações de pesquisa. Para obter mais informações, consulte Ponderação vetorial.
• vectorQueries.k é o número de correspondências a retornar.

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

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2024-07-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
        }
    ]
}

2024-05-01-pré-visualização

2024-05-01-preview é a versão de API de visualização mais recente de Pesquisa - POST. Ele suporta a mesma sintaxe de consulta vetorial que 2024-07-01, mas tem parâmetros extras para pesquisa híbrida e limites mínimos para excluir resultados mais fracos.

Esta pré-visualização adiciona:

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

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

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2024-05-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
            },

        }
    ]

Portal do Azure

Use o Search Explorer para formular uma consulta vetorial. O Gerenciador de Pesquisa tem o modo de exibição de consulta e o modo de exibição JSON. Se você tiver um vetorizador, poderá usar o modo de exibição de consulta, que é descrito na seção Consulta com vetorização integrada deste artigo.

Caso contrário, se você não tiver um vetorizador, deverá usar a exibição JSON e formular a consulta vetorial em JSON colando uma matriz vetorial como a entrada de consulta.

1. Entre no portal do Azure e encontre seu serviço de pesquisa.

2. No menu à esquerda, selecione Gestão de pesquisa>Índices e, em seguida, selecione o seu índice.

   

3. Na guia Gerenciador de pesquisa , selecione Exibir>modo de exibição JSON.

   

4. Escolha a versão da API desejada.

5. Cole em uma consulta vetorial JSON e selecione Pesquisar.

   

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 representem o 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 é um array de strings de incorporações, que foram truncadas neste exemplo para facilitar a leitura. 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:

• k determina quantos resultados do vizinho mais próximo são retornados, neste caso, três. As consultas vetoriais sempre retornam k resultados, supondo que pelo menos k os documentos existam, mesmo que alguns documentos tenham pouca semelhança. Isso ocorre porque o algoritmo encontra os k vizinhos mais próximos do vetor de consulta.

• O algoritmo de pesquisa vetorial determina o @search.score.

• Os campos nos resultados da pesquisa são todos campos retrievable ou campos de uma cláusula select. Durante a execução da consulta vetorial, a correspondência é feita apenas em dados vetoriais. No entanto, uma resposta pode incluir qualquer retrievable campo 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.

Vários campos vetoriais

Você pode definir a vectorQueries.fields propriedade como vários campos vetoriais. A consulta vetorial é executada em relação a cada campo vetorial fornecido na fields lista. Você pode especificar até 10 campos.

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

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2024-07-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. Este tipo de consulta é comumente usado com modelos como CLIP para pesquisa multimodal, onde o mesmo modelo pode vetorizar texto e imagens.

Exemplo de consulta a seguir procura semelhança em ambos myImageVector e myTextVector, mas envia duas incorporações de consulta respetivas, que são executadas em paralelo. Este resultado da consulta é avaliado utilizando a fusão de classificação recíproca (RRF).

• vectorQueries fornece uma matriz 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 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 í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 vetorial que invoca a vetorização integrada para converter uma consulta de texto ou imagem em um vetor. Recomendamos a API REST estável 2024-07-01 , o Search Explorer ou pacotes mais recentes do SDK do Azure para esse recurso.

Um pré-requisito é um índice de pesquisa que tenha 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.

Portal do Azure

O Search Explorer oferece 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 em vetor.

1. Entre no portal do Azure e encontre seu serviço de pesquisa.

2. No menu à esquerda, selecione Gestão de pesquisa>Índices e, em seguida, selecione o seu índice.

3. Selecione a guia Perfis de vetor para confirmar que você tem um vetorizador.

   

4. 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 vetorizador integrado converte sua cadeia de caracteres em um vetor, executa a pesquisa e retorna resultados.

   Como alternativa, você pode selecionar Exibir>exibição JSON para exibir ou modificar a consulta. Se houver vetores, o Search Explorer configurará uma consulta vetorial automaticamente. Você pode usar o modo de exibição JSON para selecionar campos para uso na pesquisa e na 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.

API REST

1. Use Index - GET para retornar a definição de índice e verificar a presença de uma configuração de vetorizador. Procure na sua definição de vectorizers índice. Ele deve especificar um modelo de incorporação implantado.

2. Use Pesquisar - POST para a solicitação de consulta.

   • kind deve ser definido como text.
   • text deve ter uma cadeia de caracteres 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 serem retornadas.

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 descriptionVector campo.

POST https://{{search-service}}.search.windows.net/indexes/{{index}}/docs/search?api-version=2024-07-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 vetorização integrada para 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 search consulta, que é "mystery novel set in London".

POST https://{{search-service}}.search.windows.net/indexes/{{index}}/docs/search?api-version=2024-07-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 utilizar a classificação semântica com vetores, defina k como 50. O classificador semântico usa até 50 correspondências como entrada. Especificar menos de 50 priva os modelos de classificação semântica das 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 no searchFields único, impulsionando os resultados que são os mais alinhados semanticamente ao "search":"mystery novel set in London".

Nota

A vetorização ocorre 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. Neste fluxo de trabalho, a vetorização é usada somente no momento da consulta para converter uma cadeia de texto ou uma imagem em uma incorporação. Você pode definir um vetorizador no índice de pesquisa para esta etapa.

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 você está familiarizado com a pesquisa de texto completo, sabe esperar resultados zero 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 sempre retorna k resultados, mesmo que os vizinhos mais próximos não sejam tão 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 semelhança 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 inclua pesquisa de texto completo pode atenuar esse problema. Outra soluçã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 mais voláteis.

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

• "k": n resultados para consultas somente 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 em uma resposta é 50. Você pode definir top e skip para percorrer mais resultados ou alterar a configuração padrão.

Algoritmos de classificação usados em uma consulta vetorial

A classificação dos resultados é calculada por:

• A métrica de semelhança.
• 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.

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 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. 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 o Reciprocal Rank Fusion.

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. 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 RRF de cada documento. O cálculo é um multiplicador do valor em relação à weight 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.

POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2024-07-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 aos 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 (visualização)

Como a pesquisa de vizinhos mais próximos sempre retorna os vizinhos solicitadosk, é possível obter várias correspondências de baixa pontuação como parte do cumprimento do requisito de quantidadek nos resultados da pesquisa. Para excluir resultados de 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 da fusão dos resultados de diferentes conjuntos de recordação.

Este parâmetro está em pré-visualização. Recomendamos a versão 2024-05-01-preview da API REST.

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 incluam componentes search e vectorQueries ambos.

Este parâmetro está em pré-visualização. Recomendamos a versão 2024-05-01-preview da API REST.

Para obter mais informações, consulte Definir maxTextRecallSize - Criar uma consulta híbrida.

Próximos passos

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