Zum Hauptinhalt springen

Einen Q&A‑Assistenten in Django mit MongoDB Auto‑Embeddings bauen

Baue semantische Suche in Django mit MongoDB Auto‑Embeddings: kein Embedding‑Code, automatisches Re‑Sync bei Dokumentänderungen und Klartext‑Queries.
· 7 Min. lesen

Entdecke KI

Was Auto‑Embeddings vereinfachen

In einem typischen Retrieval-Augmented-Generation-(RAG)-Setup erzeugst du Embeddings beim Einfügen eines Dokuments, regenerierst sie bei Inhaltsänderungen und bettest jede Query selbst ein. Automated Embedding vereinfacht den Aufbau semantischer Suche: MongoDB Atlas übernimmt die Embedding-Erzeugung, -Aktualisierung und -Abfrage nativ, und Vector Search speichert die erzeugten Vektorembeddings in deinem Cluster.

So erstellt MongoDB automatische Embeddings

Wenn ein Vector-Search-Index vom Typ autoEmbed erstellt wird, generiert MongoDB Embeddings für das gewählte Feld mit dem VoyageAI-Modell, hält sie bei Dokumentänderungen synchron und bettet den Query-Text zur Suchzeit mit demselben Modell ein. Die erzeugten Embeddings werden asynchron auf dem MongoDB‑Cluster in einer separaten internen Datenbank gespeichert.

In diesem Tutorial bauen wir einen Q&A‑Docs‑Assistenten mit MongoDB Auto‑Embeddings. Das Django‑MongoDB‑Backend dient zum Definieren der Models und zum Ingest der Dokumente, MongoDB übernimmt Lookups sowie das automatische Erzeugen und Synchronisieren der Embeddings, und das LLM liefert auf Basis der Treffer passende Dokumente zurück.

Am Ende dieses Tutorials hast du die Retrieval‑Phase einer RAG‑Pipeline gebaut: eine semantische Suche über Federal‑Register‑Dokumente, bei der Auto‑Embeddings die Arbeit für dich übernehmen. Die Dokumente werden beim Einfügen eingebettet, bei Änderungen erneut eingebettet, und deine Queries werden zur Laufzeit eingebettet – alles ohne eigenen Embedding‑Code.

Es gibt zwei Wege, diesem Tutorial zu folgen.

Setup

Bevor du startest, stelle sicher, dass du Folgendes hast:

Sind die Voraussetzungen erfüllt, erstellst du als Nächstes deinen Projektordner.

Projekt und virtuelle Umgebung anlegen

Erstelle einen leeren Ordner für dein Projekt und wechsle per cd hinein.

mkdir regulations_qa
cd regulations_qa

Dies ist das Root‑Verzeichnis deines Projekts. Lege hier deine virtuelle Umgebung an und aktiviere sie, falls noch nicht geschehen:

python -m venv .venv

Zum Aktivieren der virtuellen Umgebung unter macOS oder Linux:

source .venv/bin/activate

Unter Windows:

.venv\Scripts\activate

Abhängigkeiten installieren

Erstelle im Projektroot eine Datei requirements.txt mit folgendem Inhalt:

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

Dann alles installieren:

pip install -r requirements.txt

Django‑Projekt und Django‑App erstellen

Führe im Root‑Verzeichnis deines Projekts den folgenden Befehl aus, um ein neues Django‑Projekt und eine App anzulegen. Füge im startproject-Befehl den abschließenden Punkt . hinzu, damit Django das Projekt im aktuellen Verzeichnis installiert statt einen verschachtelten Ordner zu erzeugen.

django-admin startproject regulations_qa --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/6.0.x.zip .

Die App documents erstellen

python manage.py startapp documents

Registriere die App in regulations_qa/settings.py, indem du sie zu INSTALLED_APPS hinzufügst:

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

Umgebungsvariablen konfigurieren

Lege im Projektroot eine .env-Datei mit deinen Werten an und trage sie in .gitignore ein, damit sie beim Pushen nicht mit eingecheckt wird.

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

Lösche die ursprüngliche hartkodierte Zeile SECRET_KEY = '...' aus settings.py, kopiere den von Django beim startproject generierten Wert aus settings.py und trage ihn in deiner .env ein. Standardmäßig ist er dort hartkodiert; wir verschieben ihn in die .env, um ihn aus der Versionsverwaltung herauszuhalten, da Django ihn zum Signieren von Session‑Cookies, CSRF‑Tokens und weiteren sicherheitsrelevanten Daten nutzt.

