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.
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 .Bereitgestellt von
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',]Bereitgestellt von
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_indexBereitgestellt von
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"),},}Bereitgestellt von
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__.pyBereitgestellt von
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.
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"Bereitgestellt von
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.
Du kannst den Import in der MongoDB‑Atlas‑UI bestätigen:
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.
Öffne in der Atlas‑UI deinen Cluster, gehe zu Search & Vector Search und klicke auf Create Search Index.
Wähle als Suchtyp Vector Search und als Methode für deine Vektordaten Automated Embedding.
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"}]}Bereitgestellt von
Prüfe die Definition und erstelle dann den Index.
Warte, bis der Index‑Status zeigt, dass er abfragbar ist. Die Embeddings werden im Hintergrund generiert.
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.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))Bereitgestellt von
_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.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]}")Bereitgestellt von
Zum Testen führe aus:
python manage.py search_docs "limits on pollution from factories"Bereitgestellt von
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.
Schritt 1: Suche über MongoDB Atlas und die Shell
Zum Testen in der MongoDB‑Atlas‑UI gib diese Query ein:
Ö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 inenumerate(hits,1)))Bereitgestellt von
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")Bereitgestellt von
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 inenumerate(hits,1)))Bereitgestellt von
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.
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.
Lerne, wie man mit JSON in Python arbeitet, einschließlich Serialisierung, Deserialisierung, Formatierung, Leistungsoptimierung, Umgang mit APIs und Verständnis der Einschränkungen und Alternativen von JSON.
Mach dich mit Python-Datenstrukturen vertraut: Lerne mehr über Datentypen und primitive sowie nicht-primitive Datenstrukturen wie Strings, Listen, Stapel usw.
Erforsche Pythons match-case: eine Anleitung zu seiner Syntax, Anwendungen in Data Science und ML sowie eine vergleichende Analyse mit dem traditionellen switch-case.
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
autoEmbederstellt wird, generiert MongoDB Embeddings für das gewählte Feld mit demVoyageAI-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
cdhinein.Dies ist das Root‑Verzeichnis deines Projekts. Lege hier deine virtuelle Umgebung an und aktiviere sie, falls noch nicht geschehen:
Zum Aktivieren der virtuellen Umgebung unter macOS oder Linux:
Unter Windows:
Abhängigkeiten installieren
Erstelle im Projektroot eine Datei
requirements.txtmit folgendem Inhalt:Dann alles installieren:
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.Die App
documentserstellenRegistriere die App in
regulations_qa/settings.py, indem du sie zuINSTALLED_APPShinzufügst:Umgebungsvariablen konfigurieren
Lege im Projektroot eine
.env-Datei mit deinen Werten an und trage sie in.gitignoreein, damit sie beim Pushen nicht mit eingecheckt wird.Lösche die ursprüngliche hartkodierte Zeile
SECRET_KEY = '...'aussettings.py, kopiere den von Django beimstartprojectgenerierten Wert aussettings.pyund trage ihn in deiner.envein. 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.pyund stelle sicher, dass alles Folgende enthalten ist. Die Importzeilen undload_dotenv()kommen nach oben. Ersetze die bestehenden Definitionen vonSECRET_KEYundDATABASESund füge die ZeileVECTOR_INDEX_NAMEhinzu: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 Paketmanagement/commands/erkennt.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_urlund eineagencies-Liste.<INF>2.5</INF>in „PM2.5“ – wir entfernen die Tags vor dem Speichern.next_page_url(cursorbasiert).Endpoint per Shell testen
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.Als Nächstes erstellen und führen wir Migrationen aus.
Weiter geht es mit dem Ingest‑Teil.
Führe den Befehl aus:
Du kannst den Import in der MongoDB‑Atlas‑UI bestätigen:
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.
documents_documentund benenne den Indexautoembed_index(der Name muss zuVECTOR_INDEX_NAMEin deiner.envpassen). Füge diese Definition ein:Prüfe die Definition und erstelle dann den Index.
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.
_get_client()stellt einmal die Verbindung zu MongoDB her und verwendet sie wieder.lru_cachemerkt 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 Datenbankregulations_qaund die Collectiondocuments_documentgemäß 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 Feldquery. 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:
Zum Testen führe aus:
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 Testerin MongoDB Atlas nutzen, der an den zuvor erstelltenautoembed_indexauf der Collectionregulations_qa.documents_documentgebunden ist, oder die Python‑Shell.Schritt 1: Suche über MongoDB Atlas und die Shell
Zum Testen in der MongoDB‑Atlas‑UI gib diese Query ein:
Zum Testen über die Shell:
Öffne die Shell mit
python manage.py shellund führe dann aus:Die Ausgabe sollte mit dem Ergebnis aus der GUI übereinstimmen.
Schritt 2: Das Dokument bearbeiten
Schritt 3: Erneut suchen
Auto‑Embeddings werden asynchron erzeugt. Warte daher 30–60 Sekunden und führe die Query erneut aus:
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:
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