Lewati ke konten utama

Membangun Asisten Q&A di Django dengan MongoDB Auto-Embeddings

Bangun pencarian semantik di Django dengan MongoDB auto-embeddings: tanpa kode embedding, sinkronisasi ulang otomatis saat dokumen berubah, dan kueri teks biasa.
· 7 mnt Baca

Jelajahi bersama AI

Apa yang Disederhanakan oleh Auto-Embeddings

Dalam pengaturan retrieval-augmented generation (RAG) yang umum, Anda membuat embedding saat menyisipkan dokumen, membuat ulang embedding ketika konten berubah, dan melakukan embedding setiap kueri sendiri. Automated Embedding menyederhanakan proses membangun pencarian semantik, karena MongoDB Atlas menangani pembuatan, pembaruan, dan kueri embedding secara native, dan Vector Search menyimpan vektor embedding yang dihasilkan di kluster Anda.

Cara MongoDB melakukan embedding otomatis

Saat indeks pencarian vektor bertipe autoEmbed dibuat, MongoDB membuat embedding untuk field yang dipilih, menggunakan model VoyageAI, menjaganya tetap sinkron ketika ada perubahan pada dokumen, dan melakukan embedding teks kueri saat pencarian dengan model yang sama. Embedding yang dihasilkan disimpan secara asinkron di kluster MongoDB dalam basis data internal terpisah.

Dalam tutorial ini, kita akan membangun Asisten Dokumen Q&A dengan autoembeddings MongoDB. Backend Django MongoDB akan digunakan untuk mendefinisikan model dan mengimpor dokumen, MongoDB akan digunakan untuk lookup, membuat dan menyinkronkan embedding secara otomatis, dan LLM akan mengembalikan dokumen berdasarkan hasil yang diambil.

Pada akhir tutorial ini, Anda akan membangun tahap retrieval dari pipeline RAG: pencarian semantik atas dokumen Federal Register di mana auto-embeddings menangani pekerjaan embedding untuk Anda. Dokumen di-embed saat Anda menyisipkannya, di-embed ulang ketika berubah, dan kueri Anda di-embed saat waktu pencarian, semuanya tanpa menulis kode embedding.

Ada dua cara untuk mengikuti tutorial ini.

Penyiapan

Sebelum memulai, pastikan Anda memiliki:

Setelah prasyarat ini selesai, langkah berikutnya adalah membuat folder proyek Anda.

Buat proyek dan virtual environment

Buat folder kosong untuk proyek Anda dan cd ke dalamnya.

mkdir regulations_qa
cd regulations_qa

Ini adalah direktori root proyek Anda. Buat dan aktifkan virtual environment di sini, jika belum:

python -m venv .venv

Untuk mengaktifkan virtual environment di macOS atau Linux, jalankan:

source .venv/bin/activate

Di Windows, jalankan:

.venv\Scripts\activate

Instal Dependensi

Buat file requirements.txt di root proyek dengan isi berikut:

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

Kemudian instal semuanya:

pip install -r requirements.txt

Buat Proyek Django dan Aplikasi Django

Dari direktori root proyek Anda, jalankan perintah berikut untuk membuat proyek dan aplikasi Django baru. Tambahkan . di akhir perintah startproject, yang memberi tahu Django untuk memasang proyek ke direktori saat ini alih-alih membuat folder bertingkat baru.

django-admin startproject regulations_qa --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/6.0.x.zip .

Buat aplikasi documents

python manage.py startapp documents

Daftarkan aplikasi di regulations_qa/settings.py dengan menambahkannya ke 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',
]

Konfigurasikan variabel lingkungan

Buat file .env di root proyek dengan nilai Anda sendiri, dan cantumkan di .gitignore agar tidak di-commit saat Anda 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

Hapus baris SECRET_KEY = '...' yang di-hardcode dari settings.py, salin nilai yang dihasilkan Django di settings.py saat Anda menjalankan startproject dan ganti di file .env Anda. Secara bawaan nilainya di-hardcode di sana, dan kita memindahkannya ke .env agar tidak masuk version control, karena Django menggunakannya untuk menandatangani session cookie, token CSRF, dan data sensitif keamanan lainnya.

Buka regulations_qa/settings.py dan pastikan berisi semua hal berikut. Baris import dan load_dotenv() diletakkan di bagian atas. Ganti definisi SECRET_KEY dan DATABASES yang ada, dan tambahkan baris 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"),
    },
}