Öffne regulations_qa/settings.py und stelle sicher, dass alles Folgende enthalten ist. Die Importzeilen und load_dotenv() kommen nach oben. Ersetze die bestehenden Definitionen von SECRET_KEY und DATABASES und füge die Zeile VECTOR_INDEX_NAME hinzu:

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

Ordner für Management‑Commands anlegen

Als Nächstes legen wir Ordner mit leeren __init__.py-Dateien für Management‑Commands an, da Django benutzerdefinierte Commands nur in einem Paket management/commands/ erkennt.

mkdir -p documents/management/commands documents/services && touch documents/management/__init__.py documents/management/commands/__init__.py documents/services/__init__.py

Die Datenquelle: Federal‑Register‑Dokumente

In diesem Tutorial indexieren wir Dokumente aus dem Federal Register, den täglichen Veröffentlichungen der US‑Regierung zu Regeln, Regelentwürfen und Bekanntmachungen. Die Datenquelle ist eine öffentliche API mit Dokumenten, die einen Titel und eine kurze Fließtext‑Zusammenfassung enthalten – ideal für semantische Suche.

API‑Dokumentation: https://www.federalregister.gov/developers/documentation/api/v1

Die Datensätze haben Felder wie title, type, abstract, document_number (eine eindeutige ID), publication_date, html_url und eine agencies-Liste.

  • Einige Dokumente enthalten Nullwerte – diese lassen wir weg.
  • Abstracts enthalten Markup wie <INF>2.5</INF> in „PM2.5“ – wir entfernen die Tags vor dem Speichern.
  • Ergebnisse sind paginiert mit bis zu 100 pro Request; jede Seite enthält eine zu verfolgende next_page_url (cursorbasiert).

Endpoint per Shell testen

curl -g "https://www.federalregister.gov/api/v1/documents.json?conditions[agencies][]=environmental-protection-agency&per_page=2"

Hinweis: Dies sind öffentliche Daten der US‑Regierung zu Demonstrationszwecken. Sie sind keine Rechtsquelle; für juristische Recherchen nutze die amtliche Ausgabe.

Daten ingestieren

Wir starten mit den Models in der Datei 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]}"

Als Nächstes erstellen und führen wir Migrationen aus.

python manage.py makemigrations documents
python manage.py migrate

Weiter geht es mit dem Ingest‑Teil.

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

Führe den Befehl aus:

python manage.py ingest_federal_register --limit 100

Du kannst den Import in der MongoDB‑Atlas‑UI bestätigen:

MongoDB Atlas Data Explorer zeigt 100 Federal‑Register‑Dokumente in der Collection regulations_qa.documents_document

Den Auto‑Embed‑Index definieren

Der Vector‑Search‑Index sagt MongoDB, auf welchem Feld Embeddings erzeugt werden sollen, und welches Modell verwendet wird. Danach generiert MongoDB die Embeddings automatisch und speichert sie.

  1. Öffne in der Atlas‑UI deinen Cluster, gehe zu Search & Vector Search und klicke auf Create Search Index.

Search & Vector Search Seite in MongoDB Atlas mit dem Button Create Search Index

  1. Wähle als Suchtyp Vector Search und als Methode für deine Vektordaten Automated Embedding.

Atlas Index‑Konfiguration mit Vector Search und Automated Embedding ausgewählt

  1. Wähle den JSON‑Editor, wähle deine Datenbank und die Collection documents_document und benenne den Index autoembed_index (der Name muss zu VECTOR_INDEX_NAME in deiner .env passen). Füge diese Definition ein:
{
  "fields": [
    {
      "type": "autoEmbed",
      "modality": "text",
      "path": "abstract",
      "model": "voyage-4-lite"
    }
  ]
}

Atlas JSON‑Editor mit der autoEmbed‑Indexdefinition für das Feld abstract mit voyage-4-lite

Prüfe die Definition und erstelle dann den Index.

Review‑Schritt für den Vector‑Search‑Index autoembed_index auf regulations_qa.documents_document

  1. Warte, bis der Index‑Status zeigt, dass er abfragbar ist. Die Embeddings werden im Hintergrund generiert.

Atlas Search & Vector Search Liste mit autoembed_index im Status READY und queryable

Mit Klartext abfragen

Für Auto‑Embeddings verwenden wir die $vectorSearch-Stage mit einer Klartext‑Query und lassen die Frage mit demselben Modell einbetten, das der Index nutzt – es gibt also keinen Embedding‑Aufruf in unserem Code.

Dafür erstellen wir ein Service‑Modul.

