Saltar al contenido principal

Cómo crear un asistente de preguntas y respuestas en Django con auto-embeddings de MongoDB

Crea búsqueda semántica en Django con auto-embeddings de MongoDB: sin código de embeddings, resincronización automática cuando cambian los documentos y consultas en texto plano.
· 7 min leer

Explora con IA

Qué simplifican los auto-embeddings

En una arquitectura típica de RAG (retrieval-augmented generation), generas embeddings al insertar un documento, los vuelves a generar cuando el contenido cambia y te encargas de incrustar cada consulta. Automated Embedding simplifica la creación de búsquedas semánticas: MongoDB Atlas se encarga de generar, actualizar y consultar embeddings de forma nativa, y Vector Search almacena los vectores en tu clúster.

Cómo hace MongoDB el embedding automático

Cuando se crea un índice de vector search de tipo autoEmbed, MongoDB genera embeddings para el campo elegido usando el modelo VoyageAI, los mantiene sincronizados cuando hay cambios en el documento y, en tiempo de búsqueda, incrusta el texto de la consulta con el mismo modelo. Los embeddings generados se almacenan de forma asíncrona en el clúster de MongoDB en una base de datos interna separada.

En este tutorial, construiremos un asistente de preguntas y respuestas (Q&A) sobre documentación con auto-embeddings de MongoDB. Usaremos el backend de Django para MongoDB para definir los modelos e ingerir documentos; MongoDB se encargará de las búsquedas, de generar y sincronizar embeddings automáticamente, y el LLM devolverá documentos según los resultados recuperados.

Al finalizar este tutorial, habrás construido la fase de recuperación de una canalización RAG: una búsqueda semántica sobre documentos del Federal Register donde los auto-embeddings hacen el trabajo por ti. Los documentos se incrustan al insertarlos, se re-incrustan cuando cambian, y tus consultas se incrustan en tiempo de búsqueda, todo ello sin escribir código de embeddings.

Hay dos formas de seguir este tutorial.

Configuración

Antes de empezar, asegúrate de tener:

Una vez tengas estos requisitos, el siguiente paso es crear la carpeta del proyecto.

Crea un proyecto y un entorno virtual

Crea una carpeta vacía para tu proyecto y ve a ella con cd.

mkdir regulations_qa
cd regulations_qa

Este será el directorio raíz del proyecto. Crea y activa aquí tu entorno virtual si aún no lo has hecho:

python -m venv .venv

Para activar el entorno virtual en macOS o Linux, ejecuta:

source .venv/bin/activate

En Windows, ejecuta:

.venv\Scripts\activate

Instala las dependencias

Crea un archivo requirements.txt en la raíz del proyecto con este contenido:

# requirements.txt
django-mongodb-backend
python-dotenv
requests #to fetch documents from the Federal Register API.

Después, instala todo:

pip install -r requirements.txt

Crea el proyecto y la app de Django

Desde la raíz del proyecto, ejecuta el siguiente comando para crear un nuevo proyecto y una app de Django. Añade el . final en el comando startproject para decirle a Django que instale el proyecto en el directorio actual en lugar de crear una carpeta anidada.

django-admin startproject regulations_qa --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/6.0.x.zip .

Crea la app documents

python manage.py startapp documents

Registra la app en regulations_qa/settings.py añadiéndola a INSTALLED_APPS:

INSTALLED_APPS = [
    'regulations_qa.apps.MongoAdminConfig',
    'regulations_qa.apps.MongoAuthConfig',
    'regulations_qa.apps.MongoContentTypesConfig',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django_mongodb_backend',
    'documents',
]

Configura las variables de entorno

Crea un archivo .env en la raíz del proyecto con tus propios valores, y añádelo a .gitignore para que no se suba al repositorio.

# .env
SECRET_KEY=[REPLACE_WITH_YOUR_SECRET_KEY]
MONGODB_URI="mongodb+srv://<username>:<password>@<cluster>.mongodb.net/?retryWrites=true&w=majority"
DB_NAME=regulations_qa
VECTOR_INDEX_NAME=autoembed_index

Elimina la línea original con SECRET_KEY = '...' de settings.py, copia el valor que generó Django en settings.py cuando ejecutaste startproject y sustitúyelo en tu .env. Por defecto viene codificado en el archivo, y lo movemos a .env para mantenerlo fuera del control de versiones, ya que Django lo usa para firmar cookies de sesión, tokens CSRF y otros datos sensibles.

