Cómo almacenar y consultar incrustaciones en MongoDB

El auge de los LLM y la búsqueda semántica ha cambiado radicalmente la forma en que creamos sistemas de búsqueda, recomendación y recuperación. La búsqueda tradicional por palabras clave, ya sea mediante SQL LIKE, Lucene invertido o índices de texto completo, resulta cada vez más insuficiente cuando los usuarios esperan una comprensión del lenguaje natural.

Aquí es donde incrustaciones y las bases de datos vectoriales entran en escena.

MongoDB ha evolucionado rápidamente en este ámbito con Atlas Vector Search, que ofrece a los programadores una única base de datos para documentos, metadatos y vectores, todo ello bajo una única API. En esta guía, veremos lo siguiente:

• ¿Qué es MongoDB?
• Qué son las incrustaciones de consultas y por qué son importantes.
• Cuándo debes utilizar incrustaciones.
• Cómo almacenar incrustaciones en MongoDB.
• Cómo generarlos y consultarlos utilizando Python.

Este tutorial es práctico y está listo para integrarse en tu generación aumentada por recuperación (RAG), búsqueda por similitud o canalización de recomendaciones.

¿Qué es MongoDB?

MongoDB es una base de datos nosql orientada a documentos que almacena datos en documentosBSONflexibles .BSON es una notación de objetos JavaScript codificada en binario (JSON), una notación de objetos textuales muy utilizada para transmitir y almacenar datos en aplicaciones basadas en la web. A diferencia de las bases de datos relacionales rígidas, MongoDB simplifica la evolución del esquema y ofrece:

• Escalabilidad horizontal (fragmentación).
• Marco de agregación enriquecido.
• Búsqueda de texto completo.
• Búsqueda vectorial.
• Colecciones de series temporales.
• Flexibilidad del esquema.

MongoDB Atlas, el servicio en la nube totalmente gestionado, amplía esto con:

• Búsqueda Atlas (basada en Lucene).
• Búsqueda vectorial Atlas (búsqueda semántica mediante indexación HNSW).
• Escalado automático, copias de seguridad, seguridad y supervisión.

MongoDB se ha convertido en una opción sólida para las cargas de trabajo de IA porque los vectores suelen coexistir con los metadatos, y MongoDB Atlas reúne todo eso en un solo sistema.

¿Qué son las incrustaciones y por qué utilizamos incrustaciones de consulta?

Cuando trabajas con búsqueda o recuperación en aplicaciones de IA, uno de los primeros conceptos con los que te encuentras es el de incrustaciones. 

Una incrustación es esencialmente una representación numérica, una larga lista de valores de coma flotante, que captura el significado de un fragmento de texto (o imagen, audio, etc.). En lugar de fijarse en las palabras exactas, las incrustaciones mapean el texto en un espacio vectorial donde las ideas similares terminan juntas. Por ejemplo, consideremos tres declaraciones de usuario diferentes:

• Problema de facturación
• Error de pago
• Salario no abonado

Aunque las palabras son diferentes, las tres describen un problema financiero. Un buen modelo de incrustación coloca estos textos cerca unos de otros en el espacio vectorial, lo que te permite recuperarlos en función del significado en lugar de las palabras clave.

Esto cobra especial importancia cuando el usuario realiza una búsqueda. El texto que escriben («¿Por qué se retrasa mi salario?») también se convierte en una incrustación. Este nuevo vector se denomina«incrustación de consulta de tipo» ( ).. A continuación, comparas este vector de consulta con todas las incrustaciones almacenadas para encontrar qué documentos son semánticamente similares. Cuanto más cercanos estén los vectores, más relevante será el resultado.

MongoDB Atlas simplifica enormemente todo este flujo de trabajo con Atlas Vector Search. Después de almacenar tus documentos y sus incrustaciones en una colección MongoDB, Atlas crea uníndice vectorial de búsqueda de documentos ( ) (utilizando HNSW en segundo plano) que puede recuperar rápidamente documentos similares a gran escala. Por ejemplo, si almacenas artículos de soporte técnico con sus incrustaciones, una consulta como...

query = "Why isn't my salary showing up this month?"
query_vec = get_embedding(query) # Explained in below examples

... se puede utilizar directamente en MongoDB:

results = collection.aggregate([
    {
        "$vectorSearch": {
            "path": "embedding",
            "queryVector": query_vec,
            "index": "vector_index",
            "limit": 3
        }
    }
])

MongoDB devolverá automáticamente los tres artículos de soporte más relevantes cuyos embeddings sean más similares a la consulta, sin que tengas que realizar ninguna coincidencia de palabras clave ni puntuación manual.

