Vai al contenuto principale

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.
· 7 min leggi

Scopri con l'IA

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

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 cd al suo interno.

mkdir regulations_qa
cd regulations_qa

Questa è la directory root del tuo progetto. Crea e attiva qui il tuo ambiente virtuale, se non l'hai già fatto:

python -m venv .venv

Per attivare l'ambiente virtuale su macOS o Linux, esegui:

source .venv/bin/activate

Su Windows, esegui:

.venv\Scripts\activate

Installa le dipendenze

Crea un file requirements.txt nella root del progetto con il seguente contenuto:

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

Poi installa tutto:

pip install -r requirements.txt

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

Crea l'app documents

python manage.py startapp documents

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',
]

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_index

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

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__.py

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

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.

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

Poi creiamo ed eseguiamo le migrazioni.

python manage.py makemigrations documents
python manage.py migrate

Passiamo quindi alla parte di ingest.

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

Esegui il comando:

python manage.py ingest_federal_register --limit 100

Puoi confermare l'import nella UI di MongoDB Atlas:

MongoDB Atlas Data Explorer che mostra 100 documenti del Federal Register nella collection regulations_qa.documents_document

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.

  1. Nell'interfaccia di Atlas, apri il tuo cluster, vai su Search & Vector Search e clicca su Create Search Index.

Pagina Search & Vector Search in MongoDB Atlas con il pulsante Create Search Index

  1. Scegli Vector Search come tipo di ricerca e Automated Embedding come modalità per impostare i tuoi dati vettoriali.

Configurazione dell'indice in Atlas con Vector Search e Automated Embedding selezionati

  1. 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"
    }
  ]
}

Editor JSON di Atlas con la definizione dell'indice autoEmbed per il campo abstract usando voyage-4-lite

Rivedi la definizione, quindi crea l'indice.

Fase di review per l'indice di vector search autoembed_index su regulations_qa.documents_document

  1. Attendi che lo stato dell'indice indichi che è pronto per le query, mentre gli embedding vengono generati in background.

Elenco Search & Vector Search in Atlas che mostra autoembed_index con stato READY e queryable

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

Ora, per testare, esegui:

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

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.

Search Tester di Atlas per autoembed_index su regulations_qa.documents_document

Passo 1: cerca tramite MongoDB Atlas e shell

Per testarlo nella UI di MongoDB Atlas, inserisci questa query:

which states need to clean up their air

Risultati del Search Tester per la query which states need to clean up their air, con punteggi di similarità

Per testare via shell:

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 in enumerate(hits, 1)))

Output della shell Django con i primi 10 risultati della ricerca semantica e i relativi punteggi

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

Shell Django che aggiunge una frase all'abstract del documento 2026-16515 e lo salva

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 in enumerate(hits, 1)))

Risultati della ricerca dopo la modifica, con il documento 2026-16515 passato dalla decima alla quinta posizione

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.

Riferimenti

Afi Gbadago

Autore

Afi Gbadago

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.

Argomenti

Correlato