Como armazenar e consultar embeddings no MongoDB

O surgimento dos LLMs e da pesquisa semântica mudou completamente a forma como criamos sistemas de pesquisa, recomendação e recuperação. A pesquisa tradicional por palavras-chave — seja por meio deSQL LIKE, Lucene invertido ou índices de texto completo — está cada vez mais insuficiente quando os usuários esperam compreensão da linguagem natural.

É aqui que embeddings e bancos de dados vetoriais entram em cena.

O MongoDB evoluiu rapidamente nesse espaço com o Atlas Vector Search, oferecendo aos desenvolvedores um único banco de dados para documentos + metadados + vetores — tudo sob uma única API. Neste guia, vamos ver:

• O que é o MongoDB.
• O que são embeddings de consulta e por que são importantes.
• Quando você deve usar embeddings.
• Como guardar embeddings no MongoDB.
• Como gerá-los e consultá-los usando Python.

Este tutorial é prático e pronto para integrar na sua geração aumentada por recuperação (RAG), pesquisa por similaridade ou pipeline de recomendação.

O que é o MongoDB?

O MongoDB é um banco de dados nosql orientado a documentos que guarda dados em documentosBSONflexíveis —BSON é uma notação de objeto JavaScript codificada em binário (JSON) — uma notação de objeto textual amplamente usada para transmitir e armazenar dados em aplicativos baseados na web. Diferente dos bancos de dados relacionais rígidos, o MongoDB simplifica a evolução do esquema e oferece:

• Escalabilidade horizontal (sharding).
• Estrutura de agregação rica.
• Pesquisa de texto completo.
• Pesquisa vetorial.
• Coleções de séries temporais.
• Flexibilidade do esquema.

O MongoDB Atlas — o serviço em nuvem totalmente gerenciado — amplia isso com:

• Pesquisa Atlas (baseada em Lucene).
• Pesquisa vetorial Atlas (busca semântica via indexação HNSW).
• Escalonamento automático, backups, segurança e monitoramento.

O MongoDB virou uma escolha forte para cargas de trabalho de IA porque os vetores geralmente ficam junto com os metadados, e o MongoDB Atlas junta tudo isso em um só sistema.

O que são embeddings e por que usamos embeddings de consulta?

Quando você trabalha com pesquisa ou recuperação em aplicativos de IA, um dos primeiros conceitos que você encontra é embeddings. 

Uma incorporação é basicamente uma representação numérica, uma longa lista de valores de ponto flutuante, que capta o significado de um trecho de texto (ou imagem, áudio, etc.). Em vez de olhar para as palavras exatas, os embeddings colocam o texto num espaço vetorial onde ideias parecidas ficam próximas umas das outras. Por exemplo, pense em três declarações diferentes de usuários:

• Problema de cobrança
• Erro de pagamento
• Salário não creditado

Mesmo que as palavras sejam diferentes, todas as três falam de um problema financeiro. Um bom modelo de incorporação coloca esses textos próximos uns dos outros no espaço vetorial, permitindo que você os recupere com base no significado, em vez de palavras-chave.

Isso é super importante quando o usuário faz uma busca. O texto que eles digitam — “Por que meu salário está atrasado?” — também vira uma incorporação. Esse novo vetor é chamado deincorporação de consulta de vetor de representação ( ). Depois, você compara esse vetor de consulta com todas as incorporações armazenadas para descobrir quais documentos são parecidos em termos de significado. Quanto mais próximos os vetores estiverem, mais relevante será o resultado.

O MongoDB Atlas torna todo esse fluxo de trabalho super simples com o Atlas Vector Search. Depois de guardar seus documentos e suas incorporações em uma coleção MongoDB, o Atlas cria umíndice vetorial de similaridade ( ) (usando HNSW nos bastidores) que pode recuperar rapidamente documentos parecidos em grande escala. Por exemplo, se você armazenar artigos de suporte com suas incorporações, uma consulta como...

query = "Why isn't my salary showing up this month?"
query_vec = get_embedding(query) # Explained in below examples

... pode ser usado diretamente no MongoDB:

results = collection.aggregate([
    {
        "$vectorSearch": {
            "path": "embedding",
            "queryVector": query_vec,
            "index": "vector_index",
            "limit": 3
        }
    }
])

O MongoDB vai mostrar automaticamente os três principais artigos de suporte cujas incorporações são mais parecidas com a consulta, sem você precisar fazer nenhuma correspondência de palavras-chave ou pontuação manual.

