Chuyển đến nội dung chính

Xây dựng Trợ lý Hỏi & Đáp trong Django với MongoDB Auto-Embeddings

Xây dựng tìm kiếm ngữ nghĩa trong Django với auto-embeddings của MongoDB: không cần mã nhúng, tự động đồng bộ lại khi tài liệu thay đổi, và truy vấn văn bản thuần.
· 7 phút đọc

Khám phá cùng AI

Những gì Auto-Embeddings đơn giản hóa

Trong một thiết lập retrieval-augmented generation (RAG) điển hình, bạn tạo embeddings khi chèn tài liệu, tạo lại khi nội dung thay đổi, và tự nhúng mọi truy vấn. Automated Embedding đơn giản hóa quy trình xây dựng tìm kiếm ngữ nghĩa, khi MongoDB Atlas xử lý việc tạo, cập nhật, truy vấn embeddings một cách bản địa, và Vector Search lưu trữ các vector embedding đã tạo trên cụm của bạn.

Cách MongoDB thực hiện nhúng tự động

Khi một chỉ mục vector kiểu autoEmbed được tạo, MongoDB sẽ tạo embeddings cho trường đã chọn, dùng mô hình VoyageAI, giữ chúng đồng bộ khi tài liệu thay đổi, và nhúng văn bản truy vấn tại thời điểm tìm kiếm bằng cùng mô hình đó. Các embeddings được tạo được lưu không đồng bộ trên cụm MongoDB trong một cơ sở dữ liệu nội bộ riêng.

Trong hướng dẫn này, chúng ta sẽ xây dựng một Trợ lý Hỏi & Đáp cho tài liệu với autoembeddings của MongoDB. Backend MongoDB cho Django sẽ được dùng để định nghĩa models và nạp tài liệu, và MongoDB sẽ được dùng để tra cứu, tự động tạo và đồng bộ embeddings, và LLM sẽ trả về tài liệu dựa trên kết quả truy xuất.

Đến cuối hướng dẫn, bạn sẽ xây dựng giai đoạn truy xuất của một pipeline RAG: một tìm kiếm ngữ nghĩa trên các tài liệu Federal Register nơi auto-embeddings xử lý công việc nhúng thay bạn. Tài liệu được nhúng khi bạn chèn, nhúng lại khi chúng thay đổi, và truy vấn của bạn được nhúng tại thời điểm tìm kiếm, tất cả mà không cần viết mã nhúng.

Có hai cách để theo dõi hướng dẫn này.

  • Tùy chọn A: Clone repo GitHub chứa mã hoàn chỉnh từ hướng dẫn này, thiết lập theo README của repo, và tự khám phá. Liên kết dự án GitHub: https://github.com/mongodb-developer/django-mongodb-regulations-qa
  • Tùy chọn B: Xây dựng dự án từ đầu bằng cách làm theo các bước dưới đây.

Thiết lập

Trước khi bắt đầu, hãy đảm bảo bạn có:

Khi đã xong các điều kiện tiên quyết này, bước tiếp theo là tạo thư mục dự án của bạn.

Tạo dự án và môi trường ảo

Tạo một thư mục trống cho dự án và cd vào đó.

mkdir regulations_qa
cd regulations_qa

Đây là thư mục gốc của dự án. Tạo và kích hoạt môi trường ảo tại đây, nếu bạn chưa làm:

python -m venv .venv

Để kích hoạt môi trường ảo trên macOS hoặc Linux, chạy:

source .venv/bin/activate

Trên Windows, chạy:

.venv\Scripts\activate

Cài đặt phụ thuộc

Tạo tệp requirements.txt ở thư mục gốc dự án với nội dung sau:

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

Sau đó cài đặt tất cả:

pip install -r requirements.txt

Tạo Dự án Django và Ứng dụng Django

Từ thư mục gốc dự án, chạy lệnh sau để tạo dự án và ứng dụng Django mới. Thêm dấu . ở cuối lệnh startproject, để Django cài dự án vào thư mục hiện tại thay vì tạo một thư mục lồng nhau mới.

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

Tạo ứng dụng documents

python manage.py startapp documents

Đăng ký ứng dụng trong regulations_qa/settings.py bằng cách thêm vào 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',
]

Cấu hình biến môi trường

Tạo tệp .env ở thư mục gốc dự án với các giá trị của riêng bạn, và liệt kê tệp này trong .gitignore để không bị commit khi bạn đẩy mã lên.

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

Xóa dòng SECRET_KEY = '...' hardcode gốc khỏi settings.py, sao chép giá trị Django đã tạo trong settings.py khi bạn chạy startproject và thay vào tệp .env của bạn. Theo mặc định giá trị đó được hardcode, và chúng ta chuyển nó vào .env để tránh đưa vào hệ thống quản lý phiên bản, vì Django dùng nó để ký cookie phiên, token CSRF, và các dữ liệu nhạy cảm khác.

