Cómo funciona la incrustación automatizada

Insertos de documentos

Cuando insertas un nuevo documento con el campo de texto indexado, MongoDB Vector Search automáticamente:

1. Detecta el nuevo documento a través de flujos de cambios.

2. Genera incrustaciones para el campo de texto utilizando el modelo configurado.

3. Almacena las incrustaciones en la colección del sistema.

4. Actualiza el índice de búsqueda vectorial de MongoDB para incluir las nuevas incrustaciones.

Document Updates

Cuando actualizas un documento y el campo de texto indexado cambia, MongoDB Vector Search automáticamente:

1. Detecta el cambio de campo a través de flujos de cambios.

2. Genera nuevas incrustaciones para el texto actualizado.

3. Reemplaza las incrustaciones antiguas en la colección del sistema.

4. Actualiza el índice de búsqueda vectorial de MongoDB con las nuevas incrustaciones.

Eliminación de documentos

Cuando se elimina un documento, MongoDB Vector Search elimina automáticamente las incrustaciones correspondientes de la colección del sistema y actualiza el índice.

Infraestructura modelo

• Servicio alojado: Todos los modelos de incrustación están alojados y mantenidos por MongoDB. La plataforma de inferencia de modelos se ejecuta en la infraestructura de MongoDB en la nube de Google Cloud en una región de EE. UU. No necesita implementar, configurar ni administrar ninguna infraestructura de modelos.

• Acceso basado en API: Para implementaciones autogestionadas configuradas para usar la clave API de Voyage AI, MongoDB envía texto a los puntos finales de la API de Voyage AI para generar incrustaciones. Estas incrustaciones se devuelven a MongoDB y se almacenan en su clúster.

• Arquitectura multiusuario: El servicio de integración se comparte entre varios usuarios. Este modelo multiusuario proporciona:

  • Eficiencia de costes mediante infraestructura compartida

  • Actualizaciones y mejoras automáticas del modelo

  • Alta disponibilidad y escalabilidad

Privacidad de datos

• El texto enviado al servicio de incrustación automatizada se utiliza únicamente para generar incrustaciones y no se almacena ni se utiliza para el entrenamiento del modelo.

• Los datos incrustados se devuelven a su clúster de MongoDB y se almacenan en su propia base de datos.

• Toda la comunicación con el servicio de incrustación automatizada se realiza a través de conexiones cifradas.

Límites de velocidad

El servicio de incrustación es multiusuario. Por lo tanto, MongoDB aplica límites de velocidad para garantizar un uso equitativo entre todos los clientes. Para obtener más información sobre los límites de velocidad y cómo afectan a las operaciones de incrustación automatizada, consulte Límites de velocidad.

Límites de frecuencia de consultas

Cada consulta que utiliza la función de incrustación automática se contabiliza dentro de los límites de uso de dicha función, ya que requiere una llamada a la API para generar las incrustaciones. Para obtener más información sobre cómo gestionar el rendimiento y los costes de las consultas, consulte la sección Límites de uso.

Sincronización inicial

• Las colecciones grandes pueden tardar bastante tiempo en completar la sincronización inicial si se alcanzan los límites de velocidad.

• MongoDB reintenta automáticamente las solicitudes de incrustación fallidas e implementa un retroceso exponencial.

• Puedes monitorear el progreso de la sincronización a través de Monitoreo de Atlas Search.

Actualizaciones constantes

• Las actualizaciones de documentos se procesan a medida que se producen, sujetas a límites de frecuencia.

• Si las actualizaciones superan los límites de velocidad, se ponen en cola y se procesan cuando hay capacidad disponible.

• Su aplicación continúa funcionando con normalidad; solo la generación de la incrustación podría sufrir un retraso.

Queries

• Los límites de frecuencia de las consultas afectan a la cantidad de búsquedas simultáneas que puede realizar.

• Si se superan los límites de frecuencia de las consultas, estas devolverán un error que indica que se ha excedido dicho límite.

• Considere la posibilidad de almacenar en caché los resultados de las consultas de uso frecuente o de actualizar a un plan de pago para obtener un mayor rendimiento.

Encuentra la colección de incrustaciones generadas

