Sari la conținutul principal

Construirea unui asistent Q&A în Django cu Auto-Embeddings în MongoDB

Construiește căutare semantică în Django cu auto-embeddings în MongoDB: fără cod de embedding, re-sincronizare automată când se schimbă documentele și interogări în text simplu.
· 7 min. citește

Descoperă cu AI

Ce simplifică Auto-Embeddings

Într-o configurație tipică de generare augmentată cu regăsire (RAG), generezi embeddings când inserezi un document, le regenerezi când se schimbă conținutul și îți embedezi singur fiecare interogare. Automated Embedding simplifică procesul de construire a căutării semantice, deoarece MongoDB Atlas gestionează nativ generarea, actualizarea și interogarea embeddings, iar Vector Search stochează vectorii generați în clusterul tău.

Cum face MongoDB embedding automat

Când este creat un index de căutare vectorială de tip autoEmbed, MongoDB generează embeddings pentru câmpul ales, folosește modelul VoyageAI, le menține sincronizate când apar modificări ale documentului și embedează textul interogării la momentul căutării cu același model. Embeddings generate sunt stocate asincron pe clusterul MongoDB într-o bază de date internă separată.

În acest tutorial, vom construi un asistent Q&A pentru documente cu autoembeddings în MongoDB. Backend-ul Django MongoDB va fi folosit pentru a defini modelele și a ingera documente, MongoDB va fi folosit pentru căutări, generarea și sincronizarea automată a embeddings, iar LLM-ul va întoarce documente pe baza rezultatelor regăsite.

Până la finalul acestui tutorial, vei construi etapa de regăsire a unui pipeline RAG: o căutare semantică peste documente din Federal Register în care auto-embeddings se ocupă de partea de embedding pentru tine. Documentele sunt embedate când le inserezi, re-embedate când se schimbă, iar interogările tale sunt embedate la momentul căutării, toate fără să scrii cod pentru embedding.

Există două moduri de a urma acest tutorial.

  • Opțiunea A: Clonează repo-ul GitHub care conține codul finalizat din acest tutorial, configurează-l folosind README-ul repo-ului și explorează-l pe cont propriu. Link către proiectul GitHub: https://github.com/mongodb-developer/django-mongodb-regulations-qa
  • Opțiunea B: Construiește proiectul de la zero urmând pașii de mai jos.

Configurare

Înainte să începi, asigură-te că ai:

După ce finalizezi aceste cerințe prealabile, următorul pas este să creezi folderul proiectului.

Creează un proiect și un mediu virtual

Creează un folder gol pentru proiectul tău și rulează cd în el.

mkdir regulations_qa
cd regulations_qa

Acesta este directorul rădăcină al proiectului tău. Creează și activează mediul tău virtual aici, dacă nu ai făcut-o deja:

python -m venv .venv

Pentru a activa mediul virtual pe macOS sau Linux, rulează:

source .venv/bin/activate

Pe Windows, rulează:

.venv\Scripts\activate

Instalează dependențele

Creează un fișier requirements.txt la rădăcina proiectului cu următorul conținut:

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

Apoi instalează totul:

pip install -r requirements.txt

Creează proiectul Django și aplicația Django

Din directorul rădăcină al proiectului tău, rulează următoarea comandă pentru a crea un nou proiect și o nouă aplicație Django. Adaugă . la finalul comenzii startproject, ceea ce îi spune lui Django să instaleze proiectul în directorul curent în loc să creeze un folder imbricat nou.

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

Creează aplicația documents

python manage.py startapp documents

Înregistrează aplicația în regulations_qa/settings.py adăugând-o în 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',
]

Configurează variabilele de mediu

Creează un fișier .env la rădăcina proiectului cu valorile tale și adaugă-l în .gitignore ca să nu fie comis când faci push.

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

