# 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))技术支持
# 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]}")技术支持
现在进行测试,运行:
python manage.py search_docs "limits on pollution from factories"技术支持
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)))技术支持
输出应与我们在图形界面中看到的结果一致。
步骤 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")技术支持
步骤 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 inenumerate(hits,1)))技术支持
自动嵌入能简化什么
在典型的检索增强生成(RAG)方案中,您需要在插入文档时生成嵌入,在内容变更时重新生成嵌入,并为每次查询自行生成嵌入。自动嵌入让构建语义搜索的流程更简单:MongoDB Atlas 原生负责嵌入的生成、更新和查询,向量搜索会在集群中存储生成的向量嵌入。
MongoDB 如何进行自动嵌入
当创建类型为
autoEmbed的向量搜索索引时,MongoDB 会为选定字段生成嵌入,使用VoyageAI模型,在文档发生变更时保持嵌入同步,并在搜索时用同一个模型对查询文本进行嵌入。生成的嵌入会异步存储在 MongoDB 集群的一个内部数据库中。在本教程中,我们将使用 MongoDB 自动嵌入构建一个文档问答助手。我们将使用 Django MongoDB 后端定义模型并导入文档,由 MongoDB 负责查找、自动生成和同步嵌入,LLM 将基于检索结果返回文档。
完成本教程后,您将构建一个 RAG 流水线中的检索阶段:针对《联邦公报》文档的语义搜索,由自动嵌入为您处理嵌入工作。文档在插入时嵌入,变更时重新嵌入,查询在搜索时自动嵌入,整个过程无需编写任何嵌入代码。
有两种方式跟进本教程。
环境准备
在开始之前,请确认您已具备:
完成以上先决条件后,下一步是创建您的项目文件夹。
创建项目与虚拟环境
为项目创建一个空文件夹,并
cd进入其中。这是项目的根目录。如果尚未创建,请在此创建并激活虚拟环境:
在 macOS 或 Linux 上激活虚拟环境:
在 Windows 上运行:
安装依赖
在项目根目录创建一个
requirements.txt文件,内容如下:然后安装所有依赖:
创建 Django 项目与应用
在项目根目录运行以下命令以创建新的 Django 项目与应用。在
startproject命令中添加末尾的.,表示将项目安装到当前目录,而不是创建一个嵌套文件夹。创建
documents应用在
regulations_qa/settings.py中注册该应用,将其添加到INSTALLED_APPS:配置环境变量
在项目根目录创建
.env文件并填入您自己的值,同时将其加入.gitignore,以避免在推送时被提交。从
settings.py中删除原有的硬编码SECRET_KEY = '...'行,复制您在运行startproject时settings.py里生成的值,替换到.env文件中。默认情况下它被硬编码,我们将其移至.env,以避免进入版本控制,因为 Django 会使用它签署会话 Cookie、CSRF 令牌等安全敏感数据。打开
regulations_qa/settings.py并确保包含以下所有内容。导入行与load_dotenv()放在顶部。用下方代码替换现有的SECRET_KEY与DATABASES定义,并新增VECTOR_INDEX_NAME行:为管理命令创建文件夹
接下来,我们创建带空
__init__.py的文件夹用于管理命令,因为 Django 只会在management/commands/包中发现自定义命令。数据来源:《联邦公报》文档
在本教程中,我们将索引《联邦公报》的文档;这是美国政府关于规则、拟议规则和公告的每日发布。数据来源是一个公共 API,文档包含标题与简短的文字摘要,非常适合语义搜索。
API 文档:https://www.federalregister.gov/developers/documentation/api/v1
记录包含诸如
title、type、abstract、document_number(唯一 ID)、publication_date、html_url和agencies列表等字段。<INF>2.5</INF>等标记,因此在保存前需要去除标签。next_page_url(基于游标)。通过命令行测试端点
注意:这是用于演示的美国政府公共数据。它不是法律来源;若进行法律研究,请使用官方版本。
导入数据
我们将先在
models.py文件中创建模型。接下来,创建并运行迁移。
然后,我们转到数据导入部分。
运行该命令:
您可以在 MongoDB Atlas 界面中确认导入:
定义自动嵌入索引
向量搜索索引用于告知 MongoDB 要在哪个字段上执行嵌入,并指定所用的模型。之后,MongoDB 会自动生成并存储嵌入。
documents_document集合,并将索引命名为autoembed_index(名称必须与.env中的VECTOR_INDEX_NAME一致)。粘贴以下定义:检查定义无误后,创建索引。
使用纯文本查询
对于自动嵌入,我们使用
$vectorSearch阶段配合纯文本查询,在搜索时用与索引相同的模型对问题进行嵌入,因此代码中不需要任何嵌入调用。为此,我们将创建一个服务模块。
_get_client()仅创建一次与 MongoDB 的连接并复用。借助lru_cache记忆首次调用的结果,每次搜索都会共享一个客户端,而不是每次都新建连接。_get_collection()使用与 Django 相同的设置,选取regulations_qa数据库与documents_document集合。_get_index_name()从设置中读取索引名,若缺失则给出清晰的错误提示。semantic_search()将问题作为文本放入query字段。第二个阶段将输出裁剪为所需字段,并添加相似度分数。然后我们添加一个用于搜索文档的辅助命令:
现在进行测试,运行:
在示例中,我们选择与摘要不共享关键词的问题。例如关于“工厂污染限值”的问题,应能检索到关于排放标准的文档。
注意:在未绑定支付方式的免费(M0)集群上,查询嵌入请求可能会被限流。
演示:编辑文档并观察自动同步
在演示中,我们可以使用 MongoDB Atlas 的
Search Tester(此前在regulations_qa.documents_document集合上创建了autoembed_index),或使用 Python 交互式 Shell。步骤 1:通过 MongoDB Atlas 与 Shell 搜索
在 MongoDB Atlas 界面中测试,输入以下查询:
通过 Shell 测试:
使用
python manage.py shell打开 Shell,然后运行:输出应与我们在图形界面中看到的结果一致。
步骤 2:编辑文档
步骤 3:再次搜索
自动嵌入是异步生成的,等待 30–60 秒后再次运行查询:
现在,我们应能看到被编辑的文档排名较之前更高。
在 Search Tester 中运行相同查询,可在图形界面查看结果。
其原理是 MongoDB 注意到被索引的字段发生了变化,并重新生成了该文档的嵌入,因此样本中原本排名第 10 的文档
2026-16515在编辑并同步后被提升到了第 5 位。总结
恭喜您完成至此!我们已经构建了一个文档问答助手,数据中的嵌入流程由 MongoDB 负责。实现步骤如下:
注意:本教程中的数据来自发布美国政府文档的《联邦公报》。本教程为独立内容,与《联邦公报》无关,亦未获其认可。
参考资料