Accéder au contenu principal

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.
· 7 min lire

Explorez l'IA

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 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.

Deux façons de suivre ce tutoriel.

  • Option A : clonez le dépôt GitHub contenant le code final de ce tutoriel, configurez-le à l’aide du README du dépôt et explorez-le par vous-même. Lien vers le projet GitHub : https://github.com/mongodb-developer/django-mongodb-regulations-qa
  • Option B : construisez le projet from scratch en suivant les étapes ci-dessous.

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 cd pour y entrer.

mkdir regulations_qa
cd regulations_qa

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 :

python -m venv .venv

Pour activer l’environnement virtuel sur macOS ou Linux, exécutez :

source .venv/bin/activate

Sur Windows, exécutez :

.venv\Scripts\activate

Installer les dépendances

Créez un fichier requirements.txt à la racine du projet avec le contenu suivant :

# requirements.txt
django-mongodb-backend
python-dotenv
requests # pour récupérer des documents via l’API du Federal Register.

Puis installez le tout :

pip install -r requirements.txt

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 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 .

Créer l’app documents

python manage.py startapp documents

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',
]

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_index

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"),
    },
}

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__.py

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_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"

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.

# 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]}"

Créons ensuite et appliquons les migrations.

python manage.py makemigrations documents
python manage.py migrate

Passons maintenant à l’ingestion.

# 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()}")

Exécutez la commande :

python manage.py ingest_federal_register --limit 100

Vous pouvez vérifier l’import dans l’interface MongoDB Atlas :

MongoDB Atlas Data Explorer affichant 100 documents du Federal Register dans la collection regulations_qa.documents_document

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.

  1. Dans l’interface Atlas, ouvrez votre cluster, allez dans Search & Vector Search et cliquez sur Create Search Index.

Page Search & Vector Search dans MongoDB Atlas avec le bouton Create Search Index

  1. Choisissez Vector Search comme type de recherche et Automated Embedding pour configurer vos données vectorielles.

Configuration d’index Atlas avec Vector Search et Automated Embedding sélectionnés

  1. 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"
    }
  ]
}

Éditeur JSON d’Atlas avec la définition d’index autoEmbed pour le champ abstract utilisant voyage-4-lite

Vérifiez la définition, puis créez l’index.

Étape de revue pour l’index de recherche vectorielle autoembed_index sur regulations_qa.documents_document

  1. 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.

Liste Atlas Search & Vector Search montrant autoembed_index avec le statut READY et queryable

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.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() 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.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]}"
            )

Pour tester, exécutez :

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

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.

Search Tester d’Atlas pour autoembed_index sur regulations_qa.documents_document

É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 air

Résultats du Search Tester pour la requête which states need to clean up their air, avec les scores de similarité

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 in enumerate(hits, 1)))

Sortie du shell Django listant les 10 meilleurs résultats de recherche sémantique et leurs scores

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")

Shell Django ajoutant une phrase au résumé du document 2026-16515 et l’enregistrant

É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 in enumerate(hits, 1)))

Résultats de recherche après modification, avec le document 2026-16515 passé de la 10e à la 5e place

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.

Références

Afi Gbadago

Auteur

Afi Gbadago

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.

Sujets

Contenus associés

Tutoriel

Données JSON Python : Un guide illustré d'exemples