跳至主要内容

在 Django 中构建基于 MongoDB 自动嵌入的问答助手

在 Django 中构建语义搜索,使用 MongoDB 自动嵌入:无需嵌入代码,文档变更自动重新同步,查询使用纯文本。
· 7分钟 阅读

使用 AI 探索

自动嵌入能简化什么

在典型的检索增强生成(RAG)方案中,您需要在插入文档时生成嵌入,在内容变更时重新生成嵌入,并为每次查询自行生成嵌入。自动嵌入让构建语义搜索的流程更简单:MongoDB Atlas 原生负责嵌入的生成、更新和查询,向量搜索会在集群中存储生成的向量嵌入。

MongoDB 如何进行自动嵌入

当创建类型为 autoEmbed 的向量搜索索引时,MongoDB 会为选定字段生成嵌入,使用 VoyageAI 模型,在文档发生变更时保持嵌入同步,并在搜索时用同一个模型对查询文本进行嵌入。生成的嵌入会异步存储在 MongoDB 集群的一个内部数据库中。

在本教程中,我们将使用 MongoDB 自动嵌入构建一个文档问答助手。我们将使用 Django MongoDB 后端定义模型并导入文档,由 MongoDB 负责查找、自动生成和同步嵌入,LLM 将基于检索结果返回文档。

完成本教程后,您将构建一个 RAG 流水线中的检索阶段:针对《联邦公报》文档的语义搜索,由自动嵌入为您处理嵌入工作。文档在插入时嵌入,变更时重新嵌入,查询在搜索时自动嵌入,整个过程无需编写任何嵌入代码。

有两种方式跟进本教程。

环境准备

在开始之前,请确认您已具备:

完成以上先决条件后,下一步是创建您的项目文件夹。

创建项目与虚拟环境

为项目创建一个空文件夹,并 cd 进入其中。

mkdir regulations_qa
cd regulations_qa

这是项目的根目录。如果尚未创建,请在此创建并激活虚拟环境:

python -m venv .venv

在 macOS 或 Linux 上激活虚拟环境:

source .venv/bin/activate

在 Windows 上运行:

.venv\Scripts\activate

安装依赖

在项目根目录创建一个 requirements.txt 文件,内容如下:

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

然后安装所有依赖:

pip install -r requirements.txt

创建 Django 项目与应用

在项目根目录运行以下命令以创建新的 Django 项目与应用。在 startproject 命令中添加末尾的 .,表示将项目安装到当前目录,而不是创建一个嵌套文件夹。

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

创建 documents 应用

python manage.py startapp documents

在 regulations_qa/settings.py 中注册该应用,将其添加到 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',
]

配置环境变量

在项目根目录创建 .env 文件并填入您自己的值,同时将其加入 .gitignore,以避免在推送时被提交。

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

从 settings.py 中删除原有的硬编码 SECRET_KEY = '...' 行,复制您在运行 startproject 时 settings.py 里生成的值,替换到 .env 文件中。默认情况下它被硬编码,我们将其移至 .env,以避免进入版本控制,因为 Django 会使用它签署会话 Cookie、CSRF 令牌等安全敏感数据。

打开 regulations_qa/settings.py 并确保包含以下所有内容。导入行与 load_dotenv() 放在顶部。用下方代码替换现有的 SECRET_KEY 与 DATABASES 定义,并新增 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"),
    },
}

为管理命令创建文件夹

接下来,我们创建带空 __init__.py 的文件夹用于管理命令,因为 Django 只会在 management/commands/ 包中发现自定义命令。

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

数据来源:《联邦公报》文档

在本教程中,我们将索引《联邦公报》的文档;这是美国政府关于规则、拟议规则和公告的每日发布。数据来源是一个公共 API,文档包含标题与简短的文字摘要,非常适合语义搜索。

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

记录包含诸如 title、type、abstract、document_number(唯一 ID)、publication_date、html_url 和 agencies 列表等字段。

  • 部分文档包含空值,我们将跳过这些记录。
  • 摘要包含如 “PM2.5” 中的 <INF>2.5</INF> 等标记,因此在保存前需要去除标签。
  • 结果按页返回,每次请求最多 100 条,每页包含一个可跟随的 next_page_url(基于游标)。

通过命令行测试端点

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

注意:这是用于演示的美国政府公共数据。它不是法律来源;若进行法律研究,请使用官方版本。

导入数据

我们将先在 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]}"

接下来,创建并运行迁移。

python manage.py makemigrations documents
python manage.py migrate

然后,我们转到数据导入部分。

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

运行该命令:

python manage.py ingest_federal_register --limit 100

您可以在 MongoDB Atlas 界面中确认导入:

MongoDB Atlas 数据浏览器显示 regulations_qa.documents_document 集合中的 100 条《联邦公报》文档

定义自动嵌入索引

