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.
$vectorSearchO
$vectorSearchestá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.
Clientes aceitos
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).
Sintaxe
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>] } } }
Campos
O estágio $vectorSearch recebe um documento com os seguintes campos:
Campo | Tipo | necessidade | Descrição |
|---|---|---|---|
| booleano | Opcional | Isso é necessário se Sinalizador que especifica se a pesquisa ENN ou ANN deve ser executada. O valor pode ser um dos seguintes:
Se omitido, o padrão é 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 . |
| 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 . |
| 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. |
| número | Obrigatório | Número (somente do tipo |
| número | Condicional | Este campo é obrigatório se Número de vizinhos mais próximos a serem utilizados durante a pesquisa. O valor deve ser menor ou igual a ( Recomendamos especificar um número pelo menos 20 vezes maior que o número de documentos a serem retornados ( 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 |
| string | Obrigatório | Campo do tipo vetor indexado para pesquisa. |
| array de números | Obrigatório | Array de números de Para aprender mais sobre como gerar vetores BSON O tamanho da array deve corresponder ao número do vetor 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 |
| documento | Opcional | Trace uma lista de vetores (identificados por |
explainOptions.traceDocumentIds | array de IDs de documento | Obrigatório | Lista de documento |
Tipos de Vector Search
Ao definir um estágio, você pode usar $vectorSearch o exact campo para especificar se deseja executar uma pesquisa ANN ou ENN.
Pesquisa ANN
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.
numCandidates Seleção
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
numCandidatesmais 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
numCandidatesestá altamente correlacionado com o tamanho do índice, valores baixos delimitexigem valores proporcionalmente mais altos denumCandidatespara manter o recall.Quantização de vetores: vetores quantizados reduzem o armazenamento ao custo da precisão. O uso de vetores quantizados (subtipos
int8ouint1) pode exigir valores denumCandidatesmais altos em comparação com vetores de precisão totalfloat32para manter um recall semelhante.
Pesquisa ENN
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.
Comportamento
$vectorSearchdeve ser o primeiro estágio de qualquer pipeline onde aparece.
Limitações
$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. |
Indexação da Vector Search do MongoDB
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.
Pontuação da Vector Search do MongoDB
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:
1 db.<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.
Pré-filtragem do MongoDB Vector Search
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 |
Observação
A opção $vectorSearch filter não suporta outros operadores de query, operadores de pipeline de agregação ou operadores de pesquisa MongoDB.
Considerações de filtragem
O MongoDB Vector Search suporta a forma abreviada de
$eq. Na forma abreviada, você não precisa especificar$eqna 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
$andde MQL para especificar uma array de filtros em uma única query.Por exemplo, considere o seguinte pré-filtro para documentos com um campo
genresigual aActione um campoyearcom o valor1999,2000ou2001:"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
$searchestágio.
Paralelização da Execução de Consultas Entre Segmentos
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.
Exemplos
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.
Pré-requisitos
Antes de executar estes exemplos, realize as seguintes ações:
Adicione a coleção de amostra ao seu cluster Atlas.
Criar índices de Vector Search MongoDB para a coleção. Para obter instruções, consulte o procedimento Criar um índice de Vector Search do MongoDB e copie as configurações dos exemplos básicos ou de filtro na linguagem desejada.
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.
Exemplo básico de ANN
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
_ide inclua somente os camposplotetitlenos resultados.Adicione um campo chamado
scoreque exibe a pontuação da pesquisa vetorial para cada documento nos resultados.
Exemplo de ANN filtrada
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
_ide inclua apenas os camposplot,titleeyearnos resultados.Adicione um campo denominado
scoreque 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.
Exemplos de ENN
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
_ide inclua somente os camposplot,titleeyearnos resultados.Adicione um campo denominado
scoreque mostra a pontuação do Atlas Vector Search dos documentos nos resultados.