Mở regulations_qa/settings.py và đảm bảo có đầy đủ những nội dung sau. Các dòng import và load_dotenv() đặt ở đầu. Thay thế các định nghĩa SECRET_KEY và DATABASES hiện có, và thêm dòng 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"),
    },
}

Tạo thư mục cho các lệnh quản trị

Tiếp theo, chúng ta tạo các thư mục với tệp __init__.py rỗng cho các lệnh quản trị, vì Django chỉ phát hiện lệnh tùy chỉnh trong package management/commands/.

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

Nguồn dữ liệu: Các tài liệu Federal Register

Trong hướng dẫn này, chúng ta sẽ lập chỉ mục các tài liệu từ Federal Register; ấn phẩm hàng ngày của chính phủ Hoa Kỳ về các quy định, quy định đề xuất và thông báo. Nguồn dữ liệu là một API công khai gồm các tài liệu có tiêu đề và phần tóm tắt ngắn bằng văn xuôi, rất phù hợp với tìm kiếm ngữ nghĩa.

Tài liệu API: https://www.federalregister.gov/developers/documentation/api/v1

Bản ghi có các trường như title, type, abstract, document_number (ID duy nhất), publication_date, html_url, và danh sách agencies.

  • Một số tài liệu có giá trị null, nên chúng ta sẽ bỏ qua.
  • Phần tóm tắt có chứa markup như <INF>2.5</INF> trong “PM2.5”, nên chúng ta loại bỏ thẻ trước khi lưu.
  • Kết quả được phân trang tối đa 100 mỗi yêu cầu, và mỗi trang có next_page_url (dựa trên cursor) để theo tiếp.

Thử endpoint qua shell

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

Lưu ý: Đây là dữ liệu công khai của chính phủ Hoa Kỳ dùng cho mục đích minh họa. Đây không phải nguồn pháp lý; để nghiên cứu pháp lý, hãy dùng ấn bản chính thức.

Nạp dữ liệu

Chúng ta sẽ bắt đầu bằng cách tạo các model trong tệp 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]}"

Tiếp theo, chúng ta tạo và chạy migration.

python manage.py makemigrations documents
python manage.py migrate

Tiếp theo, chuyển sang phần nạp dữ liệu.

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

Chạy lệnh:

python manage.py ingest_federal_register --limit 100

Bạn có thể xác nhận việc nhập dữ liệu trong giao diện MongoDB Atlas:

Trình khám phá dữ liệu MongoDB Atlas hiển thị 100 tài liệu Federal Register trong collection regulations_qa.documents_document

Định nghĩa Chỉ mục Auto-Embed

Chỉ mục vector search cho MongoDB biết trường nào sẽ thực hiện nhúng và chỉ định mô hình sẽ dùng. Sau đó, MongoDB sẽ tự động tạo và lưu trữ các embeddings.

  1. Trong Atlas UI, mở cụm của bạn, vào Search & Vector Search, và nhấp Create Search Index.

Trang Search & Vector Search trong MongoDB Atlas với nút Create Search Index

  1. Chọn Vector Search làm loại tìm kiếm và Automated Embedding làm cách thiết lập dữ liệu vector của bạn.

Cấu hình chỉ mục Atlas với Vector Search và Automated Embedding được chọn

  1. Chọn trình soạn thảo JSON, chọn cơ sở dữ liệu của bạn và collection documents_document, và đặt tên chỉ mục là autoembed_index (tên này phải khớp với VECTOR_INDEX_NAME trong tệp .env). Dán định nghĩa sau:
{
  "fields": [
    {
      "type": "autoEmbed",
      "modality": "text",
      "path": "abstract",
      "model": "voyage-4-lite"
    }
  ]
}

Trình soạn JSON của Atlas với định nghĩa chỉ mục autoEmbed cho trường abstract dùng voyage-4-lite

Rà soát định nghĩa, sau đó tạo chỉ mục.

Bước Review cho chỉ mục vector search autoembed_index trên regulations_qa.documents_document

  1. Chờ đến khi trạng thái chỉ mục hiển thị sẵn sàng truy vấn, vì embeddings đang được tạo ở nền.

Danh sách Atlas Search & Vector Search hiển thị autoembed_index với trạng thái READY và có thể truy vấn

Truy vấn bằng văn bản thuần

Với auto-embeddings, chúng ta dùng stage $vectorSearch với truy vấn văn bản thuần và nhúng câu hỏi bằng cùng mô hình mà chỉ mục dùng, nên không có lời gọi nhúng nào trong mã của chúng ta.

Để thực hiện điều này, chúng ta sẽ tạo một module service.

