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.
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.
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 .Con la tecnología de
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',]Con la tecnología de
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_indexCon la tecnología de
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"),},}Con la tecnología de
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__.pyCon la tecnología de
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.
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"Con la tecnología de
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.
Puedes confirmar la importación en la interfaz de MongoDB Atlas:
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.
En la interfaz de Atlas, abre tu clúster, ve a Search & Vector Search y haz clic en Create Search Index.
Elige Vector Search como tipo de búsqueda y Automated Embedding como método para configurar tus datos vectoriales.
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"}]}Con la tecnología de
Revisa la definición y crea el índice.
Espera a que el estado del índice indique que está listo para consultar; los embeddings se están generando en segundo plano.
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.pyfrom 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 itdef_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
ifnot index_name:raise ValueError("VECTOR_INDEX_NAME is not set. Add it to your .env file.")return index_name
defsemantic_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"},}},]returnlist(_get_collection().aggregate(pipeline))Con la tecnología de
_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.pyfrom django.core.management.base import BaseCommand
from documents.services.search_service import semantic_search
classCommand(BaseCommand):help="Run a plain-text search."defadd_arguments(self, parser):
parser.add_argument("question")defhandle(self,*args,**options):for hit in semantic_search(options["question"]):
self.stdout.write(f"{hit['score']:.3f}{hit['document_number']}{hit['title'][:80]}")Con la tecnología de
Para probarlo, ejecuta:
python manage.py search_docs "limits on pollution from factories"Con la tecnología de
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.
Paso 1: busca desde MongoDB Atlas y desde la shell
Para probarlo en la interfaz de MongoDB Atlas, introduce esta consulta:
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 inenumerate(hits,1)))Con la tecnología de
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")Con la tecnología de
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 inenumerate(hits,1)))Con la tecnología de
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.
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.
Prepárate para tu entrevista con esta guía completa sobre preguntas relacionadas con el machine learning, que abarca desde conceptos básicos y algoritmos hasta temas avanzados y específicos de cada puesto.
Preguntas esenciales sobre Python para entrevistas de trabajo con ejemplos para personas en busca de empleo, estudiantes de último año y profesionales de datos.
Aprende algunas posibilidades de modelado de datos que incluyen documentos anidados al diseñar un sistema de gestión de contenidos (CMS) o una aplicación de blog.
Obtenga información a partir de datos no estructurados con el modelado de temas. Explore conceptos básicos, técnicas como LSA y LDA, ejemplos prácticos y mucho más.
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 modeloVoyageAI, 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.Este será el directorio raíz del proyecto. Crea y activa aquí tu entorno virtual si aún no lo has hecho:
Para activar el entorno virtual en macOS o Linux, ejecuta:
En Windows, ejecuta:
Instala las dependencias
Crea un archivo
requirements.txten la raíz del proyecto con este contenido:Después, instala todo:
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 comandostartprojectpara decirle a Django que instale el proyecto en el directorio actual en lugar de crear una carpeta anidada.Crea la app
documentsRegistra la app en
regulations_qa/settings.pyañadiéndola aINSTALLED_APPS:Configura las variables de entorno
Crea un archivo
.enven la raíz del proyecto con tus propios valores, y añádelo a.gitignorepara que no se suba al repositorio.Elimina la línea original con
SECRET_KEY = '...'desettings.py, copia el valor que generó Django ensettings.pycuando ejecutastestartprojecty sustitúyelo en tu.env. Por defecto viene codificado en el archivo, y lo movemos a.envpara 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.pyy asegúrate de que contiene todo lo siguiente. Las líneas de importación yload_dotenv()van arriba. Sustituye las definiciones existentes deSECRET_KEYyDATABASESy añade la líneaVECTOR_INDEX_NAME:Crea las carpetas para los comandos de gestión
A continuación creamos carpetas con archivos
__init__.pyvacíos para los management commands, porque Django solo detecta comandos personalizados en un paquetemanagement/commands/.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_urly una lista deagencies.<INF>2.5</INF>en “PM2.5”, por lo que eliminamos etiquetas antes de guardar.next_page_url(basado en cursor) para seguir.Prueba del endpoint por shell
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.Después, creamos y ejecutamos las migraciones.
Ahora pasamos a la parte de ingesta.
Ejecuta el comando:
Puedes confirmar la importación en la interfaz de MongoDB Atlas:
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.
documents_document, y pon al índice el nombreautoembed_index(debe coincidir conVECTOR_INDEX_NAMEen tu.env). Pega esta definición:Revisa la definición y crea el índice.
Consulta en texto plano
Con auto-embeddings, usamos la etapa
$vectorSearchcon 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.
_get_client()crea la conexión a MongoDB una sola vez y la reutiliza.lru_cacherecuerda 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 datosregulations_qay la coleccióndocuments_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 campoquery. 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:
Para probarlo, ejecuta:
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 Testeren MongoDB Atlas, que está vinculado alautoembed_indexque creamos antes en la colecciónregulations_qa.documents_document, o la shell de Python.Paso 1: busca desde MongoDB Atlas y desde la shell
Para probarlo en la interfaz de MongoDB Atlas, introduce esta consulta:
Para probarlo desde la shell:
Abre la shell con
python manage.py shelly luego ejecuta:La salida debería coincidir con lo visto en la GUI.
Paso 2: edita el documento
Paso 3: busca de nuevo
Los auto-embeddings se generan de forma asíncrona; espera 30–60 segundos y vuelve a lanzar la consulta:
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:
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