Menu Docs
Página inicial do Docs
/ /

Executar queries no Vector Search

Uma query do MongoDB Vector Search tem a forma de um agregação pipeline do que utiliza como o primeiro estágio. Este guia explica $vectorSearch $vectorSearch a sintaxe, as opções e o comportamento do estágio.

$vectorSearch

O $vectorSearch estágio realiza uma pesquisa semântica para um vetor de query no campo ou campos especificados. O campo ou campos devem ser indexados como o tipo de vetor MongoDB Vector Search dentro de um índice do tipo vectorSearch.

Observação

O MongoDB Vector Search suporta ANN pesquisa em clusters que executam o MongoDB v6.0.11, v7.0.2, ou posterior e pesquisa ENN em clusters que executam o MongoDB v6.0.16, v7.0.10, v7.3.2, ou mais tarde.

Você pode executar$vectorSearchconsultas usando a interface do usuário do Atlas , mongoshe qualquer driver MongoDB .

Você também pode utilizar a Vector Search do MongoDB com implementações locais do Atlas que você cria com o Atlas CLI. Para saber mais, consulte Criar uma implantação de Atlas local.

$vectorSearch é suportado apenas em clusters Atlas que executam as seguintes versões MongoDB:

  • v6.0.11

  • v7.0.2 e posterior (incluindo RCs).

O campo que você deseja pesquisar deve ser indexado como tipo de vetor MongoDB Vector Search vector dentro de um tipo de índice vectorSearch.

Um pipeline $vectorSearch tem a seguinte forma de protótipo:

{
"$vectorSearch": {
"exact": true | false,
"filter": {<filter-specification>},
"index": "<index-name>",
"limit": <number-of-results>,
"numCandidates": <number-of-candidates>,
"path": "<field-to-search>",
"queryVector": [<array-of-numbers>],
"explainOptions": {
"traceDocumentIds": [<array-of-documentIDs>]
}
}
}

O estágio $vectorSearch recebe um documento com os seguintes campos:

Campo
Tipo
necessidade
Descrição

exact

booleano

Opcional

Isso é necessário se numCandidates for omitido.

Sinalizador que especifica se a pesquisa ENN ou ANN deve ser executada. O valor pode ser um dos seguintes:

  • false - para executar a pesquisa ANN

  • true - para executar a pesquisa ENN

Se omitido, o padrão é false.

O MongoDB Vector Search suporta pesquisa ANN em clusters que executam o MongoDB v6.0.11, v7.0.2, ou posterior e pesquisa ENN em clusters que executam o MongoDB v6.0.16, v7.0.10, v7.3.2, ou mais tarde.

Para saber mais sobre esses tipos de pesquisa, consulte Tipos de Vector Search .

filter

documento

Opcional

Expressão MQL que compara um campo indexado para ser usada como pré-filtro. Você pode aplicar filtro a valores booleanos, data, objectId, valores numéricos, string e UUID, incluindo arrays desses tipos.

Para saber quais operadores MQL o MongoDB Vector Search suporta em seu filtro, consulte Pré-filtragem da Vector Search do MongoDB .

index

string

Obrigatório

Nome do índice do MongoDB Vector Search a ser usado.

A Vector Search do MongoDB não retorna resultados se você digitar incorretamente o nome do índice ou se o índice especificado ainda não existir no cluster.

limit

número

Obrigatório

Número (somente do tipo int) de documentos para retornar nos resultados. Este valor não pode exceder o valor de numCandidates se você especificar numCandidates.

numCandidates

número

Condicional

Este campo é obrigatório se exact for false ou omitido.

Número de vizinhos mais próximos a serem utilizados durante a pesquisa. O valor deve ser menor ou igual a (<=) 10000. Você não pode especificar um número menor que o número de documentos a serem retornados (limit).

Recomendamos especificar um número pelo menos 20 vezes maior que o número de documentos a serem retornados (limit) para aumentar a precisão.

Esse padrão de solicitação excessiva é a maneira recomendada de equilibrar a latência e recall em suas pesquisas ANN, e recomendamos ajustar esse parâmetro com base no tamanho específico do seu conjunto de dados e nos requisitos de query.

Para aprender mais sobre outras variáveis que podem impactar este parâmetro, consulte Seleção de numCandidates.

