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.
Î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.
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 .Funcționează cu
Î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',]Funcționează cu
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_indexFuncționează cu
Ș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"),},}Funcționează cu
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__.pyFuncționează cu
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ă.
Î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"Funcționează cu
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.
python manage.py makemigrations documents
python manage.py migrateFuncționează cu
Apoi, să trecem la partea de ingestie.
# documents/management/commands/ingest_federal_register.pyimport 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"<[^>]+>")classCommand(BaseCommand):help="Load Federal Register documents into MongoDB."defadd_arguments(self, parser):
parser.add_argument("--agency", default="environmental-protection-agency")
parser.add_argument("--limit",type=int, default=300)defhandle(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,0while url and processed < options["limit"]:
response = requests.get(
url,
params=params if url == API_URL elseNone,
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()ifnot 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 +=1if processed >= options["limit"]:break
url = page.get("next_page_url")
time.sleep(1)
self.stdout.write(f"Documents in database: {Document.objects.count()}")Funcționează cu
Rulează comanda:
python manage.py ingest_federal_register --limit100Funcționează cu
Poți confirma importul în interfața MongoDB Atlas:
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.
În interfața Atlas, deschide clusterul, mergi la Search & Vector Search și dă click pe Create Search Index.
Alege Vector Search ca tip de căutare și Automated Embedding ca modalitate de a seta datele vectoriale.
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"}]}Funcționează cu
Revizuiește definiția, apoi creează indexul.
Așteaptă până când statusul indexului arată că este gata de interogat, deoarece embeddings sunt generate în fundal.
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.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))Funcționează cu
_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.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]}")Funcționează cu
Acum, pentru test, rulează:
python manage.py search_docs "limits on pollution from factories"Funcționează cu
Î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.
Pasul 1: Caută prin MongoDB Atlas și din shell
Pentru a testa în interfața MongoDB Atlas, introdu această interogare:
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 inenumerate(hits,1)))Funcționează cu
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")Funcționează cu
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 inenumerate(hits,1)))Funcționează cu
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.
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 modelulVoyageAI, 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.
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.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:
Pentru a activa mediul virtual pe macOS sau Linux, rulează:
Pe Windows, rulează:
Instalează dependențele
Creează un fișier
requirements.txtla rădăcina proiectului cu următorul conținut:Apoi instalează totul:
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 comenziistartproject, ceea ce îi spune lui Django să instaleze proiectul în directorul curent în loc să creeze un folder imbricat nou.Creează aplicația
documentsÎnregistrează aplicația în
regulations_qa/settings.pyadăugând-o înINSTALLED_APPS:Configurează variabilele de mediu
Creează un fișier
.envla rădăcina proiectului cu valorile tale și adaugă-l în.gitignoreca să nu fie comis când faci push.Șterge linia hardcodată originală
SECRET_KEY = '...'dinsettings.py, copiază valoarea pe care a generat-o Django însettings.pycând ai rulatstartprojectși înlocuiește-o în fișierul.env. Implicit este hardcodată acolo, iar noi o mutăm în.envca 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 șiload_dotenv()merg la început. Înlocuiește definițiile existente pentruSECRET_KEYșiDATABASESși adaugă liniaVECTOR_INDEX_NAME:Creează foldere pentru comenzile de management
În continuare, creăm foldere cu fișiere
__init__.pygoale pentru comenzile de management, deoarece Django descoperă comenzi personalizate doar într-un pachetmanagement/commands/.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.<INF>2.5<INF>în „PM2.5”, așa că eliminăm tag-urile înainte de salvare.next_page_url(bazat pe cursor) de urmat.Testează endpoint-ul din shell
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.În continuare, creăm și rulăm migrațiile.
Apoi, să trecem la partea de ingestie.
Rulează comanda:
Poți confirma importul în interfața MongoDB Atlas:
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.
documents_documentși denumește indexulautoembed_index(numele trebuie să corespundă cuVECTOR_INDEX_NAMEdin.env). LiPește această definiție:Revizuiește definiția, apoi creează indexul.
Interogare în text simplu
Pentru auto-embeddings, folosim etapa
$vectorSearchcu 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.
_get_client()creează conexiunea la MongoDB o singură dată și o reutilizează.lru_cachememorează 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 dateregulations_qași colecțiadocuments_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âmpulquery. 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:
Acum, pentru test, rulează:
Î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 deautoembed_indexcreat anterior pe colecțiaregulations_qa.documents_document, fie shell-ul Python.Pasul 1: Caută prin MongoDB Atlas și din shell
Pentru a testa în interfața MongoDB Atlas, introdu această interogare:
Pentru a testa din shell:
Deschide shell-ul cu
python manage.py shell, apoi rulează:Rezultatul ar trebui să fie același ca ce am văzut în interfața grafică.
Pasul 2: Editează documentul
Pasul 3: Caută din nou
Auto-embeddings sunt generate asincron, așa că așteaptă 30–60 de secunde, apoi rulează din nou interogarea:
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:
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