Importante
La incrustación automatizada está en vista previa para mongot autogestionados. La funcionalidad y la documentación correspondiente pueden cambiar en cualquier momento durante el período de vista previa. Para obtener más información, consulte Funcionalidades de la vista previa.
Este tutorial describe cómo configurar la incrustación automatizada en una implementación mongot autogestionada. Con la incrustación automatizada, mongot genera incrustación de vectores para tus datos de texto en el momento del índice y para el texto de la query en el momento de la query. No tienes que mantener un pipeline de incrustación separado en tu aplicación.
Este tutorial es para desarrolladores que están creando funcionalidad de búsqueda semántica o RAG y quieren mongot gestionar incrustaciones. Para la implementación de MongoDB Controllers para operadores de Kubernetes, consulte incrustación automatizada.
Qué hace la incrustación automatizada
Sin incrustación automatizada, tu aplicación debe:
Generar una incrustación para cada documento que inserte o actualice.
Almacene esa incrustación junto con el documento en su colección.
Genere una incrustación para cada query, utilizando el mismo modelo, en el momento de la query.
Envía la query incrustación a
$vectorSearch.
Con la incrustación automatizada, mongot gestiona los pasos 1, 2 y 3. Su aplicación:
Configura un índice de MongoDB búsqueda vectorial con el tipo de campo
autoEmbedpara el campo de texto.Inserta y actualiza documentos normalmente.
mongotlee el campo de texto, genera la incrustación a través del modelo de incrustación configurado y la almacena.Emite
$vectorSearchqueries con el texto de la query, no una incrustación precalculada.mongotgenera 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.
Modelo | Descripción |
|---|---|
| Recomendado. Rendimiento equilibrado para la búsqueda de texto general. |
| Aplicaciones de alto volumen y sensibles al costo. |
| Máxima precisión para relaciones semánticas complejas. |
| Especializado en búsqueda de código y documentación técnica. |
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
Debes cumplir con los siguientes requisitos previos para utilizar la incrustación automatizada:
mongot1.70.1 o posterior en una implementación autogestionada (tarball o contenedor de la Community, desarrollo local y Enterprise Edition a través del operador de Kubernetes).MongoDB 8.3 o posterior para implementaciones autónomos y gestionadas por el operador de Kubernetes. Para obtener más información, consulte Compatibilidad y requisitos
mongotpara.Dos claves API de Voyage AI.
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
mongotal punto final de incrustación.El punto final es por defecto
https://ai.mongodb.com/v1/embeddings. Este punto final actúa como proxy de Voyage AI con facturación gestionada por MongoDB, para las claves generadas mediante la interfaz de usuario de Atlas. También puede usarhttps://api.voyageai.com/v1/embeddingspara el acceso directo a Voyage AI si generó la clave de API directamente desde Voyage AI.
Procedimiento
Generar claves de API de Voyage AI.
Puede generar claves de API de Voyage AI mediante cualquiera de los siguientes métodos:
(Recomendado) A través de su cuenta de Atlas. Atlas proporciona gestión de claves de API con funcionalidad incorporada de configuración de límite de velocidad. Las claves no están vinculadas a un clúster de Atlas. Para aprender más, consulte Gestionar claves 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 un almacenamiento secreto seguro.
Configurar mongot para la incrustación automatizada.
La configuración depende de la ruta de implementación. Seleccione la pestaña de su implementación.
La incrustación automatizada requiere la imagen de desarrollo local preview (mongodb/mongodb-atlas-local:preview). La imagen preview agrupa la compilación de la Community de mongot, que incluye la integración de incrustación automatizada.
Si inicia el contenedor directamente con docker run, pase la clave de la API de Voyage AI con la variable de entorno VOYAGE_API_KEY y utilice la etiqueta :preview:
docker run \ -e VOYAGE_API_KEY=<your-voyage-api-key> \ -p 27017:27017 \ mongodb/mongodb-atlas-local:previewSi emitió su clave de Voyage AI directamente a través de Voyage AI en lugar de Atlas, anule el punto final por defecto:
docker run \ -e VOYAGE_API_KEY=<your-voyage-api-key> \ -e EMBEDDING_PROVIDER_ENDPOINT=https://api.voyageai.com/v1/embeddings \ -p 27017:27017 \ mongodb/mongodb-atlas-local:previewNota
El desarrollo local solo acepta una única clave de API de Voyage AI y la utiliza tanto para la generación de incrustaciones en tiempo de índice como en tiempo de query. Una sola clave es aceptable para el desarrollo. Para implementaciones de producción que necesitan claves separadas de indexación y query, utilice la ruta de implementación de Community Edition o Kubernetes Operator.
Agregue el bloque embedding a su archivo de configuración mongot:
embedding: queryKeyFile: /etc/mongot/secrets/voyage-api-query-key indexingKeyFile: /etc/mongot/secrets/voyage-api-indexing-key providerEndpoint: https://ai.mongodb.com/v1/embeddingsCada archivo de clave contiene la clave de API como su único contenido. Establezca los permisos del archivo en 0600 y establezca el propietario del archivo al usuario que ejecuta el proceso mongot.
Cree un índice de incrustación automatizada.
Una vez que configure mongot con sus claves de API de Voyage AI, defina un índice de MongoDB búsqueda vectorial que utilice el tipo de campo autoEmbed. La definición del índice especifica qué campo de texto mongot incrusta y qué modelo utiliza. También especifica el método de indexación, la cuantificación y otros parámetros.
db.movies.createSearchIndex( "movie-semantic-index", "vectorSearch", { "fields": [ { "type": "autoEmbed", "modality": "text", "path": "plot", "model": "voyage-4", "numDimensions": 1024, "similarity": "cosine", "indexingMethod": "hnsw", "hnswOptions": { "maxEdges": 16, "numEdgeCandidates": 50 }, "quantization": "scalar" }, { "type": "filter", "path": "genre" } ] })La siguiente tabla describe los campos de definición de índice autoEmbed:
Campo | Propósito |
|---|---|
| Marca el campo para la incrustación automática. |
| La modalidad de datos. |
| El campo de su colección para incrustar. |
| El nombre del modelo Voyage AI. El modelo debe ser uno al que su clave de API tenga acceso. |
| El número de dimensiones para el vector de incrustación. El modelo determina las dimensiones admitidas. |
| La función de similitud que se utilizará para la búsqueda vectorial. Las funciones admitidas son |
| El método de indexación que se utilizará. Los métodos admitidos son |
| (Opcional) Las opciones de índice HNSW. Obligatorio si |
| (Opcional) El tipo de cuantificación que se debe usar. Los tipos admitidos son |
Puede mezclar campos autoEmbed con campos filter en el mismo índice. No puede mezclar autoEmbed con campos vectoriales sin procesar en la misma ruta. Elija un enfoque por campo.
Ejecute 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.
db.movies.aggregate([ { "$vectorSearch": { "index": "movie-semantic-index", "path": "plot", "query": "a heist gone wrong in a rainy city", "model": "voyage-4", "numCandidates": 100, "limit": 10 } }, { "$project": { "_id": 0, "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. 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, por lo que se le cobrará por la generación de incrustaciones. Consulte Cuándo mongot regenera las incrustaciones.
Para obtener más información, consulte colección de incrustaciones generadas.
Cuando mongot regenera la incrustación
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.
mongotdetecta 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ó usando 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 más información, consulte Gestionar facturación para 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
Síntoma | Causa probable | Acción |
|---|---|---|
El índice permanece en estado |
| Compruebe los registros de |
Los retrasos de indexación aparecen de forma intermitente. | Limitación de velocidad del lado de Voyage IA. | Aumente su límite de velocidad o reduzca la carga de incrustación en tiempo de indexación. |
Las queries contra el índice devuelven un error que menciona las incrustaciones. | La clave de API de query es inválida o ha caducado. | Verifique el contenido de |
Todas las query contra el índice devuelven resultados vacíos. | Es posible que el índice se haya reconstruido y aún esté volviendo a incrustar el corpus. | Compruebe el estado del índice con |
Limitaciones
Se aplican las siguientes limitaciones a la incrustación automatizada:
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.
Próximos pasos
Descripción general de la incrustación automatizada para la descripción general conceptual multiplataforma.
Configure mongot para obtener la referencia de configuración completa de
mongot.