1
use <database_name>
2
db.<collection_name>.aggregate( [ { $listSearchIndexes: { name: "<index_name>" } } ] )

1
[
2
   {
3
      id: '69f382ecd6fa583100184fe7',
4
      name: 'auto-embed-index',
5
      type: 'vectorSearch',
6
      status: 'READY',
7
      numDocs: 0,
8
      latestDefinition: { ... },
9
      statusDetail: [ ... ]
10
   }
11
]

1
use __mdb_internal_search
2
db.getCollectionNames().filter(n => n.startsWith("<index_id>"))

[ '69f382ecd6fa583100184fe7-96dad03b0a735a19fd9f1a22f9694efc-1-0' ]

1
use __mdb_internal_search
2
const mvColl = "<generated_embeddings_collection_name>"
3
db.getCollection(mvColl).countDocuments()

1
100

Compruebe el tamaño de almacenamiento de la colección de incrustaciones generadas.

Puedes consultar el tamaño de almacenamiento de las colecciones de incrustaciones generadas para comprender el consumo de espacio en disco e índice que generan. Esto resulta útil para la planificación de capacidad, la depuración de crecimientos inesperados y la validación de la limpieza tras eliminar o redefinir un índice.

1
use __mdb_internal_search
2
const mvColl = "<generated_embeddings_collection_name>"
3
db.getCollection(mvColl).stats()

1
use __mdb_internal_search
2
3
const mvColl = "<generated_embeddings_collection_name>";
4
5
db.runCommand({ collStats: mvColl }).count
6
db.runCommand({ collStats: mvColl, scale: 1024 * 1024 })

1
{
2
   ns: '__mdb_internal_search.69f382ecd6fa583100184fe7-96dad03b0a735a19fd9f1a22f9694efc-1-0',
3
   size: 5142,
4
   count: 1250000,
5
   avgObjSize: 4312,
6
   numOrphanDocs: 0,
7
   storageSize: 1830,
8
   freeStorageSize: 7,
9
   capped: false,
10
   wiredTiger: { ... },
11
   nindexes: 1,
12
   indexDetails: { ... },
13
   indexBuilds: [],
14
   totalIndexSize: 42,
15
   indexSizes: { _id_: 0 },
16
   totalSize: 1872,
17
   scaleFactor: 1048576,
18
   ok: 1,
19
   '$clusterTime': {
20
      clusterTime: Timestamp({ t: 1777646199, i: 1 }),
21
      signature: {
22
         hash: Binary.createFromBase64('pomqluUIpiZzLro3VWhO4dt2LKE=', 0),
23
         keyId: Long('7634583163557117960')
24
      }
25
   },
26
   operationTime: Timestamp({ t: 1777646199, i: 1 })
27
}

1
const s = db.runCommand({ collStats: mvColl, scale: 1024 * 1024 });
2
({
3
  count:          s.count,
4
  avgObjSizeKB:   (s.avgObjSize / 1024).toFixed(2),
5
  dataMB:         s.size,
6
  storageMB:      s.storageSize,
7
  indexesMB:      s.totalIndexSize,
8
  totalMB:        s.totalSize,
9
})

1
{
2
  "count": 1250000,
3
  "avgObjSizeKB": "4.21",
4
  "dataMB": 5142,
5
  "storageMB": 1830,
6
  "indexesMB": 42,
7
  "totalMB": 1872
8
}

1
from pymongo import MongoClient
2
3
MV_DATABASE = "__mdb_internal_search"
4
MB = 1024 * 1024
5
6
def get_mv_storage_stats(client, mv_collection_name):
7
    """Return storage metrics for a generated embeddings collection."""
8
    db = client[MV_DATABASE]
9
    stats = db.command("collStats", mv_collection_name, scale=MB)
10
    return {
11
        "count":         stats["count"],
12
        "avg_obj_kb":    round(stats["avgObjSize"] / 1024, 2),
13
        "data_mb":       stats["size"],
14
        "storage_mb":    stats["storageSize"],
15
        "indexes_mb":    stats["totalIndexSize"],
16
        "total_mb":      stats["totalSize"],
17
    }
