Criar uma consulta vetorial no Azure AI Search

Na Pesquisa de IA do Azure, se você tiver campos de vetor em um índice de pesquisa, este artigo explicará como:

Este artigo usa REST para ilustração. Para obter exemplos de código em outros idiomas, consulte o repositório GitHub azure-search-vector-samples para soluções de ponta a ponta que incluem consultas de vetor.

Pré-requisitos

Dica

Para determinar rapidamente se o índice tem vetores, procure campos do tipo Collection(Edm.Single), com um atributo dimensions e uma atribuição vectorSearchProfile.

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

Para consultar um campo vetorial, 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 inserções no repositório azure-search-vector-samples.

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 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 "embedding" 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.vector" em uma solicitação de consulta, usando a sintaxe mostrada nas próximas seções.

A resposta real dessa chamada POST para o modelo implantado inclui 1536 inserçõ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 inserções e lidar com a resposta.

Dica

Experimente Consulta com a vetorização integrada, atualmente em versão prévia pública, para que a Pesquisa de IA do Azure manipule suas entradas e saídas de vetorização de consulta.

Solicitação de consulta vetorial

Esta seção mostra a estrutura básica de uma consulta vetorial. Você pode usar o portal do Azure, as APIs REST ou os SDKs do Azure para formular uma consulta de vetor. Se você estiver migrando de 2023-07-01-Preview, haverá alterações significativas. 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 dá suporte a:

  • vectorQueries é o constructo da busca em vetores.
  • kind definido para vector especifica que a consulta é uma matriz de vetores.
  • vector é a consulta (uma representação de vetor de texto ou uma imagem).
  • exhaustive (opcional) invoca o KNN exaustivo no momento da consulta, mesmo que o campo seja 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 tem como destino o campo contentVector. A consulta retorna k resultados. O vetor real tem 1536 inserções. Portanto, ele é cortado neste exemplo para fins de 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 da consulta vetorial

Na 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 campos retrievable listando-os em uma instrução select.

Em uma consulta de vetor, considere cuidadosamente se você precisa vetor de campos em uma 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 que não são representativos do resultado. Por exemplo, se a consulta for executada em contentVector, você poderá retornar content.

Se você quiser campos de vetor no resultado, aqui está um exemplo da estrutura de resposta. contentVector é uma matriz de cadeia de caracteres de inserções, cortada aqui para fins de brevidade. 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 principais:

  • k determina quantos resultados vizinhos mais próximos são retornados, neste caso, três. As consultas vetoriais sempre retornam k resultados, supondo que pelo menos k documentos existam, mesmo que haja documentos com pouca similaridade, pois o algoritmo encontra qualquer k vizinho mais próximo ao vetor de consulta.

  • O @search.score é determinado pelo algoritmo de busca em vetores.

  • Os campos nos resultados da pesquisa são todos retrievable campos 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 campo retrievable 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 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 se aplicam a campos de texto e numéricos filterable 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, uma consulta pode especificar filtros em outros campos no mesmo índice.

Nas versões de API mais recentes, você pode definir um modo de filtro para aplicar filtros antes ou depois da execução da consulta vetorial. Para obter uma comparação de cada modo e o desempenho esperado com base no tamanho do índice, confira Filtros em consultas vetoriais.

Dica

Se você não tiver campos de origem com texto ou valores numéricos, verifique se há metadados de documento, como propriedades LastModified ou CreatedBy, que possam ser úteis em um filtro de metadados.

2023-11-01 é a versão estável para essa API. Ele tem:

No exemplo a seguir, o vetor é uma representação dessa cadeia de caracteres de consulta: "quais serviços do Azure dão suporte à pesquisa de texto completo". A consulta tem como destino o campo contentVector. O vetor real tem 1536 inserções. Portanto, ele é cortado neste exemplo para fins de legibilidade.

Os critérios de filtro são aplicados a um campo de texto filtrado (category neste exemplo) antes que o mecanismo de pesquisa execute a consulta de vetor.

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 de vetor. A consulta de vetor é executada em cada campo de vetor que você fornece na lista fields. Ao consultar vários campos de vetor, verifique se cada um contém inserções do mesmo modelo de inserção e se a consulta também é gerada do mesmo modelo de inserçã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 busca em vetores de várias consultas envia várias consultas em vários campos de vetor no índice de pesquisa. Um exemplo comum dessa solicitação de consulta é o uso de modelos como CLIP para uma busca em vetores multimodal em que o mesmo modelo pode vetorizar conteúdo de imagem e texto.

