Pular para o conteúdo principal

Criando um assistente de perguntas e respostas em Django com auto-embeddings do MongoDB

Implemente busca semântica no Django com auto-embeddings do MongoDB: sem código de embedding, re-sync automático quando os documentos mudarem e consultas em texto simples.
· 7 min leer

Explore com IA

O que os auto-embeddings simplificam

Em um setup típico de RAG (retrieval-augmented generation), você gera embeddings ao inserir um documento, os regenera quando o conteúdo muda e faz o embedding de cada consulta por conta própria. O Automated Embedding simplifica a construção de busca semântica, pois o MongoDB Atlas lida nativamente com a geração, atualização e consulta de embeddings, e o Vector Search armazena os vetores gerados no seu cluster.

Como o MongoDB faz embedding automático

Quando um índice de busca vetorial do tipo autoEmbed é criado, o MongoDB gera embeddings para o campo escolhido usando o modelo VoyageAI, mantém tudo em sincronia quando houver alterações no documento e faz o embedding do texto da consulta no momento da busca com o mesmo modelo. Os embeddings são armazenados de forma assíncrona no cluster do MongoDB em um banco interno separado.

Neste tutorial, vamos criar um assistente de Q&A de documentação com auto-embeddings do MongoDB. Usaremos o backend do Django para MongoDB para definir os modelos e ingerir documentos; o MongoDB fará as buscas, gerará e sincronizará embeddings automaticamente, e o LLM retornará documentos com base nos resultados recuperados.

Ao final, você terá construído a etapa de recuperação de uma pipeline RAG: uma busca semântica sobre documentos do Federal Register em que os auto-embeddings fazem o trabalho pesado para você. Os documentos são embedded quando você os insere, re-embedded quando mudam e suas consultas são embedded no momento da busca — tudo isso sem escrever código de embedding.

Há duas maneiras de acompanhar este tutorial.

Configuração

Antes de começar, confirme que você tem:

Com os pré-requisitos prontos, o próximo passo é criar a pasta do projeto.

Crie um projeto e um ambiente virtual

Crie uma pasta vazia para o seu projeto e execute cd nela.

mkdir regulations_qa
cd regulations_qa

Este é o diretório raiz do seu projeto. Crie e ative seu ambiente virtual aqui, se ainda não fez isso:

python -m venv .venv

Para ativar o ambiente virtual no macOS ou Linux, rode:

source .venv/bin/activate

No Windows, rode:

.venv\Scripts\activate

Instale as dependências

Crie um arquivo requirements.txt na raiz do projeto com o conteúdo abaixo:

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

Depois, instale tudo:

pip install -r requirements.txt

Crie o projeto e o app no Django

No diretório raiz do projeto, rode o comando abaixo para criar um novo projeto e app Django. Inclua o . ao final do comando startproject — ele instrui o Django a instalar o projeto no diretório atual em vez de criar uma pasta aninhada.

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

Crie o app documents

python manage.py startapp documents

Registre o app em regulations_qa/settings.py adicionando-o a 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',
]

Configure as variáveis de ambiente

Crie um arquivo .env na raiz do projeto com seus próprios valores e adicione-o ao .gitignore para não ser commitado.

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

Apague a linha hardcoded original SECRET_KEY = '...' do settings.py, copie o valor que o Django gerou em settings.py quando você rodou o startproject e substitua no seu .env. Por padrão, ele vem hardcoded e nós o movemos para o .env para mantê-lo fora do controle de versão, já que o Django usa essa chave para assinar cookies de sessão, tokens de CSRF e outros dados sensíveis.

Abra regulations_qa/settings.py e garanta que ele contenha tudo a seguir. As linhas de import e o load_dotenv() ficam no topo. Substitua as definições atuais de SECRET_KEY e DATABASES e adicione a linha 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"),
    },
}

Crie pastas para management commands

Agora, vamos criar pastas com arquivos __init__.py vazios para os management commands, porque o Django só descobre comandos personalizados dentro do pacote management/commands/.

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

A fonte dos dados: documentos do Federal Register

Neste tutorial, vamos indexar documentos do Federal Register — as publicações diárias do governo dos EUA com regras, propostas de regras e comunicados. A fonte de dados é uma API pública com documentos que têm um título e um resumo em prosa, ótimo para busca semântica.

Documentação da API: https://www.federalregister.gov/developers/documentation/api/v1

Os registros têm campos como title, type, abstract, document_number (um ID único), publication_date, html_url e uma lista agencies.

  • Alguns documentos contêm valores nulos, então vamos omiti-los.
  • Os resumos trazem marcações como <INF>2.5</INF> em “PM2.5”; vamos remover as tags antes de salvar.
  • Os resultados são paginados em até 100 por requisição, e cada página inclui um next_page_url (baseado em cursor) para seguir.

Teste o endpoint via shell

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

Observação: estes são dados públicos do governo dos EUA usados para demonstração. Não é uma fonte legal; para pesquisa jurídica, use a edição oficial.

Ingestão dos dados

Vamos começar criando os modelos no arquivo 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]}"

Em seguida, crie e rode as migrações.

python manage.py makemigrations documents
python manage.py migrate

Agora, vamos para a parte de ingestão.

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

Rode o comando:

python manage.py ingest_federal_register --limit 100

Você pode confirmar a importação na interface do MongoDB Atlas:

MongoDB Atlas Data Explorer mostrando 100 documentos do Federal Register na coleção regulations_qa.documents_document

