Przejdź do głównej treści

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

Odkryj z AI

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

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.

mkdir regulations_qa
cd regulations_qa

To katalog główny twojego projektu. Utwórz i aktywuj tu wirtualne środowisko, jeśli jeszcze tego nie zrobiłeś:

python -m venv .venv

Aby aktywować środowisko w macOS lub Linux, uruchom:

source .venv/bin/activate

W systemie Windows uruchom:

.venv\Scripts\activate

Zainstaluj zależności

Utwórz plik requirements.txt w katalogu głównym projektu z następującą zawartością:

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

Następnie zainstaluj wszystko:

pip install -r requirements.txt

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

Utwórz aplikację documents

python manage.py startapp documents

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

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_index

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

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

Ź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_url oraz listę agencies.

  • Niektóre dokumenty zawierają wartości null, więc je pominiemy.
  • Abstrakty zawierają znaczniki jak <INF>2.5<INF> w „PM2.5”, dlatego przed zapisem usuwamy tagi.
  • Wyniki są stronicowane do 100 na żądanie, a każda strona zawiera next_page_url (na kursorze) do śledzenia.

Przetestuj endpoint przez shell

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

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.

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

Następnie tworzymy i uruchamiamy migracje.

python manage.py makemigrations documents
python manage.py migrate

Teraz przejdźmy do części związanej z ładowaniem.

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

Uruchom polecenie:

python manage.py ingest_federal_register --limit 100

Import możesz potwierdzić w interfejsie MongoDB Atlas:

MongoDB Atlas Data Explorer pokazujący 100 dokumentów Federal Register w kolekcji regulations_qa.documents_document

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.

  1. W interfejsie Atlas otwórz swój klaster, przejdź do Search & Vector Search i kliknij Create Search Index.

Strona Search & Vector Search w MongoDB Atlas z przyciskiem Create Search Index

  1. Wybierz Vector Search jako typ wyszukiwania i Automated Embedding jako sposób przygotowania danych wektorowych.

Konfiguracja indeksu w Atlas z wybranymi Vector Search i Automated Embedding

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

Edytor JSON w Atlas z definicją indeksu autoEmbed dla pola abstract z użyciem voyage-4-lite

Przejrzyj definicję, a następnie utwórz indeks.

Krok przeglądu dla indeksu wyszukiwania wektorowego autoembed_index w regulations_qa.documents_document

  1. Poczekaj, aż status indeksu pokaże gotowość do zapytań — w tle generowane są osadzenia.

Lista Atlas Search & Vector Search pokazująca autoembed_index ze statusem READY i queryable

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

Teraz, aby przetestować, uruchom:

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

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.

Atlas Search Tester dla autoembed_index na regulations_qa.documents_document

Krok 1: Wyszukiwanie przez MongoDB Atlas i shell

Aby przetestować to w interfejsie MongoDB Atlas, wpisz to zapytanie:

which states need to clean up their air

Wyniki Search Tester dla zapytania which states need to clean up their air, z wynikami podobieństwa

Aby przetestować przez shell:

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

Wyjście powłoki Django z listą 10 najlepszych wyników wyszukiwania semantycznego i ich wynikami

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

Powłoka Django dopisująca zdanie do abstraktu dokumentu 2026-16515 i zapisująca go

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

Wyniki wyszukiwania po edycji, z dokumentem 2026-16515 przesuniętym z 10. na 5. miejsce

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.

Materiały

Tematy