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 a geração de incorporação. Para saber mais, consulte Gerenciar o faturamento da incorporação automatizada.

Pré-requisitos

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

• MongoDB 8.3 ou posterior.

• Duas chaves de API do Voyage AI.

  Use duas chaves separadas, uma para geração de incorporação em tempo de índice e outra para tempo de query. Chaves separadas isolam o volume de trabalho de query do volume de trabalho de indexação e permitem uma contabilização independente do limite de taxa. Para saber mais, consulte Limites de taxa.

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

  O endpoint padrão é https://ai.mongodb.com/v1/embeddings, que procura a Voyage AI com o faturamento gerenciado MongoDB, para chaves geradas usando a UI do Atlas . Você também pode usar https://api.voyageai.com/v1/embeddings para acesso direto à Voyage AI se tiver gerado a chave de API diretamente da Voyage AI.

Gerar chaves de API VoyageAI

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

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

• Por meio da Voyage AI diretamente em routeai.com.

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

Configurar mongot para Incorporação Automática

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 o mongot com as chaves da API do Voyage AI, defina um índice do Vector Search que use o tipo de campo autoEmbed. A definição de í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 do índice de Vector Search 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 queries ANN e ENN do Vector Search .

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 incorporação, nas dimensões de saída ou na quantização acionam uma nova incorporação completa do índice afetado. Você incorre em cobranças pela recuperação. Para saber mais, consulte Quando mongot Regenera Incorporações.

Para saber mais, consulte Coleção de incorporações geradas.

Quando mongot regenera incorporações

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 Voyage AI que você criou usando sua conta do Atlas , poderá visualizar o uso da chave de API e os limites de taxa na UI do Atlas . Para saber mais, consulte Gerenciar faturamento para a API de incorporação e reclassificação. Se você usar chaves criadas diretamente da Voyage AI, deverá monitorar seu uso e limites de taxa no dashboard da 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.