Como indexar campos para pesquisa vetorial

Tipo de implementação

Interface

Você pode usar o tipo vectorSearch para indexar campos para executar queries $vectorSearch. É possível definir o índice para as incorporações vetoriais nas quais deseja fazer query e quaisquer campos adicionais que deseja usar para pré-filtrar seus dados. É útil filtrar os dados para restringir o escopo da pesquisa semântica e garantir que determinadas incorporações vetoriais não sejam consideradas para comparação, como em um ambiente de vários inquilinos.

Você pode usar a UI do Atlas, a Administration API do Atlas, o Atlas CLI, mongosh ou um driver do MongoDB compatível para criar seu índice de Vector Search do MongoDB.

Observação

Não é possível usar o operador knnBeta obsoleto para fazer query nos campos indexados usando a definição de índice do tipo vectorSearch.

Considerações

Em uma definição de índice do tipo vectorSearch, você pode indexar arrays com apenas um único elemento. Você não pode indexar campos de incorporação dentro de arrays de documentos ou campos de incorporação dentro de arrays de objetos. Você pode indexar campos incorporados dentro de documentos usando a notação de ponto}. O mesmo campo de incorporação não pode ser indexado várias vezes na mesma definição de índice.

Antes de indexar suas embeddings, recomendamos convertê-las em vetores BSON BinData com subtipo float32, int1 ou int8 para armazenamento eficiente em seu cluster. Para saber mais, consulte como converter suas incorporações em vetores BSON.

Ao utilizar índices do MongoDB Vector Search , você pode experimentar um alto consumo de recursos em um nó ocioso para seu Atlas cluster. Isso se deve ao processo mongot subjacente, que executa várias operações essenciais para o MongoDB Vector Search. A utilização da CPU em um nó ocioso pode variar dependendo do número, complexidade e tamanho dos índices.

Para aprender mais sobre considerações de dimensionamento para seus índices, veja Requisitos de memória para indexação de vetores.

Se você fizer alterações na collection para a qual definiu o índice da MongoDB Vector Search , os dados mais recentes podem não estar disponíveis imediatamente para query. No entanto, o mongot monitora os fluxos de alteração e atualiza cópias armazenadas de dados, tornando os índices do MongoDB Vector Search eventualmente consistentes. Você pode visualizar o número de Documents indexados na UI do Atlas para verificar se as alterações na collection estão refletidas no índice.

Como alternativa, você pode criar um novo índice depois de adicionar novos documentos à sua coleção e aguardar que o índice se torne consultável. Você também pode implementar uma lógica de pesquisa semelhante à seguinte para garantir que o índice esteja pronto para consulta antes de tentar usá-lo.

Exemplo

console.log("Polling to check if the index is ready. This may take up to a minute.")
let isQueryable = false;
while (!isQueryable) {
  const cursor = collection.listSearchIndexes();
  for await (const index of cursor) {
    if (index.name === result) {
      if (index.queryable) {
        console.log(`${result} is ready for querying.`);
        isQueryable = true;
      } else {
        await new Promise(resolve => setTimeout(resolve, 5000));
      }
    }
  }
}

Clientes aceitos

Você pode criar e gerenciar índices do MongoDB Vector Search por meio da UI do Atlas ,, Atlas CLI, Atlas Administration API e dosmongosh seguintes drivers do MongoDB :

Driver do MongoDB	Versão
C	1.28.0 ou superior
C++	3.11.0 ou superior
C#	3.1.0 ou superior
Go	1.16.0 ou superior
Java	5.2.0 ou superior
Kotlin	5.2.0 ou superior
Node	6.6.0 ou superior
PHP	1.20.0 ou superior
Python	4.7 ou superior
Rust	3.1.0 ou superior
Scala	5.2.0 ou superior

Sintaxe

A seguinte sintaxe define o tipo de índice vectorSearch:

1 {
2   "fields":[
3     {
4       "type": "vector",
5       "path": "<field-to-index>",
6       "numDimensions": <number-of-dimensions>,
7       "similarity": "euclidean | cosine | dotProduct",
8       "quantization": "none | scalar | binary",
9       "hnswOptions": {
10         "maxEdges": <number-of-connected-neighbors>,
11         "numEdgeCandidates": <number-of-nearest-neighbors>
12       }
13     },
14     {
15       "type": "filter",
16       "path": "<field-to-index>"
17     },
18     ...
19   ]
20 }

Campos de índice de Vector Search do MongoDB

A definição do índice MongoDB Vector Search utiliza os seguintes campos:

