Hoppa till huvudinnehållet

Bygga en frågor-och-svar-assistent i Django med MongoDB Auto-Embeddings

Bygg semantisk sökning i Django med MongoDB auto-embeddings: ingen embeddingskod, automatisk omsynk när dokument ändras och frågor i klartext.
· 7 min läs

Utforska med AI

Vad Auto-Embeddings förenklar

I en typisk RAG-uppsättning (retrieval-augmented generation) genererar du embeddings när du lägger in ett dokument, återskapar dem när innehållet ändras och embed:ar varje fråga själv. Automated Embedding förenklar arbetet med att bygga semantisk sökning, eftersom MongoDB Atlas hanterar generering, uppdateringar och frågor inbyggt, och Vector Search lagrar genererade vektorembeddings i din kluster.

Hur MongoDB gör automatisk embedding

När ett vektorsökningsindex av typen autoEmbed skapas, genererar MongoDB embeddings för det valda fältet, använder modellen VoyageAI, håller dem synkade när dokumentet ändras och embed:ar frågetexten vid sökningstillfället med samma modell. De genererade embeddings lagras asynkront på MongoDB-klustret i en separat intern databas.

I den här handledningen bygger vi en Q&A-assistent för dokument med MongoDB auto-embeddings. Django MongoDB-backenden används för att definiera modeller och importera dokument, och MongoDB används för uppslagningar, för att generera och synka embeddings automatiskt, och LLM:et returnerar dokument baserat på de hämtade resultaten.

I slutet av den här handledningen har du byggt hämtningssteget i en RAG-pipeline: en semantisk sökning över Federal Register-dokument där auto-embeddings sköter embedding-arbetet åt dig. Dokument embed:as när du lägger in dem, embed:as på nytt när de ändras, och dina frågor embed:as vid sökningstillfället — allt utan att skriva embeddingskod.

Det finns två sätt att följa den här handledningen.

Förberedelser

Innan du börjar, se till att du har:

När dessa förutsättningar är på plats är nästa steg att skapa din projektmapp.

Skapa ett projekt och en virtuell miljö

Skapa en tom mapp för ditt projekt och kör cd in i den.

mkdir regulations_qa
cd regulations_qa

Detta är ditt projekts rotkatalog. Skapa och aktivera din virtuella miljö här om du inte redan gjort det:

python -m venv .venv

För att aktivera den virtuella miljön på macOS eller Linux, kör:

source .venv/bin/activate

På Windows, kör:

.venv\Scripts\activate

Installera beroenden

Skapa en fil requirements.txt i projektets rot med följande innehåll:

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

Installera sedan allt:

pip install -r requirements.txt

Skapa Django-projekt och Django-app

Från projektets rotkatalog, kör följande kommando för att skapa ett nytt Django-projekt och en app. Lägg till det avslutande . i kommandot startproject, vilket säger åt Django att installera projektet i den aktuella katalogen i stället för att skapa en ny underkatalog.

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

Skapa appen documents

python manage.py startapp documents

Registrera appen i regulations_qa/settings.py genom att lägga till den i 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',
]

Konfigurera miljövariabler

Skapa en .env-fil i projektets rot med dina egna värden, och lista den i .gitignore så att den inte checkas in när du pushar.

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

Ta bort den ursprungliga hårdkodade raden SECRET_KEY = '...' från settings.py, kopiera värdet som Django genererade i settings.py när du körde startproject och ersätt det i din .env-fil. Det är hårdkodat där som standard, och vi flyttar det till .env för att hålla det utanför versionshanteringen, eftersom Django använder det för att signera sessionscookies, CSRF-token och annan säkerhetskänslig data.

Öppna regulations_qa/settings.py och säkerställ att den innehåller allt följande. Importerna och load_dotenv() ska ligga högst upp. Ersätt befintliga definitioner av SECRET_KEY och DATABASES, och lägg till raden 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"),
    },
}

Skapa mappar för management-kommandon

Nästa steg är att skapa mappar med tomma __init__.py-filer för management-kommandon, eftersom Django bara hittar egna kommandon i ett paket management/commands/.

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

Datakällan: Federal Register-dokumenten

I den här handledningen indexerar vi dokument från Federal Register; USA:s dagliga publikation av regler, förslag till regler och meddelanden. Datakällan är ett offentligt API med dokument som har en titel och en kort textsammanfattning, vilket passar bra för semantisk sökning.

API-dokumentation: https://www.federalregister.gov/developers/documentation/api/v1

Poster har fält som title, type, abstract, document_number (ett unikt ID), publication_date, html_url och en lista agencies.

  • Vissa dokument innehåller null-värden, så vi utelämnar dem.
  • Abstracts innehåller markup som <INF>2.5<INF> i ”PM2.5”, så vi tar bort taggar innan vi sparar.
  • Resultat pagineras med upp till 100 per begäran, och varje sida har en next_page_url (kursbaserad) att följa.

Testa slutpunkten via shell

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

Obs: Detta är offentlig amerikansk myndighetsdata som används för demonstration. Det är inte en juridisk källa; för juridisk forskning, använd den officiella utgåvan.

Importera data

Vi börjar med att skapa modeller i filen 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]}"

Nästa steg är att skapa och köra migrationer.

python manage.py makemigrations documents
python manage.py migrate

