Cómo crear una aplicación de búsqueda vectorial con MongoDB Atlas y Python

Hasta hace poco, los ordenadores funcionaban como bibliotecarios eficientes pero literales. Si buscabas "batallas de robots gigantes", solo encontraban títulos con esas palabras exactas. Un ajuste perfecto como "Kaiju Mech Warfare" pasaría desapercibido. Los ordenadores reconocían palabras pero se perdían la música: les faltaban comprensión, matiz y contexto. Era la era de la búsqueda por palabras clave, nuestra mejor opción durante muchos años.

Luego llegó una revolución. Inspirándose en el cerebro humano, la inteligencia artificial desarrolló una nueva forma de aprender. En lugar de memorizar palabras, la IA empezó a comprender las relaciones entre ellas. Entiende que "rey" se relaciona con "hombre" igual que "reina" con "mujer". Reconoce que "feliz", "alegre" y "eufórico" comparten un territorio emocional, mientras que "sombrío" vive en un mundo completamente distinto.

¿Cómo lo consiguió la IA? Creando un mapa del significado.

¿Qué es la búsqueda vectorial? El mapa del significado

Imagina una vasta galaxia multidimensional donde cada concepto—una palabra, una frase, una imagen, una canción—es una estrella. En esta galaxia, las estrellas con significados similares se agrupan, mientras que las no relacionadas están a años luz de distancia.

Un vector embedding no es más que la coordenada de una estrella en esta galaxia. Es una lista de números (p. ej., [0.12, -0.45, 0.89, ...]) que sitúa con precisión un concepto en este mapa del significado.

La búsqueda vectorial es la capacidad revolucionaria de navegar por este mapa. Cuando preguntas "una película sobre un niño huérfano que descubre que es mago", no buscamos esas palabras exactas. En su lugar:

1. Encontramos la coordenada (el vector) de tu consulta en el mapa.
2. Localizamos las estrellas vecinas más cercanas (nuestras sinopsis de películas).

Las estrellas más próximas representan los resultados semánticamente más similares. Así pasó la IA de ser una bibliotecaria literal a una sabia que entiende qué quieres decir de verdad.

¿Por qué es tan importante?

Buscar por significado en lugar de por palabras clave impulsa aplicaciones modernas de IA en todos los sectores. Esta capacidad permite:

• Netflix recomendarte películas nuevas que comparten un "vibe" similar con tu historial de visionado.
• Spotify crear listas con canciones que se sienten como tus favoritas, sin importar el género o la época.
• Chatbots y LLMs comprender la intención detrás de tus preguntas y ofrecer respuestas relevantes y con contexto.
• Sitios de e-commerce mostrar productos visualmente similares a las imágenes que subes.

La búsqueda vectorial conecta la intención humana con los datos digitales, transformando de raíz cómo interactuamos con la información. Hace que los sistemas digitales se sientan menos mecánicos y más como colaboradores intuitivos.

Aprendamos: crea tu primera aplicación de búsqueda vectorial con MongoDB

¡Bienvenido a la nueva frontera de la búsqueda! MongoDB incorporó Vector Search en Atlas. Te permite almacenar y consultar embeddings vectoriales (de texto, imágenes o audio) directamente en MongoDB, sin necesidad de una base de datos vectorial aparte como Pinecone o Weaviate.

En este tutorial, crearemos un sencillo pero potente motor de recomendaciones de zapatillas usando Python y MongoDB Atlas. Aprenderás a convertir texto en representaciones numéricas con significado (vectores) y luego usar la Vector Search integrada de Atlas para encontrar productos con descripciones similares.

Qué vas a aprender

• Cómo conectarte de forma segura a un clúster de MongoDB Atlas usando la librería pymongo de Python.
• Cómo crear e insertar documentos que contengan embeddings vectoriales.
• Cómo generar embeddings vectoriales a partir de texto con la librería sentence-transformers.
• Cómo crear un índice de Vector Search en la interfaz de MongoDB Atlas.
• Cómo realizar una consulta de búsqueda semántica usando la canalización de agregación $vectorSearch.

Requisitos previos

• Una cuenta gratuita de MongoDB Atlas
• Python 3.9+ instalado localmente
• Instalar dependencias:

pip install pymongo sentence-transformers numpy

Paso 1: crea un clúster de MongoDB Atlas

• Inicia sesión en Atlas.

• Crea un clúster gratuito. Crea un usuario y copia el nombre de usuario y la contraseña.

• Tras crear el usuario, haz clic en Choose a connection method. Verás la primera pantalla de abajo. Haz clic en Drivers y pasa a la segunda pantalla. Selecciona Python como driver y la versión correspondiente. Copia la cadena de conexión.

• Ve a Database Deployments → Haz clic en Browse Collections → Crea una base de datos nueva:
• Nombre de la base de datos: vectorDemo
• Nombre de la colección: items