Șterge linia hardcodată originală SECRET_KEY = '...' din settings.py, copiază valoarea pe care a generat-o Django în settings.py când ai rulat startproject și înlocuiește-o în fișierul .env. Implicit este hardcodată acolo, iar noi o mutăm în .env ca să nu ajungă în controlul versiunilor, deoarece Django o folosește pentru a semna cookie-uri de sesiune, token-uri CSRF și alte date sensibile de securitate.

Deschide regulations_qa/settings.py și asigură-te că include tot ce urmează. Liniile de import și load_dotenv() merg la început. Înlocuiește definițiile existente pentru SECRET_KEY și DATABASES și adaugă linia 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"),
    },
}

Creează foldere pentru comenzile de management

În continuare, creăm foldere cu fișiere __init__.py goale pentru comenzile de management, deoarece Django descoperă comenzi personalizate doar într-un pachet management/commands/.

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

Sursa datelor: documentele Federal Register

În acest tutorial, vom indexa documente din Federal Register; publicațiile zilnice ale guvernului SUA cu reguli, propuneri de reguli și notificări. Sursa de date este un API public alcătuit din documente care au un titlu și un rezumat scurt redactat, ceea ce funcționează bine cu căutarea semantică.

Documentația API: https://www.federalregister.gov/developers/documentation/api/v1

Înregistrările au câmpuri precum title, type, abstract, document_number (un ID unic), publication_date, html_url și o listă agencies.

  • Unele documente conțin valori nule, așa că le vom omite.
  • Rezumatelor le apar marcaje precum <INF>2.5<INF> în „PM2.5”, așa că eliminăm tag-urile înainte de salvare.
  • Rezultatele sunt paginate la maximum 100 pe cerere, iar fiecare pagină include un next_page_url (bazat pe cursor) de urmat.

Testează endpoint-ul din shell

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

Notă: Acestea sunt date publice ale guvernului SUA folosite pentru demonstrație. Nu reprezintă o sursă legală; pentru cercetare juridică, folosește ediția oficială.

Ingestia datelor

Vom începe prin a crea modele în fișierul 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 continuare, creăm și rulăm migrațiile.

python manage.py makemigrations documents
python manage.py migrate

Apoi, să trecem la partea de ingestie.

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

Rulează comanda:

python manage.py ingest_federal_register --limit 100

Poți confirma importul în interfața MongoDB Atlas:

MongoDB Atlas Data Explorer arătând 100 de documente Federal Register în colecția regulations_qa.documents_document

Definește indexul Auto-Embed

Indexul de căutare vectorială îi spune lui MongoDB pe ce câmp să facă embeddings și specifică ce model să fie folosit. După asta, MongoDB generează și stochează automat embeddings.

  1. În interfața Atlas, deschide clusterul, mergi la Search & Vector Search și dă click pe Create Search Index.

Pagina Search & Vector Search în MongoDB Atlas cu butonul Create Search Index

  1. Alege Vector Search ca tip de căutare și Automated Embedding ca modalitate de a seta datele vectoriale.

Configurația indexului Atlas cu Vector Search și Automated Embedding selectate

  1. Alege editorul JSON, selectează baza ta de date și colecția documents_document și denumește indexul autoembed_index (numele trebuie să corespundă cu VECTOR_INDEX_NAME din .env). LiPește această definiție:
{
  "fields": [
    {
      "type": "autoEmbed",
      "modality": "text",
      "path": "abstract",
      "model": "voyage-4-lite"
    }
  ]
}

Editorul JSON Atlas cu definiția indexului autoEmbed pentru câmpul abstract folosind voyage-4-lite

Revizuiește definiția, apoi creează indexul.

Pasul de revizuire pentru indexul de căutare vectorială autoembed_index pe regulations_qa.documents_document

  1. Așteaptă până când statusul indexului arată că este gata de interogat, deoarece embeddings sunt generate în fundal.

Lista Atlas Search & Vector Search arătând autoembed_index cu status READY și queryable

Interogare în text simplu