Buat folder untuk perintah manajemen

Berikutnya, kita membuat folder dengan file kosong __init__.py untuk perintah manajemen, karena Django hanya menemukan perintah kustom di paket management/commands/.

mkdir -p documents/management/commands documents/services && touch documents/management/__init__.py documents/management/commands/__init__.py documents/services/__init__.py

Sumber data: Dokumen Federal Register

Dalam tutorial ini, kita akan mengindeks dokumen dari Federal Register; publikasi harian pemerintah AS tentang peraturan, rancangan peraturan, dan pemberitahuan. Sumber data adalah API publik yang terdiri dari dokumen dengan judul dan ringkasan prosa pendek, yang cocok untuk pencarian semantik.

Dokumentasi API: https://www.federalregister.gov/developers/documentation/api/v1

Rekaman memiliki field seperti title, type, abstract, document_number (ID unik), publication_date, html_url, dan daftar agencies.

  • Beberapa dokumen berisi nilai null, jadi kita akan mengabaikannya.
  • Ringkasan berisi markup seperti <INF>2.5<INF> dalam “PM2.5”, jadi kita hapus tag sebelum menyimpan.
  • Hasil dipaginasi hingga 100 per permintaan, dan setiap halaman menyertakan next_page_url (berbasis kursor) untuk diikuti.

Uji endpoint melalui shell

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

Catatan: Ini adalah data publik pemerintah AS yang digunakan untuk demonstrasi. Ini bukan sumber hukum; untuk riset hukum, gunakan edisi resmi.

Impor Data

Kita akan mulai dengan membuat model di 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]}"

Selanjutnya, kita membuat dan menjalankan migrasi.

python manage.py makemigrations documents
python manage.py migrate

Berikutnya, mari beralih ke bagian impor.

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

Jalankan perintah:

python manage.py ingest_federal_register --limit 100

Anda dapat mengonfirmasi impor di UI MongoDB Atlas:

Penjelajah Data MongoDB Atlas menampilkan 100 dokumen Federal Register di koleksi regulations_qa.documents_document

Definisikan Indeks Auto-Embed

Indeks pencarian vektor memberi tahu MongoDB field mana yang akan dilakukan embedding dan menentukan model apa yang harus digunakan. Setelah itu, MongoDB secara otomatis membuat dan menyimpan embedding.

  1. Di UI Atlas, buka kluster Anda, masuk ke Search & Vector Search, dan klik Create Search Index.

Halaman Search & Vector Search di MongoDB Atlas dengan tombol Create Search Index

  1. Pilih Vector Search sebagai tipe pencarian dan Automated Embedding sebagai cara menyiapkan data vektor Anda.

Konfigurasi indeks Atlas dengan Vector Search dan Automated Embedding yang dipilih

  1. Pilih editor JSON, pilih basis data Anda dan koleksi documents_document, dan beri nama indeks autoembed_index (namanya harus sama dengan VECTOR_INDEX_NAME di .env Anda). Tempel definisi ini:
{
  "fields": [
    {
      "type": "autoEmbed",
      "modality": "text",
      "path": "abstract",
      "model": "voyage-4-lite"
    }
  ]
}

Editor JSON Atlas dengan definisi indeks autoEmbed untuk field abstract menggunakan voyage-4-lite

Tinjau definisinya, lalu buat indeks.

Langkah peninjauan untuk indeks pencarian vektor autoembed_index pada regulations_qa.documents_document

  1. Tunggu hingga status indeks menunjukkan siap untuk di-query, karena embedding sedang dibuat di latar belakang.

Daftar Atlas Search & Vector Search menampilkan autoembed_index dengan status READY dan queryable

Kueri dalam Teks Biasa

Untuk auto-embeddings, kita menggunakan tahap $vectorSearch dengan kueri teks biasa dan melakukan embedding pertanyaan dengan model yang sama seperti yang digunakan indeks, jadi tidak ada pemanggilan embedding dalam kode kita.

Untuk mencapainya, kita akan membuat modul layanan.

