Créer un assistant Q&R dans Django avec les auto-embeddings MongoDB
Mettez en place une recherche sémantique dans Django avec les auto-embeddings MongoDB : pas de code d’embedding, re-synchronisation automatique lors des modifications, et requêtes en texte libre.
Dans une configuration RAG (retrieval-augmented generation) classique, vous générez des embeddings à l’insertion d’un document, vous les régénérez quand le contenu change, et vous vectorisez chaque requête vous-même. L’Automated Embedding simplifie la mise en place d’une recherche sémantique : MongoDB Atlas gère nativement la génération, la mise à jour et l’interrogation des embeddings, et Vector Search stocke les vecteurs générés sur votre cluster.
Comment MongoDB effectue l’embedding automatique
Lorsqu’un index de recherche vectorielle de type autoEmbed est créé, MongoDB génère des embeddings pour le champ choisi à l’aide du modèle VoyageAI, les maintient synchronisés lorsqu’un document change et vectorise le texte de la requête au moment de la recherche avec le même modèle. Les embeddings générés sont stockés de manière asynchrone sur le cluster MongoDB dans une base interne distincte.
Dans ce tutoriel, nous allons créer un assistant de questions-réponses sur des documents avec les auto-embeddings MongoDB. Le backend Django MongoDB servira à définir les modèles et à ingérer les documents, MongoDB assurera les recherches, la génération et la synchronisation automatique des embeddings, et le LLM renverra des documents en fonction des résultats récupérés.
À la fin de ce tutoriel, vous aurez construit l’étape de récupération d’un pipeline RAG : une recherche sémantique sur des documents du Federal Register, où les auto-embeddings se chargent du travail d’embedding pour vous. Les documents sont vectorisés à l’insertion, re-vectorisés lorsqu’ils changent, et vos requêtes sont vectorisées au moment de la recherche, le tout sans écrire de code d’embedding.
Depuis la racine du projet, exécutez la commande suivante pour créer un nouveau projet et une app Django. Ajoutez le . final à la commande startproject pour installer le projet dans le répertoire courant plutôt que de créer un sous-dossier.
django-admin startproject regulations_qa --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/6.0.x.zip .Propulsé par
Enregistrez l’app dans regulations_qa/settings.py en l’ajoutant à 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',]Propulsé par
Configurer les variables d’environnement
Créez un fichier .env à la racine du projet avec vos propres valeurs, et ajoutez-le à .gitignore afin de ne pas le valider lors de vos commits.
# .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_indexPropulsé par
Supprimez la ligne d’origine SECRET_KEY = '...' de settings.py, copiez la valeur générée par Django dans settings.py lors de startproject et remplacez-la dans votre fichier .env. Elle est en dur par défaut ; nous la déplaçons dans .env pour l’exclure du contrôle de version, car Django s’en sert pour signer les cookies de session, les jetons CSRF et d’autres données sensibles.
Ouvrez regulations_qa/settings.py et assurez-vous qu’il contient tout ce qui suit. Les lignes d’import et load_dotenv() vont en haut. Remplacez les définitions existantes de SECRET_KEY et DATABASES, et ajoutez la ligne 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"),},}Propulsé par
Créer les dossiers pour les commandes de gestion
Créons ensuite les dossiers avec des fichiers __init__.py vides pour les commandes de gestion, car Django ne détecte les commandes personnalisées que dans un package management/commands/.
mkdir-p documents/management/commands documents/services &&touch documents/management/__init__.py documents/management/commands/__init__.py documents/services/__init__.pyPropulsé par
Source des données : les documents du Federal Register
Dans ce tutoriel, nous allons indexer des documents issus du Federal Register, la publication quotidienne du gouvernement américain référençant règles, projets de règles et avis. La source est une API publique composée de documents avec un titre et un résumé court en prose, particulièrement adaptés à la recherche sémantique.
Les enregistrements comportent des champs tels que title, type, abstract, document_number (un identifiant unique), publication_date, html_url et une liste agencies.
Certains documents contiennent des valeurs nulles, que nous omettrons.
Les résumés contiennent parfois des balises comme <INF>2.5</INF> dans « PM2.5 », nous supprimons donc le balisage avant la sauvegarde.
Les résultats sont paginés jusqu’à 100 par requête, et chaque page inclut une next_page_url (basée sur un curseur) à suivre.
Tester l’endpoint via le shell
curl-g"https://www.federalregister.gov/api/v1/documents.json?conditions[agencies][]=environmental-protection-agency&per_page=2"Propulsé par
NB : il s’agit de données publiques du gouvernement américain utilisées à des fins de démonstration. Ce n’est pas une source juridique ; pour la recherche juridique, utilisez l’édition officielle.
Ingestion des données
Nous allons commencer par créer les modèles dans le fichier models.py.
python manage.py makemigrations documents
python manage.py migratePropulsé par
Passons maintenant à l’ingestion.
# documents/management/commands/ingest_federal_register.pyimport 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"<[^>]+>")classCommand(BaseCommand):help="Load Federal Register documents into MongoDB."defadd_arguments(self, parser):
parser.add_argument("--agency", default="environmental-protection-agency")
parser.add_argument("--limit",type=int, default=300)defhandle(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,0while url and processed < options["limit"]:
response = requests.get(
url,
params=params if url == API_URL elseNone,
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()ifnot 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 +=1if processed >= options["limit"]:break
url = page.get("next_page_url")
time.sleep(1)
self.stdout.write(f"Documents in database: {Document.objects.count()}")Propulsé par
Exécutez la commande :
python manage.py ingest_federal_register --limit100Propulsé par
Vous pouvez vérifier l’import dans l’interface MongoDB Atlas :
Définir l’index auto-embed
L’index de recherche vectorielle indique à MongoDB sur quel champ générer des embeddings et précise le modèle à utiliser. Ensuite, MongoDB génère et stocke automatiquement les embeddings.
Dans l’interface Atlas, ouvrez votre cluster, allez dans Search & Vector Search et cliquez sur Create Search Index.
Choisissez Vector Search comme type de recherche et Automated Embedding pour configurer vos données vectorielles.
Choisissez l’éditeur JSON, sélectionnez votre base de données et la collection documents_document, et nommez l’index autoembed_index (le nom doit correspondre à VECTOR_INDEX_NAME dans votre .env). Collez cette définition :
{"fields":[{"type":"autoEmbed","modality":"text","path":"abstract","model":"voyage-4-lite"}]}Propulsé par
Vérifiez la définition, puis créez l’index.
Attendez que le statut de l’index indique qu’il est prêt à être interrogé, le temps que les embeddings soient générés en arrière-plan.
Interroger en texte libre
Avec les auto-embeddings, nous utilisons l’étape $vectorSearch avec une requête en texte libre et la question est vectorisée avec le même modèle que l’index : aucun appel d’embedding n’est nécessaire dans notre code.
Pour cela, nous allons créer un module de service.
# 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))Propulsé par
_get_client() crée une connexion à MongoDB une seule fois et la réutilise. lru_cache mémorise le résultat du premier appel, ainsi chaque recherche partage un client unique au lieu d’ouvrir une nouvelle connexion à chaque fois.
_get_collection() sélectionne la base regulations_qa et la collection documents_document, en s’appuyant sur la même configuration que Django.
_get_index_name() lit le nom de l’index depuis les paramètres et lève une erreur explicite s’il manque.
semantic_search() envoie la question en texte dans le champ query. La deuxième étape limite la sortie aux champs nécessaires et ajoute le score de similarité.
Ajoutons ensuite un helper pour interroger les documents :
# 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]}")Propulsé par
Pour tester, exécutez :
python manage.py search_docs "limits on pollution from factories"Propulsé par
Dans notre exemple, nous choisissons des questions qui ne partagent pas de mots-clés avec les résumés. Une question sur les « limites de pollution des usines » devrait remonter des documents sur les normes d’émission.
NB : sur un cluster gratuit (M0) sans moyen de paiement, les requêtes d’embedding de la recherche peuvent être soumises à un rate limiting.
Démo : modifier un document et observer la re-synchronisation
Pour la démo, nous pouvons utiliser soit le Search Tester dans MongoDB Atlas, lié à l’autoembed_index créé précédemment sur la collection regulations_qa.documents_document, soit le shell Python.
Étape 1 : recherche via MongoDB Atlas et le shell
Pour tester dans l’interface MongoDB Atlas, saisissez cette requête :
which states need to clean up their airPropulsé par
Pour tester via le shell :
Ouvrez le shell avec python manage.py shell, puis exécutez :
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)))Propulsé par
La sortie devrait correspondre à celle observée via l’interface.
Étape 2 : modifier le document
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")Propulsé par
Étape 3 : relancer la recherche
Les auto-embeddings sont générés de façon asynchrone : attendez 30–60 secondes, puis relancez la requête :
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)))Propulsé par
Nous devrions maintenant voir le document modifié mieux classé qu’auparavant.
Lancez la même requête dans le Search Tester pour comparer via l’interface.
Concrètement, MongoDB a détecté la modification du champ indexé et a régénéré l’embedding de ce document. Ainsi, le document 2026-16515, auparavant 10e dans l’échantillon, est remonté à la 5e position après l’édition et la synchronisation.
Conclusion
Bravo pour être arrivé jusqu’ici ! Nous avons mis en place un assistant Q&A sur des documents, avec un workflow d’embedding entièrement géré par MongoDB. Les étapes clés :
Insertion : documents chargés via l’ORM Django
Indexation : une définition d’index créée dans l’interface Atlas, indiquant le champ et le modèle
Requête : questions en texte libre via un petit service, sans appel d’embedding séparé
Édition : les changements sur le champ indexé sont re-synchronisés sans script de re-vectorisation
NB : les données de ce tutoriel proviennent du Federal Register, qui publie des documents du gouvernement américain. Ce tutoriel est indépendant, non affilié ni approuvé par le Federal Register.
Afi s’engage aux côtés des développeurs chez MongoDB, avec un accent sur Django et Python, pour aider les ingénieurs à créer avec des technologies de données modernes via des tutoriels, des conférences et l’animation de communauté. Reconnue Microsoft MVP pour Python et le Web, elle siège au conseil d’administration de la Django Software Foundation et est Programme Chair pour DjangoCon US 2025. Afi est également Regional Executor pour Black Python Devs, ainsi que contributrice active open source et conférencière internationale.
Apprenez à utiliser l'API DeepSeek : choix des modèles, gestion des paramètres, optimisation des coûts, mise en cache du contexte et optimisation du chain-of-thought.
Apprenez à utiliser JSON en Python, notamment la sérialisation, la désérialisation, le formatage, l'optimisation des performances, la gestion des API, ainsi que les limites et les alternatives de JSON.
Initiez-vous aux structures de données de Python : apprenez-en plus sur les types de données et les structures de données primitives et non primitives, telles que les chaînes de caractères, les listes, les piles, etc.
Ce que les auto-embeddings simplifient
Dans une configuration RAG (retrieval-augmented generation) classique, vous générez des embeddings à l’insertion d’un document, vous les régénérez quand le contenu change, et vous vectorisez chaque requête vous-même. L’Automated Embedding simplifie la mise en place d’une recherche sémantique : MongoDB Atlas gère nativement la génération, la mise à jour et l’interrogation des embeddings, et Vector Search stocke les vecteurs générés sur votre cluster.
Comment MongoDB effectue l’embedding automatique
Lorsqu’un index de recherche vectorielle de type
autoEmbedest créé, MongoDB génère des embeddings pour le champ choisi à l’aide du modèleVoyageAI, les maintient synchronisés lorsqu’un document change et vectorise le texte de la requête au moment de la recherche avec le même modèle. Les embeddings générés sont stockés de manière asynchrone sur le cluster MongoDB dans une base interne distincte.Dans ce tutoriel, nous allons créer un assistant de questions-réponses sur des documents avec les auto-embeddings MongoDB. Le backend Django MongoDB servira à définir les modèles et à ingérer les documents, MongoDB assurera les recherches, la génération et la synchronisation automatique des embeddings, et le LLM renverra des documents en fonction des résultats récupérés.
À la fin de ce tutoriel, vous aurez construit l’étape de récupération d’un pipeline RAG : une recherche sémantique sur des documents du Federal Register, où les auto-embeddings se chargent du travail d’embedding pour vous. Les documents sont vectorisés à l’insertion, re-vectorisés lorsqu’ils changent, et vos requêtes sont vectorisées au moment de la recherche, le tout sans écrire de code d’embedding.
Deux façons de suivre ce tutoriel.
Configuration
Avant de commencer, assurez-vous d’avoir :
Une fois ces prérequis réunis, créez votre dossier de projet.
Créer un projet et un environnement virtuel
Créez un dossier vide pour votre projet et exécutez
cdpour y entrer.C’est le répertoire racine de votre projet. Créez et activez votre environnement virtuel ici si ce n’est pas déjà fait :
Pour activer l’environnement virtuel sur macOS ou Linux, exécutez :
Sur Windows, exécutez :
Installer les dépendances
Créez un fichier
requirements.txtà la racine du projet avec le contenu suivant :Puis installez le tout :
Créer le projet et l’app Django
Depuis la racine du projet, exécutez la commande suivante pour créer un nouveau projet et une app Django. Ajoutez le
.final à la commandestartprojectpour installer le projet dans le répertoire courant plutôt que de créer un sous-dossier.Créer l’app
documentsEnregistrez l’app dans
regulations_qa/settings.pyen l’ajoutant àINSTALLED_APPS:Configurer les variables d’environnement
Créez un fichier
.envà la racine du projet avec vos propres valeurs, et ajoutez-le à.gitignoreafin de ne pas le valider lors de vos commits.Supprimez la ligne d’origine
SECRET_KEY = '...'desettings.py, copiez la valeur générée par Django danssettings.pylors destartprojectet remplacez-la dans votre fichier.env. Elle est en dur par défaut ; nous la déplaçons dans.envpour l’exclure du contrôle de version, car Django s’en sert pour signer les cookies de session, les jetons CSRF et d’autres données sensibles.Ouvrez
regulations_qa/settings.pyet assurez-vous qu’il contient tout ce qui suit. Les lignes d’import etload_dotenv()vont en haut. Remplacez les définitions existantes deSECRET_KEYetDATABASES, et ajoutez la ligneVECTOR_INDEX_NAME:Créer les dossiers pour les commandes de gestion
Créons ensuite les dossiers avec des fichiers
__init__.pyvides pour les commandes de gestion, car Django ne détecte les commandes personnalisées que dans un packagemanagement/commands/.Source des données : les documents du Federal Register
Dans ce tutoriel, nous allons indexer des documents issus du Federal Register, la publication quotidienne du gouvernement américain référençant règles, projets de règles et avis. La source est une API publique composée de documents avec un titre et un résumé court en prose, particulièrement adaptés à la recherche sémantique.
Documentation de l’API : https://www.federalregister.gov/developers/documentation/api/v1
Les enregistrements comportent des champs tels que
title,type,abstract,document_number(un identifiant unique),publication_date,html_urlet une listeagencies.<INF>2.5</INF>dans « PM2.5 », nous supprimons donc le balisage avant la sauvegarde.next_page_url(basée sur un curseur) à suivre.Tester l’endpoint via le shell
NB : il s’agit de données publiques du gouvernement américain utilisées à des fins de démonstration. Ce n’est pas une source juridique ; pour la recherche juridique, utilisez l’édition officielle.
Ingestion des données
Nous allons commencer par créer les modèles dans le fichier
models.py.Créons ensuite et appliquons les migrations.
Passons maintenant à l’ingestion.
Exécutez la commande :
Vous pouvez vérifier l’import dans l’interface MongoDB Atlas :
Définir l’index auto-embed
L’index de recherche vectorielle indique à MongoDB sur quel champ générer des embeddings et précise le modèle à utiliser. Ensuite, MongoDB génère et stocke automatiquement les embeddings.
documents_document, et nommez l’indexautoembed_index(le nom doit correspondre àVECTOR_INDEX_NAMEdans votre.env). Collez cette définition :Vérifiez la définition, puis créez l’index.
Interroger en texte libre
Avec les auto-embeddings, nous utilisons l’étape
$vectorSearchavec une requête en texte libre et la question est vectorisée avec le même modèle que l’index : aucun appel d’embedding n’est nécessaire dans notre code.Pour cela, nous allons créer un module de service.
_get_client()crée une connexion à MongoDB une seule fois et la réutilise.lru_cachemémorise le résultat du premier appel, ainsi chaque recherche partage un client unique au lieu d’ouvrir une nouvelle connexion à chaque fois._get_collection()sélectionne la baseregulations_qaet la collectiondocuments_document, en s’appuyant sur la même configuration que Django._get_index_name()lit le nom de l’index depuis les paramètres et lève une erreur explicite s’il manque.semantic_search()envoie la question en texte dans le champquery. La deuxième étape limite la sortie aux champs nécessaires et ajoute le score de similarité.Ajoutons ensuite un helper pour interroger les documents :
Pour tester, exécutez :
Dans notre exemple, nous choisissons des questions qui ne partagent pas de mots-clés avec les résumés. Une question sur les « limites de pollution des usines » devrait remonter des documents sur les normes d’émission.
NB : sur un cluster gratuit (M0) sans moyen de paiement, les requêtes d’embedding de la recherche peuvent être soumises à un rate limiting.
Démo : modifier un document et observer la re-synchronisation
Pour la démo, nous pouvons utiliser soit le
Search Testerdans MongoDB Atlas, lié à l’autoembed_indexcréé précédemment sur la collectionregulations_qa.documents_document, soit le shell Python.Étape 1 : recherche via MongoDB Atlas et le shell
Pour tester dans l’interface MongoDB Atlas, saisissez cette requête :
Pour tester via le shell :
Ouvrez le shell avec
python manage.py shell, puis exécutez :La sortie devrait correspondre à celle observée via l’interface.
Étape 2 : modifier le document
Étape 3 : relancer la recherche
Les auto-embeddings sont générés de façon asynchrone : attendez 30–60 secondes, puis relancez la requête :
Nous devrions maintenant voir le document modifié mieux classé qu’auparavant.
Lancez la même requête dans le Search Tester pour comparer via l’interface.
Concrètement, MongoDB a détecté la modification du champ indexé et a régénéré l’embedding de ce document. Ainsi, le document
2026-16515, auparavant 10e dans l’échantillon, est remonté à la 5e position après l’édition et la synchronisation.Conclusion
Bravo pour être arrivé jusqu’ici ! Nous avons mis en place un assistant Q&A sur des documents, avec un workflow d’embedding entièrement géré par MongoDB. Les étapes clés :
NB : les données de ce tutoriel proviennent du Federal Register, qui publie des documents du gouvernement américain. Ce tutoriel est indépendant, non affilié ni approuvé par le Federal Register.
Références