# 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() stellt einmal die Verbindung zu MongoDB her und verwendet sie wieder. lru_cache merkt sich das Ergebnis des ersten Aufrufs, sodass alle Suchen einen Client teilen statt jedes Mal eine neue Verbindung zu öffnen.
  • _get_collection() wählt die Datenbank regulations_qa und die Collection documents_document gemäß den Django‑Settings.
  • _get_index_name() liest den Indexnamen aus den Settings und wirft eine klare Fehlermeldung, wenn er fehlt.
  • semantic_search() sendet die Frage als Text im Feld query. Die zweite Stage reduziert die Ausgabe auf die benötigten Felder und ergänzt den Similarity‑Score.

Dann fügen wir einen Helper hinzu, um in den Docs zu suchen:

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

Zum Testen führe aus:

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

In unserem Beispiel wählen wir Fragen, die keine Keywords mit den Abstracts teilen. Eine Frage zu „limits on pollution from factories“ sollte Dokumente zu Emissionsstandards zurückliefern.

Hinweis: Auf einem kostenlosen (M0) Cluster ohne Zahlungsmethode können Query‑Embedding‑Anfragen rate‑limitiert werden.

Demo: Ein Dokument bearbeiten und das Re‑Sync beobachten

Für die Demo können wir entweder den Search Tester in MongoDB Atlas nutzen, der an den zuvor erstellten autoembed_index auf der Collection regulations_qa.documents_document gebunden ist, oder die Python‑Shell.

Atlas Search Tester für autoembed_index auf regulations_qa.documents_document

Schritt 1: Suche über MongoDB Atlas und die Shell

Zum Testen in der MongoDB‑Atlas‑UI gib diese Query ein:

which states need to clean up their air

Search‑Tester‑Ergebnisse für die Query which states need to clean up their air mit Similarity‑Scores

Zum Testen über die Shell:

Öffne die Shell mit python manage.py shell und führe dann aus:

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‑Shell‑Ausgabe mit den Top‑10‑Ergebnissen der semantischen Suche und ihren Scores

Die Ausgabe sollte mit dem Ergebnis aus der GUI übereinstimmen.

Schritt 2: Das Dokument bearbeiten

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 hängt einen Satz an das Abstract des Dokuments 2026-16515 an und speichert es

Schritt 3: Erneut suchen

Auto‑Embeddings werden asynchron erzeugt. Warte daher 30–60 Sekunden und führe die Query erneut aus:

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

Suchergebnisse nach dem Edit: Dokument 2026-16515 steigt von Platz 10 auf Platz 5

Jetzt solltest du sehen, dass das bearbeitete Dokument höher rankt als zuvor.

Führe dieselbe Query im Search Tester aus, um die Ergebnisse in der GUI zu sehen.

Was passiert ist: MongoDB hat erkannt, dass sich das indexierte Feld geändert hat, und das Embedding für dieses Dokument neu generiert. Dadurch wurde das Dokument 2026-16515, das zuvor auf Platz 10 lag, nach dem Edit und Sync höher eingestuft und auf Platz 5 gesetzt.

Fazit

Glückwunsch, bis hierher geschafft! Wir haben einen Q&A‑Assistenten für Dokumente aufgebaut, bei dem MongoDB den Embedding‑Workflow übernimmt. Das gelang in folgenden Schritten:

  • Insert: Dokumente über das Django‑ORM geladen
  • Index: Eine Indexdefinition in der Atlas‑UI, die Feld und Modell festlegt.
  • Query: Klartext‑Fragen über einen kleinen Service, ohne separaten Embedding‑Aufruf.
  • Edit: Änderungen am indexierten Feld werden ohne Re‑Embedding‑Skript automatisch synchronisiert.

Hinweis: Die Daten in diesem Tutorial stammen aus dem Federal Register, das Dokumente der US‑Regierung veröffentlicht. Dieses Tutorial ist unabhängig und weder mit dem Federal Register verbunden noch von diesem genehmigt.

Referenzen

Afi Gbadago

Autor

Afi Gbadago

Afi setzt sich bei MongoDB für Entwicklerinnen und Entwickler ein – mit Schwerpunkt auf Django und Python – und unterstützt Engineering-Teams dabei, mit modernen Datentechnologien zu bauen, etwa durch Tutorials, Vorträge und Community-Engagement. Als anerkannte Microsoft MVP für Python und Web ist sie Mitglied im Vorstand der Django Software Foundation und Programme Chair für die DjangoCon US 2025. Afi ist zudem Regional Executor bei Black Python Devs sowie aktive Open-Source-Mitwirkende und internationale Sprecherin.

Themen

Ähnlich

Tutorial

Python JSON-Daten: Ein Leitfaden mit Beispielen

Tutorial

Ein Leitfaden zu Python-Hashmaps