向量搜索索引用于告知 MongoDB 要在哪个字段上执行嵌入,并指定所用的模型。之后,MongoDB 会自动生成并存储嵌入。

  1. 在 Atlas 界面中打开您的集群,进入Search & Vector Search,点击Create Search Index。

MongoDB Atlas 的 Search & Vector Search 页面,带有 Create Search Index 按钮

  1. 选择 Vector Search 作为搜索类型,并选择 Automated Embedding 作为设置向量数据的方式。

Atlas 索引配置中已选择 Vector Search 和 Automated Embedding

  1. 选择 JSON 编辑器,选中您的数据库与 documents_document 集合,并将索引命名为 autoembed_index(名称必须与 .env 中的 VECTOR_INDEX_NAME 一致)。粘贴以下定义:
{
  "fields": [
    {
      "type": "autoEmbed",
      "modality": "text",
      "path": "abstract",
      "model": "voyage-4-lite"
    }
  ]
}

Atlas JSON 编辑器中针对 abstract 字段使用 voyage-4-lite 的 autoEmbed 索引定义

检查定义无误后,创建索引。

regulations_qa.documents_document 上名为 autoembed_index 的向量搜索索引的复核步骤

  1. 等待索引状态显示可查询,期间后台会生成嵌入。

Atlas Search & Vector Search 列表显示 autoembed_index 状态为 READY 且可查询

使用纯文本查询

对于自动嵌入,我们使用 $vectorSearch 阶段配合纯文本查询,在搜索时用与索引相同的模型对问题进行嵌入,因此代码中不需要任何嵌入调用。

为此,我们将创建一个服务模块。

# 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() 仅创建一次与 MongoDB 的连接并复用。借助 lru_cache 记忆首次调用的结果,每次搜索都会共享一个客户端,而不是每次都新建连接。
  • _get_collection() 使用与 Django 相同的设置,选取 regulations_qa 数据库与 documents_document 集合。
  • _get_index_name() 从设置中读取索引名,若缺失则给出清晰的错误提示。
  • semantic_search() 将问题作为文本放入 query 字段。第二个阶段将输出裁剪为所需字段,并添加相似度分数。

然后我们添加一个用于搜索文档的辅助命令:

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

现在进行测试,运行:

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

在示例中,我们选择与摘要不共享关键词的问题。例如关于“工厂污染限值”的问题,应能检索到关于排放标准的文档。

注意:在未绑定支付方式的免费(M0)集群上,查询嵌入请求可能会被限流。

演示:编辑文档并观察自动同步

在演示中,我们可以使用 MongoDB Atlas 的 Search Tester(此前在 regulations_qa.documents_document 集合上创建了 autoembed_index),或使用 Python 交互式 Shell。

Atlas 中针对 regulations_qa.documents_document 的 autoembed_index 的 Search Tester

步骤 1:通过 MongoDB Atlas 与 Shell 搜索

在 MongoDB Atlas 界面中测试,输入以下查询:

which states need to clean up their air

针对查询 which states need to clean up their air 的 Search Tester 结果及相似度分数

通过 Shell 测试:

使用 python manage.py shell 打开 Shell,然后运行:

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

Django Shell 输出列出前 10 条语义搜索结果及其分数

输出应与我们在图形界面中看到的结果一致。

步骤 2:编辑文档

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 中为文档 2026-16515 的摘要追加一句话并保存

步骤 3:再次搜索

自动嵌入是异步生成的,等待 30–60 秒后再次运行查询:

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

编辑后搜索结果,文档 2026-16515 从第 10 名升至第 5 名

现在,我们应能看到被编辑的文档排名较之前更高。

在 Search Tester 中运行相同查询,可在图形界面查看结果。

其原理是 MongoDB 注意到被索引的字段发生了变化,并重新生成了该文档的嵌入,因此样本中原本排名第 10 的文档 2026-16515 在编辑并同步后被提升到了第 5 位。

总结

恭喜您完成至此!我们已经构建了一个文档问答助手,数据中的嵌入流程由 MongoDB 负责。实现步骤如下:

  • 插入:通过 Django ORM 加载文档
  • 索引:在 Atlas 界面创建一条索引定义,指定字段与模型
  • 查询:通过一个小型服务以纯文本提问,无需额外的嵌入调用
  • 编辑:对被索引字段的变更会自动重新同步,无需重嵌入脚本

注意:本教程中的数据来自发布美国政府文档的《联邦公报》。本教程为独立内容,与《联邦公报》无关,亦未获其认可。

参考资料

Afi Gbadago

作者

Afi Gbadago

Afi 在 MongoDB 为开发者发声,专注于 Django 和 Python,通过教程、演讲和社区参与,帮助工程师构建现代数据技术方案。她是获得认可的 Microsoft MVP(Python 与 Web 方向),现任 Django 软件基金会董事会成员,并担任 2025 年 DjangoCon US 的议程主席。Afi 还是 Black Python Devs 的区域执行者、活跃的开源贡献者以及国际演讲者。

主题