18
19
client = MongoClient("mongodb+srv://<user>:<pwd>@<cluster>/")
20
print(get_mv_storage_stats(client, "<generated_embeddings_collection_name>"))

{'count': 1250000, 'avg_obj_kb': 4.21, 'data_mb': 5142, 'storage_mb': 1830, 'indexes_mb': 42, 'total_mb': 1872}

db.adminCommand({ listShards: 1 })

1
from pymongo import MongoClient
2
3
MV_DATABASE = "__mdb_internal_search"
4
MB = 1024 * 1024
5
6
def _resolve_mv_name(client, source_db, source_collection, index_name):
7
   """Find the generated embeddings collection name for an index."""
8
   src = client[source_db][source_collection]
9
   indexes = list(src.aggregate([{"$listSearchIndexes": {"name": index_name}}]))
10
   if not indexes:
11
      raise LookupError(f"No search index named {index_name!r}")
12
   index_id = indexes[0]["id"]
13
   matches = [n for n in client[MV_DATABASE].list_collection_names()
14
               if n.startswith(index_id)]
15
   if not matches:
16
      return None
17
   matches.sort(reverse=True)
18
   return matches[0]
19
20
def get_mv_storage_per_shard(shard_uris, source_db, source_collection, index_name):
21
   """Get per-shard and total storage for a sharded cluster."""
22
   per_shard = {}
23
   totals = {"count": 0, "data_mb": 0, "storage_mb": 0,
24
            "indexes_mb": 0, "total_mb": 0}
25
26
   for shard_name, uri in shard_uris.items():
27
      client = MongoClient(uri)
28
      mv_name = _resolve_mv_name(client, source_db, source_collection, index_name)
29
30
      if mv_name is None:
31
            per_shard[shard_name] = {"note": "no MV found (still building?)"}
32
            continue
33
34
      s = client[MV_DATABASE].command("collStats", mv_name, scale=MB)
35
      row = {
36
            "mv":           mv_name,
37
            "count":        s["count"],
38
            "data_mb":      s["size"],
39
            "storage_mb":   s["storageSize"],
40
            "indexes_mb":   s["totalIndexSize"],
41
            "total_mb":     s["totalSize"],
42
      }
43
      per_shard[shard_name] = row
44
45
      for k in totals:
46
            totals[k] += row[k]
47
48
   return {"per_shard": per_shard, "totals": totals}
49
50
# Usage
51
shard_uris = {
52
   "shard-00": "mongodb://<user>:<pwd>@shard-00.example.net:27017/?replicaSet=shard-00",
53
   "shard-01": "mongodb://<user>:<pwd>@shard-01.example.net:27017/?replicaSet=shard-01",
54
   "shard-02": "mongodb://<user>:<pwd>@shard-02.example.net:27017/?replicaSet=shard-02",
55
}
56
57
result = get_mv_storage_per_shard(
58
   shard_uris,
59
   source_db="<source_db>",
60
   source_collection="<source_collection>",
61
   index_name="<index_name>",
62
)
63
64
for shard, row in result["per_shard"].items():
65
   print(shard, row)
66
print("TOTAL:", result["totals"])

shard-00 {'mv': '69e183...-1-3', 'count': 416000, 'data_mb': 1714, 'storage_mb': 612, 'indexes_mb': 14, 'total_mb': 626}
shard-01 {'mv': '69e183...-1-3', 'count': 418200, 'data_mb': 1721, 'storage_mb': 615, 'indexes_mb': 14, 'total_mb': 629}
shard-02 {'mv': '69e183...-1-3', 'count': 415800, 'data_mb': 1707, 'storage_mb': 603, 'indexes_mb': 14, 'total_mb': 617}
TOTAL: {'count': 1250000, 'data_mb': 5142, 'storage_mb': 1830, 'indexes_mb': 42, 'total_mb': 1872}

