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.

You incur costs for embedding generation. To learn more, see Manage Billing for Automated Embedding.

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.

  Use two separate keys, one for index-time embedding generation and one for query-time. Separate keys isolate query workload from indexing workload and allow independent rate-limit accounting. To learn more, see Rate Limits.

• 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 você gerou a chave de API diretamente do Voyage AI.

Gerar chaves de API Voyage AI

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

• (Recommended) Through your Atlas account. Atlas provides API key management with built-in rate-limit configuration. The keys are not tied to an Atlas cluster. To learn more, see Manage API Keys.

• 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 o 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

After you configure mongot with your Voyage AI API keys, define a Vector Search index that uses the autoEmbed field type. The index definition specifies which text field mongot embeds, which model it uses, the indexing method, quantization, and other parameters. To learn more about the autoEmbed index definition, see MongoDB Vector Search Index Fields.

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" }
      }
   }]);'

To learn more, see Run Vector Search ANN and ENN Queries.

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.

Changes to the embedding model, output dimensions, or quantization trigger a full re-embedding of the affected index. You incur charges for the regeneration. To learn more, see When mongot Regenerates Embeddings.

To learn more, see Generated Embeddings Collection.

Quando o mongot regenera os embedding

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.

If you use the Voyage AI API key that you created using your Atlas account, you can view API key usage and rate limits in the Atlas UI. To learn more, see Manage Billing for the Embedding and Reranking API. If you use keys created directly from Voyage AI, you must monitor your usage and rate limits in the Voyage AI dashboard.

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.