• Activa Vector Search:
• En la interfaz de MongoDB Atlas, ve a Vector Search Indexes → Crea un índice nuevo para items.
• Nombre del índice: “vector_index”
• Usa esta definición:

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

Nota: 768 es el tamaño del embedding que usaremos con el modelo de sentence-transformers.

Entendiendo la definición del índice:

• "type": "vector": Indica a MongoDB Atlas que es un índice vectorial.
• "path": "embedding": Señala el campo de nuestros documentos que contiene los vectores.
• "numDimensions": 768: Debe coincidir con la dimensión de los vectores que genera nuestro modelo.
• "similarity": "cosine": El algoritmo para medir la "cercanía" de los vectores. Es excelente para similitud basada en texto.

Paso 2: conecta Python con MongoDB Atlas

Obtén tu cadena de conexión de MongoDB Atlas:

• En MongoDB Atlas, haz clic en Connect → Drivers → Python.
• Sustituye <username>, <password> y <cluster-url> en el fragmento siguiente.

from pymongo import MongoClient

# Replace with your Atlas connection string
uri = "mongodb+srv://<username>:<password>@<cluster-url>/vectorDemo?retryWrites=true&w=majority"

client = MongoClient(uri)
db = client["vectorDemo"]
collection = db["items"]
print("Connected to MongoDB Atlas")

# Clear existing
collection.delete_many({})
print("Cleared collection.")

Paso 3: genera embeddings con Python

Usaremos SentenceTransformers para convertir texto en embeddings.

from sentence_transformers import SentenceTransformer
# Choose model: higher-quality for search -> "sentence-transformers/all-mpnet-base-v2" (768-d)
# If you need faster/smaller: "all-MiniLM-L6-v2" (384-d)
MODEL_NAME = "sentence-transformers/all-mpnet-base-v2"
# MODEL_NAME = "all-MiniLM-L6-v2"

# Note: if you use all-mpnet-base-v2, your Atlas vector index must use numDimensions: 768
# If you use all-MiniLM-L6-v2, index numDimensions: 384
model = SentenceTransformer(MODEL_NAME)

def embed_text(text: str):
    return model.encode(text).tolist()

Paso 4: inserta documentos de ejemplo con embeddings

Vamos a guardar algunas descripciones de producto en MongoDB junto con sus embeddings.

# Each product includes name, description, list of features, use_cases and tags.
products = [
    # Marathon / long-distance running (explicit!)
    {
        "name": "MarathonPro 3000",
        "description": "Designed specifically for marathon and ultra distance running: maximum cushioning, breathable knit upper, responsive midsole and engineered heel support for long-run comfort.",
        "features": ["marathon", "long-distance", "max cushioning", "breathable", "support"],
        "category": "shoes",
        "use_cases": ["marathon", "long-distance running", "road running"],
        "tags": ["running", "endurance", "comfort"]
    },
    {
        "name": "Enduro LongRun",
        "description": "Lightweight long-run trainer optimized for marathon pacing with added cushioning, stable platform, and enhanced forefoot energy return for hours of comfortable running.",
        "features": ["long-run", "lightweight", "energy return", "cushioning"],
        "category": "shoes",
        "use_cases": ["marathon", "road running"],
        "tags": ["running","marathon","comfort"]
    },

    # Road running / neutral
    {
        "name": "Red Road Runner",
        "description": "Neutral road running shoe for daily training: breathable mesh, moderate cushioning and responsive ride; suitable for tempo runs and long easy runs.",
        "features": ["road running", "breathable", "moderate cushioning"],
        "category": "shoes",
        "use_cases": ["training", "road running", "tempo runs"],
        "tags": ["running","training"]
    },

    # Trail running (explicit trail)
    {
        "name": "TrailMaster RidgeGrip",
        "description": "Trail-running shoe with aggressive outsole, rock plate for protection, waterproof upper, designed for technical trails and rugged terrain.",
        "features": ["trail", "high grip", "rock plate", "waterproof"],
        "category": "shoes",
        "use_cases": ["trail running", "hiking", "off-road"],
        "tags": ["trail","outdoors"]
    },

    # Tennis & court
    {
        "name": "CourtPro Tennis",
        "description": "Court shoe with lateral support, non-marking sole and reinforced toe; built for tennis footwork and short intense bursts, not for long-distance running.",
        "features": ["court", "lateral support", "non-marking sole"],
        "category": "shoes",
        "use_cases": ["tennis","court sports"],
        "tags": ["tennis","sport"]
    },

    # Formal
    {
        "name": "Oxford Leather Formal",
        "description": "Classic leather formal shoe for office and events: polished leather, sturdy sole, refined silhouette.",
        "features": ["formal", "leather", "office"],
        "category": "shoes",
        "use_cases": ["formal wear","office"],
        "tags": ["formal","leather"]
    },

    # Hiking
    {
        "name": "Alpine Trek Boots",
        "description": "High-ankle hiking boots with waterproof membrane, ankle support and durable lugged outsole for mountain treks.",
        "features": ["hiking", "waterproof", "ankle support", "lugged outsole"],
        "category": "shoes",
        "use_cases": ["hiking","trekking","outdoor"],
        "tags": ["outdoors","hiking"]
    },

    # Casual sneakers
    {
        "name": "Classic Canvas Sneaker",
        "description": "Casual everyday canvas sneaker with rubber sole, comfortable fit for daily wear and walking.",
        "features": ["casual","canvas", "everyday"],
        "category": "shoes",
        "use_cases": ["casual","walking"],
        "tags": ["casual"]
    },

    # Cross-trainer
    {
        "name": "CrossFit Trainer",
        "description": "Stable cross-trainer shoe engineered for gym workouts, short sprints, and lateral movements; flexible yet supportive.",
        "features": ["cross-train","stable","gym"],
        "category": "shoes",
        "use_cases": ["gym","cross-training"],
        "tags": ["training","gym"]
    },

    # Cleats
    {
        "name": "Pro Soccer Cleats",
        "description": "Low-profile football/soccer cleats with studded outsole; optimized for grip on grass and agility.",
        "features": ["cleats","studs","agility"],
        "category": "shoes",
        "use_cases": ["soccer","football"],
        "tags": ["sports","cleats"]
    }
]