1
use __mdb_internal_search
2
3
const MB = 1024 * 1024;
4
const rows = db.getCollectionNames().map(name => {
5
const s = db.runCommand({ collStats: name, scale: MB });
6
return {
7
   collection: name,
8
   count:      s.count,
9
   storageMB:  s.storageSize,
10
   indexesMB:  s.totalIndexSize,
11
   totalMB:    s.totalSize,
12
};
13
});
14
15
const total = rows.reduce((a, r) => ({
16
storageMB: a.storageMB + r.storageMB,
17
indexesMB: a.indexesMB + r.indexesMB,
18
totalMB:   a.totalMB   + r.totalMB,
19
}), { storageMB: 0, indexesMB: 0, totalMB: 0 });
20
21
print("Per-collection:");
22
printjson(rows);
23
print("Cluster total:");
24
printjson(total);

1
Per-collection:
2
[
3
   { "collection": "69e183...-1-3", "count": 1250000, "storageMB": 1830, "indexesMB": 42, "totalMB": 1872 },
4
   { "collection": "71fa42...-1-1", "count":   84000, "storageMB":  121, "indexesMB":  3,  "totalMB":  124 }
5
]
6
Cluster total:
7
  { "storageMB": 1951, "indexesMB": 45, "totalMB": 1996 }
8
}

Recuperar incrustaciones de la colección de incrustaciones generadas

1
use __mdb_internal_search
2
const mvColl = "<generated_embeddings_collection_name>"
3
db.getCollection(mvColl).findOne(
4
   { _id: "<document_id>" },
5
   { _id: 1, "_autoEmbed.<auto_embed_field>": 1 }
6
)

1
[
2
   { _autoEmbed: {}, _id: "ObjectId('573a1390f29313caabcd5c0f')" },
3
   { _autoEmbed: {}, _id: "ObjectId('573a1390f29313caabcd5c0f')" },
4
   {
5
      _autoEmbed: {
6
         fullplot: Binary.fromInt8Array(new Int8Array([
7
            5, -30,  16,   4, -57,  -8, -17, -13,  16,  11, -22,  15,
8
            -7,  13,   8,  -2,  -1, -14,  27,  10,  -9,  20,  14,  -2,
9
            3, -56, -21,  10, -24,  12,  10,   9,  12,   7,   4,  14,
10
            -7, -24, -15,  16,  13,  21,  -4, -16, -12, -15,   3, -33,
11
            5, -21,   2,  -1,   0,  16,   7,  13,  19,   4,   5, -14,
12
         -34,   7, -16,  38,   4,   4,   7, -22,   8,  14,  15, -14,
13
            -4,   6,  22, -17,   8,  27,   8,  13,  46, -12,  -7,  -9,
14
         -20,  13,  10,   4, -14, -11,  31,  -7,   0,  -3,   1,  16,
15
            9,   5,   6,  -2,
16
         ... 924 more items
17
         ]))
18
      },
19
      _id: "ObjectId('573a1390f29313caabcd5c0f')"
20
   },
21
   {
22
      _autoEmbed: {
23
         fullplot: Binary.fromInt8Array(new Int8Array([
24
            -5, -22,  22,  -6, -43, -13,  -5,   4,  5,   2,   4,  13,
25
            0,  -3,  -3, -50,  -5,  -2,  -2,  27, -5,  36,  27,  12,
26
         -12,  -6,  -1,   9,  -7,  25,   4, -28,  3,   9,   3,  23,
27
            8,  11,  11,  25, -19,  27,  17,  18, -1,   0,   5, -12,
28
            13,  -5,  -3,   3, -17,  16, -15,  43, -1,   1,   1,  -6,
29
         -26,  16, -11,  13,  14,   0,  -9, -23, 25, -16,  11, -25,
30
            7,   9,  -1,   0,  33,  -8,  -3, -18,  3,   4, -20, -14,
31
            17,  -2,  -2, -10,  17, -25, -11,   9,  1,   2,  -8,   7,
32
            20,  18,  17,  -2,
33
         ... 924 more items
34
         ]))
35
      },
36
      _id: "ObjectId('573a1390f29313caabcd5c0f')"
37
   },
38
   {
39
      _autoEmbed: {
40
         fullplot: Binary.fromInt8Array(new Int8Array([
41
            0,  -1,  47,   6, -20, -14,  29,  -2,  13,  -1,  20,  11,
42
         -18,  -7,  12, -10, -25,  10,   7, -15,  11,   9, -14,  12,
43
            -9, -22,  16,   0,  18,   5,   9, -26,  14, -27,   6,  20,
44
         -19,  -8,   1,  -5,  21,  13, -37,  -7,   0, -21, -51,   1,
45
         -38, -14,   4,   6, -23,  15,  19,  33,   8,   0,  -7,  -3,
46
         -25,   8, -29,  25,  -1,  12,   4, -21,  -1,   0, -14,  -3,
47
            -6,  -3,   7,  30,   8,  -8,  34, -19, -12, -29, -15, -14,
48
            1,  -4,   6,  -2, -36, -18,  -2,   4,  23,  17, -13,   1,
49
            0,   7,  25, -19,
50
         ... 924 more items
51
         ]))
52
      },
53
      _id: "ObjectId('573a1390f29313caabcd5c0f')"
54
   }
55
]