Opção	Tipo	necessidade	Propósito
`fields`	Array de documentos de definição de campos	Obrigatório	Definições para os campos de vetor e filtro a serem indexados, uma definição por documento. Cada documento de definição de campo especifica o `type`, `path` e outras opções de configuração para o campo indexar. A array `fields` deve conter pelo menos uma definição de campo do tipo `vector`. Você pode adicionar definições de campo do tipo `filter`adicionais à sua array para pré-filtrar seus dados.
`fields.` `type`	String	Obrigatório	Tipo de campo a ser usado para indexar campos para `$vectorSearch`. Você pode especificar um dos seguintes valores: `vector` - para campos que contêm incorporações de vetor. `filter` - para campos adicionais para filtrar. É possível aplicar filtro a valores booleanos, data, objectId, valores numéricos, string e UUID, incluindo arrays desses tipos. Para saber mais, consulte Sobre o tipo `vector` e Sobre o tipo `filter` .
`fields.` `path`	String	Obrigatório	Nome do campo a ser indexado. Para campos aninhados, utilize notação de ponto para especificar o caminho para campos incorporados.
`fields.` `numDimensions`	Int	Obrigatório	Número de dimensões vetoriais que o MongoDB Vector Search impõe no momento do índice e no momento da consulta. Você pode definir este campo somente para campos tipo `vector`. Você deve especificar um valor menor ou igual a `8192`. Para indexar vetores quantizados ou BinData, você pode especificar um dos seguintes valores: `1` a `8192` para `int8` vetores para ingestão. Múltiplo de `8` para `int1` vetores para ingestão. `1` a `8192` para `binData(float32)` e `array(float32)` vetores para quantização escalar automática. Múltiplo de `8` para `binData(float32)` e `array(float32)` vetores para quantização binária automática. O modelo de incorporação escolhido determina o número de dimensões em suas incorporações vetoriais, com alguns modelos tendo múltiplas opções para quantas dimensões são geradas. Para saber mais, consulte Escolher um método para criar incorporações.
`fields.` `similarity`	String	Obrigatório	Função de similaridade vetorial a ser usada para procurar os K- vizinhos mais próximos. Você pode definir este campo somente para campos tipo `vector`. Você pode especificar um dos seguintes valores: `euclidean` - mede a distância entre as extremidades dos vetores. `cosine` - mede a similaridade com base no ângulo entre os vetores. `dotProduct` - mede a similaridade como `cosine`, mas leva em conta a magnitude do vetor. Para saber mais, consulte Sobre as funções de similaridade.
`fields.` `quantization`	String	Opcional	Tipo de quantização vetorial automática para seus vetores. Use essa configuração somente se suas incorporações forem `float` ou `double` vetores. Você pode especificar um dos seguintes valores: `none` - Indica que não há quantização automática para as incorporações vetoriais. Use essa configuração se você tiver vetores pré-quantizados para ingestão. Se omitido, este é o valor padrão. `scalar` - Indica a quantização escalar, que transforma valores em inteiros de 1 bytes. `binary` - Indica a quantização binária, que transforma valores em um único bit. Para usar esse valor, `numDimensions` deve ser um múltiplo de 8. Se a precisão for crítica, selecione `none` ou `scalar` em vez de `binary`. Para saber mais, consulte Quantização vetorial.
`fields.` `hnswOptions`	Objeto	Opcional	Parâmetros a serem usados na construção do grafo Hierarchical Navigable Small Worlds. Se omitido, usa os valores padrão para os parâmetros `maxEdges` e `numEdgeCandidates`. IMPORTANTE: isso está disponível como um recurso de visualização. A modificação dos valores padrão pode impacto negativamente o índice e as consultas do MongoDB Vector Search .
`fields.` `hnswOptions.` `maxEdges`	Int	Opcional	Número máximo de arestas (ou conexões) que um nó pode ter no grafo Hierarchical Navigable Small Worlds. O valor pode estar entre `16` e `64`, ambos incluídos. Se omitido, o padrão é `16`. Por exemplo, para um valor de `16`, cada nó pode ter um máximo de dezesseis arestas de saída em cada camada do grafo Hierarchical Navigable Small Worlds. Um número maior melhora a recuperação (precisão dos resultados da pesquisa) porque o gráfico está mais bem conectado. No entanto, isso reduz a velocidade da consulta devido ao número de vizinhos para avaliar por nó de gráfico, aumenta a memória do gráfico de Mundos Pequenos Hierárquicos Navegáveis porque cada nó armazena mais conexões e reduz a indexação porque o MongoDB Vector Search avalia mais vizinhos e ajusta para cada novo nó adicionado ao gráfico.
`fields.` `hnswOptions.` `numEdgeCandidates`	Int	Opcional	Analogamente a `numCandidates` no momento da query, este parâmetro controla o número máximo de nós a serem avaliados para encontrar os vizinhos mais próximos para se conectar a um novo nó. O valor pode estar entre `100` e `3200`, ambos incluídos. Se omitido, o padrão é `100`. Um número mais alto fornece um grafo com conexões de alta qualidade, o que pode melhorar a qualidade da pesquisa (recall), mas também pode afetar negativamente a latência da query.

