Ga naar hoofdinhoud

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

Verken met AI

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

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 cd ernaartoe uit.

mkdir regulations_qa
cd regulations_qa

Dit is de hoofdmap van je project. Maak en activeer hier je virtuele omgeving als je dat nog niet hebt gedaan:

python -m venv .venv

Activeer de virtuele omgeving op macOS of Linux met:

source .venv/bin/activate

Op Windows voer je uit:

.venv\Scripts\activate

Installeer dependencies

Maak een requirements.txt-bestand in de hoofdmap van het project met de volgende inhoud:

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

Installeer daarna alles:

pip install -r requirements.txt

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

Maak de documents-app

python manage.py startapp documents

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

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_index

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

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

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

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.

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

Vervolgens maken en draaien we migrations.

python manage.py makemigrations documents
python manage.py migrate

Daarna gaan we door naar het importgedeelte.

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

Voer de opdracht uit:

python manage.py ingest_federal_register --limit 100

Je kunt de import bevestigen in de MongoDB Atlas-UI:

MongoDB Atlas Data Explorer met 100 Federal Register-documenten in de regulations_qa.documents_document-collectie

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.

  1. Open in de Atlas-UI je cluster, ga naar Search & Vector Search en klik op Create Search Index.

Pagina Search & Vector Search in MongoDB Atlas met de knop Create Search Index

  1. Kies Vector Search als zoektype en Automated Embedding als manier om je vectordata in te richten.

Atlas indexconfiguratie met Vector Search en Automated Embedding geselecteerd

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

Atlas JSON-editor met de autoEmbed-indexdefinitie voor het abstract-veld met voyage-4-lite

Controleer de definitie en maak vervolgens de index aan.

Review-stap voor de autoembed_index vectorzoekindex op regulations_qa.documents_document

  1. Wacht tot de indexstatus aangeeft dat deze klaar is om te query'en, terwijl de embeddings op de achtergrond worden gegenereerd.

Atlas Search & Vector Search-lijst met autoembed_index met status READY en queryable

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

Test nu met:

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

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.

Atlas Search Tester voor autoembed_index op regulations_qa.documents_document

Stap 1: Zoeken via MongoDB Atlas en de shell

Om dit te testen in de MongoDB Atlas-UI, voer deze query in:

which states need to clean up their air

Search Tester-resultaten voor de query which states need to clean up their air, met similariteitsscores

Om via de shell te testen:

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

Django-shelluitvoer met de top 10 semantische zoekresultaten en hun scores

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

Django-shell voegt een zin toe aan de samenvatting van document 2026-16515 en slaat het op

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

Zoekresultaten na de bewerking, met document 2026-16515 verschoven van plek 10 naar plek 5

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.

Referenties

Afi Gbadago

Auteur

Afi Gbadago

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.

Onderwerpen

Gerelateerd