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.
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.
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 .Didukung oleh
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',]Didukung oleh
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_indexDidukung oleh
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"),},}Didukung oleh
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__.pyDidukung oleh
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.
Selanjutnya, kita membuat dan menjalankan migrasi.
python manage.py makemigrations documents
python manage.py migrateDidukung oleh
Berikutnya, mari beralih ke bagian impor.
# 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()}")Didukung oleh
Jalankan perintah:
python manage.py ingest_federal_register --limit100Didukung oleh
Anda dapat mengonfirmasi impor di UI MongoDB Atlas:
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.
Di UI Atlas, buka kluster Anda, masuk ke Search & Vector Search, dan klik Create Search Index.
Pilih Vector Search sebagai tipe pencarian dan Automated Embedding sebagai cara menyiapkan data vektor Anda.
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"}]}Didukung oleh
Tinjau definisinya, lalu buat indeks.
Tunggu hingga status indeks menunjukkan siap untuk di-query, karena embedding sedang dibuat di latar belakang.
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.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))Didukung oleh
_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.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]}")Didukung oleh
Sekarang, untuk menguji, jalankan:
python manage.py search_docs "limits on pollution from factories"Didukung oleh
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.
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 airDidukung oleh
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 inenumerate(hits,1)))Didukung oleh
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")Didukung oleh
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 inenumerate(hits,1)))Didukung oleh
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.
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.
Kuasai pertanyaan wawancara basis data, dari konsep SQL dasar hingga skenario desain sistem tingkat lanjut. Panduan mendalam ini mencakup semua yang Anda perlukan untuk sukses di wawancara DBMS dan meraih peran berikutnya.
Temukan alasan mengapa Anda sebaiknya (tidak) menggunakan spaghetti plot untuk menyampaikan ketidakpastian jalur prediksi badai serta dampaknya terhadap interpretasi.
Dalam kursus konseptual ini (tidak memerlukan pemrograman), Anda akan mempelajari empat jenis utama basis data NoSQL dan mesin-mesin populer yang digunakan.
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
autoEmbeddibuat, MongoDB membuat embedding untuk field yang dipilih, menggunakan modelVoyageAI, 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
cdke dalamnya.Ini adalah direktori root proyek Anda. Buat dan aktifkan virtual environment di sini, jika belum:
Untuk mengaktifkan virtual environment di macOS atau Linux, jalankan:
Di Windows, jalankan:
Instal Dependensi
Buat file
requirements.txtdi root proyek dengan isi berikut:Kemudian instal semuanya:
Buat Proyek Django dan Aplikasi Django
Dari direktori root proyek Anda, jalankan perintah berikut untuk membuat proyek dan aplikasi Django baru. Tambahkan
.di akhir perintahstartproject, yang memberi tahu Django untuk memasang proyek ke direktori saat ini alih-alih membuat folder bertingkat baru.Buat aplikasi
documentsDaftarkan aplikasi di
regulations_qa/settings.pydengan menambahkannya keINSTALLED_APPS:Konfigurasikan variabel lingkungan
Buat file
.envdi root proyek dengan nilai Anda sendiri, dan cantumkan di.gitignoreagar tidak di-commit saat Anda push.Hapus baris
SECRET_KEY = '...'yang di-hardcode darisettings.py, salin nilai yang dihasilkan Django disettings.pysaat Anda menjalankanstartprojectdan ganti di file.envAnda. Secara bawaan nilainya di-hardcode di sana, dan kita memindahkannya ke.envagar tidak masuk version control, karena Django menggunakannya untuk menandatangani session cookie, token CSRF, dan data sensitif keamanan lainnya.Buka
regulations_qa/settings.pydan pastikan berisi semua hal berikut. Baris import danload_dotenv()diletakkan di bagian atas. Ganti definisiSECRET_KEYdanDATABASESyang ada, dan tambahkan barisVECTOR_INDEX_NAME:Buat folder untuk perintah manajemen
Berikutnya, kita membuat folder dengan file kosong
__init__.pyuntuk perintah manajemen, karena Django hanya menemukan perintah kustom di paketmanagement/commands/.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 daftaragencies.<INF>2.5<INF>dalam “PM2.5”, jadi kita hapus tag sebelum menyimpan.next_page_url(berbasis kursor) untuk diikuti.Uji endpoint melalui shell
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.Selanjutnya, kita membuat dan menjalankan migrasi.
Berikutnya, mari beralih ke bagian impor.
Jalankan perintah:
Anda dapat mengonfirmasi impor di UI MongoDB Atlas:
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.
documents_document, dan beri nama indeksautoembed_index(namanya harus sama denganVECTOR_INDEX_NAMEdi.envAnda). Tempel definisi ini:Tinjau definisinya, lalu buat indeks.
Kueri dalam Teks Biasa
Untuk auto-embeddings, kita menggunakan tahap
$vectorSearchdengan 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.
_get_client()membuat koneksi ke MongoDB satu kali dan menggunakannya kembali.lru_cachemengingat hasil panggilan pertama, sehingga setiap pencarian berbagi satu klien alih-alih membuka koneksi baru setiap kali._get_collection()memilih basis dataregulations_qadan koleksidocuments_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 fieldquery. Tahap kedua memangkas output ke field yang kita perlukan dan menambahkan skor kemiripan.Kemudian kita menambahkan helper untuk menelusuri dokumen:
Sekarang, untuk menguji, jalankan:
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 Testerdi MongoDB Atlas, yang terkait denganautoembed_indexyang kita buat sebelumnya pada koleksiregulations_qa.documents_document, atau menggunakan shell Python.Langkah 1: Pencarian melalui MongoDB Atlas dan shell
Untuk menguji ini di UI MongoDB Atlas, masukkan kueri berikut:
Untuk menguji melalui shell:
Buka shell dengan
python manage.py shell, lalu jalankan:Output seharusnya sama seperti yang kita lihat melalui GUI.
Langkah 2: Edit dokumen
Langkah 3: Cari lagi
Auto-embeddings dibuat secara asinkron, jadi tunggu 30–60 detik, lalu jalankan kueri lagi:
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:
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