Sobre o tipo `vector`

O campo vector da definição do seu índice deve conter uma array de números de um dos seguintes tipos:

BSON double
BSON BinData vector Subtipo float32
BSON BinData vector Subtipo int1
BSON BinData vector Subtipo int8

Observação

Para aprender mais sobre como gerar vetores BSON BinData com subtipo float32 int1 ou int8 para seus dados, veja Como ingerir vetores pré-quantificados.

Você deve indexar o campo vetorial como o tipo vector dentro do array fields.

A seguinte sintaxe define o tipo de campo vector:

1 {
2   "fields":[
3     {
4       "type": "vector",
5       "path": <field-to-index>,
6       "numDimensions": <number-of-dimensions>,
7       "similarity": "euclidean | cosine | dotProduct",
8       "quantization": "none | scalar | binary",
9       "hnswOptions": {
10         "maxEdges": <number-of-connected-neighbors>,
11         "numEdgeCandidates": <number-of-nearest-neighbors>
12       }
13     },
14     ...
15   ]
16 }

Sobre as funções de similaridade

O MongoDB Vector Search oferece suporte às seguintes funções de similaridade:

euclidean - mede a distância entre as extremidades dos vetores. Esse valor permite medir a similaridade com base na variação de dimensões. Para saber mais, consulte Plano euclideano.
cosine - mede a similaridade com base no ângulo entre os vetores. Esse valor permite que você meça a similaridade que não é dimensionada pela magnitude. Você não pode utilizar vetores de magnitude zero com cosine. Para medir a similaridade do cosseno, recomendamos normalizar seus vetores e usar dotProduct.
dotProduct - mede a similaridade como cosine, mas leva em consideração a magnitude do vetor. Se você normalizar a magnitude, cosine e dotProduct são quase idênticos na medição de similaridade.
Para usar dotProduct, você deve normalizar o vetor para o comprimento unitário no momento do índice e no momento da query.

A tabela a seguir mostra as funções de similaridade para os vários tipos:

Tipo de incorporação do vetor	`euclidean`	`cosine`	`dotProduct`
`binData(int1)`	√
`binData(int8)`	√	√	√
`binData(float32)`	√	√	√
`array(float32)`	√	√	√

Para ingestão de vetores.

Para quantização escalar ou binária automática.

A fórmula para cada função de similaridade é a seguinte:

Para cosine, o MongoDB Vector Search utiliza o seguinte algoritmo para normalizar a pontuação:

score = (1 + cosine(v1,v2)) / 2

Este algoritmo normaliza a pontuação considerando a pontuação de similaridade do vetor de documento (v1) e do vetor de query (v2), que tem o intervalo [-1, 1]. O MongoDB Vector Search adiciona 1 à pontuação de similaridade para normalizar a pontuação para um intervalo [0, 2] e depois divide por 2 para garantir um valor entre 0 e 1.

Para dotProduct, o MongoDB Vector Search utiliza o seguinte algoritmo para normalizar a pontuação:

score = (1 + dotProduct(v1,v2)) / 2

Este algoritmo normaliza a pontuação considerando a pontuação de similaridade do vetor de documento (v1) e do vetor de query (v2), que tem o intervalo [-1, 1]. O MongoDB Vector Search adiciona 1 à pontuação de similaridade para normalizar a pontuação para um intervalo [0, 2] e depois divide por 2 para garantir um valor entre 0 e 1.

Para euclidean similaridade, o MongoDB Vector Search usa o seguinte algoritmo para normalizar a pontuação e garantir um valor entre 0 e 1:

score = 1 / (1 + euclidean(v1,v2))

Este algoritmo normaliza a pontuação calculando a distância euclideana, que é a distância entre o vetor de documento (v1) e o vetor de query (v2), que tem o intervalo [0, ∞]. O MongoDB Vector Search transforma a distância em uma pontuação de similaridade adicionando 1 à distância e, em seguida, divide 1 pelo resultado para garantir um valor entre 0 e 1.

