Configurar embedding automatizado para pesquisa vetorial

O que o embedding automatizado faz

Sem o embedding automatizado, seu aplicativo deve:

1. Gere um embedding para cada documento que você inserir ou atualizar.

2. Armazene esse embedding junto com o documento em sua coleção.

3. Gere um embedding para cada query, usando o mesmo modelo, no momento da query.

4. Envie o embedding de query para $vectorSearch.

Com o embedding automatizado, o processo mongot lida com as etapas 1, 2 e 3. Seu aplicativo:

1. Configura um índice de pesquisa vetorial com o tipo de campo autoEmbed para o campo de texto.

2. Insere e atualiza documentos normalmente. Em seguida, mongot lê o campo de texto, gera o embedding por meio do modelo de embedding configurado e o armazena.

3. Emite $vectorSearch query com o texto da query, não um embedding pré-calculado. Em seguida, mongot gera o embedding para o texto da query.

Provedores de embedding suportados

O embedding automatizado do mongot autogerenciado se integra aos modelos de embedding do Voyage AI.

Você incorre em custos para geração de embedding. Para aprender mais, consulte Gerenciar Faturamento para embedding automatizado.

Pré-requisitos

• mongot 1.70.1 ou posterior em sua implantação do Kubernetes.

• MongoDB 8.2 ou posterior.

• Duas chaves de API do Voyage AI API.

  Use duas chaves separadas, uma para geração de embedding em tempo de índice e outra para tempo de query. Chaves separadas isolam a carga de trabalho de query da carga de trabalho de indexação e permitem a contabilidade independente do limite de taxa. Para aprender mais, consulte Limites de taxa.

• Acesso de rede de saída de mongot para o ponto de extremidade de embedding.

  O ponto de extremidade padrão é https://ai.mongodb.com/v1/embeddings, que faz proxy do Voyage AI com faturamento gerenciado pelo MongoDB, para chaves geradas usando a IU do Atlas. Você também pode usar https://api.voyageai.com/v1/embeddings para acesso direto ao Voyage AI se tiver gerado a chave API diretamente do Voyage AI.

Gerar chaves de API do Voyage AI

Você pode gerar chaves de API do Voyage AI por meio de qualquer um dos seguintes caminhos:

• (Recomendado) Por meio de sua conta Atlas. O Atlas fornece gerenciamento de chaves de API com configuração de limite de taxa integrada. As chaves não estão vinculadas a um cluster Atlas. Para saber mais, consulte Gerenciar chaves de API.

• Através do Voyage AI diretamente em voyageai.com.

Gere duas chaves e nomeie-as claramente, por exemplo, mongot-prod-index e mongot-prod-query. Armazene as chaves em armazenamento secreto seguro.

Configure mongot para embedding automatizado

Crie um secret do Kubernetes com ambas as chaves:

kubectl create secret generic voyage-api-keys \
  --from-literal=indexing-key=<your-index-key> \
  --from-literal=query-key=<your-query-key> \
  --namespace=<your-namespace>

Referencie-o a partir do recurso personalizado do MongoDBSearch:

apiVersion: mongodb.com/v1
kind: MongoDBSearch
metadata:
  name: mdbs
spec:
  # ...
  autoEmbedding:
    embeddingModelAPIKeySecret:
      name: voyage-api-keys

Opcionalmente, defina spec.autoEmbedding.providerEndpoint para substituir o ponto de extremidade de embedding que mongot usa. Quando você omite este campo, mongot usa seu ponto de extremidade padrão integrado, https://ai.mongodb.com/v1/embeddings. Para saber mais, consulte Especificação de recurso do MongoDBSearch.

Criar um índice de embedding automatizado

Depois de configurar mongot com suas chaves de API do Voyage AI, defina um índice de pesquisa vetorial que use o tipo de campo autoEmbed. A definição do índice especifica qual campo de texto mongot incorpora, qual modelo ele usa, o método de indexação, a quantização e outros parâmetros. Para saber mais sobre a definição do índice autoEmbed, consulte Campos de índice de pesquisa vetorial do MongoDB.