# 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() tạo kết nối đến MongoDB một lần và tái sử dụng. lru_cache ghi nhớ kết quả của lần gọi đầu, vì vậy mọi tìm kiếm dùng chung một client thay vì mở kết nối mới mỗi lần.
  • _get_collection() chọn cơ sở dữ liệu regulations_qa và collection documents_document, dùng cùng cấu hình mà Django đang dùng.
  • _get_index_name() đọc tên chỉ mục từ settings và đưa ra lỗi rõ ràng nếu thiếu.
  • semantic_search() gửi câu hỏi dạng văn bản trong trường query. Stage thứ hai cắt tỉa kết quả về các trường cần thiết và thêm điểm tương đồng.

Sau đó thêm một helper để tìm kiếm tài liệu:

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

Bây giờ, để kiểm thử, chạy:

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

Trong ví dụ, chúng ta chọn các câu hỏi không chia sẻ từ khóa với phần tóm tắt. Một câu hỏi về “limits on pollution from factories” sẽ truy xuất các tài liệu về tiêu chuẩn phát thải.

Lưu ý: Trên cụm miễn phí (M0) không có phương thức thanh toán, các yêu cầu nhúng truy vấn có thể bị giới hạn tốc độ.

Demo: Chỉnh sửa tài liệu và xem đồng bộ lại

Cho phần demo, chúng ta có thể dùng Search Tester trong MongoDB Atlas, gắn với autoembed_index đã tạo trước đó trên collection regulations_qa.documents_document, hoặc dùng Python shell.

Atlas Search Tester cho autoembed_index trên regulations_qa.documents_document

Bước 1: Tìm kiếm qua MongoDB Atlas và shell

Để thử trong giao diện MongoDB Atlas, nhập truy vấn này:

which states need to clean up their air

Kết quả Search Tester cho truy vấn which states need to clean up their air, kèm điểm tương đồng

Để thử qua shell:

Mở shell với python manage.py shell, sau đó chạy:

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

Kết quả đầu ra Django shell liệt kê 10 kết quả tìm kiếm ngữ nghĩa hàng đầu và điểm số

Kết quả đầu ra sẽ giống như những gì ta thấy qua giao diện.

Bước 2: Chỉnh sửa tài liệu

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

Django shell nối thêm một câu vào phần tóm tắt của tài liệu 2026-16515 và lưu lại

Bước 3: Tìm kiếm lại

Auto-embeddings được tạo không đồng bộ, nên chờ 30–60 giây, rồi chạy lại truy vấn:

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

Kết quả tìm kiếm sau khi chỉnh sửa, với tài liệu 2026-16515 chuyển từ hạng 10 lên hạng 5

Bây giờ, chúng ta kỳ vọng thấy tài liệu đã chỉnh sửa xếp hạng cao hơn trước.

Chạy cùng truy vấn trong Search Tester để xem kết quả qua giao diện.

Điều đã xảy ra là MongoDB nhận thấy trường đã lập chỉ mục thay đổi và tạo lại embedding cho tài liệu đó, nên tài liệu 2026-16515, vốn đứng thứ 10 trong mẫu, đã được xếp hạng cao hơn và ở vị trí thứ 5 sau khi chỉnh sửa và đồng bộ.

Tổng kết

Chúc mừng bạn đã hoàn thành đến đây! Chúng ta đã có một trợ lý Hỏi & Đáp cho tài liệu sử dụng dữ liệu mà MongoDB xử lý quy trình embedding. Điều này đạt được qua các bước sau:

  • Chèn: tài liệu được nạp qua Django ORM
  • Chỉ mục: một định nghĩa chỉ mục, tạo trong Atlas UI, chỉ định trường và mô hình.
  • Truy vấn: câu hỏi văn bản thuần qua một service nhỏ mà không cần thêm lời gọi nhúng riêng.
  • Chỉnh sửa: thay đổi ở trường đã lập chỉ mục được đồng bộ lại mà không cần script nhúng lại.

Lưu ý: Dữ liệu trong hướng dẫn này đến từ Federal Register, nơi xuất bản các tài liệu của chính phủ Hoa Kỳ. Hướng dẫn này độc lập và không được Federal Register bảo trợ hay chứng thực.

Tài liệu tham khảo

Afi Gbadago

Tác giả

Afi Gbadago

Afi vận động cho các nhà phát triển tại MongoDB với trọng tâm là Django và Python, hỗ trợ kỹ sư xây dựng cùng các công nghệ dữ liệu hiện đại thông qua hướng dẫn, bài nói chuyện và hoạt động cộng đồng. Là Microsoft MVP được công nhận cho Python và Web, cô phục vụ trong ban quản trị Django Software Foundation và là Trưởng ban Chương trình của DjangoCon US 2025. Afi cũng là Điều phối viên Khu vực của Black Python Devs, đồng thời là người đóng góp mã nguồn mở năng động và diễn giả quốc tế.

Chủ đề

Liên quan