Перейти к основному содержимому

Создание помощника Q&A в Django с автоэмбеддингами MongoDB

Постройте семантический поиск в Django с автоэмбеддингами MongoDB: без кода эмбеддингов, автоматическая повторная синхронизация при изменениях документов и текстовые запросы.
· 7 мин читать

Исследуйте с ИИ

Что упрощают автоэмбеддинги

В типичной схеме RAG (retrieval-augmented generation) вы генерируете эмбеддинги при вставке документа, пересоздаёте их при изменении контента и самостоятельно векторизуете каждый запрос. Автоматические эмбеддинги упрощают построение семантического поиска: MongoDB Atlas нативно обрабатывает генерацию, обновление и запросы эмбеддингов, а Vector Search хранит сгенерированные векторные представления в вашем кластере.

Как MongoDB выполняет автоматическое эмбеддирование

Когда создаётся индекс векторного поиска типа autoEmbed, MongoDB генерирует эмбеддинги для выбранного поля, использует модель VoyageAI, поддерживает их синхронизацию при изменениях в документе и встраивает текст запроса во время поиска той же моделью. Сгенерированные эмбеддинги асинхронно сохраняются в кластере MongoDB во внутренней базе данных.

В этом руководстве мы построим помощника по документам Q&A с автоэмбеддингами MongoDB. Бэкенд Django MongoDB будет использоваться для определения моделей и загрузки документов, MongoDB — для поиска, автоматической генерации и синхронизации эмбеддингов, а LLM будет возвращать документы на основе полученных результатов.

К концу руководства вы реализуете этап извлечения данных в конвейере RAG: семантический поиск по документам Federal Register, где автоэмбеддинги берут на себя всю работу с эмбеддингами. Документы векторизуются при вставке, пере-векторизуются при изменениях, а ваши запросы векторизуются во время поиска — и всё это без написания кода для эмбеддингов.

Есть два способа пройти это руководство.

  • Вариант A: Клонируйте репозиторий GitHub с готовым кодом из этого руководства, настройте его по README в репо и изучайте самостоятельно. Ссылка на проект GitHub: https://github.com/mongodb-developer/django-mongodb-regulations-qa
  • Вариант B: Соберите проект с нуля, следуя шагам ниже.

Подготовка окружения

Перед началом убедитесь, что у вас есть:

После выполнения этих предварительных шагов создайте папку проекта.

Создайте проект и виртуальное окружение

Создайте пустую папку для проекта и выполните в неё 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 установить проект в текущую директорию, а не создавать вложенную папку.

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

Удалите исходную жёстко заданную строку 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 с документами, у которых есть заголовок и краткая аннотация, что хорошо подходит для семантического поиска.

Документация API: https://www.federalregister.gov/developers/documentation/api/v1

Записи содержат поля, такие как 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"

Примечание: Это публичные данные правительства США, используемые для демонстрации. Это не юридический источник; для правовых исследований используйте официальное издание.

Загрузка данных

Начнём с создания моделей в файле 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 Data Explorer показывает 100 документов Federal Register в коллекции regulations_qa.documents_document

Определите индекс Auto-Embed

Индекс векторного поиска указывает MongoDB, по какому полю выполнять эмбеддинг, и какую модель использовать. Далее MongoDB автоматически создаёт и сохраняет эмбеддинги.

  1. В интерфейсе Atlas откройте свой кластер, перейдите в Search & Vector Search и нажмите Create Search Index.

Страница Search & Vector Search в MongoDB Atlas с кнопкой Create Search Index

  1. Выберите Vector Search как тип поиска и Automated Embedding как способ настройки векторных данных.

Конфигурация индекса в Atlas с выбранными Vector Search и Automated Embedding

  1. Выберите JSON-редактор, укажите вашу базу данных и коллекцию documents_document, а индекс назовите autoembed_index (имя должно совпадать с VECTOR_INDEX_NAME в вашем .env). Вставьте это определение:
{
  "fields": [
    {
      "type": "autoEmbed",
      "modality": "text",
      "path": "abstract",
      "model": "voyage-4-lite"
    }
  ]
}

JSON-редактор Atlas с определением индекса autoEmbed для поля abstract с использованием voyage-4-lite

Проверьте определение и создайте индекс.

Шаг проверки для индекса векторного поиска autoembed_index на regulations_qa.documents_document

  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() выбирает базу regulations_qa и коллекцию documents_document, используя те же настройки, что и Django.
  • _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) без платёжного метода запросы на векторизацию могут ограничиваться по скорости.

Демо: отредактируйте документ и посмотрите, как он пересинхронизируется

Для демонстрации можно воспользоваться либо Search Tester в MongoDB Atlas, привязанным к созданному ранее autoembed_index на коллекции regulations_qa.documents_document, либо Python-shell.

Atlas Search Tester для autoembed_index на regulations_qa.documents_document

Шаг 1: Поиск через MongoDB Atlas и shell

Чтобы протестировать в интерфейсе MongoDB Atlas, введите этот запрос:

which states need to clean up their air

Результаты Search Tester для запроса 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 in enumerate(hits, 1)))

Вывод Django shell со списком топ-10 результатов семантического поиска и их баллами

Вывод должен совпасть с тем, что мы видели в 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")

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, чтобы увидеть результаты в GUI.

Произошло следующее: MongoDB заметил, что индексируемое поле изменилось, и сгенерировал эмбеддинг этого документа заново, поэтому документ 2026-16515, который был 10-м в выборке, после редактирования и синхронизации поднялся на 5-ю позицию.

Итоги

Поздравляем, вы дошли до конца! У нас есть помощник Q&A по документам, где MongoDB берёт на себя рабочий процесс по эмбеддингам. Это было достигнуто в следующих шагах:

  • Вставка: документы загружены через Django ORM
  • Индекс: одно определение индекса, созданное в интерфейсе Atlas, с указанием поля и модели.
  • Запрос: текстовые вопросы через небольшой сервис без отдельного вызова эмбеддинга.
  • Правки: изменения индексируемого поля синхронизируются без отдельного скрипта переэмбеддинга.

Примечание: Данные в этом руководстве взяты из Federal Register, который публикует документы правительства США. Это руководство независимо и не связано с Federal Register и не одобрено им.

Ссылки

Темы