Cómo funciona la generación automática de incrustaciones

Document Inserts

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

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

2. Genera incrustaciones para el campo de texto utilizando el model 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 actualices un document y el campo de texto indexado cambie, MongoDB Vector Search automáticamente:

1. Detecta el cambio del campo mediante flujos de cambio.

2. Genera nuevas incrustaciones para el texto actualizado.

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

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

document Eliminaciones

Cuando eliminas un document, MongoDB Vector Search elimina automáticamente los embeddings correspondientes de la colección del sistema y actualiza el índice.

Infraestructura de model

• Servicio alojado: Todos los embedding model son alojados y mantenidos por MongoDB. La plataforma de inferencia del model funciona en la infraestructura de MongoDB en Google Cloud en una región de EE. UU. No necesitas implementar, configurar o gestionar ninguna infraestructura de model.

• Acceso basado en API: para implementaciones autogestionadas que están configuradas para usar la clave de API de Voyage AI, MongoDB envía texto a los endpoints de la API de Voyage AI para generar incrustaciones. Las incrustaciones se devuelven a MongoDB y se almacenan en tu clúster.

• Arquitectura multi-inquilino: El servicio de incrustación se comparte entre varios usuarios. Este model multi-inquilino proporciona:

  • Eficiencia de costos mediante infraestructura compartida

  • Actualizaciones y mejoras automáticas del model

  • Alta disponibilidad y escalabilidad

Privacidad de los datos

• El texto enviado al servicio de Embedding automático se utiliza únicamente para generar incrustaciones y no se almacena ni se usa para el entrenamiento del model.

• Las incrustaciones se devuelven a tu clúster de MongoDB y se almacenan en tu propia base de datos.

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

Límites de velocidad

El servicio de incrustación es multiusuario. Por este motivo, 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 tasa y cómo afectan las operaciones de incrustación automatizada, véase Límites de tasa.

Query Límites de velocidad

Cada query que utiliza la Incrustación Automatizada cuenta para tus límites de tasa de Incrustación Automatizada porque requiere una llamada a la API para generar incrustaciones. Para obtener más información sobre cómo gestionar el rendimiento y los costes de las consultas, consulta Límites de tasa.

Sincronización inicial

• Las colecciones grandes pueden tardar un tiempo considerable en completar la sincronización inicial si te topas con límites de velocidad.

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

• Puede supervisar el progreso de la sincronización a través de Supervisión de búsqueda.

Actualizaciones continuas

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

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

• Tu aplicación sigue funcionando con normalidad; solo la generación de incrustaciones podría retrasarse.

Queries

• Los límites de frecuencia de consulta afectan la cantidad de búsquedas concurrentes que puedes realizar.

• Si excedes los límites de la tasa de queries, las queries devolverán un error que indica que se ha superado el límite de tasa de query.

• Considera almacenar en caché los resultados de las consultas que se usan con frecuencia o actualizar a un nivel de pago para 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

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

Puedes verificar el tamaño de almacenamiento de las colecciones de incrustaciones generadas para comprender el consumo de espacio en disco e índice a partir de las incrustaciones generadas. Esto es útil para la planificación de la capacidad, la depuración de crecimientos inesperados y la validación de la limpieza después de 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 proporcionan orientación para la resolución de problemas comunes con la incrustación automática.

No hay ninguna colección de incrustaciones generadas que coincida con el ID de índice

Tu índice aún podría estar en el estado Building o Pending. La colección de incrustaciones generadas se crea de forma perezosa en la primera escritura. Comprobar el estado utilizando el $listSearchIndexes.

document faltante para una fuente _id

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

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

La configuración del campo de inserción automática se ha actualizado. Aunque se ha creado una nueva colección de incrustaciones generadas, la anterior puede permanecer temporalmente hasta que se realice la limpieza.