# ---------- Create 'canonical_text' to improve embedding quality for better scoring ----------
for p in products:
    # join features and others into one rich text blob
    features = ", ".join(p["features"])
    uses = ", ".join(p["use_cases"])
    tags = ", ".join(p["tags"])
    canonical = f"{p['name']}. {p['description']}. Features: {features}. Use cases: {uses}. Tags: {tags}."
    p["canonical_text"] = canonical

# ---------- Embed canonical_text----------
print("Embedding items...")
for p in products:
    p["embedding"] = embed_text(p["canonical_text"])

# ---------- Insert into MongoDB ----------
collection.insert_many(products)

Usando insert_many, realizamos una única operación de escritura en bloque eficiente en nuestra base de datos.

Paso 5: realiza tu primera búsqueda vectorial

¡Es hora del último y más emocionante paso! Usaremos el framework de agregación de MongoDB y $vectorSearch—un operador para encontrar las mejores zapatillas según la consulta.

query_text = "25k long running best shoes"
query_embedding = embed_text(query_text)

pipeline = [
    {
        "$vectorSearch": {
            "index": "vector_index",  # Use the vector search index you created
            "path": "embedding",
            "queryVector": query_embedding,
            "numCandidates": 100,
            "limit": 3
        }
    },
    {
        "$project": {
            "name": 1,
            "description":1,
            "score": {"$meta": "vectorSearchScore"}
        }
    }
]

results = collection.aggregate(pipeline)

print(f"\nSearch results for: '{query_text}'\n")
for r in results:
    print(f"- {r['name']} (score: {r['score']:.4f})")

Destripando la canalización de $vectorSearch:

• $vectorSearch: Es el operador central. Compara eficientemente nuestro queryVector con el campo indexado plot_embedding de todos los documentos.
• $project: Esta etapa reestructura la salida. Incluimos name y description, excluimos el ruidoso _id y otros campos, y lo más importante: añadimos un campo score usando $meta: "vectorSearchScore". Esta puntuación, de 0 a 1, indica cuán similar es el resultado a nuestra consulta.

Salida esperada

Si todo está bien configurado, verás algo como esto:

Search results for: '25k long running best shoes'

- MarathonPro 3000 (score: 0.7980)
- Red Road Runner (score: 0.7479)
- Enduro LongRun (score: 0.7389)

Observa que “MarathonPro 3000” aparece en primer lugar—exactamente lo esperado.

Enhorabuena. Has creado desde cero una aplicación de búsqueda vectorial. Has aprendido a conectarte a una base de datos, crear y validar datos, generar embeddings vectoriales y aprovechar la potencia de MongoDB Atlas para encontrar información de forma realmente inteligente. Bienvenido al futuro de la interacción con los datos.

Conclusión

En este tutorial has aprendido a:

• Conectarte a MongoDB Atlas con Python y pymongo, base para aplicaciones impulsadas por bases de datos.
• Crear embeddings (solo texto) a partir de un catálogo de productos realista con modelos de alta calidad como all-mpnet-base-v2, y a almacenarlos en MongoDB con la normalización adecuada.
• Construir un dataset rico y estructurado usando canonical_text (nombre, descripción, características, casos de uso, etiquetas), lo que mejora la relevancia de los embeddings.
• Realizar búsquedas por similitud vectorial con la etapa de agregación $vectorSearch de MongoDB para encontrar productos semánticamente similares a partir de consultas en lenguaje natural.

Próximos pasos (ponlo en práctica)

• Almacena reseñas de usuarios y crea un motor de búsqueda semántica.

Experimenta con diferentes métricas de similitud (dotProduct, euclidean).