kubectl exec --context "${K8S_CTX}" -n "${MDB_NS}" mongodb-tools-pod -- \
mongosh --quiet "${MDB_CONNECTION_STRING}" \
   --eval "use sample_mflix" \
   --eval 'db.movies.createSearchIndex("vector_auto_embed_index", "vectorSearch",
      { "fields": [ {
         "type": "autoEmbed",
         "modality": "text",
         "path": "plot",
         "model": "'"${EMBEDDING_MODEL}"'",
         "numDimensions": 1024,
         "similarity": "cosine",
         "quantization": "scalar",
         "indexingMethod": "hnsw",
         "hnswOptions": {
            "maxEdges": 16,
            "numEdgeCandidates": 200
         }
      } ] });'

A tabela a seguir descreve os campos de definição de índice autoEmbed:

Você pode misturar campos autoEmbed com campos filter no mesmo índice. Você não pode misturar autoEmbed com campos vetoriais brutos no mesmo caminho.

Executar uma query de embedding automatizada

Envie texto de query, não um embedding pré-computado. mongot gera o embedding de query para você.

kubectl exec --context "${K8S_CTX}" -n "${MDB_NS}" mongodb-tools-pod -- \
mongosh --quiet "${MDB_CONNECTION_STRING}" \
   --eval "use sample_mflix" \
   --eval 'db.movies.aggregate([ {
      $vectorSearch: {
         index: "vector_auto_embed_index",
         path: "plot",
         query: "spy thriller",
         numCandidates: 150,
         limit: 10
      }
   }, {
      $project: {
         _id: 0,
         plot: 1,
         title: 1,
         score: { $meta: "vectorSearchScore" }
      }
   }]);'

Para saber mais, consulte Executar query de pesquisa vetorial.

Armazenamento de embedding

mongot persiste embedding em um banco de dados interno dedicado no cluster do Kubernetes. mongot não armazena embedding em sua coleção de origem. mongot pode regenerar embedding do texto de origem, e você incorre em cobranças pela geração de embedding.

Alterações no modelo de embedding, dimensões de saída ou quantização trigger um re-embedding completo do índice afetado. Você será cobrado pela regeneração. Para aprender mais, consulte Quando mongot regenera embedding.

Para aprender mais, consulte Coleção de embedding gerado.

Quando mongot regenera embeddings

mongot regenera embedding para um campo autoEmbed quando ocorre qualquer um dos seguintes:

• Você insere um documento.

• Você altera o campo incorporado em um documento. mongot detecta a alteração por meio de fluxos de alteração.

• Você altera o modelo de embedding na definição do índice.

• Você altera a dimensão de saída do embedding ou o tipo de dados.

• Você altera o caminho do campo de texto.

Se você alterar qualquer um dos três últimos itens, mongot reconstrói todo o índice do zero. A reconstrução pode ser cara para grandes coleções. Planeje as alterações do modelo deliberadamente.

Custo e limitação de taxa

O MongoDB cobra por milhão de tokens em taxas específicas do modelo. O custo de indexação é proporcional ao volume total de texto do campo indexado em toda a coleção. O custo da query é proporcional ao volume de texto da query.

Se você usar a chave de API do Voyage AI que você criou usando sua conta do Atlas, poderá visualizar o uso da chave de API e os limites de taxa na IU do Atlas. Para saber mais, consulte Gerenciar faturamento para a Embedding and Reranking API. Se você usar chaves criadas diretamente do Voyage AI, deverá monitorar seu uso e limites de taxa no dashboard do Voyage AI.

Os erros de limite de taxa do lado do Voyage AI aparecem nos logs do mongot e como indicadores de documento com falha no índice afetado. Esses erros não desativam o índice, mas podem atrasar a indexação de novos documentos.

Modos de falha

Limitações

• **Status de pré-visualização.** O formato da configuração, os modelos compatíveis e os pontos de extremidade padrão podem mudar antes que o Automated Embedding esteja geralmente disponível.

• Um modelo de embedding por campo. Índices de modelo misto não são suportados.

• Sem failover de modelo de embedding. Se o ponto de extremidade do Voyage AI estiver inacessível, a indexação de novos documentos será interrompida.