Pentru auto-embeddings, folosim etapa $vectorSearch cu o interogare în text simplu și embedăm întrebarea cu același model pe care îl folosește indexul, astfel încât nu există apel de embedding în codul nostru.

Pentru a realiza asta, vom crea un modul de servicii.

# 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() creează conexiunea la MongoDB o singură dată și o reutilizează. lru_cache memorează rezultatul primei apelări, astfel încât fiecare căutare partajează un singur client în loc să deschidă o conexiune nouă de fiecare dată.
  • _get_collection() alege baza de date regulations_qa și colecția documents_document, folosind aceleași setări ca Django.
  • _get_index_name() citește numele indexului din setări și oferă o eroare clară dacă lipsește.
  • semantic_search() trimite întrebarea ca text în câmpul query. A doua etapă reduce ieșirea la câmpurile de care avem nevoie și adaugă scorul de similaritate.

Apoi adăugăm un helper pentru a căuta în documente:

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

Acum, pentru test, rulează:

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

În exemplu, alegem întrebări care nu împart cuvinte-cheie cu rezumatele. O întrebare despre „limits on pollution from factories” ar trebui să regăsească documente despre standarde de emisii.

Notă: Pe un cluster gratuit (M0) fără metodă de plată, cererile de embedding pentru interogări pot fi limitate în rată.

Demo: Editează un document și urmărește re-sincronizarea

Pentru demo, putem folosi fie Search Tester în MongoDB Atlas, care este legat de autoembed_index creat anterior pe colecția regulations_qa.documents_document, fie shell-ul Python.

Atlas Search Tester pentru autoembed_index pe regulations_qa.documents_document

Pasul 1: Caută prin MongoDB Atlas și din shell

Pentru a testa în interfața MongoDB Atlas, introdu această interogare:

which states need to clean up their air

Rezultatele Search Tester pentru interogarea which states need to clean up their air, cu scoruri de similaritate

Pentru a testa din shell:

Deschide shell-ul cu python manage.py shell, apoi rulează:

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

Ieșirea din shell-ul Django listând primele 10 rezultate ale căutării semantice și scorurile lor

Rezultatul ar trebui să fie același ca ce am văzut în interfața grafică.

Pasul 2: Editează documentul

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

Shell-ul Django adăugând o propoziție la rezumatul documentului 2026-16515 și salvând

Pasul 3: Caută din nou

Auto-embeddings sunt generate asincron, așa că așteaptă 30–60 de secunde, apoi rulează din nou interogarea:

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

Rezultatele căutării după editare, cu documentul 2026-16515 mutat de pe locul 10 pe locul 5

Acum, ar trebui să vezi că documentul editat se clasează mai sus decât înainte.

Rulează aceeași interogare în Search Tester pentru a vedea rezultatele în interfața grafică.

Ce s-a întâmplat a fost că MongoDB a observat că s-a schimbat câmpul indexat și a regenerat embedding-ul acelui document, astfel încât documentul 2026-16515, care era al 10-lea în eșantion, a fost clasat mai sus și a ajuns pe poziția a 5-a după editare și sincronizare.

Concluzie

Felicitări că ai ajuns până aici! Avem un asistent Q&A pentru documente folosind date în care MongoDB gestionează fluxul de lucru pentru embeddings. Acest lucru a fost realizat în următorii pași:

  • Inserare: documente încărcate prin ORM-ul Django
  • Indexare: o definiție de index, creată în interfața Atlas, care numește câmpul și modelul.
  • Interogare: întrebări în text simplu printr-un mic serviciu fără a adăuga un apel separat pentru embedding.
  • Editare: modificările aduse câmpului indexat sunt re-sincronizate fără un script de re-embedding.

Notă: Datele din acest tutorial provin din Federal Register, care publică documente ale guvernului SUA. Acest tutorial este independent și nu este afiliat sau aprobat de Federal Register.

Referințe

Subiecte