1
use __mdb_internal_search
2
const mvColl = "<generated_embeddings_collection_name>"
3
db.getCollection(mvColl).find(
4
   {},
5
   { _id: "<document_id>", "_autoEmbed.<auto_embed_field>": { $slice: 5 } }
6
).limit(<number_of_documents>)

1
[
2
   { _autoEmbed: {}, _id: "ObjectId('573a1390f29313caabcd5c0f')" },
3
   { _autoEmbed: {}, _id: "ObjectId('573a1390f29313caabcd5c0f')" },
4
   {
5
      _autoEmbed: {
6
         fullplot: Binary.fromInt8Array(new Int8Array([
7
            5, -30,  16,   4, -57,  -8, -17, -13,  16,  11, -22,  15,
8
            -7,  13,   8,  -2,  -1, -14,  27,  10,  -9,  20,  14,  -2,
9
            3, -56, -21,  10, -24,  12,  10,   9,  12,   7,   4,  14,
10
            -7, -24, -15,  16,  13,  21,  -4, -16, -12, -15,   3, -33,
11
            5, -21,   2,  -1,   0,  16,   7,  13,  19,   4,   5, -14,
12
         -34,   7, -16,  38,   4,   4,   7, -22,   8,  14,  15, -14,
13
            -4,   6,  22, -17,   8,  27,   8,  13,  46, -12,  -7,  -9,
14
         -20,  13,  10,   4, -14, -11,  31,  -7,   0,  -3,   1,  16,
15
            9,   5,   6,  -2,
16
         ... 924 more items
17
         ]))
18
      },
19
      _id: "ObjectId('573a1390f29313caabcd5c0f')"
20
   },
21
   {
22
      _autoEmbed: {
23
         fullplot: Binary.fromInt8Array(new Int8Array([
24
            -5, -22,  22,  -6, -43, -13,  -5,   4,  5,   2,   4,  13,
25
            0,  -3,  -3, -50,  -5,  -2,  -2,  27, -5,  36,  27,  12,
26
         -12,  -6,  -1,   9,  -7,  25,   4, -28,  3,   9,   3,  23,
27
            8,  11,  11,  25, -19,  27,  17,  18, -1,   0,   5, -12,
28
            13,  -5,  -3,   3, -17,  16, -15,  43, -1,   1,   1,  -6,
29
         -26,  16, -11,  13,  14,   0,  -9, -23, 25, -16,  11, -25,
30
            7,   9,  -1,   0,  33,  -8,  -3, -18,  3,   4, -20, -14,
31
            17,  -2,  -2, -10,  17, -25, -11,   9,  1,   2,  -8,   7,
32
            20,  18,  17,  -2,
33
         ... 924 more items
34
         ]))
35
      },
36
      _id: "ObjectId('573a1390f29313caabcd5c0f')"
37
   },
38
   {
39
      _autoEmbed: {
40
         fullplot: Binary.fromInt8Array(new Int8Array([
41
            0,  -1,  47,   6, -20, -14,  29,  -2,  13,  -1,  20,  11,
42
         -18,  -7,  12, -10, -25,  10,   7, -15,  11,   9, -14,  12,
43
            -9, -22,  16,   0,  18,   5,   9, -26,  14, -27,   6,  20,
44
         -19,  -8,   1,  -5,  21,  13, -37,  -7,   0, -21, -51,   1,
45
         -38, -14,   4,   6, -23,  15,  19,  33,   8,   0,  -7,  -3,
46
         -25,   8, -29,  25,  -1,  12,   4, -21,  -1,   0, -14,  -3,
47
            -6,  -3,   7,  30,   8,  -8,  34, -19, -12, -29, -15, -14,
48
            1,  -4,   6,  -2, -36, -18,  -2,   4,  23,  17, -13,   1,
49
            0,   7,  25, -19,
50
         ... 924 more items
51
         ]))
52
      },
53
      _id: "ObjectId('573a1390f29313caabcd5c0f')"
54
   }
55
]