path

string

Obrigatório

Campo do tipo vetor indexado para pesquisa.

queryVector

array de números

Obrigatório

Array de números de float32, vetores BSON BinData com subtipo float32, ou vetores BSON BinData com subtipo int1 ou tipo int8 que representam o vetor de consulta.

Para aprender mais sobre como gerar vetores BSON binData com subtipo float32, int8, int1, consulte Como ingerir vetores pré-quantizados.

O tamanho da array deve corresponder ao número do vetor dimensions especificado na definição de índice para o campo.

Você deve incorporar sua query com o mesmo modelo que utilizou para incorporar os dados.

Você pode executar query de suas incorporações com vetores de fidelidade total, desde que o subtipo de vetor seja o mesmo. Isso só é possível com vetores binData com subtipo float32. Se você usar qualquer outro subtipo (int8 ou int1), o MongoDB Vector Search não retornará nenhum resultado ou erro.

explainOptions

documento

Opcional

Trace uma lista de vetores (identificados por _id seus) em uma executionStats query de explicação. Você não pode utilizar esta opção explain sem. Para saber mais, consulte Explicar resultados da Vector Search do MongoDB .

explainOptions.
traceDocumentIds

array de IDs de documento

Obrigatório

Lista de documento _ids.

Ao definir um estágio, você pode usar $vectorSearch o exact campo para especificar se deseja executar uma pesquisa ANN ou ENN.

Para a pesquisa de vizinhos mais próximos aproximados (ANN), o MongoDB Vector Search encontra incorporações vetoriais em seus dados que estão mais próximas da incorporação vetorial em sua consulta com base em sua proximidade no espaço multidimensional e com base no número de vizinhos que considera. Ele usa o algoritmo Hierarchical Navigable Small Worlds e encontra as incorporações vetoriais mais semelhantes à incorporação vetorial em sua query sem examinar todos os vetores. Portanto, a pesquisaANN é ideal para consultar grandes conjuntos de dados sem filtragem significativa.

Observação

Normalmente, considera-se que a recuperação ideal para a pesquisa ANN esteja em torno de 90a95% de sobreposição nos resultados com a pesquisa ENN, mas com latência significativamente menor. Isso fornece um bom equilíbrio entre precisão e desempenho. Para conseguir isso com a Vector Search do MongoDB, ajuste o parâmetro numCandidates no momento da query.

Você deve especificar o numCandidates campo para executar a pesquisa ANN. Este campo determina quantos vizinhos mais próximos o MongoDB Vector Search considera durante a pesquisa.

Recomendamos que você especifique um numCandidates número pelo menos 20 vezes maior que o número de documentos a serem devolvidoslimit () para aumentar a precisão e reduzir as discrepâncias entre os resultados da consulta ENN e ANN. Por exemplo, se você limit definir para retornar 5 resultados, considere definir numCandidates 100 como como ponto de partida. Para saber mais, consulte Como medir a precisão dos resultados da sua query.

Esse padrão de solicitação excessiva é a maneira recomendada de compensar a latência e a recuperação em suas pesquisas de ANN. No entanto, recomendamos ajustar o numCandidates parâmetro com base no tamanho específico do conjunto de dados e nos requisitos de query. Para garantir que você obtenha resultados precisos, considere as seguintes variáveis:

  • Tamanho do índice: coleções maiores normalmente exigem valores de numCandidates mais altos para manter o recall. Uma coleção com milhões de vetores pode precisar de muito mais candidatos do que uma com milhares de vetores.

  • Valor-limite: como numCandidates está altamente correlacionado com o tamanho do índice, valores baixos de limit exigem valores proporcionalmente mais altos de numCandidates para manter o recall.

  • Quantização de vetores: vetores quantizados reduzem o armazenamento ao custo da precisão. O uso de vetores quantizados (subtipos int8 ou int1) pode exigir valores de numCandidates mais altos em comparação com vetores de precisão total float32 para manter um recall semelhante.