Abre regulations_qa/settings.py y asegúrate de que contiene todo lo siguiente. Las líneas de importación y load_dotenv() van arriba. Sustituye las definiciones existentes de SECRET_KEY y DATABASES y añade la línea VECTOR_INDEX_NAME:

import os
from dotenv import load_dotenv

load_dotenv()

SECRET_KEY = os.getenv("SECRET_KEY")
VECTOR_INDEX_NAME = os.getenv("VECTOR_INDEX_NAME")

DATABASES = {
    'default': {
        'ENGINE': 'django_mongodb_backend',
        'HOST': os.getenv("MONGODB_URI"),
        'NAME': os.getenv("DB_NAME"),
    },
}

Crea las carpetas para los comandos de gestión

A continuación creamos carpetas con archivos __init__.py vacíos para los management commands, porque Django solo detecta comandos personalizados en un paquete management/commands/.

mkdir -p documents/management/commands documents/services && touch documents/management/__init__.py documents/management/commands/__init__.py documents/services/__init__.py

La fuente de datos: los documentos del Federal Register

En este tutorial indexaremos documentos del Federal Register, las publicaciones diarias del gobierno de EE. UU. con normas, propuestas y avisos. La fuente de datos es una API pública con documentos que incluyen un título y un breve resumen en prosa, ideal para búsqueda semántica.

Documentación de la API: https://www.federalregister.gov/developers/documentation/api/v1

Los registros tienen campos como title, type, abstract, document_number (un ID único), publication_date, html_url y una lista de agencies.

  • Algunos documentos contienen valores nulos, así que los omitiremos.
  • Los resúmenes incluyen marcas como <INF>2.5</INF> en “PM2.5”, por lo que eliminamos etiquetas antes de guardar.
  • Los resultados están paginados hasta 100 por solicitud y cada página incluye un next_page_url (basado en cursor) para seguir.

Prueba del endpoint por shell

curl -g "https://www.federalregister.gov/api/v1/documents.json?conditions[agencies][]=environmental-protection-agency&per_page=2"

Nota: Son datos públicos del gobierno de EE. UU. usados con fines de demostración. No es una fuente legal; para investigación jurídica usa la edición oficial.

Ingesta de datos

Empezaremos creando los modelos en el archivo models.py.

# documents/models.py
from django.db import models


class Document(models.Model):
    document_number = models.CharField(max_length=32, unique=True)
    title = models.TextField()
    doc_type = models.CharField(max_length=32)
    agency = models.CharField(max_length=128)
    publication_date = models.DateField()
    abstract = models.TextField()
    source_url = models.URLField(max_length=500)

    def __str__(self):
        return f"{self.document_number}: {self.title[:60]}"

Después, creamos y ejecutamos las migraciones.

python manage.py makemigrations documents
python manage.py migrate

Ahora pasamos a la parte de ingesta.

# documents/management/commands/ingest_federal_register.py

import re
import time

import requests
from django.core.management.base import BaseCommand

from documents.models import Document

API_URL = "https://www.federalregister.gov/api/v1/documents.json"
TAG_PATTERN = re.compile(r"<[^>]+>")


class Command(BaseCommand):
    help = "Load Federal Register documents into MongoDB."

    def add_arguments(self, parser):
        parser.add_argument("--agency", default="environmental-protection-agency")
        parser.add_argument("--limit", type=int, default=300)

    def handle(self, *args, **options):
        params = [
            ("conditions[agencies][]", options["agency"]),
            ("conditions[type][]", "RULE"),
            ("conditions[type][]", "PRORULE"),
            ("per_page", "100"),
        ]
        headers = {"User-Agent": "regulations-qa-tutorial"}
        url, processed = API_URL, 0

        while url and processed < options["limit"]:
            response = requests.get(
                url,
                params=params if url == API_URL else None,
                headers=headers,
                timeout=30,
            )
            response.raise_for_status()
            page = response.json()

            for item in page["results"]:
                abstract = TAG_PATTERN.sub("", item.get("abstract") or "").strip()
                if not abstract:
                    continue
                agencies = item.get("agencies") or [{}]
                Document.objects.update_or_create(
                    document_number=item["document_number"],
                    defaults={
                        "title": TAG_PATTERN.sub("", item["title"]),
                        "doc_type": item["type"],
                        "agency": agencies[0].get("name", ""),
                        "publication_date": item["publication_date"],
                        "abstract": abstract,
                        "source_url": item["html_url"],
                    },
                )
                processed += 1
                if processed >= options["limit"]:
                    break
            url = page.get("next_page_url")
            time.sleep(1)

        self.stdout.write(f"Documents in database: {Document.objects.count()}")