Esse é o poder das incorporações no MongoDB Atlas: você armazena significado, não só texto, e faz consultas com base na intenção, não só em palavras. Essa mudança é o motivo pelo qual os embeddings se tornaram um elemento fundamental para a pesquisa semântica, os sistemas RAG, os assistentes de IA e as bases de conhecimento inteligentes.

Quando usar incorporações de consulta

Use embeddings quando quiser semelhança semântica, como:

Geração aumentada por recuperação (RAG)

• Alimente seu LLM com contexto preciso a partir de sua base de conhecimento
• Substitua a pesquisa por palavra-chave frágil

Chatbots que precisam de um entendimento profundo

• Central de ajuda do portal
• Suporte ao cliente

Recomendação de produto

• “itens parecidos com este item”

Detecção de documentos ou duplicatas

• Agrupamento
• Agrupamento de tópicos

Quando a pesquisa por palavra-chave não dá certo

• Dúvidas como “atraso no crédito salarial” versus “problema no processamento do pagamento”

Faça não use incorporações quando:

• Você precisa de uma correspondência exata (IDs, números de fatura).
• Seu conjunto de dados é bem pequeno (a pesquisa simples funciona).
• Você precisa de filtragem/comparações numéricas (os metadados devem cuidar disso).

Como armazenar incorporações no MongoDB

O legal do MongoDB é que os embeddings se encaixam naturalmente nos documentos. Você só precisa armazená-los como matrizes de valores flutuantes.

Exemplo de esquema de documento

Aqui tá uma estrutura típica de documento:

{
  "_id": "uuid-123",
  "text": "This is a sample document about MongoDB vector search.",
  "embedding": [0.123, -0.241, 0.998, ...],
  "tags": ["mongodb", "vector", "ai"],
  "createdAt": "2025-01-01T10:20:00Z"
}

Coisas importantes pra lembrar:

• Cada incorporação em uma coleção precisa ter a mesma dimensionalidade.
• Idealmente, os embeddings devem ser armazenados como float32 (o MongoDB vai converter internamente para float64).
• Se seus documentos forem longos, divida-os antes de incorporá-los.
• Guarde os metadados separadamente — tags, categoria, URL, carimbos de data/hora, etc. Isso torna a pesquisa híbrida super eficiente.

Criando um índice vetorial no MongoDB (etapa crítica)

Antes de guardar ou consultar incorporações, você precisa criar um índice de pesquisa vetorial no MongoDB Atlas.

No MongoDB Atlas, vá para: Atlas → Banco de dados → Coleções → Pesquisa → Criar índice de pesquisa

Use uma definição como:

{
  "fields": [
    {
      "type": "vector",
      "path": "embedding",
      "numDimensions": 1536,
      "similarity": "cosine"
    }
  ]
}

This tells MongoDB:

• O campo contém contém vetores.
• Cada vetor tem 1536 dimensões.
• Use a similaridade coseno para classificar.

Esse índice alimenta todas as consultas de pesquisa vetorial.

O MongoDB tem recursos nativos de pesquisa vetorial com suporte para:

• Similaridade coseno.
• Distância euclidiana.
• Pontuação dotProduct.

Escolha com base no seu modelo de incorporação, mas como saber o que escolher? Vamos mergulhar fundo.

Similaridade coseno

O que ele mede

Mede o quanto dois vetores estãoalinhados — ou seja, o ângulo entre eles. Ignora a magnitude e foca só na direção.

Intuição

• Se dois vetores apontam na mesma direção → semelhança próxima a 1
• Direções opostas → –1
• Ortogonal (não relacionado) → 0

Quando usar

Use o cosseno quando a magnitude não importa, apenas o padrão ou conceito que está sendo expresso.

Usos comuns

• Incorporação de texto/NLP
• Pesquisa semântica
• Sistemas de recomendação baseados no significado, não na escala

O coseno é a opção padrão mais segura para a maioria dos modelos de incorporação.

distância euclidiana

O que ele mede

Mede a distância em linha reta entre dois vetores no espaço.

Intuição

• Pequena distância → os vetores são parecidos
• Grande distância → os vetores estão bem afastados

Quando usar

Use o Euclidiano quando valores absolutos e magnitudes importarem, e não apenas a direção.

Usos comuns

• Incorporação de imagens
• Medições físicas/dados do sensor
• Algoritmos de agrupamento como K-means (que usa internamente o método euclidiano)

Se seus dados naturalmente se encaixam em um espaço geométrico (por exemplo, intensidades de pixels), a geometria euclidiana geralmente faz mais sentido.

Produto escalar

O que ele mede

Ele mede uma combinação de similaridade e magnitude. 

Matematicamente: dot(u, v) = |u| × |v| × cos(θ)