Defina o índice Auto-Embed

O índice de busca vetorial informa ao MongoDB em qual campo gerar embeddings e qual modelo usar. Depois disso, o MongoDB gera e armazena os embeddings automaticamente.

  1. Na interface do Atlas, abra seu cluster, vá em Search & Vector Search e clique em Create Search Index.

Página Search & Vector Search no MongoDB Atlas com o botão Create Search Index

  1. Escolha Vector Search como o tipo de busca e Automated Embedding como a forma de configurar seus dados vetoriais.

Configuração do índice no Atlas com Vector Search e Automated Embedding selecionados

  1. Escolha o editor JSON, selecione seu banco e a coleção documents_document e nomeie o índice como autoembed_index (o nome deve corresponder a VECTOR_INDEX_NAME no seu .env). Cole esta definição:
{
  "fields": [
    {
      "type": "autoEmbed",
      "modality": "text",
      "path": "abstract",
      "model": "voyage-4-lite"
    }
  ]
}

Editor JSON do Atlas com a definição do índice autoEmbed para o campo abstract usando voyage-4-lite

Revise a definição e crie o índice.

Etapa de revisão do índice de busca vetorial autoembed_index em regulations_qa.documents_document

  1. Aguarde até o status do índice indicar que está pronto para consulta, enquanto os embeddings são gerados em segundo plano.

Lista Search & Vector Search do Atlas mostrando autoembed_index com status READY e consultável

Consulte em texto simples

Com auto-embeddings, usamos a etapa $vectorSearch com uma consulta em texto simples; a pergunta é embedded com o mesmo modelo do índice, então não há chamada de embedding no nosso código.

Para isso, vamos criar um módulo de serviço.

# 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() cria a conexão com o MongoDB uma vez e a reutiliza. lru_cache memoriza o resultado da primeira chamada, então cada busca compartilha um único client em vez de abrir uma nova conexão.
  • _get_collection() seleciona o banco regulations_qa e a coleção documents_document, usando as mesmas configurações do Django.
  • _get_index_name() lê o nome do índice das configurações e fornece um erro claro se estiver ausente.
  • semantic_search() envia a pergunta como texto no campo query. A segunda etapa reduz a saída aos campos necessários e adiciona a pontuação de similaridade.

Depois, adicionamos um helper para pesquisar os documentos:

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

Para testar, rode:

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

No exemplo, escolhemos perguntas que não compartilham palavras-chave com os resumos. Uma pergunta sobre “limites de poluição de fábricas” deve recuperar documentos sobre padrões de emissão.

Observação: em um cluster gratuito (M0) sem método de pagamento, as requisições de embedding de consulta podem sofrer rate limiting.

Demonstração: edite um documento e veja a re-sincronização

Para a demo, você pode usar o Search Tester no MongoDB Atlas, vinculado ao autoembed_index que criamos na coleção regulations_qa.documents_document, ou usar o shell do Python.

Atlas Search Tester para autoembed_index em regulations_qa.documents_document

Passo 1: busque via MongoDB Atlas e via shell

Para testar na interface do MongoDB Atlas, digite esta consulta:

which states need to clean up their air

Resultados do Search Tester para a consulta which states need to clean up their air, com pontuações de similaridade

Para testar via shell:

Abra o shell com python manage.py shell e rode:

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

Saída do shell do Django listando os 10 principais resultados de busca semântica e suas pontuações

A saída deve ser a mesma vista pela interface.

Passo 2: edite o documento

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

Shell do Django adicionando uma frase ao abstract do documento 2026-16515 e salvando

Passo 3: busque novamente

Os auto-embeddings são gerados de forma assíncrona; aguarde de 30 a 60 segundos e rode a consulta de novo:

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

Resultados da busca após a edição, com o documento 2026-16515 subindo da 10ª para a 5ª posição

Agora, você deve ver o documento editado subir no ranking.

Rode a mesma consulta no Search Tester para ver os resultados pela interface.

O que aconteceu: o MongoDB detectou que o campo indexado foi alterado e regenerou o embedding daquele documento. Assim, o documento 2026-16515, que era o 10º na amostra, passou a ocupar a 5ª posição após a edição e a sincronização.

Fechamento

Parabéns por chegar até aqui! Temos um assistente de Q&A de docs em que o MongoDB cuida do fluxo de embeddings. Fizemos isso nos seguintes passos:

  • Inserção: documentos carregados via ORM do Django
  • Indexação: uma definição de índice criada na interface do Atlas, informando o campo e o modelo
  • Consulta: perguntas em texto simples via um pequeno serviço, sem chamada separada de embedding
  • Edição: alterações no campo indexado são resincronizadas sem script de re-embedding

Observação: os dados deste tutorial vêm do Federal Register, que publica documentos do governo dos EUA. Este tutorial é independente e não é afiliado nem endossado pelo Federal Register.

Referências

Afi Gbadago

Autor

Afi Gbadago

Afi atua na defesa dos desenvolvedores na MongoDB com foco em Django e Python, ajudando engenheiros a construir com tecnologias modernas de dados por meio de tutoriais, palestras e engajamento com a comunidade. Reconhecida como Microsoft MVP em Python e Web, ela integra o conselho da Django Software Foundation e é Programme Chair da DjangoCon US 2025. Afi também é Regional Executor na Black Python Devs, além de colaboradora ativa de open source e palestrante internacional.

Temas

Relacionado

Tutorial

Introdução ao Text Embeddings com a API OpenAI