Configurar la incrustación automatizada para la búsqueda vectorial

Qué hace la incrustación automatizada

Sin incrustación automatizada, tu aplicación debe:

1. Generar una incrustación para cada documento que inserte o actualice.

2. Almacene esa incrustación junto con el documento en su colección.

3. Genere una incrustación para cada query, utilizando el mismo modelo, en el momento de la query.

4. Envía la query incrustación a $vectorSearch.

Con la incrustación automatizada, el proceso mongot gestiona los pasos 1, 2 y 3. Su aplicación:

1. Configura un índice de búsqueda vectorial con el tipo de campo autoEmbed para el campo de texto.

2. Inserta y actualiza documentos normalmente. Luego, mongot lee el campo de texto, genera la incrustación a través del modelo de incrustación configurado y la almacena.

3. Emite $vectorSearch query con el texto de la query, no una incrustación precalculada. Luego, mongot genera la incrustación para el texto de la query.

Proveedores de incrustación compatibles

La incrustación automatizada de mongot autogestionada se integra con los modelos de incrustación de Voyage AI.

Usted incurre en costos por la generación de incrustaciones. Para obtener más información, consulte Gestionar la facturación de la incrustación automatizada.

Requisitos previos

• mongot 1.70.1 o posterior en su implementación de Kubernetes.

• MongoDB 8.2 o posterior.

• Dos claves de Voyage AI API.

  Utilice dos claves separadas, una para la generación de incrustaciones en tiempo de índice y otra para el tiempo de query. Las claves separadas aíslan la carga de trabajo de la query de la carga de trabajo de indexación y permiten una contabilidad independiente del límite de cuota. Para obtener más información, consulte Límites de cuota.

• Acceso a la red saliente desde mongot al punto final de incrustación.

  El endpoint por defecto es https://ai.mongodb.com/v1/embeddings, que utiliza Voyage AI con facturación gestionada por MongoDB para las claves generadas con la interfaz de usuario de Atlas. También puede utilizar https://api.voyageai.com/v1/embeddings para el acceso directo a Voyage AI si generó la clave API directamente desde Voyage AI.

Generar Voyage AI API Keys

Puede generar claves de API de Voyage AI a través de cualquiera de las siguientes rutas:

• (Recomendado) A través de tu cuenta de Atlas. Atlas ofrece gestión de claves de API con configuración de límites de velocidad mediante funcionalidad incorporada. Las claves no están vinculadas a un clúster de Atlas. Para obtener más información, consulta Gestionar claves de API.

• A través de Voyage AI directamente en voyageai.com.

Genere dos claves y nómbrelas claramente, por ejemplo, mongot-prod-index y mongot-prod-query. Almacene las claves en almacenamiento secreto seguro.

Configure mongot para la incrustación automatizada

Cree un secreto de Kubernetes con ambas claves:

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

Haga referencia a él desde el recurso personalizado MongoDBSearch:

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

Opcionalmente, establezca spec.autoEmbedding.providerEndpoint para anular el punto final de incrustación que utiliza mongot. Cuando omite este campo, mongot utiliza su punto final por defecto incorporada, https://ai.mongodb.com/v1/embeddings. Para obtener más información, consulte Especificación de recursos de MongoDBSearch.

Crear un índice de incrustación automatizado

Después de configurar mongot con sus claves de API de Voyage AI, defina un índice de búsqueda vectorial que utilice el tipo de campo autoEmbed. La definición del índice especifica qué campo de texto mongot incrusta, qué modelo utiliza, el método de indexación, la cuantificación y otros parámetros. Para obtener más información sobre la definición del índice autoEmbed, consulte Campos de índice de búsqueda vectorial de 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
         }
      } ] });'

La siguiente tabla describe los campos de definición de índice autoEmbed:

Puede mezclar campos autoEmbed con campos filter en el mismo índice. No puede mezclar autoEmbed con campos vectoriales sin procesar en la misma ruta.

Ejecutar una query de incrustación automatizada

Envíe texto de query, no una incrustación precalculada. mongot genera la incrustación de la query por usted.

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 obtener más información, consulta Ejecutar query de búsqueda vectorial ANN y ENN.

Almacenamiento de incrustaciones

mongot persiste las incrustaciones en una base de datos interna dedicada en el clúster de Kubernetes. mongot no almacena incrustaciones en su colección de origen. mongot puede regenerar incrustaciones a partir del texto de origen, y se le cobrará por la generación de incrustaciones.

Los cambios en el modelo de incrustación, las dimensiones de salida o la cuantificación activan una reincrustación completa del índice afectado. Usted incurre en cargos por la regeneración. Para obtener más información, consulte Cuándo mongot regenera las incrustaciones.

Para obtener más información, consulte colección de incrustaciones generadas.

Cuando mongot regenera incrustaciones

mongot regenera las incrustaciones para un campo autoEmbed cuando se produce cualquiera de los siguientes eventos:

• Inserta un documento.

• Cambia el campo incrustado en un documento. mongot detecta el cambio a través de change streams.

• Cambia el modelo de incrustación en la definición del índice.

• Cambia la dimensión de salida de incrustación o el tipo de dato.

• Cambia la ruta de campo.

Si cambia alguno de los tres últimos elementos, mongot reconstruye todo el índice desde cero. La reconstrucción puede ser costosa para colecciones grandes. Planifique los cambios del modelo deliberadamente.

Costo y limitación de tasa

MongoDB cobra por millón de tokens a tarifas específicas del modelo. El costo de indexación es proporcional al volumen total de texto del campo indexado en toda la colección. El costo de la query es proporcional al volumen de texto de la query.

Si utiliza la clave API de Voyage AI que creó con su cuenta Atlas, puede ver el uso de la clave API y los límites de velocidad en la interfaz de usuario de Atlas. Para obtener más información, consulte Gestionar la facturación de la Embedding and Reranking API. Si utiliza claves creadas directamente desde Voyage AI, debe supervisar su uso y los límites de velocidad en el tablero de Voyage AI.

Los errores de límite de velocidad del lado de Voyage AI aparecen en los registros de mongot y como indicadores de documentos fallidos en el índice afectado. Estos errores no deshabilitan el índice, pero pueden retrasar la indexación de nuevos documentos.

Modos de error

Limitaciones

• Estado de vista previa. La forma de configuración, los modelos admitidos y los endpoints por defecto pueden cambiar antes de que la incrustación automatizada esté disponible de forma general.

• Un modelo de incrustación por campo. No se admiten índices de modelos mixtos.

• No hay conmutación por error del modelo de incrustación. Si el punto de conexión de Voyage AI no es accesible, la indexación de nuevos documentos se detiene.