Intuição

• Maior magnitude E alinhamento → maior pontuação
• Sensível ao comprimento do vetor
• Não normalizado automaticamente

Quando usar

Use o produto escalar quando você quiser que vetores mais longos tenham mais influência ou quando o modelo de incorporação for treinado com o produto escalar em mente.

Usos comuns

• Incorporações de modelos de linguagem grandes que assumem produto interno pontuação
• Camadas de similaridade da rede neural
• Modelos de recomendação em que a “força” das características é importante

Regra prática rápida

Gerar, armazenar e consultar incorporações no MongoDB (tutorial em Python)

Vamos ver isso como se estivéssemos montando um sistema de verdade.

Instalar dependências

pip install pymongo openai

Gerar incorporações

Usando o OpenAI (troque por qualquer provedor de incorporação que você preferir):

import os
from openai import OpenAI

os.environ["OPENAI_API_KEY"] = "your_api_key_here"
client = OpenAI()

def get_embedding(text: str):
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=text
    )
    return response.data[0].embedding

Conecte-se ao MongoDB e insira documentos

Usando o OpenAI (troque por qualquer provedor de incorporação que você preferir):

from pymongo import MongoClient
import uuid

mongo = MongoClient("<MONGODB_ATLAS_URI>")
db = mongo["vector_db"]
collection = db["documents"]

text = "This is a sample document about MongoDB vector search."
embedding = get_embedding(text)

document = {
    "_id": str(uuid.uuid4()),
    "text": text,
    "embedding": embedding,
    "tags": ["mongodb", "search"],
}

collection.insert_one(document)
print("Document inserted successfully!")

Agora, seus dados estão prontos para a pesquisa semântica.

Consultando incorporações no MongoDB

Agora vem a parte divertida: recuperar documentos parecidos usando uma consulta vetorial. O MongoDB usa $vectorSearch em um pipeline de agregação.

Gerar vetor de consulta

from pymongo import MongoClient
query = "How does MongoDB handle semantic search?"
query_vec = get_embedding(query)

Fazer uma busca vetorial (embeddings de consulta)

results = collection.aggregate([
    {
        "$vectorSearch": {
            "index": "vector_index",
            "path": "embedding",
            "queryVector": query_vec,
            "numCandidates": 100,
            "limit": 5,
            "similarity": "cosine"
        }
    },
    {
        "$project": {
            "text": 1,
            "score": {"$meta": "vectorSearchScore"}
        }
    }
])

for r in results:
    print(r)

Isso mostra os cinco documentos mais parecidos em termos de significado.

Isso é super útil para pipelines RAG onde você quer fazer uma busca semântica.

Explicação passo a passo da consulta acima

$vectorSearch → Encontra documentos cuja campo de incorporação esteja mais próximo de queryVector usando a métrica de similaridade especificada

numCandidates → Quantos resultados possíveis o mecanismo deve considerar antes de escolher os melhores resultados

limite → Número de resultados finais semelhantes a retornar

$project → Mostra o texto original mais um campo especial chamado score

O que é o campo de pontuação?

A Pesquisa Vetorial do MongoDB Atlas retorna um campo de metadados especial, "score": {"$meta": "vectorSearchScore"}, que informa quão parecido um vetor armazenado é ao seu vetor de consulta.

O significado da pontuação depende da métrica de similaridade que você escolher, como explicado abaixo:

Melhores práticas

• Divida documentos longos (300–500 tokens cada): Melhor relevância + evita a incorporação de blobs longos
• Armazene os metadados separadamente: Ajuda a filtrar e classificar
• Geração de incorporação em lote: Melhora o rendimento e reduz o custo do modelo
• Use incorporações float32 no seu modelo: O MongoDB usa float64 internamente, mas aceita matrizes float32.
• Indexe só o campo vetorial: Campos extras no índice aumentam a memória e a latência

Erros comuns a evitar

Considerações finais

Embeddings e pesquisa semântica agora são essenciais para os produtos modernos de IA. Se você está criando um chatbot, um pipeline RAG, um mecanismo de recomendação ou uma camada de pesquisa inteligente, precisa de uma maneira confiável de armazenar vetores e consultá-los com eficiência.

O MongoDB oferece uma plataforma unificada onde:

• Seu texto vive.
• Seus metadados continuam vivos.
• Suas incorporações estão ativas.
• Sua pesquisa vetorial está rolando.
• Tudo se adapta junto.

Isso evita a confusão de ter que lidar com vários bancos de dados e te deixa focar em desenvolver os recursos do produto, não a infraestrutura.