# 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() membuat koneksi ke MongoDB satu kali dan menggunakannya kembali. lru_cache mengingat hasil panggilan pertama, sehingga setiap pencarian berbagi satu klien alih-alih membuka koneksi baru setiap kali.
  • _get_collection() memilih basis data regulations_qa dan koleksi documents_document, menggunakan pengaturan yang sama dengan yang digunakan Django.
  • _get_index_name() membaca nama indeks dari settings dan memberikan error yang jelas jika tidak ada.
  • semantic_search() mengirimkan pertanyaan sebagai teks di field query. Tahap kedua memangkas output ke field yang kita perlukan dan menambahkan skor kemiripan.

Kemudian kita menambahkan helper untuk menelusuri dokumen:

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

Sekarang, untuk menguji, jalankan:

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

Pada contoh ini, kita memilih pertanyaan yang tidak berbagi kata kunci dengan ringkasan. Pertanyaan tentang “limits on pollution from factories” seharusnya mengambil dokumen tentang standar emisi.

Catatan: Pada kluster gratis (M0) tanpa metode pembayaran, permintaan embedding kueri mungkin dibatasi (rate limited).

Demo: Edit Dokumen dan Lihat Sinkronisasi Ulang

Untuk demo, kita dapat menggunakan Search Tester di MongoDB Atlas, yang terkait dengan autoembed_index yang kita buat sebelumnya pada koleksi regulations_qa.documents_document, atau menggunakan shell Python.

Atlas Search Tester untuk autoembed_index pada regulations_qa.documents_document

Langkah 1: Pencarian melalui MongoDB Atlas dan shell

Untuk menguji ini di UI MongoDB Atlas, masukkan kueri berikut:

which states need to clean up their air

Hasil Search Tester untuk kueri which states need to clean up their air, dengan skor kemiripan

Untuk menguji melalui shell:

Buka shell dengan python manage.py shell, lalu jalankan:

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 shell Django yang mencantumkan 10 hasil pencarian semantik teratas dan skornya

Output seharusnya sama seperti yang kita lihat melalui GUI.

Langkah 2: Edit dokumen

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 menambahkan sebuah kalimat ke ringkasan dokumen 2026-16515 dan menyimpannya

Langkah 3: Cari lagi

Auto-embeddings dibuat secara asinkron, jadi tunggu 30–60 detik, lalu jalankan kueri lagi:

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

Hasil pencarian setelah pengeditan, dengan dokumen 2026-16515 naik dari peringkat 10 ke 5

Sekarang, kita seharusnya melihat dokumen yang diedit berada di peringkat lebih tinggi daripada sebelumnya.

Jalankan kueri yang sama di Search Tester untuk melihat hasilnya melalui GUI.

Yang terjadi adalah MongoDB mendeteksi bahwa field yang diindeks berubah dan membuat ulang embedding dokumen tersebut, sehingga dokumen 2026-16515, yang sebelumnya merupakan dokumen ke-10 dalam sampel, naik peringkat dan ditempatkan di posisi ke-5 setelah pengeditan dan sinkronisasi.

Ringkasan

Selamat telah sampai di titik ini! Kita memiliki asisten Q&A dokumen yang menggunakan data di mana MongoDB menangani alur kerja embedding. Ini dicapai melalui langkah-langkah berikut:

  • Sisip: dokumen dimuat melalui Django ORM
  • Indeks: satu definisi indeks, dibuat di UI Atlas, menamai field dan model.
  • Kueri: pertanyaan teks biasa melalui layanan kecil tanpa menambahkan pemanggilan embedding terpisah.
  • Edit: perubahan pada field yang diindeks disinkronkan ulang tanpa skrip re-embedding.

Catatan: Data dalam tutorial ini berasal dari Federal Register, yang menerbitkan dokumen pemerintah AS. Tutorial ini independen dan tidak berafiliasi atau didukung oleh Federal Register.

Referensi

Afi Gbadago

Penulis

Afi Gbadago

Afi mengadvokasi para pengembang di MongoDB dengan fokus pada Django dan Python, membantu para engineer membangun dengan teknologi data modern melalui tutorial, presentasi, dan keterlibatan komunitas. Diakui sebagai Microsoft MVP untuk Python dan Web, ia menjadi anggota dewan Django Software Foundation dan menjabat sebagai Programme Chair untuk DjangoCon US 2025. Afi juga merupakan Regional Executor untuk Black Python Devs serta kontributor open-source aktif dan pembicara internasional.

Topik

Terkait

blogs

40 Pertanyaan Wawancara DBMS Teratas di 2026

blogs

Spaghetti Plot dan Jalur Badai

blogs

Tutorial Korelasi di R