Ejecuta el comando:

python manage.py ingest_federal_register --limit 100

Puedes confirmar la importación en la interfaz de MongoDB Atlas:

Explorador de datos de MongoDB Atlas mostrando 100 documentos del Federal Register en la colección regulations_qa.documents_document

Define el índice auto-embed

El índice de vector search indica a MongoDB en qué campo generar embeddings y qué modelo usar. A partir de ahí, MongoDB genera y almacena los embeddings automáticamente.

  1. En la interfaz de Atlas, abre tu clúster, ve a Search & Vector Search y haz clic en Create Search Index.

Página de Search & Vector Search en MongoDB Atlas con el botón Create Search Index

  1. Elige Vector Search como tipo de búsqueda y Automated Embedding como método para configurar tus datos vectoriales.

Configuración de índice en Atlas con Vector Search y Automated Embedding seleccionados

  1. Elige el editor JSON, selecciona tu base de datos y la colección documents_document, y pon al índice el nombre autoembed_index (debe coincidir con VECTOR_INDEX_NAME en tu .env). Pega esta definición:
{
  "fields": [
    {
      "type": "autoEmbed",
      "modality": "text",
      "path": "abstract",
      "model": "voyage-4-lite"
    }
  ]
}

Editor JSON de Atlas con la definición del índice autoEmbed para el campo abstract usando voyage-4-lite

Revisa la definición y crea el índice.

Paso de revisión para el índice de vector search autoembed_index en regulations_qa.documents_document

  1. Espera a que el estado del índice indique que está listo para consultar; los embeddings se están generando en segundo plano.

Lista de Atlas Search & Vector Search mostrando autoembed_index con estado READY y queryable

Consulta en texto plano

Con auto-embeddings, usamos la etapa $vectorSearch con una consulta en texto plano y dejamos que MongoDB incruste la pregunta con el mismo modelo que usa el índice, así que no hay ninguna llamada de embedding en nuestro código.

Para ello, crearemos un módulo de servicio.

# documents/services/search_service.py
from functools import lru_cache

from django.conf import settings
from pymongo import MongoClient

from documents.models import Document

DEFAULT_LIMIT = 5


@lru_cache(maxsize=1)  # create the client once and reuse it
def _get_client():
    return MongoClient(settings.DATABASES["default"]["HOST"])


def _get_collection():
    db_name = settings.DATABASES["default"]["NAME"]
    return _get_client()[db_name][Document._meta.db_table]


def _get_index_name():
    index_name = settings.VECTOR_INDEX_NAME
    if not index_name:
        raise ValueError("VECTOR_INDEX_NAME is not set. Add it to your .env file.")
    return index_name


def semantic_search(question: str, limit: int = DEFAULT_LIMIT) -> list:
    """Search with a plain-text question.

    There is no query vector to pass in: MongoDB embeds the question
    with the index's model.
    """
    pipeline = [
        {
            "$vectorSearch": {
                "index": _get_index_name(),
                "path": "abstract",
                "query": question,
                "numCandidates": limit * 20,
                "limit": limit,
            }
        },
        {
            "$project": {
                "_id": 0,
                "document_number": 1,
                "title": 1,
                "abstract": 1,
                "source_url": 1,
                "score": {"$meta": "vectorSearchScore"},
            }
        },
    ]
    return list(_get_collection().aggregate(pipeline))
  • _get_client() crea la conexión a MongoDB una sola vez y la reutiliza. lru_cache recuerda el resultado de la primera llamada, así que todas las búsquedas comparten un cliente en lugar de abrir una conexión nueva cada vez.
  • _get_collection() selecciona la base de datos regulations_qa y la colección documents_document, usando la misma configuración que Django.
  • _get_index_name() lee el nombre del índice desde settings y lanza un error claro si falta.
  • semantic_search() envía la pregunta como texto en el campo query. La segunda etapa reduce la salida a los campos que necesitamos y añade la puntuación de similitud.

Luego añadimos un helper para buscar en los documentos:

# documents/management/commands/search_docs.py
from django.core.management.base import BaseCommand

from documents.services.search_service import semantic_search


