Budowa asystenta Q&A w Django z autoosadzaniem wektorów MongoDB
Zbuduj wyszukiwanie semantyczne w Django z auto-embeddingami MongoDB: bez kodu embeddingu, automatyczna ponowna synchronizacja po zmianie dokumentów i zapytania w zwykłym tekście.
W typowej konfiguracji RAG (retrieval-augmented generation) generujesz wektory osadzeń przy wstawianiu dokumentu, regenerujesz je po zmianie treści i sam osadzasz każde zapytanie. Automated Embedding upraszcza budowę wyszukiwania semantycznego, ponieważ MongoDB Atlas natywnie obsługuje generowanie, aktualizowanie i zapytania embeddingów, a Vector Search przechowuje wygenerowane wektorowe osadzenia w twoim klastrze.
Jak MongoDB wykonuje automatyczne osadzanie
Gdy utworzysz indeks wyszukiwania wektorowego typu autoEmbed, MongoDB generuje osadzenia dla wybranego pola, używa modelu VoyageAI, utrzymuje je w synchronizacji przy zmianach dokumentu oraz osadza tekst zapytania w czasie wyszukiwania tym samym modelem. Wygenerowane osadzenia są asynchronicznie przechowywane na klastrze MongoDB w osobnej wewnętrznej bazie danych.
W tym samouczku zbudujemy asystenta Q&A do dokumentów z auto-embeddingami MongoDB. Backend Django MongoDB posłuży do zdefiniowania modeli i załadowania dokumentów, MongoDB zajmie się wyszukiwaniem, automatycznym generowaniem i synchronizacją osadzeń, a LLM zwróci dokumenty na podstawie wyników pobrania.
Pod koniec tego samouczka zbudujesz etap pobierania w potoku RAG: wyszukiwanie semantyczne w dokumentach Federal Register, w którym auto-embeddingi wykonują za ciebie całą pracę z osadzaniem. Dokumenty są osadzane przy wstawianiu, ponownie osadzane przy zmianach, a twoje zapytania są osadzane w czasie wyszukiwania — wszystko bez pisania kodu embeddingu.
Z katalogu głównego projektu uruchom poniższe polecenie, aby utworzyć nowy projekt i aplikację Django. Dodaj kończący . w poleceniu startproject, co mówi Django, by zainstalował projekt w bieżącym katalogu zamiast tworzyć nowy, zagnieżdżony folder.
django-admin startproject regulations_qa --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/6.0.x.zip .Obsługiwane przez
Zarejestruj aplikację w regulations_qa/settings.py, dodając ją do 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',]Obsługiwane przez
Skonfiguruj zmienne środowiskowe
Utwórz plik .env w katalogu głównym projektu z własnymi wartościami i dodaj go do .gitignore, aby nie został zacommitowany przy wysyłce.
# .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_indexObsługiwane przez
Usuń oryginalną, zahardkodowaną linię SECRET_KEY = '...' z settings.py, skopiuj wartość wygenerowaną przez Django w settings.py przy uruchamianiu startproject i wstaw ją do pliku .env. Domyślnie jest zahardkodowana, a my przenosimy ją do .env, aby trzymać ją poza kontrolą wersji, ponieważ Django używa jej do podpisywania cookies sesyjnych, tokenów CSRF i innych danych wrażliwych dla bezpieczeństwa.
Otwórz regulations_qa/settings.py i upewnij się, że zawiera wszystko z poniższego. Linie importu i load_dotenv() daj na górze. Zastąp istniejące definicje SECRET_KEY i DATABASES oraz dodaj linię 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"),},}Obsługiwane przez
Utwórz foldery dla poleceń zarządzania
Następnie tworzymy foldery z pustymi plikami __init__.py dla poleceń zarządzania, ponieważ Django wykrywa własne polecenia tylko w pakiecie management/commands/.
mkdir-p documents/management/commands documents/services &&touch documents/management/__init__.py documents/management/commands/__init__.py documents/services/__init__.pyObsługiwane przez
Źródło danych: dokumenty Federal Register
W tym samouczku zindeksujemy dokumenty z Federal Register — codziennych publikacji rządu USA zawierających reguły, projekty reguł i zawiadomienia. Źródłem danych jest publiczne API z dokumentami, które mają tytuł i krótki abstrakt w formie prozy, co dobrze współgra z wyszukiwaniem semantycznym.
python manage.py makemigrations documents
python manage.py migrateObsługiwane przez
Teraz przejdźmy do części związanej z ładowaniem.
# 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()}")Obsługiwane przez
Uruchom polecenie:
python manage.py ingest_federal_register --limit100Obsługiwane przez
Import możesz potwierdzić w interfejsie MongoDB Atlas:
Zdefiniuj indeks auto-embed
Indeks wyszukiwania wektorowego mówi MongoDB, na którym polu wykonywać osadzanie i jaki model ma zostać użyty. Po tym MongoDB automatycznie generuje i przechowuje osadzenia.
W interfejsie Atlas otwórz swój klaster, przejdź do Search & Vector Search i kliknij Create Search Index.
Wybierz Vector Search jako typ wyszukiwania i Automated Embedding jako sposób przygotowania danych wektorowych.
Wybierz edytor JSON, zaznacz swoją bazę danych i kolekcję documents_document oraz nazwij indeks autoembed_index (nazwa musi odpowiadać VECTOR_INDEX_NAME w twoim .env). Wklej tę definicję:
{"fields":[{"type":"autoEmbed","modality":"text","path":"abstract","model":"voyage-4-lite"}]}Obsługiwane przez
Przejrzyj definicję, a następnie utwórz indeks.
Poczekaj, aż status indeksu pokaże gotowość do zapytań — w tle generowane są osadzenia.
Zapytania zwykłym tekstem
W przypadku auto-embeddingów używamy etapu $vectorSearch z zapytaniem w zwykłym tekście i osadzamy pytanie tym samym modelem, którego używa indeks, więc w naszym kodzie nie ma wywołania embeddingu.
Aby to osiągnąć, stworzymy moduł serwisowy.
# 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))Obsługiwane przez
_get_client() tworzy połączenie z MongoDB raz i je ponownie wykorzystuje. lru_cache zapamiętuje wynik pierwszego wywołania, więc każde wyszukiwanie współdzieli jednego klienta zamiast otwierać nowe połączenie za każdym razem.
_get_collection() wybiera bazę regulations_qa i kolekcję documents_document, używając tych samych ustawień co Django.
_get_index_name() odczytuje nazwę indeksu z ustawień i zgłasza czytelny błąd, jeśli jej brakuje.
semantic_search() wysyła pytanie jako tekst w polu query. Drugi etap przycina wynik do potrzebnych pól i dodaje wynik podobieństwa.
Następnie dodajemy pomocnicze polecenie do przeszukiwania dokumentów:
# 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]}")Obsługiwane przez
Teraz, aby przetestować, uruchom:
python manage.py search_docs "limits on pollution from factories"Obsługiwane przez
W przykładzie wybieramy pytania, które nie dzielą słów kluczowych z abstraktami. Pytanie o „limits on pollution from factories” powinno zwrócić dokumenty o standardach emisji.
Uwaga: Na darmowym klastrze (M0) bez metody płatności żądania osadzania zapytań mogą być ograniczane.
Demo: Edytuj dokument i zobacz ponowną synchronizację
Do dema możemy użyć Search Tester w MongoDB Atlas, który jest powiązany z utworzonym wcześniej autoembed_index na kolekcji regulations_qa.documents_document, lub powłoki Pythona.
Krok 1: Wyszukiwanie przez MongoDB Atlas i shell
Aby przetestować to w interfejsie MongoDB Atlas, wpisz to zapytanie:
Otwórz powłokę poleceniem python manage.py shell, a następnie uruchom:
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)))Obsługiwane przez
Wynik powinien być taki sam jak ten, który widzieliśmy w GUI.
Krok 2: Edytuj dokument
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")Obsługiwane przez
Krok 3: Wyszukaj ponownie
Auto-embeddingi są generowane asynchronicznie, więc poczekaj 30–60 sekund, a następnie uruchom ponownie zapytanie:
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)))Obsługiwane przez
Teraz powinniśmy zobaczyć, że edytowany dokument plasuje się wyżej niż wcześniej.
Uruchom to samo zapytanie w Search Tester, aby zobaczyć wyniki w GUI.
Stało się tak, ponieważ MongoDB zauważył, że zindeksowane pole się zmieniło, i zregenerował embedding tego dokumentu, więc dokument 2026-16515, który był 10. w próbce, po edycji i synchronizacji został oceniony wyżej i znalazł się na 5. pozycji.
Podsumowanie
Gratulacje, że dotarłeś do tego miejsca! Mamy asystenta Q&A do dokumentów, w którym MongoDB obsługuje przepływ pracy związany z embeddingami. Osiągnęliśmy to w następujących krokach:
Wstawianie: dokumenty załadowane przez ORM Django
Indeks: jedna definicja indeksu utworzona w interfejsie Atlas, wskazująca pole i model.
Zapytanie: pytania w zwykłym tekście poprzez mały serwis, bez dodawania osobnego wywołania embeddingu.
Edycja: zmiany w zindeksowanym polu są synchronizowane bez skryptu ponownego osadzania.
Uwaga: Dane w tym samouczku pochodzą z Federal Register, który publikuje dokumenty rządu USA. Ten samouczek jest niezależny i nie jest powiązany ani wspierany przez Federal Register.
Co upraszczają auto-embeddingi
W typowej konfiguracji RAG (retrieval-augmented generation) generujesz wektory osadzeń przy wstawianiu dokumentu, regenerujesz je po zmianie treści i sam osadzasz każde zapytanie. Automated Embedding upraszcza budowę wyszukiwania semantycznego, ponieważ MongoDB Atlas natywnie obsługuje generowanie, aktualizowanie i zapytania embeddingów, a Vector Search przechowuje wygenerowane wektorowe osadzenia w twoim klastrze.
Jak MongoDB wykonuje automatyczne osadzanie
Gdy utworzysz indeks wyszukiwania wektorowego typu
autoEmbed, MongoDB generuje osadzenia dla wybranego pola, używa modeluVoyageAI, utrzymuje je w synchronizacji przy zmianach dokumentu oraz osadza tekst zapytania w czasie wyszukiwania tym samym modelem. Wygenerowane osadzenia są asynchronicznie przechowywane na klastrze MongoDB w osobnej wewnętrznej bazie danych.W tym samouczku zbudujemy asystenta Q&A do dokumentów z auto-embeddingami MongoDB. Backend Django MongoDB posłuży do zdefiniowania modeli i załadowania dokumentów, MongoDB zajmie się wyszukiwaniem, automatycznym generowaniem i synchronizacją osadzeń, a LLM zwróci dokumenty na podstawie wyników pobrania.
Pod koniec tego samouczka zbudujesz etap pobierania w potoku RAG: wyszukiwanie semantyczne w dokumentach Federal Register, w którym auto-embeddingi wykonują za ciebie całą pracę z osadzaniem. Dokumenty są osadzane przy wstawianiu, ponownie osadzane przy zmianach, a twoje zapytania są osadzane w czasie wyszukiwania — wszystko bez pisania kodu embeddingu.
Masz dwa sposoby, by przerobić ten samouczek.
Konfiguracja
Zanim zaczniesz, upewnij się, że masz:
Gdy spełnisz te wymagania wstępne, kolejnym krokiem jest utworzenie folderu projektu.
Utwórz projekt i wirtualne środowisko
Utwórz pusty folder dla projektu i przejdź do niego poleceniem
cd.To katalog główny twojego projektu. Utwórz i aktywuj tu wirtualne środowisko, jeśli jeszcze tego nie zrobiłeś:
Aby aktywować środowisko w macOS lub Linux, uruchom:
W systemie Windows uruchom:
Zainstaluj zależności
Utwórz plik
requirements.txtw katalogu głównym projektu z następującą zawartością:Następnie zainstaluj wszystko:
Utwórz projekt Django i aplikację Django
Z katalogu głównego projektu uruchom poniższe polecenie, aby utworzyć nowy projekt i aplikację Django. Dodaj kończący
.w poleceniustartproject, co mówi Django, by zainstalował projekt w bieżącym katalogu zamiast tworzyć nowy, zagnieżdżony folder.Utwórz aplikację
documentsZarejestruj aplikację w
regulations_qa/settings.py, dodając ją doINSTALLED_APPS:Skonfiguruj zmienne środowiskowe
Utwórz plik
.envw katalogu głównym projektu z własnymi wartościami i dodaj go do.gitignore, aby nie został zacommitowany przy wysyłce.Usuń oryginalną, zahardkodowaną linię
SECRET_KEY = '...'zsettings.py, skopiuj wartość wygenerowaną przez Django wsettings.pyprzy uruchamianiustartprojecti wstaw ją do pliku.env. Domyślnie jest zahardkodowana, a my przenosimy ją do.env, aby trzymać ją poza kontrolą wersji, ponieważ Django używa jej do podpisywania cookies sesyjnych, tokenów CSRF i innych danych wrażliwych dla bezpieczeństwa.Otwórz
regulations_qa/settings.pyi upewnij się, że zawiera wszystko z poniższego. Linie importu iload_dotenv()daj na górze. Zastąp istniejące definicjeSECRET_KEYiDATABASESoraz dodaj linięVECTOR_INDEX_NAME:Utwórz foldery dla poleceń zarządzania
Następnie tworzymy foldery z pustymi plikami
__init__.pydla poleceń zarządzania, ponieważ Django wykrywa własne polecenia tylko w pakieciemanagement/commands/.Źródło danych: dokumenty Federal Register
W tym samouczku zindeksujemy dokumenty z Federal Register — codziennych publikacji rządu USA zawierających reguły, projekty reguł i zawiadomienia. Źródłem danych jest publiczne API z dokumentami, które mają tytuł i krótki abstrakt w formie prozy, co dobrze współgra z wyszukiwaniem semantycznym.
Dokumentacja API: https://www.federalregister.gov/developers/documentation/api/v1
Rekordy mają pola takie jak
title,type,abstract,document_number(unikalne ID),publication_date,html_urloraz listęagencies.<INF>2.5<INF>w „PM2.5”, dlatego przed zapisem usuwamy tagi.next_page_url(na kursorze) do śledzenia.Przetestuj endpoint przez shell
Uwaga: To publiczne dane rządu USA użyte do demonstracji. Nie jest to źródło prawne; do badań prawniczych używaj oficjalnego wydania.
Załaduj dane
Zaczniemy od utworzenia modeli w pliku
models.py.Następnie tworzymy i uruchamiamy migracje.
Teraz przejdźmy do części związanej z ładowaniem.
Uruchom polecenie:
Import możesz potwierdzić w interfejsie MongoDB Atlas:
Zdefiniuj indeks auto-embed
Indeks wyszukiwania wektorowego mówi MongoDB, na którym polu wykonywać osadzanie i jaki model ma zostać użyty. Po tym MongoDB automatycznie generuje i przechowuje osadzenia.
documents_documentoraz nazwij indeksautoembed_index(nazwa musi odpowiadaćVECTOR_INDEX_NAMEw twoim.env). Wklej tę definicję:Przejrzyj definicję, a następnie utwórz indeks.
Zapytania zwykłym tekstem
W przypadku auto-embeddingów używamy etapu
$vectorSearchz zapytaniem w zwykłym tekście i osadzamy pytanie tym samym modelem, którego używa indeks, więc w naszym kodzie nie ma wywołania embeddingu.Aby to osiągnąć, stworzymy moduł serwisowy.
_get_client()tworzy połączenie z MongoDB raz i je ponownie wykorzystuje.lru_cachezapamiętuje wynik pierwszego wywołania, więc każde wyszukiwanie współdzieli jednego klienta zamiast otwierać nowe połączenie za każdym razem._get_collection()wybiera bazęregulations_qai kolekcjędocuments_document, używając tych samych ustawień co Django._get_index_name()odczytuje nazwę indeksu z ustawień i zgłasza czytelny błąd, jeśli jej brakuje.semantic_search()wysyła pytanie jako tekst w poluquery. Drugi etap przycina wynik do potrzebnych pól i dodaje wynik podobieństwa.Następnie dodajemy pomocnicze polecenie do przeszukiwania dokumentów:
Teraz, aby przetestować, uruchom:
W przykładzie wybieramy pytania, które nie dzielą słów kluczowych z abstraktami. Pytanie o „limits on pollution from factories” powinno zwrócić dokumenty o standardach emisji.
Uwaga: Na darmowym klastrze (M0) bez metody płatności żądania osadzania zapytań mogą być ograniczane.
Demo: Edytuj dokument i zobacz ponowną synchronizację
Do dema możemy użyć
Search Testerw MongoDB Atlas, który jest powiązany z utworzonym wcześniejautoembed_indexna kolekcjiregulations_qa.documents_document, lub powłoki Pythona.Krok 1: Wyszukiwanie przez MongoDB Atlas i shell
Aby przetestować to w interfejsie MongoDB Atlas, wpisz to zapytanie:
Aby przetestować przez shell:
Otwórz powłokę poleceniem
python manage.py shell, a następnie uruchom:Wynik powinien być taki sam jak ten, który widzieliśmy w GUI.
Krok 2: Edytuj dokument
Krok 3: Wyszukaj ponownie
Auto-embeddingi są generowane asynchronicznie, więc poczekaj 30–60 sekund, a następnie uruchom ponownie zapytanie:
Teraz powinniśmy zobaczyć, że edytowany dokument plasuje się wyżej niż wcześniej.
Uruchom to samo zapytanie w Search Tester, aby zobaczyć wyniki w GUI.
Stało się tak, ponieważ MongoDB zauważył, że zindeksowane pole się zmieniło, i zregenerował embedding tego dokumentu, więc dokument
2026-16515, który był 10. w próbce, po edycji i synchronizacji został oceniony wyżej i znalazł się na 5. pozycji.Podsumowanie
Gratulacje, że dotarłeś do tego miejsca! Mamy asystenta Q&A do dokumentów, w którym MongoDB obsługuje przepływ pracy związany z embeddingami. Osiągnęliśmy to w następujących krokach:
Uwaga: Dane w tym samouczku pochodzą z Federal Register, który publikuje dokumenty rządu USA. Ten samouczek jest niezależny i nie jest powiązany ani wspierany przez Federal Register.
Materiały