Para obter o melhor desempenho, verifique seu modelo de incorporação para determinar qual função de similaridade se alinha ao processo de treinamento do seu modelo de incorporação. Se você não tiver nenhuma orientação, comece com dotProduct. Definir fields.similarity para o valor dotProduct permite medir com eficiência a similaridade com base no ângulo e na magnitude. dotProduct consome menos recursos computacionais do que cosine e é eficiente quando os vetores são de comprimento unitário. No entanto, se seus vetores não forem normalizados, avalie as pontuações de similaridade nos resultados de uma query de exemplo para euclidean distância e cosine similaridade para determinar qual corresponde a resultados razoáveis.

Sobre o tipo `filter`

Opcionalmente, você pode indexar campos adicionais para pré-filtrar seus dados. É possível aplicar filtro a valores booleanos, data, objectId, valores numéricos, string e UUID, incluindo arrays desses tipos. É útil filtrar os dados para restringir o escopo da pesquisa semântica e garantir que nem todos os vetores sejam considerados para comparação. Isso reduz o número de documentos contra os quais executar comparações de similaridade, o que pode diminuir a latência da consulta e aumentar a precisão dos resultados da pesquisa.

Você deve indexar os campos que deseja filtrar usando o tipo filter dentro da array fields.

A seguinte sintaxe define o tipo de campo filter:

1 {
2   "fields":[
3     {
4       "type": "vector",
5       ...
6     },
7     {
8       "type": "filter",
9       "path": "<field-to-index>"
10     },
11     ...
12   ]
13 }

Se você quiser pré-filtrar usando pesquisa difusa, correspondência de frases, filtro de localização e outras funcionalidades de texto analisadas, crie um índice do tipo vetor do MongoDB Search vector e faça query usando o operador $vectorSearch em um estágio $search.

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.

Crie um índice de Vector Search do MongoDB

Você pode criar um índice do MongoDB Vector Search para todas as collections que contêm incorporações vetoriais menores ou iguais a 8192 dimensões de comprimento para qualquer tipo de dados junto com outros dados em seu cluster por meio da UI do Atlas, API de administração do Atlas, Atlas CLI, mongosh ou um driver MongoDB compatível.

Pré-requisitos

Para criar um índice do MongoDB Vector Search , você deve ter um cluster com os seguintes pré-requisitos:

MongoDB versão 6.0.11, 7.0.2 ou superior
Uma collection para a qual criar o índice do MongoDB Vector Search

Observação

Você pode utilizar o comandomongosh ou métodos de assistente do driver para criar índices MongoDB Vector Search em todas as camadas do cluster Atlas. Para obter uma lista de versões de driver compatíveis, consulte Clientes compatíveis.

Acesso necessário

Você precisa da função Project Data Access Admin ou superior para criar e gerenciar índices de Vector Search do MongoDB.

Limitações do índice

Não é possível criar mais de:

Índices 3 (independentemente do tipo, search ou vector) em clusters M0.
10 índices em clusters Flex.

Recomendamos que você crie não mais do que 2,500 índices de pesquisa em um único cluster M10+.

Procedimento

Observação

O procedimento inclui exemplos de definição de índice para a coleção embedded_movies no banco de dados sample_mflix . Se você carregar os dados de amostra em seu cluster e criar os índices de Vector Search do MongoDB de exemplo para essa coleção, poderá executar as queries de amostra $vectorSearch nessa coleção. Para saber mais sobre os exemplos de consultas que você pode executar, consulte Exemplos de $vectorSearch.

Ver um índice de Vector Search do MongoDB

Você pode visualizar índices do MongoDB Vector Search para todas as collections a partir da UI do Atlasmongosh , Atlas Administration API, Atlas CLI, ou de um MongoDB Driver compatível.

Acesso necessário

Você precisa ter a função Project Search Index Editor ou superior para visualizar os índices do MongoDB Vector Search.

Observação

Você pode utilizar o comando mongosh ou métodos de assistente do driver para recuperar índices MongoDB Vector Search em todas as camadas do Atlas cluster. Para obter uma lista de versões de driver compatíveis, consulte Clientes compatíveis.

Procedimento

Editar um índice de Vector Search do MongoDB

Você pode alterar a definição de índice de um índice existente do MongoDB Vector Search a partir da UI do Atlas, da Administration API do Atlas, do Atlas CLI, do mongosh ou de um driver do MongoDB compatível. Você não pode renomear um índice ou alterar o tipo de índice. Se você precisar alterar um nome ou tipo de índice, deverá criar um novo índice e excluir o antigo.

Importante

Depois de editar um índice, o MongoDB Vector Search o reconstrói. Enquanto o índice é reconstruído, você pode continuar a executar queries de pesquisa vetorial usando a definição de índice antiga. Quando o índice terminar de ser reconstruído, o índice antigo será automaticamente substituído. Este processo é semelhante aos índices de pesquisa MongoDB . Para saber mais, consulte Criar e atualizar um índice de pesquisa MongoDB.