1
from pymongo import MongoClient
2
3
MV_DATABASE = "__mdb_internal_search"
4
5
def get_mv_collection(client, source_db, source_collection, index_name):
6
   """Resolve the MV collection for an auto-embedding index."""
7
   # 1. Look up the index ID via $listSearchIndexes on the source collection.
8
   src = client[source_db][source_collection]
9
   indexes = list(src.aggregate([{"$listSearchIndexes": {"name": index_name}}]))
10
   if not indexes:
11
      raise LookupError(f"No search index named {index_name!r} on {source_db}.{source_collection}")
12
   index_id = indexes[0]["id"]
13
14
   # 2. Find the MV collection in __mdb_internal_search whose name starts with the index ID.
15
   mv_db = client[MV_DATABASE]
16
   matches = [n for n in mv_db.list_collection_names() if n.startswith(index_id)]
17
   if not matches:
18
      raise LookupError(f"No MV collection found for index {index_id} (index may still be building)")
19
   if len(matches) > 1:
20
      # Possible briefly during an auto-embed field update; pick the newest.
21
      matches.sort(reverse=True)
22
   return mv_db[matches[0]]
23
24
def get_embedding(client, source_db, source_collection, index_name, embed_path, source_id):
25
   """Fetch the embedding for a single source document."""
26
   mv = get_mv_collection(client, source_db, source_collection, index_name)
27
   doc = mv.find_one(
28
      {"_id": source_id},
29
      {"_id": 1, f"_autoEmbed.{embed_path}": 1},
30
   )
31
   if doc is None:
32
      return None
33
   return doc["_autoEmbed"][embed_path]
34
35
# --- Usage ---
36
client = MongoClient("mongodb+srv://<user>:<pwd>@<cluster>/")
37
38
embedding = get_embedding(
39
   client,
40
   source_db="<source_db>",
41
   source_collection="<source_collection>",
42
   index_name="<auto_embed_index_name>",
43
   embed_path="<auto_embed_field>",
44
   source_id="<document_id>",
45
)
46
47
print(f"dims:    {len(embedding)}")
48
print(f"first 5: {embedding[:5]}")

python get_embedding.py

1
from pymongo import MongoClient
2
3
# --- Usage ---
4
client = MongoClient("mongodb+srv://<user>:<pwd>@<cluster>/")
5
6
mv = get_mv_collection(client, "<source_db>", "<source_collection>", "<auto_embed_index_name>")
7
8
cursor = mv.find(
9
   {},
10
   {"_id": 1, "_autoEmbed.<auto_embed_field>": 1},
11
   batch_size=500,
12
)
13
14
for doc in cursor:
15
   src_id = doc["_id"]
16
   vec = doc["_autoEmbed"]["<auto_embed_field>"]

python stream_embedding.py

Solución de problemas

Las siguientes secciones ofrecen orientación para solucionar problemas comunes relacionados con la incrustación automatizada.

No se generó ninguna colección de incrustaciones que coincida con el ID del índice.

Es posible que su índice aún se encuentre en estado :guialbel`Building` o Pending. La colección de incrustaciones generada se crea de forma diferida en la primera escritura. Compruebe el estado utilizando $listSearchIndexes.

Falta el documento para una fuente _id

La incrustación para el documento especificado aún no se ha generado, o el documento fue filtrado por la expresión de filtro del índice.

Más de una colección coincide con el ID del índice.

Se ha actualizado la configuración del campo de incrustación automática. Aunque se ha creado una nueva colección de incrustaciones generadas, la anterior podría permanecer visible brevemente hasta que se complete la limpieza.