As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Pesquisa vetorial para Amazon DocumentDB A pesquisa vetorial é um método usado em machine learning para encontrar pontos de dados semelhantes a um determinado ponto de dados comparando suas representações vetoriais usando métricas de distância ou similaridade. Quanto mais próximos os dois vetores estiverem no espaço vetorial, mais semelhantes serão considerados os itens subjacentes. Essa técnica ajuda a capturar o significado semântico dos dados. Essa abordagem é útil em várias aplicações, como sistemas de recomendação, processamento de linguagem natural e reconhecimento de imagem. A pesquisa vetorial do Amazon DocumentDB combina a flexibilidade e a rica capacidade de consulta de um banco de dados de documentos baseado em JSON com o poder da pesquisa vetorial. Se você quiser usar seus dados existentes do Amazon DocumentDB ou uma estrutura flexível de dados de documentos para criar casos de uso de machine learning e IA generativa, como experiência de pesquisa semântica, recomendação de produtos, personalização, bots de chat, detecção de fraudes e detecção de anomalias, a pesquisa vetorial do Amazon DocumentDB é a escolha ideal para você. A pesquisa vetorial está disponível nos clusters baseados em instâncias do Amazon DocumentDB 5.0. **Topics** + [Inserir vetores](#w2aac21c11b9) + [Criar um índice vetorial](#w2aac21c11c11) + [Obter uma definição de índice](#w2aac21c11c13) + [Consultar vetores](#w2aac21c11c15) + [Atributos e limitações](#vector-limitations) + [Práticas recomendadas](#w2aac21c11c19) ## Inserir vetores Para inserir vetores em seu banco de dados do Amazon DocumentDB, você pode usar os métodos de inserção existentes: **Exemplo** No exemplo a seguir, uma coleção de cinco documentos em um banco de dados de teste é criada. Cada documento inclui dois campos: o nome do produto e a incorporação vetorial correspondente. ``` db.collection.insertMany([ {"product_name": "Product A", "vectorEmbedding": [0.2, 0.5, 0.8]}, {"product_name": "Product B", "vectorEmbedding": [0.7, 0.3, 0.9]}, {"product_name": "Product C", "vectorEmbedding": [0.1, 0.2, 0.5]}, {"product_name": "Product D", "vectorEmbedding": [0.9, 0.6, 0.4]}, {"product_name": "Product E", "vectorEmbedding": [0.4, 0.7, 0.2]} ]); ``` ## Criar um índice vetorial O Amazon DocumentDB oferece suporte à indexação Hierarchical Navigable Small World (HNSW) e aos métodos de indexação Inverted File with Flat Compression (). IVFFlat Um IVFFlat índice separa vetores em listas e, posteriormente, pesquisa um subconjunto selecionado dessas listas que estão mais próximas do vetor de consulta. Por outro lado, um índice HNSW organiza os dados vetoriais em um gráfico de várias camadas. Embora o HNSW tenha tempos de construção mais lentos em comparação com IVFFlat, ele oferece melhor desempenho e recuperação de consultas. Ao contrário IVFFlat, o HNSW não tem nenhuma etapa de treinamento envolvida, permitindo que o índice seja gerado sem qualquer carga inicial de dados. Para a maioria dos casos de uso, recomendamos o uso do tipo de índice HNSW para pesquisa vetorial. Se você não criar um índice vetorial, o Amazon DocumentDB executará uma busca exata do vizinho mais próximo, garantindo uma recuperação perfeita. No entanto, em cenários de produção, a velocidade é crucial. Recomendamos o uso de índices vetoriais, que podem trocar algum recall por maior velocidade. É importante observar que adicionar um índice vetorial pode levar a resultados de consultas diferentes. **Modelos** É possível usar os seguintes modelos `createIndex` ou `runCommand` para criar um índice vetorial em um campo vetorial: ------ #### [ Using createIndex ] Em certos drivers, como mongosh e Java, o uso dos parâmetros `vectorOptions` em `createIndex` pode ocasionar erro. Nesses casos, recomendamos o uso de `runCommand`: ``` db.collection.createIndex( { "": "vector" }, { "name": "", "vectorOptions": { "type": " | ", "dimensions": , "similarity": " | | ", "lists": [applicable for IVFFlat], "m": [applicable for HNSW], "efConstruction": [applicable for HNSW] } } ); ``` ------ #### [ Using runCommand ] Em certos drivers, como mongosh e Java, o uso dos parâmetros `vectorOptions` em `createIndex` pode ocasionar erro. Nesses casos, recomendamos o uso de `runCommand`: ``` db.runCommand( { "createIndexes": "", "indexes": [{ key: { "": "vector" }, vectorOptions: { type: " | ", dimensions: , similarity: " | | ", lists: [applicable for IVFFlat], m: [applicable for HNSW], efConstruction: [applicable for HNSW] }, name: "myIndex" }] } ); ``` ------ | Parâmetro | Requisito | Tipo de dados | Description | Valor(es) | | --- | --- | --- | --- | --- | | **name** | optional | string | Especifica o nome do índice. | Alfanumérico | | **type** | optional | | Especifica o tipo de índice. | Com suporte: hnsw ou ivfflat Padrão: HNSW (patch do mecanismo 3.0.4574 em diante) | | **dimensions** | obrigatório | integer | Especifica o número de dimensões nos dados vetoriais. | Máximo de 2.000 dimensões. | | **similarity** | obrigatório | string | Especifica a métrica de distância usada para o cálculo da similaridade. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/vector-search.html) | | **lists** | necessário para IVFFlat | integer | Especifica o número de clusters que o IVFFlat índice usa para agrupar os dados vetoriais. A configuração recomendada é o número de documentos/1000 para até 1 milhão de documentos e `sqrt(# of documents)` para mais de 1 milhão de documentos. | Minimum (Mínimo): 1 Máximo: consulte a tabela de listas por tipo de instância no [Atributos e limitações](#vector-limitations) abaixo. | | **m** | optional | integer | Especifica o número máximo de conexões para um índice HNSW | Padrão: 16 Intervalo: [2, 100] | | **efConstruction** | optional | integer | Especifica o tamanho da lista dinâmica de candidatos para construir o gráfico para o índice HNSW. `efConstruction` deve ser maior que ou igual a (2 \$1 m) | Padrão: 64 Intervalo [4, 1000] | É importante que você defina adequadamente o valor de subparâmetros como `lists` for IVFFlat `m` e `efConstruction` for HNSW, pois isso afetará a precisão/recuperação, o tempo de construção e o desempenho de sua pesquisa. Um valor de lista maior aumenta a velocidade da consulta, pois reduz o número de vetores em cada lista, resultando em regiões menores. No entanto, um tamanho de região menor pode levar a mais erros de recall, ocasionando menor precisão. Para o HNSW, aumentar o valor de `m` e `efConstruction` aumenta a precisão, mas também aumenta o tempo e o tamanho da construção do índice. Veja os exemplos a seguir: **Exemplos** ------ #### [ HNSW ] ``` db.collection.createIndex( { "vectorEmbedding": "vector" }, { "name": "myIndex", "vectorOptions": { "type": "hnsw", "dimensions": 3, "similarity": "euclidean", "m": 16, "efConstruction": 64 } } ); ``` ------ #### [ IVFFlat ] ``` db.collection.createIndex( { "vectorEmbedding": "vector" }, { "name": "myIndex", "vectorOptions": { "type": "ivfflat", "dimensions": 3, "similarity": "euclidean", "lists":1 } } ) ``` ------ ## Obter uma definição de índice É possível visualizar os detalhes dos seus índices, incluindo índices vetoriais, usando o comando `getIndexes`: **Exemplo** ``` db.collection.getIndexes() ``` **Exemplo de saída** ``` [ { "v" : 4, "key" : { "_id" : 1 }, "name" : "_id_", "ns" : "test.collection" }, { "v" : 4, "key" : { "vectorEmbedding" : "vector" }, "name" : "myIndex", "vectorOptions" : { "type" : "ivfflat", "dimensions" : 3, "similarity" : "euclidean", "lists" : 1 }, "ns" : "test.collection" } ] ``` ## Consultar vetores O Amazon DocumentDB oferece suporte a dois operadores de pesquisa vetorial para consultar vetores: ### Operador clássico de pesquisa vetorial Use o modelo a seguir para consultar um vetor: ``` db.collection.aggregate([ { $search: { "vectorSearch": { "vector": , "path": "", "similarity": "", "k": , "probes": [applicable for IVFFlat], "efSearch": [applicable for HNSW] } } } ]); ``` | Parâmetro | Requisito | Tipo | Description | Valor(es) | | --- | --- | --- | --- | --- | | **vectorSearch** | obrigatório | operador | Usado dentro do comando \$1search para consultar os vetores. | | | **vector** | obrigatório | array | Indica o vetor de consulta que será usado para encontrar vetores semelhantes. | | | **path** | obrigatório | string | Define o nome do campo vetorial. | | | **k** | obrigatório | integer | Especifica o número máximo de resultados que devem ser retornados da pesquisa. | | | **similarity** | obrigatório | string | Especifica a métrica de distância usada para o cálculo da similaridade. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/vector-search.html) | | **probes** | optional | integer | O número de clusters que você deseja que a pesquisa vetorial inspecione. Um valor mais alto proporciona um melhor recall em detrimento da velocidade. Ele pode ser definido como o número de listas para a pesquisa exata do vizinho mais próximo (nesse momento, o planejador não usará o índice). A configuração recomendada para iniciar o ajuste é `sqrt(# of lists)`. | Padrão: 1 | | **efSearch** | optional | integer | Especifica o tamanho da lista dinâmica de candidatos que o índice HNSW usa durante a pesquisa. Um valor mais alto de `efSearch` fornece melhor recuperação em detrimento da velocidade. | Padrão: 60 Intervalo: [1, 1000]. | É importante ajustar o valor de `efSearch` (HNSW) ou `probes` (IVFFlat) para obter o desempenho e a precisão desejados. Veja os exemplos de operações a seguir: ------ #### [ HNSW ] ``` db.collection.aggregate([ { $search: { "vectorSearch": { "vector": [0.2, 0.5, 0.8], "path": "vectorEmbedding", "similarity": "euclidean", "k": 2, "efSearch": 40 } } } ]); ``` ------ #### [ IVFFlat ] ``` db.collection.aggregate([ { $search: { "vectorSearch": { "vector": [0.2, 0.5, 0.8], "path": "vectorEmbedding", "similarity": "euclidean", "k": 2, "probes": 1 } } } ]); ``` ------ **Exemplo de saída** A saída dessa operação é semelhante à seguinte: ``` { "_id" : ObjectId("653d835ff96bee02cad7323c"), "product_name" : "Product A", "vectorEmbedding" : [ 0.2, 0.5, 0.8 ] } { "_id" : ObjectId("653d835ff96bee02cad7323e"), "product_name" : "Product C", "vectorEmbedding" : [ 0.1, 0.2, 0.5 ] } ``` ### `$vectorSearch`operador (disponível no Amazon DocumentDB 8.0 em diante) Use o modelo a seguir para consultar um vetor: ``` db.collection.aggregate([ { "$vectorSearch": { "exact": true | false, "index": "" [supports only HNSW index], "limit": [same as k], "path": "", "queryVector": , "numCandidates": [same as efSearch], } }]) ``` ## Atributos e limitações **Compatibilidade da versão** + A pesquisa vetorial do Amazon DocumentDB só está disponível em clusters baseados em instâncias do Amazon DocumentDB 5.0\$1. **Vetores** + O Amazon DocumentDB pode indexar vetores de até 2.000 dimensões. No entanto, até 16.000 dimensões podem ser armazenadas sem um índice. **Índices** + Para criação de IVFFlat índice, a configuração recomendada para o parâmetro de listas é o número de documentos/1000 para até 1 milhão de documentos e `sqrt(# of documents)` para mais de 1 milhão de documentos. Devido ao limite de memória de trabalho, o Amazon DocumentDB suporta um determinado valor máximo do parâmetro de listas, dependendo do número de dimensões. Para sua referência, a tabela a seguir fornece os valores máximos do parâmetro de listas para vetores de 500, 1000 e 2.000 dimensões: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/documentdb/latest/developerguide/vector-search.html) + Nenhuma outra opção de índice, como `compound`, `sparse` ou `partial`, é aceita para índices vetoriais. + A criação paralela de índices não é compatível com o índice HNSW no Amazon DocumentDB 5.0. **Consulta vetorial** + Para consultas de pesquisa vetorial, é importante ajustar os parâmetros, como `probes` ou `efSearch`, para obter os melhores resultados. Quanto maior o valor do parâmetro `probes` ou `efSearch`, maior o recall e menor a velocidade. A configuração recomendada para iniciar o ajuste fino do parâmetro das sondas é `sqrt(# of lists)`. ## Práticas recomendadas Conheça as práticas recomendadas para trabalhar com clusters elásticos do Amazon DocumentDB. Essa seção é continuamente atualizada conforme novas melhores práticas são identificadas. + A criação do índice Inverted File with Flat Compression (IVFFlat) envolve agrupar e organizar os pontos de dados com base nas semelhanças. Portanto, para que um índice seja mais eficaz, recomendamos que você carregue pelo menos alguns dados antes de criar o índice. + Para consultas de pesquisa vetorial, é importante ajustar os parâmetros, como `probes` ou `efSearch`, para obter os melhores resultados. Quanto maior o valor do parâmetro `probes` ou `efSearch`, maior é o recall e menor é a velocidade. A configuração recomendada para iniciar o ajuste fino do parâmetro `probes` é `sqrt(lists)`. **Recursos** + [O que há de novo em pesquisa vetorial - postagem do blog](https://aws.amazon.com/blogs/aws/vector-search-for-amazon-documentdb-with-mongodb-compatibility-is-now-generally-available) + [Exemplo de código de pesquisa semântica](https://github.com/aws-samples/amazon-documentdb-samples/tree/master/blogs/semanticsearch-docdb) + [Exemplos de código de pesquisa vetorial do Amazon DocumentDB](https://github.com/aws-samples/amazon-documentdb-samples/tree/master/samples/vector-search)