class Command(BaseCommand):
    help = "Run a plain-text search."

    def add_arguments(self, parser):
        parser.add_argument("question")

    def handle(self, *args, **options):
        for hit in semantic_search(options["question"]):
            self.stdout.write(
                f"{hit['score']:.3f}  {hit['document_number']}  {hit['title'][:80]}"
            )

Para probarlo, ejecuta:

python manage.py search_docs "limits on pollution from factories"

En el ejemplo, elegimos preguntas que no comparten palabras clave con los resúmenes. Una pregunta sobre “limits on pollution from factories” debería recuperar documentos sobre estándares de emisiones.

Nota: En un clúster gratuito (M0) sin método de pago, las solicitudes de embedding de consultas pueden tener limitación de tasa.

Demostración: edita un documento y observa la resincronización

Para la demo, podemos usar el Search Tester en MongoDB Atlas, que está vinculado al autoembed_index que creamos antes en la colección regulations_qa.documents_document, o la shell de Python.

Search Tester de Atlas para autoembed_index en regulations_qa.documents_document

Paso 1: busca desde MongoDB Atlas y desde la shell

Para probarlo en la interfaz de MongoDB Atlas, introduce esta consulta:

which states need to clean up their air

Resultados de Search Tester para la consulta which states need to clean up their air, con puntuaciones de similitud

Para probarlo desde la shell:

Abre la shell con python manage.py shell y luego ejecuta:

from documents.models import Document
from documents.services.search_service import semantic_search
Q = "which states need to clean up their air"
hits = semantic_search(Q, limit=10)
print("\n".join(f"{i}  {h['score']:.3f}  {h['document_number']}  {h['title'][:70]}" for i, h in enumerate(hits, 1)))

Salida de la shell de Django listando los 10 mejores resultados de búsqueda semántica y sus puntuaciones

La salida debería coincidir con lo visto en la GUI.

Paso 2: edita el documento

target = hits[-1]
doc = Document.objects.get(document_number=target["document_number"])
original = doc.abstract
doc.abstract = original + " This action also identifies which states and areas must clean up their air to meet health-based standards."
doc.save()
print(target["document_number"], "edited")

Shell de Django añadiendo una frase al abstract del documento 2026-16515 y guardando

Paso 3: busca de nuevo

Los auto-embeddings se generan de forma asíncrona; espera 30–60 segundos y vuelve a lanzar la consulta:

hits = semantic_search(Q, limit=10)
print("\n".join(f"{i}  {h['score']:.3f}  {h['document_number']}  {h['title'][:70]}" for i, h in enumerate(hits, 1)))

Resultados de búsqueda tras la edición, con el documento 2026-16515 pasando de la 10.ª a la 5.ª posición

Ahora deberías ver el documento editado en una posición más alta que antes.

Ejecuta la misma consulta en el Search Tester para ver los resultados en la GUI.

Lo que ha pasado es que MongoDB detectó que cambió el campo indexado y regeneró el embedding de ese documento, por lo que el documento 2026-16515, que era el 10.º en la muestra, subió a la 5.ª posición tras la edición y la sincronización.

Cierre

¡Enhorabuena por llegar hasta aquí! Ya tienes un asistente de Q&A sobre documentación en el que MongoDB gestiona el flujo de trabajo de embeddings. Lo conseguimos con estos pasos:

  • Inserción: documentos cargados mediante el ORM de Django.
  • Indexación: un índice creado en la interfaz de Atlas indicando el campo y el modelo.
  • Consulta: preguntas en texto plano a través de un pequeño servicio, sin añadir una llamada de embedding aparte.
  • Edición: los cambios en el campo indexado se resincronizan sin necesidad de un script de re-embedding.

Nota: Los datos de este tutorial provienen del Federal Register, que publica documentos del gobierno de EE. UU. Este tutorial es independiente y no está afiliado ni cuenta con el respaldo del Federal Register.

Referencias

Afi Gbadago

Autor

Afi Gbadago

Afi defiende a los desarrolladores en MongoDB con foco en Django y Python, y ayuda a ingenieros a crear con tecnologías de datos modernas mediante tutoriales, charlas y trabajo con la comunidad. Reconocida como Microsoft MVP en Python y Web, forma parte del consejo de la Django Software Foundation y es Programme Chair de DjangoCon US 2025. Afi también es Regional Executor en Black Python Devs, además de colaboradora activa de código abierto y ponente internacional.

Temas

Relacionado