Creare un assistente Q&A in Django con gli Auto-Embeddings di MongoDB
Crea la ricerca semantica in Django con gli auto-embeddings di MongoDB: niente codice per gli embedding, ri-sincronizzazione automatica quando i documenti cambiano e query in testo semplice.
In una tipica configurazione RAG (retrieval-augmented generation), generi gli embeddings quando inserisci un documento, li rigeneri quando il contenuto cambia e crei tu stesso gli embedding per ogni query. Gli Auto-Embeddings semplificano la creazione della ricerca semantica: MongoDB Atlas gestisce nativamente la generazione, l'aggiornamento e l'esecuzione delle query sugli embedding, e Vector Search archivia i vettori generati sul tuo cluster.
Come MongoDB esegue l'embedding automatico
Quando viene creato un indice di vector search di tipo autoEmbed, MongoDB genera gli embedding per il campo scelto utilizzando il modello VoyageAI, li mantiene sincronizzati quando ci sono modifiche al documento e, al momento della ricerca, crea l'embedding del testo della query con lo stesso modello. Gli embedding generati sono archiviati in modo asincrono sul cluster MongoDB in un database interno separato.
In questo tutorial, costruiremo un Docs Q&A Assistant con gli auto-embeddings di MongoDB. Il backend Django MongoDB verrà usato per definire i modelli e acquisire i documenti; MongoDB verrà utilizzato per le ricerche, per generare e sincronizzare automaticamente gli embedding, e l'LLM restituirà i documenti in base ai risultati recuperati.
Al termine di questo tutorial, avrai realizzato la fase di retrieval di una pipeline RAG: una ricerca semantica sui documenti del Federal Register in cui gli auto-embeddings gestiscono per te il lavoro di embedding. I documenti vengono incorporati quando li inserisci, ri-incorporati quando cambiano, e le tue query vengono incorporate al momento della ricerca, il tutto senza scrivere codice per gli embedding.
Dalla directory root del progetto, esegui il seguente comando per creare un nuovo progetto e un'app Django. Aggiungi il . finale nel comando startproject: indica a Django di installare il progetto nella directory corrente invece di creare una nuova cartella annidata.
django-admin startproject regulations_qa --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/6.0.x.zip .Offerto da
Registra l'app in regulations_qa/settings.py aggiungendola a 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',]Offerto da
Configura le variabili d'ambiente
Crea un file .env nella root del progetto con i tuoi valori e aggiungilo a .gitignore per evitare che venga incluso nei commit quando fai 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_indexOfferto da
Elimina la riga originale con SECRET_KEY = '...' da settings.py, copia il valore che Django ha generato in settings.py quando hai eseguito startproject e sostituiscilo nel tuo file .env. Di default è hardcoded lì, e lo spostiamo in .env per tenerlo fuori dal controllo versione, dato che Django lo usa per firmare cookie di sessione, token CSRF e altri dati sensibili.
Apri regulations_qa/settings.py e assicurati che contenga tutto quanto segue. Le righe di import e load_dotenv() vanno in cima. Sostituisci le definizioni esistenti di SECRET_KEY e DATABASES e aggiungi la riga 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"),},}Offerto da
Crea le cartelle per i comandi di management
Ora creiamo cartelle con file __init__.py vuoti per i comandi di management, perché Django rileva i comandi personalizzati solo in un package management/commands/.
mkdir-p documents/management/commands documents/services &&touch documents/management/__init__.py documents/management/commands/__init__.py documents/services/__init__.pyOfferto da
La fonte dei dati: i documenti del Federal Register
In questo tutorial, indicizzeremo documenti dal Federal Register: le pubblicazioni giornaliere del governo degli Stati Uniti su regole, proposte di regole e avvisi. La fonte dei dati è un'API pubblica con documenti che hanno un titolo e un breve abstract discorsivo, ideale per la ricerca semantica.
I record hanno campi come title, type, abstract, document_number (un ID univoco), publication_date, html_url e una lista agencies.
Alcuni documenti contengono valori null; li ometteremo.
Gli abstract contengono markup come <INF>2.5</INF> in “PM2.5”, quindi rimuoviamo i tag prima di salvare.
I risultati sono paginati fino a 100 per richiesta e ogni pagina include un next_page_url (basato su cursore) da seguire.
Prova l'endpoint via shell
curl-g"https://www.federalregister.gov/api/v1/documents.json?conditions[agencies][]=environmental-protection-agency&per_page=2"Offerto da
NB: Questi sono dati pubblici del governo degli Stati Uniti usati a scopo dimostrativo. Non è una fonte legale; per ricerche legali, usa l'edizione ufficiale.
python manage.py makemigrations documents
python manage.py migrateOfferto da
Passiamo quindi alla parte di ingest.
# 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()}")Offerto da
Esegui il comando:
python manage.py ingest_federal_register --limit100Offerto da
Puoi confermare l'import nella UI di MongoDB Atlas:
Definisci l'indice Auto-Embed
L'indice di vector search dice a MongoDB su quale campo eseguire gli embedding e specifica quale modello usare. Da lì, MongoDB genera e archivia automaticamente gli embedding.
Nell'interfaccia di Atlas, apri il tuo cluster, vai su Search & Vector Search e clicca su Create Search Index.
Scegli Vector Search come tipo di ricerca e Automated Embedding come modalità per impostare i tuoi dati vettoriali.
Scegli l'editor JSON, seleziona il tuo database e la collection documents_document, e assegna all'indice il nome autoembed_index (il nome deve corrispondere a VECTOR_INDEX_NAME nel tuo .env). Incolla questa definizione:
{"fields":[{"type":"autoEmbed","modality":"text","path":"abstract","model":"voyage-4-lite"}]}Offerto da
Rivedi la definizione, quindi crea l'indice.
Attendi che lo stato dell'indice indichi che è pronto per le query, mentre gli embedding vengono generati in background.
Query in testo semplice
Con gli auto-embeddings, usiamo lo stage $vectorSearch con una query in testo semplice e creiamo l'embedding della domanda con lo stesso modello usato dall'indice, quindi non c'è alcuna chiamata di embedding nel nostro codice.
Per farlo, creeremo un modulo di servizio.
# 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))Offerto da
_get_client() crea la connessione a MongoDB una sola volta e la riutilizza. lru_cache memorizza il risultato della prima chiamata, così ogni ricerca condivide un unico client invece di aprire una nuova connessione ogni volta.
_get_collection() seleziona il database regulations_qa e la collection documents_document, usando le stesse impostazioni di Django.
_get_index_name() legge il nome dell'indice dalle impostazioni e fornisce un errore chiaro se manca.
semantic_search() invia la domanda come testo nel campo query. Il secondo stage riduce l'output ai campi necessari e aggiunge lo score di similarità.
Poi aggiungiamo un helper per cercare nei documenti:
# 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]}")Offerto da
Ora, per testare, esegui:
python manage.py search_docs "limits on pollution from factories"Offerto da
Nell'esempio, selezioniamo domande che non condividono parole chiave con gli abstract. Una domanda su “limiti all'inquinamento delle fabbriche” dovrebbe recuperare documenti sugli standard di emissione.
NB: Su un cluster gratuito (M0) senza metodo di pagamento, le richieste di embedding delle query potrebbero essere soggette a rate limiting.
Demo: modifica un documento e guarda la ri-sincronizzazione
Per la demo, possiamo usare il Search Tester in MongoDB Atlas, collegato all'autoembed_index che abbiamo creato in precedenza sulla collection regulations_qa.documents_document, oppure la shell Python.
Passo 1: cerca tramite MongoDB Atlas e shell
Per testarlo nella UI di MongoDB Atlas, inserisci questa query:
Apri la shell con python manage.py shell, poi esegui:
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)))Offerto da
L'output dovrebbe corrispondere a quanto visto tramite la GUI.
Passo 2: modifica il documento
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")Offerto da
Passo 3: cerca di nuovo
Gli auto-embeddings sono generati in modo asincrono, quindi aspetta 30–60 secondi e poi esegui di nuovo la query:
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)))Offerto da
Ora dovresti vedere il documento modificato posizionarsi più in alto rispetto a prima.
Esegui la stessa query nel Search Tester per vedere i risultati via GUI.
È successo che MongoDB ha rilevato la modifica al campo indicizzato e ha rigenerato l'embedding di quel documento, così il documento 2026-16515, che era il decimo nel campione, è stato classificato più in alto ed è passato alla quinta posizione dopo la modifica e la sincronizzazione.
Conclusione
Complimenti per essere arrivato fin qui! Abbiamo un assistente Q&A per i documenti che usa dati in cui MongoDB gestisce il workflow degli embedding. Il tutto è stato ottenuto con questi passaggi:
Insert: documenti caricati tramite la ORM di Django
Index: una definizione di indice, creata nella UI di Atlas, che indica il campo e il modello.
Query: domande in testo semplice tramite un piccolo servizio senza aggiungere una chiamata separata per gli embedding.
Edit: le modifiche al campo indicizzato vengono ri-sincronizzate senza uno script di re-embedding.
NB: I dati in questo tutorial provengono dal Federal Register, che pubblica documenti del governo degli Stati Uniti. Questo tutorial è indipendente e non è affiliato né approvato dal Federal Register.
Afi supporta gli sviluppatori in MongoDB con un focus su Django e Python, aiutando gli ingegneri a creare con tecnologie di dati moderne attraverso tutorial, talk e attività nella community. Riconosciuta come Microsoft MVP per Python e il Web, fa parte del board della Django Software Foundation ed è Programme Chair per DjangoCon US 2025. Afi è anche Regional Executor per Black Python Devs, oltre a essere una contributor open source attiva e speaker internazionale.
Scopri i 15 migliori server MCP remoti che stanno trasformando lo sviluppo AI nel 2026. Scopri come migliorano automazione, ragionamento, sicurezza e velocità dei workflow.
Cosa semplificano gli Auto-Embeddings
In una tipica configurazione RAG (retrieval-augmented generation), generi gli embeddings quando inserisci un documento, li rigeneri quando il contenuto cambia e crei tu stesso gli embedding per ogni query. Gli Auto-Embeddings semplificano la creazione della ricerca semantica: MongoDB Atlas gestisce nativamente la generazione, l'aggiornamento e l'esecuzione delle query sugli embedding, e Vector Search archivia i vettori generati sul tuo cluster.
Come MongoDB esegue l'embedding automatico
Quando viene creato un indice di vector search di tipo
autoEmbed, MongoDB genera gli embedding per il campo scelto utilizzando il modelloVoyageAI, li mantiene sincronizzati quando ci sono modifiche al documento e, al momento della ricerca, crea l'embedding del testo della query con lo stesso modello. Gli embedding generati sono archiviati in modo asincrono sul cluster MongoDB in un database interno separato.In questo tutorial, costruiremo un Docs Q&A Assistant con gli auto-embeddings di MongoDB. Il backend Django MongoDB verrà usato per definire i modelli e acquisire i documenti; MongoDB verrà utilizzato per le ricerche, per generare e sincronizzare automaticamente gli embedding, e l'LLM restituirà i documenti in base ai risultati recuperati.
Al termine di questo tutorial, avrai realizzato la fase di retrieval di una pipeline RAG: una ricerca semantica sui documenti del Federal Register in cui gli auto-embeddings gestiscono per te il lavoro di embedding. I documenti vengono incorporati quando li inserisci, ri-incorporati quando cambiano, e le tue query vengono incorporate al momento della ricerca, il tutto senza scrivere codice per gli embedding.
Ci sono due modi per seguire questo tutorial.
Setup
Prima di iniziare, assicurati di avere:
Una volta soddisfatti questi prerequisiti, il passo successivo è creare la cartella del progetto.
Crea un progetto e un ambiente virtuale
Crea una cartella vuota per il progetto ed esegui
cdal suo interno.Questa è la directory root del tuo progetto. Crea e attiva qui il tuo ambiente virtuale, se non l'hai già fatto:
Per attivare l'ambiente virtuale su macOS o Linux, esegui:
Su Windows, esegui:
Installa le dipendenze
Crea un file
requirements.txtnella root del progetto con il seguente contenuto:Poi installa tutto:
Crea il progetto Django e l'app Django
Dalla directory root del progetto, esegui il seguente comando per creare un nuovo progetto e un'app Django. Aggiungi il
.finale nel comandostartproject: indica a Django di installare il progetto nella directory corrente invece di creare una nuova cartella annidata.Crea l'app
documentsRegistra l'app in
regulations_qa/settings.pyaggiungendola aINSTALLED_APPS:Configura le variabili d'ambiente
Crea un file
.envnella root del progetto con i tuoi valori e aggiungilo a.gitignoreper evitare che venga incluso nei commit quando fai push.Elimina la riga originale con
SECRET_KEY = '...'dasettings.py, copia il valore che Django ha generato insettings.pyquando hai eseguitostartprojecte sostituiscilo nel tuo file.env. Di default è hardcoded lì, e lo spostiamo in.envper tenerlo fuori dal controllo versione, dato che Django lo usa per firmare cookie di sessione, token CSRF e altri dati sensibili.Apri
regulations_qa/settings.pye assicurati che contenga tutto quanto segue. Le righe di import eload_dotenv()vanno in cima. Sostituisci le definizioni esistenti diSECRET_KEYeDATABASESe aggiungi la rigaVECTOR_INDEX_NAME:Crea le cartelle per i comandi di management
Ora creiamo cartelle con file
__init__.pyvuoti per i comandi di management, perché Django rileva i comandi personalizzati solo in un packagemanagement/commands/.La fonte dei dati: i documenti del Federal Register
In questo tutorial, indicizzeremo documenti dal Federal Register: le pubblicazioni giornaliere del governo degli Stati Uniti su regole, proposte di regole e avvisi. La fonte dei dati è un'API pubblica con documenti che hanno un titolo e un breve abstract discorsivo, ideale per la ricerca semantica.
Documentazione API: https://www.federalregister.gov/developers/documentation/api/v1
I record hanno campi come
title,type,abstract,document_number(un ID univoco),publication_date,html_urle una listaagencies.<INF>2.5</INF>in “PM2.5”, quindi rimuoviamo i tag prima di salvare.next_page_url(basato su cursore) da seguire.Prova l'endpoint via shell
NB: Questi sono dati pubblici del governo degli Stati Uniti usati a scopo dimostrativo. Non è una fonte legale; per ricerche legali, usa l'edizione ufficiale.
Acquisisci i dati
Inizieremo creando i modelli nel file
models.py.Poi creiamo ed eseguiamo le migrazioni.
Passiamo quindi alla parte di ingest.
Esegui il comando:
Puoi confermare l'import nella UI di MongoDB Atlas:
Definisci l'indice Auto-Embed
L'indice di vector search dice a MongoDB su quale campo eseguire gli embedding e specifica quale modello usare. Da lì, MongoDB genera e archivia automaticamente gli embedding.
documents_document, e assegna all'indice il nomeautoembed_index(il nome deve corrispondere aVECTOR_INDEX_NAMEnel tuo.env). Incolla questa definizione:Rivedi la definizione, quindi crea l'indice.
Query in testo semplice
Con gli auto-embeddings, usiamo lo stage
$vectorSearchcon una query in testo semplice e creiamo l'embedding della domanda con lo stesso modello usato dall'indice, quindi non c'è alcuna chiamata di embedding nel nostro codice.Per farlo, creeremo un modulo di servizio.
_get_client()crea la connessione a MongoDB una sola volta e la riutilizza.lru_cachememorizza il risultato della prima chiamata, così ogni ricerca condivide un unico client invece di aprire una nuova connessione ogni volta._get_collection()seleziona il databaseregulations_qae la collectiondocuments_document, usando le stesse impostazioni di Django._get_index_name()legge il nome dell'indice dalle impostazioni e fornisce un errore chiaro se manca.semantic_search()invia la domanda come testo nel campoquery. Il secondo stage riduce l'output ai campi necessari e aggiunge lo score di similarità.Poi aggiungiamo un helper per cercare nei documenti:
Ora, per testare, esegui:
Nell'esempio, selezioniamo domande che non condividono parole chiave con gli abstract. Una domanda su “limiti all'inquinamento delle fabbriche” dovrebbe recuperare documenti sugli standard di emissione.
NB: Su un cluster gratuito (M0) senza metodo di pagamento, le richieste di embedding delle query potrebbero essere soggette a rate limiting.
Demo: modifica un documento e guarda la ri-sincronizzazione
Per la demo, possiamo usare il
Search Testerin MongoDB Atlas, collegato all'autoembed_indexche abbiamo creato in precedenza sulla collectionregulations_qa.documents_document, oppure la shell Python.Passo 1: cerca tramite MongoDB Atlas e shell
Per testarlo nella UI di MongoDB Atlas, inserisci questa query:
Per testare via shell:
Apri la shell con
python manage.py shell, poi esegui:L'output dovrebbe corrispondere a quanto visto tramite la GUI.
Passo 2: modifica il documento
Passo 3: cerca di nuovo
Gli auto-embeddings sono generati in modo asincrono, quindi aspetta 30–60 secondi e poi esegui di nuovo la query:
Ora dovresti vedere il documento modificato posizionarsi più in alto rispetto a prima.
Esegui la stessa query nel Search Tester per vedere i risultati via GUI.
È successo che MongoDB ha rilevato la modifica al campo indicizzato e ha rigenerato l'embedding di quel documento, così il documento
2026-16515, che era il decimo nel campione, è stato classificato più in alto ed è passato alla quinta posizione dopo la modifica e la sincronizzazione.Conclusione
Complimenti per essere arrivato fin qui! Abbiamo un assistente Q&A per i documenti che usa dati in cui MongoDB gestisce il workflow degli embedding. Il tutto è stato ottenuto con questi passaggi:
NB: I dati in questo tutorial provengono dal Federal Register, che pubblica documenti del governo degli Stati Uniti. Questo tutorial è indipendente e non è affiliato né approvato dal Federal Register.
Riferimenti