Para uma pesquisa de vizinhos mais próximos exatos (ENN), a Vector Search do MongoDB pesquisa exaustivamente todas as incorporações de vetor indexadas calculando a distância entre todas as incorporações e encontra o vizinho mais próximo exato para a incorporação do vetor em sua consulta. Isso é computacionalmente intensivo e pode impacto negativamente a latência da query. Portanto, recomendamos pesquisas ENN para os seguintes casos de uso:

  • Você deseja determinar o recall e a precisão da query ANN usando os resultados ideais e exatos para a query ENN.

  • Você deseja executar queries de menos de documentos 10000 sem precisar ajustar o número de vizinhos mais próximos a serem considerados.

  • Você deseja incluir pré-filtros seletivos em sua query em relação a coleções em que menos de 5% dos seus dados atendem ao pré-filtro fornecido.

Se você ativar a quantização automática, o MongoDB Vector Search usará somente os vetores de fidelidade total para consultas ENN.

  • $vectorSearch deve ser o primeiro estágio de qualquer pipeline onde aparece.

$vectorSearch não pode ser usado na definição de exibição e nos seguintes estágios de pipeline:

[1] Você pode passar os resultados de para este $vectorSearch estágio.

Você deve indexar os campos a serem pesquisados usando o $vectorSearch estágio dentro de uma definição de índice do tipo vectorSearch. Você pode indexar os seguintes tipos de campos em uma definição de índice do tipo vectorSearch do MongoDB Vector Search :

  • Campos que contêm incorporações vetoriais como tipo de vetor.

  • Campos adicionais, como o tipo de filtro para viabilizar a pesquisa vetorial em dados pré-filtrados.

Para saber mais sobre esses tipos de campo do MongoDB Vector Search, consulte Como indexar campos para o Vector Search.

O MongoDB Vector Search atribui uma pontuação, em um intervalo fixo de 0 a 1 (onde 0 indica baixa similaridade e 1 indica alta similaridade), a cada documento retornado.

A pontuação é calculada de acordo com a similarity função que você especifica na definição de índice do MongoDB Vector Search . Para saber mais sobre as similarity opções de que você pode escolher, consulte Sobre as funções de similaridade.

Cada documento retornado inclui a pontuação como metadados. Para retornar a pontuação de cada documento junto com o conjunto de resultados, use um estágio em seu pipeline de agregação e configure $project o score como um campo para projeto. No score campo, especifique uma expressão $meta com o vectorSearchScore valor. A sintaxe é a seguinte:

1db.<collection>.aggregate([
2 {
3 "$vectorSearch": {
4 <query-syntax>
5 }
6 },
7 {
8 "$project": {
9 "<field-to-include>": 1,
10 "<field-to-exclude>": 0,
11 "score": { "$meta": "vectorSearchScore" }
12 }
13 }
14])

Observação

Você pode usar vectorSearchScore como uma score expressão $meta somente após o $vectorSearch estágio do pipeline. Se você utilizar vectorSearchScore após qualquer outra query, o MongoDB registrará um aviso começando no MongoDB v..82

Observação

A pré-filtragem de seus dados não afeta a pontuação que o MongoDB Vector Search retorna usando vectorSearchScore para $vectorSearch consultas.

A opção filter $vectorSearch corresponde aos valores booleanos, data, objectId, valores numéricos, de string e UUID do BSON, incluindo arrays desses tipos.

Você deve indexar os campos nos quais deseja filtrar os dados como tipo de filtro em uma definição de índice do tipo vectorSearch. É útil filtrar os dados para restringir o escopo da pesquisa semântica e garantir que nem todos os vetores sejam considerados para comparação.

O MongoDB Vector Search suporta a opção $vectorSearch filter para os seguintes operadores MQL:

Tipo
Operador MQL

Igualdade

faixa

No conjunto

Existência