Este es el poder de las incrustaciones en MongoDB Atlas: almacenas significado, no solo texto, y realizas consultas basadas en la intención, no solo en palabras. Este cambio es la razón por la que las incrustaciones se han convertido en un elemento fundamental para la búsqueda semántica, los sistemas RAG, los asistentes de IA y las bases de conocimiento inteligentes.

Cuándo utilizar incrustaciones de consultas

Utiliza incrustaciones cuando desees similitud semántica, como por ejemplo:

Generación aumentada por recuperación (RAG)

• Alimenta tu LLM con contexto preciso procedente de tu base de conocimientos.
• Reemplazar la búsqueda de palabras clave frágiles

Chatbots que requieren un profundo conocimiento

• Servicio de asistencia del portal
• Atención al cliente

Recomendación de productos

• «artículos similares a este artículo»

Detección de documentos o duplicados

• Agrupación
• Agrupación por temas

Cuando falla la búsqueda por palabra clave

• Consultas como «retraso en el abono del salario» frente a «problema en el procesamiento del pago».

Haz no utilices incrustaciones cuando:

• Se requiere una coincidencia exacta (ID, números de factura).
• Tu conjunto de datos es muy pequeño (la búsqueda simple funciona).
• Necesitas filtros/comparaciones numéricas (los metadatos deberían encargarse de eso).

Cómo almacenar incrustaciones en MongoDB

La belleza de MongoDB es que las incrustaciones encajan de forma natural dentro de los documentos. Solo tienes que almacenarlos como arreglos de números flotantes.

Ejemplo de esquema de documento

Esta es una estructura típica de documento:

{
  "_id": "uuid-123",
  "text": "This is a sample document about MongoDB vector search.",
  "embedding": [0.123, -0.241, 0.998, ...],
  "tags": ["mongodb", "vector", "ai"],
  "createdAt": "2025-01-01T10:20:00Z"
}

Aspectos importantes a tener en cuenta:

• Cada incrustación en una colección debe tener la misma dimensionalidad.
• Lo ideal es que las incrustaciones se almacenen como float32 (MongoDB los convertirá internamente a float64).
• Si tus documentos son largos, divídelos antes de incrustarlos.
• Almacenar los metadatos por separado: etiquetas, categoría, URL, marcas de tiempo, etc. Esto hace que la búsqueda híbrida sea muy potente.

Creación de un índice vectorial en MongoDB (paso crítico)

Antes de almacenar o consultar incrustaciones, debes crear un índice de búsqueda vectorial en MongoDB Atlas.

En MongoDB Atlas, ve a: Atlas → Base de datos → Colecciones → Búsqueda → Crear índice de búsqueda

Utiliza una definición como:

{
  "fields": [
    {
      "type": "vector",
      "path": "embedding",
      "numDimensions": 1536,
      "similarity": "cosine"
    }
  ]
}

Esto le indica a MongoDB:

• El campo incrustación contiene vectores.
• Cada vector tiene 1536 dimensiones.
• Utiliza la similitud coseno para la clasificación.

Este índice alimenta todas las consultas de búsqueda vectorial.

MongoDB incluye capacidades nativas de búsqueda vectorial con soporte para:

• Similitud coseno.
• Distancia euclidiana.
• Puntuación dotProduct.

Elige en función de tu modelo de integración, pero ¿cómo sabemos qué elegir? Profundicemos.

Similitud coseno

Lo que mide

Mide la alineación entre dos vectores, es decir, el ángulo entre ellos. Ignora la magnitud y se centra únicamente en la dirección.

Intuición

• Si dos vectores apuntan en la misma dirección → similitud cercana a 1
• Direcciones opuestas → –1
• Ortogonal (sin relación) → 0

Cuándo utilizarlo

Utiliza el coseno cuando la magnitud no importe, solo el patrón o concepto que se expresa.

Usos comunes

• Text embeddings/NLP
• Búsqueda semántica
• Sistemas de recomendación basados en el significado, no en la escala

El coseno es el valor predeterminado más seguro para la mayoría de los modelos de incrustación.

distancia euclidiana

Lo que mide

Mide la distancia en línea recta entre dos vectores en el espacio.

Intuición

• Pequeña distancia → los vectores son similares
• Gran distancia → los vectores están muy separados

Cuándo utilizarlo

Utiliza Euclides cuando importan los valores absolutos y las magnitudes, no solo la dirección.

Usos comunes

• Incrustaciones de imágenes
• Mediciones físicas/datos de sensores
• Algoritmos de agrupamiento como K-means (que utiliza internamente Euclides)

Si tus datos residen naturalmente en un espacio geométrico (por ejemplo, intensidades de píxeles), a menudo tiene más sentido utilizar la geometría euclidiana.

Producto escalar

Lo que mide

Mide una combinación de similitud y magnitud. 

Matemáticamente: dot(u, v) = |u| × |v| × cos(θ)

Intuición

