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.
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.
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.
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"),},}Tecnologia
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/.
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.
Você pode confirmar a importação na interface do MongoDB Atlas:
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.
Na interface do Atlas, abra seu cluster, vá em Search & Vector Search e clique em Create Search Index.
Escolha Vector Search como o tipo de busca e Automated Embedding como a forma de configurar seus dados vetoriais.
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:
Aguarde até o status do índice indicar que está pronto para consulta, enquanto os embeddings são gerados em segundo plano.
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.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))Tecnologia
_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.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]}")Tecnologia
Para testar, rode:
python manage.py search_docs "limits on pollution from factories"Tecnologia
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.
Passo 1: busque via MongoDB Atlas e via shell
Para testar na interface do MongoDB Atlas, digite esta consulta:
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)))Tecnologia
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")Tecnologia
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 inenumerate(hits,1)))Tecnologia
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.
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.
As incorporações de vetores são representações numéricas de palavras ou frases que capturam seus significados e relacionamentos, ajudando os modelos de machine learning a entender o texto com mais eficiência.
Explore o DuckDB, o banco de dados analítico rápido e fácil de usar para Python e R. Conheça seus principais recursos, casos de uso e como ele otimiza as tarefas de análise de dados.
Explore nosso guia sobre como usar a API OpenAI para criar incorporações de texto. Descubra suas aplicações na classificação de textos, recuperação de informações e detecção de similaridade semântica.
Este guia completo ensina os fundamentos do desenvolvimento backend com Python. Aprenda conceitos básicos, frameworks e boas práticas para começar a criar aplicações web.
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 modeloVoyageAI, 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
cdnela.Este é o diretório raiz do seu projeto. Crie e ative seu ambiente virtual aqui, se ainda não fez isso:
Para ativar o ambiente virtual no macOS ou Linux, rode:
No Windows, rode:
Instale as dependências
Crie um arquivo
requirements.txtna raiz do projeto com o conteúdo abaixo:Depois, instale tudo:
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 comandostartproject— ele instrui o Django a instalar o projeto no diretório atual em vez de criar uma pasta aninhada.Crie o app
documentsRegistre o app em
regulations_qa/settings.pyadicionando-o aINSTALLED_APPS:Configure as variáveis de ambiente
Crie um arquivo
.envna raiz do projeto com seus próprios valores e adicione-o ao.gitignorepara não ser commitado.Apague a linha hardcoded original
SECRET_KEY = '...'dosettings.py, copie o valor que o Django gerou emsettings.pyquando você rodou ostartprojecte substitua no seu.env. Por padrão, ele vem hardcoded e nós o movemos para o.envpara 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.pye garanta que ele contenha tudo a seguir. As linhas de import e oload_dotenv()ficam no topo. Substitua as definições atuais deSECRET_KEYeDATABASESe adicione a linhaVECTOR_INDEX_NAME:Crie pastas para management commands
Agora, vamos criar pastas com arquivos
__init__.pyvazios para os management commands, porque o Django só descobre comandos personalizados dentro do pacotemanagement/commands/.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_urle uma listaagencies.<INF>2.5</INF>em “PM2.5”; vamos remover as tags antes de salvar.next_page_url(baseado em cursor) para seguir.Teste o endpoint via shell
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.Em seguida, crie e rode as migrações.
Agora, vamos para a parte de ingestão.
Rode o comando:
Você pode confirmar a importação na interface do MongoDB Atlas:
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.
documents_documente nomeie o índice comoautoembed_index(o nome deve corresponder aVECTOR_INDEX_NAMEno seu.env). Cole esta definição:Revise a definição e crie o índice.
Consulte em texto simples
Com auto-embeddings, usamos a etapa
$vectorSearchcom 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.
_get_client()cria a conexão com o MongoDB uma vez e a reutiliza.lru_cachememoriza 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 bancoregulations_qae a coleçãodocuments_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 campoquery. 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:
Para testar, rode:
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 Testerno MongoDB Atlas, vinculado aoautoembed_indexque criamos na coleçãoregulations_qa.documents_document, ou usar o shell do Python.Passo 1: busque via MongoDB Atlas e via shell
Para testar na interface do MongoDB Atlas, digite esta consulta:
Para testar via shell:
Abra o shell com
python manage.py shelle rode:A saída deve ser a mesma vista pela interface.
Passo 2: edite o documento
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:
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:
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