Lógica

  • O MongoDB Vector Search suporta a forma abreviada de $eq. Na forma abreviada, você não precisa especificar $eq na query.

    Por exemplo, considere o seguinte filtro com $eq:

    "filter": { "_id": { "$eq": ObjectId("5a9427648b0beebeb69537a5") }

    Isso equivale ao seguinte filtro, que usa a forma abreviada de $eq:

    "filter": { "_id": ObjectId("5a9427648b0beebeb69537a5") }
  • Você pode usar o operador $and de MQL para especificar uma array de filtros em uma única query.

    Por exemplo, considere o seguinte pré-filtro para documentos com um campo genres igual a Action e um campo year com o valor 1999, 2000 ou 2001:

    "filter": {
    "$and": [
    { "genres": "Action" },
    { "year": { "$in": [ 1999, 2000, 2001 ] } }
    ]
    }
  • Para recursos avançados de filtragem, como pesquisa difusa, correspondência de frases, filtragem de localização e outros textos analisados, use o operador vectorSearch em um $search estágio.

Recomendamos nós de pesquisa dedicados para isolar o processamento de query de pesquisa vetorial. Você poderá ver o desempenho aprimorado da consulta nos nós de pesquisa dedicados. Observe que os sistemas de alta CPU podem fornecer mais melhorias de desempenho. Quando o MongoDB Vector Search é executado em nós de pesquisa, o MongoDB Vector Search paraleliza a execução da query em segmentos de dados.

A paralelização do processamento de queries melhora o tempo de resposta em muitos casos, como queries em grandes conjuntos de dados. O uso do paralelismo intraquery durante o processamento de query do MongoDB Vector Search utiliza mais recursos, mas melhora a latência para cada query individual.

Observação

A Vector Search do MongoDB não garante que cada query seja executada simultaneamente. Por exemplo, quando muitas queries simultâneas são enfileiradas, o MongoDB Vector Search pode voltar para a execução de thread único.

Você pode ver resultados inconsistentes para as mesmas queries sucessivas. Para atenuar isso, aumente o valor de numCandidates nas queries $vectorSearch.

As consultas a seguir pesquisam a coleção sample_mflix.embedded_movies usando o estágio. As consultas pesquisam $vectorSearch no plot_embedding_voyage_3_large campo , que contém incorporações criadas usando o voyage-3-large modelo de incorporação da Voyage AI.

Antes de executar estes exemplos, realize as seguintes ações:

Observação

Se você usar mongosh, colar o queryVector do código de amostra no seu terminal pode levar algum tempo, dependendo da sua máquina.

A query abaixo usa o estágio $vectorSearch para pesquisar o campo plot_embedding_voyage_3_large usando incorporações vetoriais para a string viagem no tempo. Ela considera até 150 vizinhos mais próximos, e retorna 10 documentos nos resultados. A query também especifica um estágio $project para fazer o seguinte:

  • Excluir o campo _id e inclua somente os campos plot e title nos resultados.

  • Adicione um campo chamado score que exibe a pontuação da pesquisa vetorial para cada documento nos resultados.

A query a seguir filtra os documentos para filmes lançados entre 01 de janeiro de 1955 e 01 de janeiro de 1975 antes de executar o Atlas Search semântica em relação aos dados vetoriais de amostra. Utiliza o operador $and para executar uma operação lógica AND das datas especificadas. Em seguida, ele pesquisa o campo plot_embedding_voyage_3_large nos documentos filtrados para 150 vizinhos mais próximos usando as incorporações vetoriais para a string playground e retorna 10 documentos nos resultados. A consulta também especifica um estágio $project para fazer o seguinte:

  • Exclua o campo _id e inclua apenas os campos plot, title e year nos resultados.

  • Adicione um campo denominado score que mostra a pontuação do Atlas Vector Search dos documentos nos resultados.

O MongoDB Vector Search filtra os documentos com base no valor do campo year, que varia entre 1955 e 1975. Ela retorna documentos que resumem as aventuras infantis na trama de filmes lançados entre 1955 e 1975.

Dica

Exemplos adicionais de filtro

O tutorial Como realizar uma pesquisa semântica em dados em seu cluster Atlas demonstra outros pré-filtros em queries de pesquisa semântica em relação aos dados incorporados na coleção sample_mflix.embedded_movies.

A query abaixo usa o estágio $vectorSearch para pesquisar o campo plot_embedding_voyage_3_large usando incorporações vetoriais para a string guerra mundial. Ele solicita correspondências exatas e limita os resultados apenas aos documentos 10. A query também especifica um estágio $project para fazer o seguinte:

  • Exclua o campo _id e inclua somente os campos plot, title e year nos resultados.

  • Adicione um campo denominado score que mostra a pontuação do Atlas Vector Search dos documentos nos resultados.

Voltar

Referência de índice

Receber um selo de habilidade

Domine os "Fundamentos da pesquisa vetorial" gratuitamente!

Saiba mais

Nesta página