• Mayor magnitud Y alineación → mayor puntuación
• Sensible a la longitud del vector
• No se normaliza automáticamente.

Cuándo utilizarlo

Utiliza el producto escalar cuando quieras que los vectores más largos tengan más influencia o cuando el modelo de incrustación se entrena teniendo en cuenta el producto escalar.

Usos comunes

• Incrustaciones de modelos lingüísticos grandes que asumen producto interno puntuación
• Capas de similitud de redes neuronales
• Modelos de recomendación en los que la «fuerza» de las características es significativa.

Regla general rápida

Generar, almacenar y consultar incrustaciones en MongoDB (tutorial de Python)

Veamos esto como si estuviéramos construyendo un sistema real.

Instalar dependencias

pip install pymongo openai

Generar incrustaciones

Usando OpenAI (cambia por cualquier proveedor de incrustación que prefieras):

import os
from openai import OpenAI

os.environ["OPENAI_API_KEY"] = "your_api_key_here"
client = OpenAI()

def get_embedding(text: str):
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=text
    )
    return response.data[0].embedding

Conectarse a MongoDB e insertar documentos

Usando OpenAI (cambia por cualquier proveedor de incrustación que prefieras):

from pymongo import MongoClient
import uuid

mongo = MongoClient("<MONGODB_ATLAS_URI>")
db = mongo["vector_db"]
collection = db["documents"]

text = "This is a sample document about MongoDB vector search."
embedding = get_embedding(text)

document = {
    "_id": str(uuid.uuid4()),
    "text": text,
    "embedding": embedding,
    "tags": ["mongodb", "search"],
}

collection.insert_one(document)
print("Document inserted successfully!")

En este punto, tus datos están listos para la búsqueda semántica.

Consultas de incrustaciones en MongoDB

Ahora viene la parte divertida: recuperar documentos similares utilizando una consulta vectorial. MongoDB utiliza $vectorSearch en un canal de agregación.

Generar vector de consulta

from pymongo import MongoClient
query = "How does MongoDB handle semantic search?"
query_vec = get_embedding(query)

Realizar búsqueda vectorial (incrustaciones de consultas)

results = collection.aggregate([
    {
        "$vectorSearch": {
            "index": "vector_index",
            "path": "embedding",
            "queryVector": query_vec,
            "numCandidates": 100,
            "limit": 5,
            "similarity": "cosine"
        }
    },
    {
        "$project": {
            "text": 1,
            "score": {"$meta": "vectorSearchScore"}
        }
    }
])

for r in results:
    print(r)

Esto devuelve los cinco documentos más similares semánticamente.

Esto resulta muy útil para los procesos RAG en los que se desea realizar una búsqueda semántica.

Explicación paso a paso de la consulta anterior.

$vectorSearch → Encuentra documentos cuyo campo de incrustación es más cercano a queryVector utilizando la métrica de similitud especificada.

numCandidates → Cuántas coincidencias potenciales debe considerar el motor antes de seleccionar los mejores resultados.

límite → Número de resultados similares finales que se van a devolver

$project → Devuelve el texto original más un campo especial llamado puntuación

¿Qué es el campo de puntuación?

La búsqueda vectorial de MongoDB Atlas devuelve un campo de metadatos especial, «score»: {«$meta»: «vectorSearchScore»}, que te indica cuán similar un vector almacenado con el vector de tu consulta.

El significado de la puntuación depende de la métrica de similitud que elijas, tal y como se explica a continuación:

Mejores prácticas

• Documentos largos fragmentados (300-500 tokens cada uno): Mayor relevancia + evita la incorporación de bloques largos
• Almacenar los metadatos por separado: Ayuda a filtrar y clasificar
• Generación de incrustaciones por lotes: Mejora el rendimiento y reduce el coste del modelo.
• Utiliza incrustaciones float32 en tu modelo: MongoDB utiliza internamente float64, pero acepta arreglos float32.
• Indexa solo el campo vectorial: Los campos adicionales en el índice aumentan la memoria y la latencia.

Errores comunes que debes evitar

Reflexiones finales

Las incrustaciones y la búsqueda semántica son ahora fundamentales para los productos modernos de inteligencia artificial. Ya sea que estés creando un chatbot, un canal RAG, un motor de recomendaciones o una capa de búsqueda inteligente, necesitas una forma fiable de almacenar vectores y consultarlos de manera eficiente.

MongoDB te ofrece una plataforma unificada en la que:

• Tu texto cobra vida.
• Tus metadatos cobran vida.
• Tus incrustaciones viven.
• Tu búsqueda vectorial se ejecuta.
• Todo se adapta al mismo tiempo.

Esto evita la complejidad de tener que manejar varias bases de datos independientes y te permite centrarte en desarrollar las capacidades del producto, en lugar de la infraestructura.