Een Q&A-assistent bouwen in Django met MongoDB Auto-Embeddings
Bouw semantisch zoeken in Django met MongoDB auto-embeddings: geen embeddingcode, automatische re-sync bij wijzigingen in documenten en zoekopdrachten in platte tekst.
In een typische retrieval-augmented generation (RAG)-opzet genereer je embeddings wanneer je een document invoegt, maak je ze opnieuw wanneer de inhoud verandert en embed je elke query zelf. Automated Embedding vereenvoudigt het bouwen van semantisch zoeken, omdat MongoDB Atlas embeddinggeneratie, updates en query's native afhandelt, en Vector Search de gegenereerde vector-embeddings op je cluster opslaat.
Hoe MongoDB automatisch embedden uitvoert
Wanneer een vectorzoekindex van het type autoEmbed wordt aangemaakt, genereert MongoDB embeddings voor het gekozen veld, gebruikt het het VoyageAI-model, houdt ze gesynchroniseerd wanneer er wijzigingen in het document zijn en embedt het de querytekst tijdens het zoeken met hetzelfde model. De gegenereerde embeddings worden asynchroon opgeslagen op het MongoDB-cluster in een aparte interne database.
In deze tutorial bouwen we een Q&A Docs-assistent met MongoDB auto-embeddings. De Django MongoDB-backend wordt gebruikt om de modellen te definiëren en documenten te importeren, en MongoDB wordt gebruikt voor lookups, het automatisch genereren en synchroniseren van embeddings, en de LLM retourneert documenten op basis van de opgehaalde resultaten.
Aan het einde van deze tutorial heb je de retrieval-fase van een RAG-pijplijn gebouwd: een semantische zoekfunctie over Federal Register-documenten waarbij auto-embeddings het embedden voor je regelen. De documenten worden ge-embed bij het invoegen, opnieuw ge-embed wanneer ze veranderen, en je query's worden tijdens het zoeken ge-embed — allemaal zonder embeddingcode te schrijven.
Voer vanuit de hoofdmap van je project de volgende opdracht uit om een nieuw Django-project en een app te maken. Voeg de afsluitende . toe aan de startproject-opdracht, wat Django vertelt het project in de huidige map te installeren in plaats van een geneste map te maken.
django-admin startproject regulations_qa --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/6.0.x.zip .Mogelijk gemaakt door
Registreer de app in regulations_qa/settings.py door deze toe te voegen aan 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',]Mogelijk gemaakt door
Stel omgevingsvariabelen in
Maak een .env-bestand in de hoofdmap van het project met je eigen waarden en zet het in .gitignore zodat het niet wordt gecommit wanneer je pusht.
# .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_indexMogelijk gemaakt door
Verwijder de oorspronkelijke hardcoded regel SECRET_KEY = '...' uit settings.py, kopieer de waarde die Django in settings.py heeft gegenereerd toen je startproject uitvoerde en vervang die in je .env-bestand. Standaard staat hij daar hardcoded, en we verplaatsen hem naar .env om hem uit versiebeheer te houden, omdat Django hem gebruikt om sessiecookies, CSRF-tokens en andere veiligheidsgevoelige data te ondertekenen.
Open regulations_qa/settings.py en zorg dat het het volgende bevat. De importregels en load_dotenv() komen bovenaan. Vervang de bestaande definities van SECRET_KEY en DATABASES, en voeg de regel VECTOR_INDEX_NAME toe:
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"),},}Mogelijk gemaakt door
Mappen voor managementcommands maken
Vervolgens maken we mappen met lege __init__.py-bestanden voor managementcommands, omdat Django alleen custom commands ontdekt in een management/commands/-package.
mkdir-p documents/management/commands documents/services &&touch documents/management/__init__.py documents/management/commands/__init__.py documents/services/__init__.pyMogelijk gemaakt door
De databron: de Federal Register-documenten
In deze tutorial indexeren we documenten uit de Federal Register; de dagelijkse publicaties van de Amerikaanse overheid met regels, voorgestelde regels en kennisgevingen. De databron is een openbare API met documenten die een titel en een korte prozaïsche samenvatting bevatten, wat goed werkt met semantisch zoeken.
De records hebben velden zoals title, type, abstract, document_number (een unieke ID), publication_date, html_url en een agencies-lijst.
Sommige documenten bevatten null-waarden, dus die slaan we over.
Samenvattingen bevatten markup zoals <INF>2.5</INF> in “PM2,5”, dus we strippen tags voordat we opslaan.
Resultaten zijn gepagineerd tot maximaal 100 per request, en elke pagina bevat een next_page_url (cursor-based) om te volgen.
Test de endpoint via de shell
curl-g"https://www.federalregister.gov/api/v1/documents.json?conditions[agencies][]=environmental-protection-agency&per_page=2"Mogelijk gemaakt door
NB: Dit is openbare data van de Amerikaanse overheid, gebruikt voor demonstratie. Het is geen juridische bron; gebruik voor juridisch onderzoek de officiële editie.
Importeer de data
We beginnen met het aanmaken van modellen in het bestand models.py.
Je kunt de import bevestigen in de MongoDB Atlas-UI:
Definieer de Auto-Embed-index
De vectorzoekindex vertelt MongoDB op welk veld embeddings moeten worden uitgevoerd en specificeert welk model gebruikt moet worden. Daarna genereert en slaat MongoDB automatisch de embeddings op.
Open in de Atlas-UI je cluster, ga naar Search & Vector Search en klik op Create Search Index.
Kies Vector Search als zoektype en Automated Embedding als manier om je vectordata in te richten.
Kies de JSON-editor, selecteer je database en de documents_document-collectie, en noem de index autoembed_index (de naam moet overeenkomen met VECTOR_INDEX_NAME in je .env). Plak deze definitie:
{"fields":[{"type":"autoEmbed","modality":"text","path":"abstract","model":"voyage-4-lite"}]}Mogelijk gemaakt door
Controleer de definitie en maak vervolgens de index aan.
Wacht tot de indexstatus aangeeft dat deze klaar is om te query'en, terwijl de embeddings op de achtergrond worden gegenereerd.
Zoeken in platte tekst
Voor auto-embeddings gebruiken we de $vectorSearch-fase met een query in platte tekst en embedden we de vraag met hetzelfde model dat de index gebruikt, zodat er geen embeddingaanroep in onze code staat.
Om dit te bereiken maken we een servicemodule.
# 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))Mogelijk gemaakt door
_get_client() maakt één keer de verbinding met MongoDB en hergebruikt die. lru_cache onthoudt het resultaat van de eerste aanroep, zodat elke zoekopdracht één client deelt in plaats van elke keer een nieuwe verbinding te openen.
_get_collection() kiest de regulations_qa-database en de documents_document-collectie, met dezelfde instellingen als Django gebruikt.
_get_index_name() leest de indexnaam uit de settings en geeft een duidelijke foutmelding als deze ontbreekt.
semantic_search() stuurt de vraag als tekst in het veld query. De tweede fase beperkt de output tot de velden die we nodig hebben en voegt de similariteitsscore toe.
Daarna voegen we een helper toe om in de docs te zoeken:
# 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]}")Mogelijk gemaakt door
Test nu met:
python manage.py search_docs "limits on pollution from factories"Mogelijk gemaakt door
In het voorbeeld kiezen we vragen die geen keywords delen met de samenvattingen. Een vraag over “limits on pollution from factories” zou documenten over emissiestandaarden moeten ophalen.
NB: Op een gratis (M0) cluster zonder betaalmethode kunnen embeddingaanvragen voor query's rate limited worden.
Demo: bewerk een document en kijk hoe het opnieuw wordt gesynchroniseerd
Voor de demo kunnen we ofwel de Search Tester in MongoDB Atlas gebruiken, die is gekoppeld aan de autoembed_index die we eerder hebben gemaakt op de regulations_qa.documents_document-collectie, of de Python-shell.
Stap 1: Zoeken via MongoDB Atlas en de shell
Om dit te testen in de MongoDB Atlas-UI, voer deze query in:
Open de shell met python manage.py shell en voer dan uit:
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)))Mogelijk gemaakt door
De output zou hetzelfde moeten zijn als wat we via de GUI zagen.
Stap 2: Bewerk het 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")Mogelijk gemaakt door
Stap 3: Zoek opnieuw
Auto-embeddings worden asynchroon gegenereerd, dus wacht 30–60 seconden en voer de query dan opnieuw uit:
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)))Mogelijk gemaakt door
Nu zouden we moeten zien dat het bewerkte document hoger scoort dan voorheen.
Voer dezelfde query uit in de Search Tester om de resultaten via de GUI te bekijken.
Wat er gebeurde, is dat MongoDB merkte dat het geïndexeerde veld was veranderd en de embedding van dat document opnieuw genereerde, waardoor document 2026-16515, dat het 10e document in de sample was, na de bewerking en sync hoger werd gerankt en op de 5e plek kwam te staan.
Afsluiting
Gefeliciteerd dat je tot hier bent gekomen! We hebben een Q&A-assistent voor documentatie met data waarbij MongoDB de embedding-workflow afhandelt. Dit hebben we bereikt in de volgende stappen:
Insert: documenten geladen via de Django ORM
Index: één indexdefinitie, aangemaakt in de Atlas-UI, met naam van het veld en het model.
Query: vragen in platte tekst via een kleine service, zonder een aparte embeddingaanroep toe te voegen.
Edit: wijzigingen in het geïndexeerde veld worden opnieuw gesynchroniseerd zonder een re-embedding-script.
NB: Data in deze tutorial komt uit de Federal Register, die documenten van de Amerikaanse overheid publiceert. Deze tutorial is onafhankelijk en niet gelieerd aan of goedgekeurd door de Federal Register.
Afi maakt zich sterk voor developers bij MongoDB, met een focus op Django en Python. Ze helpt engineers bouwen met moderne datatechnologieën via tutorials, talks en communitybetrokkenheid. Als erkende Microsoft MVP voor Python en het web zit ze in het bestuur van de Django Software Foundation en is ze Programme Chair voor DjangoCon US 2025. Afi is ook Regional Executor voor Black Python Devs en een actieve open-sourcestukschrijver en internationale spreker.
Wat Auto-Embeddings vereenvoudigen
In een typische retrieval-augmented generation (RAG)-opzet genereer je embeddings wanneer je een document invoegt, maak je ze opnieuw wanneer de inhoud verandert en embed je elke query zelf. Automated Embedding vereenvoudigt het bouwen van semantisch zoeken, omdat MongoDB Atlas embeddinggeneratie, updates en query's native afhandelt, en Vector Search de gegenereerde vector-embeddings op je cluster opslaat.
Hoe MongoDB automatisch embedden uitvoert
Wanneer een vectorzoekindex van het type
autoEmbedwordt aangemaakt, genereert MongoDB embeddings voor het gekozen veld, gebruikt het hetVoyageAI-model, houdt ze gesynchroniseerd wanneer er wijzigingen in het document zijn en embedt het de querytekst tijdens het zoeken met hetzelfde model. De gegenereerde embeddings worden asynchroon opgeslagen op het MongoDB-cluster in een aparte interne database.In deze tutorial bouwen we een Q&A Docs-assistent met MongoDB auto-embeddings. De Django MongoDB-backend wordt gebruikt om de modellen te definiëren en documenten te importeren, en MongoDB wordt gebruikt voor lookups, het automatisch genereren en synchroniseren van embeddings, en de LLM retourneert documenten op basis van de opgehaalde resultaten.
Aan het einde van deze tutorial heb je de retrieval-fase van een RAG-pijplijn gebouwd: een semantische zoekfunctie over Federal Register-documenten waarbij auto-embeddings het embedden voor je regelen. De documenten worden ge-embed bij het invoegen, opnieuw ge-embed wanneer ze veranderen, en je query's worden tijdens het zoeken ge-embed — allemaal zonder embeddingcode te schrijven.
Er zijn twee manieren om deze tutorial te volgen.
Setup
Voordat je begint, zorg dat je het volgende hebt:
Als deze vereisten rond zijn, is de volgende stap het aanmaken van je projectmap.
Maak een project en virtuele omgeving aan
Maak een lege map voor je project en voer
cdernaartoe uit.Dit is de hoofdmap van je project. Maak en activeer hier je virtuele omgeving als je dat nog niet hebt gedaan:
Activeer de virtuele omgeving op macOS of Linux met:
Op Windows voer je uit:
Installeer dependencies
Maak een
requirements.txt-bestand in de hoofdmap van het project met de volgende inhoud:Installeer daarna alles:
Maak een Django-project en -app
Voer vanuit de hoofdmap van je project de volgende opdracht uit om een nieuw Django-project en een app te maken. Voeg de afsluitende
.toe aan destartproject-opdracht, wat Django vertelt het project in de huidige map te installeren in plaats van een geneste map te maken.Maak de
documents-appRegistreer de app in
regulations_qa/settings.pydoor deze toe te voegen aanINSTALLED_APPS:Stel omgevingsvariabelen in
Maak een
.env-bestand in de hoofdmap van het project met je eigen waarden en zet het in.gitignorezodat het niet wordt gecommit wanneer je pusht.Verwijder de oorspronkelijke hardcoded regel
SECRET_KEY = '...'uitsettings.py, kopieer de waarde die Django insettings.pyheeft gegenereerd toen jestartprojectuitvoerde en vervang die in je.env-bestand. Standaard staat hij daar hardcoded, en we verplaatsen hem naar.envom hem uit versiebeheer te houden, omdat Django hem gebruikt om sessiecookies, CSRF-tokens en andere veiligheidsgevoelige data te ondertekenen.Open
regulations_qa/settings.pyen zorg dat het het volgende bevat. De importregels enload_dotenv()komen bovenaan. Vervang de bestaande definities vanSECRET_KEYenDATABASES, en voeg de regelVECTOR_INDEX_NAMEtoe:Mappen voor managementcommands maken
Vervolgens maken we mappen met lege
__init__.py-bestanden voor managementcommands, omdat Django alleen custom commands ontdekt in eenmanagement/commands/-package.De databron: de Federal Register-documenten
In deze tutorial indexeren we documenten uit de Federal Register; de dagelijkse publicaties van de Amerikaanse overheid met regels, voorgestelde regels en kennisgevingen. De databron is een openbare API met documenten die een titel en een korte prozaïsche samenvatting bevatten, wat goed werkt met semantisch zoeken.
API-documentatie: https://www.federalregister.gov/developers/documentation/api/v1
De records hebben velden zoals
title,type,abstract,document_number(een unieke ID),publication_date,html_urlen eenagencies-lijst.<INF>2.5</INF>in “PM2,5”, dus we strippen tags voordat we opslaan.next_page_url(cursor-based) om te volgen.Test de endpoint via de shell
NB: Dit is openbare data van de Amerikaanse overheid, gebruikt voor demonstratie. Het is geen juridische bron; gebruik voor juridisch onderzoek de officiële editie.
Importeer de data
We beginnen met het aanmaken van modellen in het bestand
models.py.Vervolgens maken en draaien we migrations.
Daarna gaan we door naar het importgedeelte.
Voer de opdracht uit:
Je kunt de import bevestigen in de MongoDB Atlas-UI:
Definieer de Auto-Embed-index
De vectorzoekindex vertelt MongoDB op welk veld embeddings moeten worden uitgevoerd en specificeert welk model gebruikt moet worden. Daarna genereert en slaat MongoDB automatisch de embeddings op.
documents_document-collectie, en noem de indexautoembed_index(de naam moet overeenkomen metVECTOR_INDEX_NAMEin je.env). Plak deze definitie:Controleer de definitie en maak vervolgens de index aan.
Zoeken in platte tekst
Voor auto-embeddings gebruiken we de
$vectorSearch-fase met een query in platte tekst en embedden we de vraag met hetzelfde model dat de index gebruikt, zodat er geen embeddingaanroep in onze code staat.Om dit te bereiken maken we een servicemodule.
_get_client()maakt één keer de verbinding met MongoDB en hergebruikt die.lru_cacheonthoudt het resultaat van de eerste aanroep, zodat elke zoekopdracht één client deelt in plaats van elke keer een nieuwe verbinding te openen._get_collection()kiest deregulations_qa-database en dedocuments_document-collectie, met dezelfde instellingen als Django gebruikt._get_index_name()leest de indexnaam uit de settings en geeft een duidelijke foutmelding als deze ontbreekt.semantic_search()stuurt de vraag als tekst in het veldquery. De tweede fase beperkt de output tot de velden die we nodig hebben en voegt de similariteitsscore toe.Daarna voegen we een helper toe om in de docs te zoeken:
Test nu met:
In het voorbeeld kiezen we vragen die geen keywords delen met de samenvattingen. Een vraag over “limits on pollution from factories” zou documenten over emissiestandaarden moeten ophalen.
NB: Op een gratis (M0) cluster zonder betaalmethode kunnen embeddingaanvragen voor query's rate limited worden.
Demo: bewerk een document en kijk hoe het opnieuw wordt gesynchroniseerd
Voor de demo kunnen we ofwel de
Search Testerin MongoDB Atlas gebruiken, die is gekoppeld aan deautoembed_indexdie we eerder hebben gemaakt op deregulations_qa.documents_document-collectie, of de Python-shell.Stap 1: Zoeken via MongoDB Atlas en de shell
Om dit te testen in de MongoDB Atlas-UI, voer deze query in:
Om via de shell te testen:
Open de shell met
python manage.py shellen voer dan uit:De output zou hetzelfde moeten zijn als wat we via de GUI zagen.
Stap 2: Bewerk het document
Stap 3: Zoek opnieuw
Auto-embeddings worden asynchroon gegenereerd, dus wacht 30–60 seconden en voer de query dan opnieuw uit:
Nu zouden we moeten zien dat het bewerkte document hoger scoort dan voorheen.
Voer dezelfde query uit in de Search Tester om de resultaten via de GUI te bekijken.
Wat er gebeurde, is dat MongoDB merkte dat het geïndexeerde veld was veranderd en de embedding van dat document opnieuw genereerde, waardoor document
2026-16515, dat het 10e document in de sample was, na de bewerking en sync hoger werd gerankt en op de 5e plek kwam te staan.Afsluiting
Gefeliciteerd dat je tot hier bent gekomen! We hebben een Q&A-assistent voor documentatie met data waarbij MongoDB de embedding-workflow afhandelt. Dit hebben we bereikt in de volgende stappen:
NB: Data in deze tutorial komt uit de Federal Register, die documenten van de Amerikaanse overheid publiceert. Deze tutorial is onafhankelijk en niet gelieerd aan of goedgekeurd door de Federal Register.
Referenties