Создание помощника Q&A в Django с автоэмбеддингами MongoDB
Постройте семантический поиск в Django с автоэмбеддингами MongoDB: без кода эмбеддингов, автоматическая повторная синхронизация при изменениях документов и текстовые запросы.
В типичной схеме RAG (retrieval-augmented generation) вы генерируете эмбеддинги при вставке документа, пересоздаёте их при изменении контента и самостоятельно векторизуете каждый запрос. Автоматические эмбеддинги упрощают построение семантического поиска: MongoDB Atlas нативно обрабатывает генерацию, обновление и запросы эмбеддингов, а Vector Search хранит сгенерированные векторные представления в вашем кластере.
Как MongoDB выполняет автоматическое эмбеддирование
Когда создаётся индекс векторного поиска типа autoEmbed, MongoDB генерирует эмбеддинги для выбранного поля, использует модель VoyageAI, поддерживает их синхронизацию при изменениях в документе и встраивает текст запроса во время поиска той же моделью. Сгенерированные эмбеддинги асинхронно сохраняются в кластере MongoDB во внутренней базе данных.
В этом руководстве мы построим помощника по документам Q&A с автоэмбеддингами MongoDB. Бэкенд Django MongoDB будет использоваться для определения моделей и загрузки документов, MongoDB — для поиска, автоматической генерации и синхронизации эмбеддингов, а LLM будет возвращать документы на основе полученных результатов.
К концу руководства вы реализуете этап извлечения данных в конвейере RAG: семантический поиск по документам Federal Register, где автоэмбеддинги берут на себя всю работу с эмбеддингами. Документы векторизуются при вставке, пере-векторизуются при изменениях, а ваши запросы векторизуются во время поиска — и всё это без написания кода для эмбеддингов.
Из корня проекта выполните следующую команду для создания нового проекта и приложения Django. Добавьте конечную точку . в команде startproject, чтобы указать Django установить проект в текущую директорию, а не создавать вложенную папку.
django-admin startproject regulations_qa --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/6.0.x.zip .Работает на
Зарегистрируйте приложение в 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Работает на
Удалите исходную жёстко заданную строку SECRET_KEY = '...' из settings.py, скопируйте значение, которое Django сгенерировал в settings.py при выполнении startproject, и замените им значение в файле .env. По умолчанию ключ захардкожен, а мы переносим его в .env, чтобы держать вне системы контроля версий, так как Django использует его для подписи сессионных cookies, 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Работает на
Источник данных: документы Federal Register
В этом руководстве мы проиндексируем документы из Federal Register — ежедневных публикаций правительства США с правилами, предлагаемыми правилами и уведомлениями. Источником данных является публичный API с документами, у которых есть заголовок и краткая аннотация, что хорошо подходит для семантического поиска.
Записи содержат поля, такие как title, type, abstract, document_number (уникальный ID), publication_date, html_url и список agencies.
Некоторые документы содержат null-значения, поэтому мы их опустим.
В аннотациях встречается разметка вроде <INF>2.5</INF> в «PM2.5», поэтому перед сохранением удаляем теги.
Результаты постраничные — до 100 на запрос, каждая страница включает next_page_url (курсор), по которому нужно переходить.
Проверьте эндпоинт через shell
curl-g"https://www.federalregister.gov/api/v1/documents.json?conditions[agencies][]=environmental-protection-agency&per_page=2"Работает на
Примечание: Это публичные данные правительства США, используемые для демонстрации. Это не юридический источник; для правовых исследований используйте официальное издание.
python manage.py makemigrations documents
python manage.py migrateРаботает на
Теперь перейдём к этапу загрузки.
# 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()}")Работает на
Выполните команду:
python manage.py ingest_federal_register --limit100Работает на
Вы можете подтвердить импорт в интерфейсе MongoDB Atlas:
Определите индекс Auto-Embed
Индекс векторного поиска указывает MongoDB, по какому полю выполнять эмбеддинг, и какую модель использовать. Далее MongoDB автоматически создаёт и сохраняет эмбеддинги.
В интерфейсе Atlas откройте свой кластер, перейдите в Search & Vector Search и нажмите Create Search Index.
Выберите Vector Search как тип поиска и Automated Embedding как способ настройки векторных данных.
Выберите JSON-редактор, укажите вашу базу данных и коллекцию documents_document, а индекс назовите autoembed_index (имя должно совпадать с VECTOR_INDEX_NAME в вашем .env). Вставьте это определение:
{"fields":[{"type":"autoEmbed","modality":"text","path":"abstract","model":"voyage-4-lite"}]}Работает на
Проверьте определение и создайте индекс.
Дождитесь, пока статус индекса покажет готовность к запросам — эмбеддинги генерируются в фоне.
Запрос на естественном языке
Для автоэмбеддингов мы используем стадию $vectorSearch с текстовым запросом: вопрос векторизуется той же моделью, что и индекс, поэтому в нашем коде нет вызова эмбеддинга.
Для этого создадим модуль сервиса.
# 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))Работает на
_get_client() создаёт подключение к MongoDB один раз и переиспользует его. lru_cache запоминает результат первого вызова, поэтому каждый поиск делит один клиент вместо открытия нового соединения.
_get_collection() выбирает базу regulations_qa и коллекцию documents_document, используя те же настройки, что и Django.
_get_index_name() читает имя индекса из настроек и выдаёт понятную ошибку, если оно не задано.
semantic_search() отправляет вопрос как текст в поле query. Вторая стадия обрезает вывод до нужных полей и добавляет оценку схожести.
Затем добавим вспомогательную команду для поиска по документам:
# 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"Работает на
В примере мы подбираем вопросы, не совпадающие по ключевым словам с аннотациями. Запрос о «лимитах загрязнения от фабрик» должен вернуть документы о стандартах выбросов.
Примечание: На бесплатном кластере (M0) без платёжного метода запросы на векторизацию могут ограничиваться по скорости.
Демо: отредактируйте документ и посмотрите, как он пересинхронизируется
Для демонстрации можно воспользоваться либо Search Tester в MongoDB Atlas, привязанным к созданному ранее autoembed_index на коллекции regulations_qa.documents_document, либо Python-shell.
Шаг 1: Поиск через MongoDB Atlas и shell
Чтобы протестировать в интерфейсе MongoDB Atlas, введите этот запрос:
which states need to clean up their airРаботает на
Чтобы протестировать через shell:
Откройте shell с python manage.py 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 inenumerate(hits,1)))Работает на
Вывод должен совпасть с тем, что мы видели в GUI.
Шаг 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)))Работает на
Теперь ожидаемо отредактированный документ должен ранжироваться выше, чем раньше.
Выполните тот же запрос в Search Tester, чтобы увидеть результаты в GUI.
Произошло следующее: MongoDB заметил, что индексируемое поле изменилось, и сгенерировал эмбеддинг этого документа заново, поэтому документ 2026-16515, который был 10-м в выборке, после редактирования и синхронизации поднялся на 5-ю позицию.
Итоги
Поздравляем, вы дошли до конца! У нас есть помощник Q&A по документам, где MongoDB берёт на себя рабочий процесс по эмбеддингам. Это было достигнуто в следующих шагах:
Вставка: документы загружены через Django ORM
Индекс: одно определение индекса, созданное в интерфейсе Atlas, с указанием поля и модели.
Запрос: текстовые вопросы через небольшой сервис без отдельного вызова эмбеддинга.
Правки: изменения индексируемого поля синхронизируются без отдельного скрипта переэмбеддинга.
Примечание: Данные в этом руководстве взяты из Federal Register, который публикует документы правительства США. Это руководство независимо и не связано с Federal Register и не одобрено им.
Что упрощают автоэмбеддинги
В типичной схеме RAG (retrieval-augmented generation) вы генерируете эмбеддинги при вставке документа, пересоздаёте их при изменении контента и самостоятельно векторизуете каждый запрос. Автоматические эмбеддинги упрощают построение семантического поиска: MongoDB Atlas нативно обрабатывает генерацию, обновление и запросы эмбеддингов, а Vector Search хранит сгенерированные векторные представления в вашем кластере.
Как MongoDB выполняет автоматическое эмбеддирование
Когда создаётся индекс векторного поиска типа
autoEmbed, MongoDB генерирует эмбеддинги для выбранного поля, использует модельVoyageAI, поддерживает их синхронизацию при изменениях в документе и встраивает текст запроса во время поиска той же моделью. Сгенерированные эмбеддинги асинхронно сохраняются в кластере MongoDB во внутренней базе данных.В этом руководстве мы построим помощника по документам Q&A с автоэмбеддингами MongoDB. Бэкенд Django MongoDB будет использоваться для определения моделей и загрузки документов, MongoDB — для поиска, автоматической генерации и синхронизации эмбеддингов, а LLM будет возвращать документы на основе полученных результатов.
К концу руководства вы реализуете этап извлечения данных в конвейере RAG: семантический поиск по документам Federal Register, где автоэмбеддинги берут на себя всю работу с эмбеддингами. Документы векторизуются при вставке, пере-векторизуются при изменениях, а ваши запросы векторизуются во время поиска — и всё это без написания кода для эмбеддингов.
Есть два способа пройти это руководство.
Подготовка окружения
Перед началом убедитесь, что у вас есть:
После выполнения этих предварительных шагов создайте папку проекта.
Создайте проект и виртуальное окружение
Создайте пустую папку для проекта и выполните в неё
cd.Это корневая директория проекта. Создайте и активируйте виртуальное окружение, если ещё не сделали этого:
Чтобы активировать виртуальное окружение на macOS или Linux, выполните:
В Windows выполните:
Установите зависимости
Создайте файл
requirements.txtв корне проекта со следующим содержимым:Затем установите всё:
Создайте проект и приложение Django
Из корня проекта выполните следующую команду для создания нового проекта и приложения Django. Добавьте конечную точку
.в командеstartproject, чтобы указать Django установить проект в текущую директорию, а не создавать вложенную папку.Создайте приложение
documentsЗарегистрируйте приложение в
regulations_qa/settings.py, добавив его вINSTALLED_APPS:Настройте переменные окружения
Создайте файл
.envв корне проекта со своими значениями и добавьте его в.gitignore, чтобы он не попал в репозиторий.Удалите исходную жёстко заданную строку
SECRET_KEY = '...'изsettings.py, скопируйте значение, которое Django сгенерировал вsettings.pyпри выполненииstartproject, и замените им значение в файле.env. По умолчанию ключ захардкожен, а мы переносим его в.env, чтобы держать вне системы контроля версий, так как Django использует его для подписи сессионных cookies, CSRF-токенов и других данных, связанных с безопасностью.Откройте
regulations_qa/settings.pyи убедитесь, что он содержит следующее. Импорты иload_dotenv()— вверху файла. Замените существующие определенияSECRET_KEYиDATABASESи добавьте строкуVECTOR_INDEX_NAME:Создайте папки для команд управления
Далее создадим папки с пустыми файлами
__init__.pyдля команд управления, поскольку Django обнаруживает пользовательские команды только в пакетеmanagement/commands/.Источник данных: документы Federal Register
В этом руководстве мы проиндексируем документы из Federal Register — ежедневных публикаций правительства США с правилами, предлагаемыми правилами и уведомлениями. Источником данных является публичный 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>в «PM2.5», поэтому перед сохранением удаляем теги.next_page_url(курсор), по которому нужно переходить.Проверьте эндпоинт через shell
Примечание: Это публичные данные правительства США, используемые для демонстрации. Это не юридический источник; для правовых исследований используйте официальное издание.
Загрузка данных
Начнём с создания моделей в файле
models.py.Далее создадим и применим миграции.
Теперь перейдём к этапу загрузки.
Выполните команду:
Вы можете подтвердить импорт в интерфейсе MongoDB Atlas:
Определите индекс Auto-Embed
Индекс векторного поиска указывает MongoDB, по какому полю выполнять эмбеддинг, и какую модель использовать. Далее MongoDB автоматически создаёт и сохраняет эмбеддинги.
documents_document, а индекс назовитеautoembed_index(имя должно совпадать сVECTOR_INDEX_NAMEв вашем.env). Вставьте это определение:Проверьте определение и создайте индекс.
Запрос на естественном языке
Для автоэмбеддингов мы используем стадию
$vectorSearchс текстовым запросом: вопрос векторизуется той же моделью, что и индекс, поэтому в нашем коде нет вызова эмбеддинга.Для этого создадим модуль сервиса.
_get_client()создаёт подключение к MongoDB один раз и переиспользует его.lru_cacheзапоминает результат первого вызова, поэтому каждый поиск делит один клиент вместо открытия нового соединения._get_collection()выбирает базуregulations_qaи коллекциюdocuments_document, используя те же настройки, что и Django._get_index_name()читает имя индекса из настроек и выдаёт понятную ошибку, если оно не задано.semantic_search()отправляет вопрос как текст в полеquery. Вторая стадия обрезает вывод до нужных полей и добавляет оценку схожести.Затем добавим вспомогательную команду для поиска по документам:
Чтобы проверить, выполните:
В примере мы подбираем вопросы, не совпадающие по ключевым словам с аннотациями. Запрос о «лимитах загрязнения от фабрик» должен вернуть документы о стандартах выбросов.
Примечание: На бесплатном кластере (M0) без платёжного метода запросы на векторизацию могут ограничиваться по скорости.
Демо: отредактируйте документ и посмотрите, как он пересинхронизируется
Для демонстрации можно воспользоваться либо
Search Testerв MongoDB Atlas, привязанным к созданному ранееautoembed_indexна коллекцииregulations_qa.documents_document, либо Python-shell.Шаг 1: Поиск через MongoDB Atlas и shell
Чтобы протестировать в интерфейсе MongoDB Atlas, введите этот запрос:
Чтобы протестировать через shell:
Откройте shell с
python manage.py shell, затем выполните:Вывод должен совпасть с тем, что мы видели в GUI.
Шаг 2: Отредактируйте документ
Шаг 3: Выполните поиск снова
Автоэмбеддинги генерируются асинхронно, поэтому подождите 30–60 секунд и запустите запрос снова:
Теперь ожидаемо отредактированный документ должен ранжироваться выше, чем раньше.
Выполните тот же запрос в Search Tester, чтобы увидеть результаты в GUI.
Произошло следующее: MongoDB заметил, что индексируемое поле изменилось, и сгенерировал эмбеддинг этого документа заново, поэтому документ
2026-16515, который был 10-м в выборке, после редактирования и синхронизации поднялся на 5-ю позицию.Итоги
Поздравляем, вы дошли до конца! У нас есть помощник Q&A по документам, где MongoDB берёт на себя рабочий процесс по эмбеддингам. Это было достигнуто в следующих шагах:
Примечание: Данные в этом руководстве взяты из Federal Register, который публикует документы правительства США. Это руководство независимо и не связано с Federal Register и не одобрено им.
Ссылки