Sedan går vi vidare till importsteget.

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

Kör kommandot:

python manage.py ingest_federal_register --limit 100

Du kan bekräfta importen i MongoDB Atlas UI:

MongoDB Atlas Data Explorer som visar 100 Federal Register-dokument i samlingen regulations_qa.documents_document

Definiera Auto-Embed-indexet

Vektorsökningsindexet talar om för MongoDB vilket fält som ska embed:as och anger vilken modell som ska användas. Därefter genererar och lagrar MongoDB embeddings automatiskt.

  1. I Atlas UI, öppna ditt kluster, gå till Search & Vector Search och klicka på Create Search Index.

Sidan Search & Vector Search i MongoDB Atlas med knappen Create Search Index

  1. Välj Vector Search som söktyp och Automated Embedding som sätt att konfigurera din vektordata.

Atlas indexkonfiguration med Vector Search och Automated Embedding markerat

  1. Välj JSON-redigeraren, välj din databas och samlingen documents_document, och namnge indexet autoembed_index (namnet måste matcha VECTOR_INDEX_NAME i din .env). Klistra in denna definition:
{
  "fields": [
    {
      "type": "autoEmbed",
      "modality": "text",
      "path": "abstract",
      "model": "voyage-4-lite"
    }
  ]
}

Atlas JSON-redigerare med autoEmbed-indexdefinitionen för fältet abstract med voyage-4-lite

Granska definitionen och skapa sedan indexet.

Granskningssteg för vektorsökningsindexet autoembed_index på regulations_qa.documents_document

  1. Vänta tills indexstatus visar att det är redo att fråga, eftersom embeddings genereras i bakgrunden.

Listan Atlas Search & Vector Search som visar autoembed_index med status READY och queryable

Fråga i klartext

För auto-embeddings använder vi steget $vectorSearch med en fråga i klartext och embed:ar frågan med samma modell som indexet använder, så det finns inget embedding-anrop i vår kod.

För att göra detta skapar vi en servicemodul.

# 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() skapar anslutningen till MongoDB en gång och återanvänder den. lru_cache minns resultatet av första anropet, så varje sökning delar en klient i stället för att öppna en ny anslutning varje gång.
  • _get_collection() väljer databasen regulations_qa och samlingen documents_document, med samma inställningar som Django använder.
  • _get_index_name() läser indexnamnet från inställningarna och ger ett tydligt fel om det saknas.
  • semantic_search() skickar frågan som text i fältet query. Det andra steget trimmar utdata till de fält vi behöver och lägger till likhetspoängen.

Sen lägger vi till en hjälpare för att söka i dokumenten:

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

För att testa, kör nu:

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

I exemplet väljer vi frågor som inte delar nyckelord med abstracten. En fråga om ”limits on pollution from factories” bör hämta dokument om utsläppsstandarder.

Obs: På ett gratis (M0) kluster utan betalningsmetod kan embed:ingsförfrågningar för frågor hastighetsbegränsas.

Demo: Redigera ett dokument och se det synkas om

För demon kan vi antingen använda Search Tester i MongoDB Atlas, som är kopplad till autoembed_index vi skapade tidigare på samlingen regulations_qa.documents_document, eller Python-skalet.

Atlas Search Tester för autoembed_index på regulations_qa.documents_document

Steg 1: Sök via MongoDB Atlas och skalet

För att testa detta i MongoDB Atlas UI, skriv in den här frågan:

which states need to clean up their air

Sökresultat i Search Tester för frågan which states need to clean up their air, med likhetspoäng

För att testa via skalet:

Öppna skalet med python manage.py shell, kör sedan:

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

Utdata i Django-skalet som listar de 10 bästa semantiska sökresultaten och deras poäng

Utdata bör vara samma som vi såg via GUI:t.

Steg 2: Redigera dokumentet

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-skalet lägger till en mening i abstractet för dokument 2026-16515 och sparar det

Steg 3: Sök igen

Auto-embeddings genereras asynkront, så vänta 30–60 sekunder och kör sedan frågan igen:

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

Sökresultat efter redigeringen, med dokument 2026-16515 flyttat från 10:e till 5:e plats

Nu bör vi förvänta oss att det redigerade dokumentet rankas högre än tidigare.

Kör samma fråga i Search Tester för att se resultaten via GUI:t.

Vad som hände var att MongoDB noterade att det indexerade fältet ändrades och återskapade dokumentets embedding, så dokument 2026-16515, som var det 10:e dokumentet i urvalet, rankades högre och placerades på 5:e plats efter redigeringen och synkningen.

Sammanfattning

Grattis till att ha kommit hit! Vi har en Q&A-assistent för dokument med data där MongoDB hanterar embedding-flödet. Detta uppnåddes i följande steg:

  • Insert: dokument laddade via Django ORM
  • Index: en indexdefinition, skapad i Atlas UI, som anger fält och modell.
  • Query: frågor i klartext via en liten tjänst utan att lägga till ett separat embedding-anrop.
  • Edit: ändringar i det indexerade fältet synkas om utan något om-embedding-skript.

Obs: Data i denna handledning kommer från Federal Register, som publicerar dokument från USA:s myndigheter. Denna handledning är fristående och varken associerad med eller godkänd av Federal Register.

Referenser

Ämnen