Acesso necessário

Você deve ter a função Project Search Index Editor ou superior para editar um índice do MongoDB Vector Search.

Observação

Você pode utilizar o comando mongosh ou métodos de assistente do driver para editar índices MongoDB Vector Search em todas as camadas do Atlas cluster. Para obter uma lista de versões de driver compatíveis, consulte Clientes compatíveis.

Procedimento

Excluir um índice de Vector Search do MongoDB

Você pode excluir um índice do MongoDB Vector Search a qualquer momento a partir da UI do Atlas, da Administration API do Atlas, do Atlas CLI, mongosh ou de um driver do MongoDBcompatível.

Acesso necessário

Você deve ter a função Project Search Index Editor ou superior para excluir um índice do MongoDB Vector Search.

Observação

Você pode usar o comando mongosh ou os métodos assistente do driver para excluir índices do MongoDB Vector Search em todas as camadas do Atlas cluster. Para obter uma lista de versões de driver compatíveis, consulte Clientes compatíveis.

Procedimento

Status do índice

Quando você cria o índice do MongoDB Vector Search , a coluna Status mostra o estado atual do índice no nó primary do cluster. Clique no link View status details abaixo do status para visualizar o estado do índice em todos os nós do cluster.

Quando a coluna Status lê Active, o índice está pronto para utilizar. Em outros estados, queries em relação ao índice podem retornar resultados incompletos.

Status	Descrição
Não iniciado	Atlas ainda não começou a construir o índice.
Sincronização inicial	O Atlas está construindo o índice ou reconstruindo o índice após uma edição. Quando o índice está neste estado: Para um novo índice, o MongoDB Vector Search não atende às query até que a criação do índice seja concluída. Para um índice existente, você pode continuar usando o índice antigo para queries novas e existentes até que a recriação do índice seja concluída.
Ativo	O índice está pronto para uso.
Recuperando	A denúncia encontrou um erro. Esse estado geralmente ocorre quando o ponto de replicação atual não está mais disponível no oplog `mongod`. Você ainda pode fazer query no índice existente até que ele atualize e seu status mude para Active. Use o erro na janela modal View status details para solucionar o problema. Para saber mais, consulte Corrigir problemas.
Falhou	O Atlas não conseguiu criar o índice. Use o erro na janela modal View status details para solucionar o problema. Para saber mais, consulte Corrigir problemas.
Exclusão em Andamento	O Atlas está excluindo o índice dos nós de cluster.

Enquanto o Atlas constrói o índice e após a conclusão da construção, a coluna Documents mostra a porcentagem e o número de documentos indexados. A coluna também mostra o número total de documentos na coleção.

Voltar

Criar incorporações

Referência de query

1	{
2	"fields":[
3	{
4	"type": "vector",
5	"path": "<field-to-index>",
6	"numDimensions": <number-of-dimensions>,
7	"similarity": "euclidean \| cosine \| dotProduct",
8	"quantization": "none \| scalar \| binary",
9	"hnswOptions": {
10	"maxEdges": <number-of-connected-neighbors>,
11	"numEdgeCandidates": <number-of-nearest-neighbors>
12	}
13	},
14	{
15	"type": "filter",
16	"path": "<field-to-index>"
17	},
18	...
19	]
20	}

1	{
2	"fields":[
3	{
4	"type": "vector",
5	"path": <field-to-index>,
6	"numDimensions": <number-of-dimensions>,
7	"similarity": "euclidean \| cosine \| dotProduct",
8	"quantization": "none \| scalar \| binary",
9	"hnswOptions": {
10	"maxEdges": <number-of-connected-neighbors>,
11	"numEdgeCandidates": <number-of-nearest-neighbors>
12	}
13	},
14	...
15	]
16	}

Observação

Considerações

Exemplo

Clientes aceitos

Sintaxe

Campos de índice de Vector Search do MongoDB

Sobre o tipo vector

Observação

Sobre as funções de similaridade

Sobre o tipo filter

Observação

Crie um índice de Vector Search do MongoDB

Pré-requisitos

Observação

Acesso necessário

Limitações do índice

Procedimento

Observação

Ver um índice de Vector Search do MongoDB

Acesso necessário

Observação

Procedimento

Editar um índice de Vector Search do MongoDB

Importante

Acesso necessário

Observação

Procedimento

Excluir um índice de Vector Search do MongoDB

Acesso necessário

Observação

Procedimento

Status do índice

Receber um selo de habilidade

Sobre o tipo `vector`

Sobre o tipo `filter`