O exemplo de consulta a seguir procura similaridade em myImageVector e myTextVector, mas envia duas inserções de consulta diferentes, respectivamente, cada uma em execução em paralelo. Essa consulta produz um resultado com pontuação usando RRF (Fusão de Classificação Recíproca).

  • vectorQueries fornece uma matriz de consultas vetoriais.
  • vector contém os vetores de imagem e os vetores de texto no índice de pesquisa. Cada instância é uma consulta separada.
  • fields especifica qual campo vetorial será direcionado.
  • k é o número de correspondências do vizinho mais próximo 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 incluem uma combinação de texto e imagens, supondo que o índice de pesquisa inclua um campo para o arquivo de imagem (um índice de pesquisa não armazena imagens).

Consultar com vetorização integrada (versão prévia)

Esta seção mostra uma consulta de vetor que invoca a nova versão prévia do recurso de vetorização integrada que converte uma consulta de texto em um vetor. Use a API REST 2023-10-01-Preview ou um pacote beta do SDK do Azure atualizado.

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.

As consultas fornecem cadeias de caracteres de texto, em vez de vetores:

  • kind deve ser definido como text.
  • text deve ter uma cadeia de caracteres de texto. Ele é passado para o vetorizador atribuído ao campo vetorial.
  • fields é o campo vetorial a ser pesquisado.

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

POST https://{{search-service}}.search.windows.net/indexes/{{index}}/docs/search?api-version=2023-10-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 a vetorização integrada de 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 vetores atribuídos a descriptionVector, synopsisVector e authorBioVector no índice. Os vetores resultantes são usados para recuperar documentos nos respectivos campos. O mecanismo de pesquisa também executa uma pesquisa de palavra-chave na consulta search, "romance misterioso ambientado em Londres".

POST https://{{search-service}}.search.windows.net/indexes/{{index}}/docs/search?api-version=2023-10-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 com pontuação de todas as quatro consultas são fundidos usando a classificação RRF. A classificação semântica secundária é invocada sobre os resultados da pesquisa fundidos, mas apenas no searchFields, aumentando os resultados que são os mais alinhados semanticamente ao "search":"mystery novel set in London".

Observação

Os vetorizadores são usados durante a indexação e a consulta. Se você não precisar de agrupamento e vetorização de dados no índice, pode ignorar etapas como a criação de um indexador, um conjunto de habilidades e uma fonte de dados. Nesse cenário, o vetorizador é usado somente no momento da consulta para converter uma cadeia de caracteres de texto em uma inserção.

Quantidade de resultados classificados em uma resposta de consulta de vetor

Uma consulta vetorial especifica o parâmetro k, que determina quantas correspondências são retornadas nos resultados. O mecanismo de pesquisa sempre retorna o número k 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, sabe que não deve esperar resultados se o índice não contiver um termo ou frase. No entanto, na busca em vetores, a operação de pesquisa está identificando vizinhos mais próximos e sempre retornará k resultados mesmo que os vizinhos mais próximos não sejam semelhantes. Portanto, é possível obter resultados para consultas sem sentido ou fora do tópico, especialmente se você não estiver usando prompts para definir limites. Os 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. Dessa forma, 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 mitigação é definir um limite mínimo na pontuação da 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 voláteis.

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

  • "k": n resultados de consultas somente de vetores
  • "top": n resultados de consultas híbridas que incluem um parâmetro "search"

Tanto "k" quanto "top" são opcionais. Não especificado, 50 é o número padrão de resultados em uma resposta. Você pode definir "top" e "skip" para percorrer mais resultados ou alterar o padrão.

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

A classificação dos resultados é calculada por uma das seguintes maneiras:

  • Métrica de similaridade
  • RRF (Fusão de Classificação Recíproca), se houver vários conjuntos de resultados da pesquisa.

Métrica de similaridade

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

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

Usando o 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 se a consulta é 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. Portanto, para vários campos vetoriais e várias consultas vetoriais, 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, os quais são fundidos usando a RRF. Para obter mais informações, consulte Pontuação de relevância usando o RRF (Reciprocal Rank Fusion).

Próximas etapas

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