Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.
Menu Docs

Integre o MongoDB com o LangChain

Você pode integrar o MongoDB ao LangChain para criar aplicativos IA generativa e RAG. Esta página fornece uma visão geral da integração do Python do MongoDB do MongoDB e dos diferentes componentes que você pode usar em seus aplicativos.

Começar

Observação

Para obter uma lista completa de componentes e métodos, consulte Referência da API.

Para a integração com JavaScript, veja LangChain JS/TS.

Para usar a Vector Search do MongoDB com o LangChain, você deve primeiro instalar o pacote langchain-mongodb :

pip install langchain-mongodb

MongoDBAtlasVectorSearch é um armazenamento de vetores que permite armazenar e recuperar incorporações vetoriais de uma coleção no MongoDB. Você pode usar esse componente para armazenar incorporações de seus dados e recuperá-las usando a Vector Search do MongoDB .

This component requires an MongoDB Vector Search Index.

O Atlas permite dois modos de incorporação:

  • Incorporação manual: Gere vetores de incorporação no lado do cliente com um modelo de incorporação que você especifica.

  • Automated embedding: MongoDB embeds text on the server's side without needing to generate them manually. To learn more, see Automated Embedding.

A maneira mais rápida de instanciar seu armazenamento de vetores é usar a string de conexão para seu cluster MongoDB ou implantação local:

from langchain_mongodb.vectorstores import MongoDBAtlasVectorSearch
from langchain_voyageai import VoyageAIEmbeddings
# Instantiate the vector store using your MongoDB connection string
vector_store = MongoDBAtlasVectorSearch.from_connection_string(
connection_string="<connection-string>", # MongoDB cluster URI
namespace="<database-name>.<collection-name>", # Database and collection name
embedding=VoyageAIEmbeddings(model="voyage-3-large"), # Embedding model to use
index_name="vector_index", # Name of the vector search index
# Other optional parameters...
)

Os retrievers do LangChain são componentes que você usa para obter documentos relevantes de seus armazenamentos de vetores. Você pode usar os recuperadores integrados do LangChain ou os seguintes recuperadores do MongoDB para consultar e recuperar dados do MongoDB.

After instantiating MongoDB as a vector store, you can use the vector store instance as a retriever to query your data using MongoDB Vector Search.

from langchain_mongodb.vectorstores import MongoDBAtlasVectorSearch
from langchain_voyageai import VoyageAIEmbeddings
# Instantiate the vector store
vector_store = MongoDBAtlasVectorSearch.from_connection_string(
connection_string="<connection-string>", # MongoDB cluster URI
namespace="<database-name>.<collection-name>", # Database and collection name
embedding=VoyageAIEmbeddings(model="voyage-3-large"), # Embedding model to use
index_name="vector_index", # Name of the vector search index
)
# Use the vector store as a retriever
retriever = vector_store.as_retriever()
# Define your query
query = "some search query"
# Print results
documents = retriever.invoke(query)
for doc in documents:
print(doc)

MongoDBAtlasFullTextSearchRetriever é um recuperador que executa a pesquisa de texto completo usando o MongoDB Search. Especificamente, ele usa o algoritmo BM25 padrão da Lucene.

This retriever requires an MongoDB Search Index.

from langchain_mongodb.retrievers.full_text_search import (
MongoDBAtlasFullTextSearchRetriever,
)
from pymongo import MongoClient
# Connect to your MongoDB cluster
client = MongoClient("<connection-string>")
collection = client["<database-name>"]["<collection-name>"]
# Initialize the retriever
retriever = MongoDBAtlasFullTextSearchRetriever(
collection=collection, # MongoDB Collection in Atlas
search_field="<field-name>", # Name of the field to search
search_index_name="<index-name>", # Name of the search index
)
# Define your query
query = "some search query"
# Print results
documents = retriever.invoke(query)
for doc in documents:
print(doc)

Observação

MongoDBAtlasHybridSearchRetriever is a retriever that combines vector search and full-text search results by using the Reciprocal Rank Fusion (RRF) algorithm. To learn more, see How to Perform Hybrid Search.

This retriever requires an existing vector store, MongoDB Vector Search Index, and MongoDB Search Index.

from langchain_mongodb.retrievers.hybrid_search import (
MongoDBAtlasHybridSearchRetriever,
)
from langchain_mongodb.vectorstores import MongoDBAtlasVectorSearch
from langchain_voyageai import VoyageAIEmbeddings
# Instantiate the vector store
vector_store = MongoDBAtlasVectorSearch.from_connection_string(
connection_string="<connection-string>", # MongoDB cluster URI
namespace="<database-name>.<collection-name>", # Database and collection name
embedding=VoyageAIEmbeddings(model="voyage-3-large"), # Embedding model to use
index_name="vector_index", # Name of the vector search index
)
# Initialize the retriever
retriever = MongoDBAtlasHybridSearchRetriever(
vectorstore=vector_store, # Vector store instance
search_index_name="<index-name>", # Name of the MongoDB Search index
top_k=5, # Number of documents to return
fulltext_penalty=60.0, # Penalty for full-text search
vector_penalty=60.0, # Penalty for vector search
)
# Define your query
query = "some search query"
# Print results
documents = retriever.invoke(query)
for doc in documents:
print(doc)

MongoDBAtlasParentDocumentRetriever é um recuperador que consulta partes menores primeiro e, em seguida, retorna o documento pai maior para o LLM. Esse tipo de recuperação é chamado de recuperação de documento pai. A recuperação do documento pai pode melhorar as respostas dos seus agentes e aplicativos RAG, permitindo pesquisas mais detalhadas em partes menores e, ao mesmo tempo, fornecendo aos LLMs o contexto completo do documento pai.

Este recuperador armazena tanto os documentos pai quanto os documentos filhos em uma única coleção MongoDB, o que permite uma recuperação eficiente, pois é necessário apenas calcular e indexar as embeddings dos documentos filhos.

Em segundo plano, este recuperador cria o seguinte:

  • Uma instância de MongoDBAtlasVectorSearch para lidar com queries de pesquisa vetorial nos documentos filhos.

  • Uma instância de MongoDBDocStore para lidar com o armazenamento e a recuperação dos documentos pai.

Defina text_key como page_content para que o armazenamento de vetores e o armazenamento de documentos pai usem o mesmo nome de campo para o texto do documento. Sem esse parâmetro, o retriever grava documentos pai em um campo e os lê de outro, e as queries falham com KeyError: 'text'.

from langchain_mongodb.retrievers import MongoDBAtlasParentDocumentRetriever
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_voyageai import VoyageAIEmbeddings
retriever = MongoDBAtlasParentDocumentRetriever.from_connection_string(
connection_string="<connection-string>", # MongoDB cluster URI
embedding_model=VoyageAIEmbeddings( # Embedding model to use
model="voyage-3-large"
),
child_splitter=RecursiveCharacterTextSplitter(), # Text splitter to use
database_name="<database-name>", # Database to store the collection
collection_name="<collection-name>", # Collection to store the collection
text_key="page_content", # Match the key the parent document store uses
# Additional vector store or parent class arguments...
)
# Define your query
query = "some search query"
# Print results
documents = retriever.invoke(query)
for doc in documents:
print(doc)

MongoDBAtlasSelfQueryRetriever é um retriever que se consulta. O recuperador usa um LLM para processar sua query de pesquisa para identificar possíveis filtros de metadados, forma uma query de pesquisa vetorial estruturada com os filtros e, em seguida, executa a query para recuperar os documentos mais relevantes.

Por exemplo, com uma consulta como "O que são filmes de ação depois de 2010 com classificações acima de 8?", O recuperador pode identificar filtros nos campos genre, year e rating e usá-los filtros para recuperar documentos que correspondam à query.

This retriever requires an existing vector store and MongoDB Vector Search Index.

from langchain_mongodb.retrievers import MongoDBAtlasSelfQueryRetriever
from langchain_mongodb import MongoDBAtlasVectorSearch
from langchain_classic.chains.query_constructor.schema import AttributeInfo
from langchain_voyageai import VoyageAIEmbeddings
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o", temperature=0)
vector_store = MongoDBAtlasVectorSearch.from_connection_string(
connection_string="<connection-string>",
namespace="langchain_db.movies",
embedding=VoyageAIEmbeddings(model="voyage-3-large"),
index_name="vector_index",
)
# Given an existing vector store with movies data, define metadata describing the data
metadata_field_info = [
AttributeInfo(
name="genre",
description="The genre of the movie. One of ['science fiction', 'comedy', 'drama', 'thriller', 'romance', 'animated']",
type="string",
),
AttributeInfo(
name="year",
description="The year the movie was released",
type="integer",
),
AttributeInfo(
name="rating", description="A 1-10 rating for the movie", type="float"
),
]
# Create the retriever from the VectorStore, an LLM and info about the documents
retriever = MongoDBAtlasSelfQueryRetriever.from_llm(
llm=llm,
vectorstore=vector_store,
metadata_field_info=metadata_field_info,
document_contents="Descriptions of movies",
enable_limit=True,
)
# This example results in the following composite filter sent to $vectorSearch:
# {'filter': {'$and': [{'year': {'$lt': 1960}}, {'rating': {'$gt': 8}}]}}
documents = retriever.invoke("Movies made before 1960 that are rated higher than 8")
print(documents)

O GraphRAG é uma abordagem alternativa ao RAG tradicional que estrutura os dados como um gráfico de conhecimento de entidades e seus relacionamentos, em vez de incorporações vetoriais. Enquanto o RAG baseado em vetor encontra documentos semanticamente semelhantes à query, o GraphRAG localiza entidades conectadas à query e atravessa os relacionamentos no grafo para recuperar informações relevantes.

Essa abordagem é particularmente útil para responder a perguntas baseadas em relacionamento, como "Qual é a conexão entre a Empresa A e a Empresa B?" ou "Quem é o gerente da Pessoa X?".

MongoDBGraphStore is a component in the LangChain MongoDB integration that allows you to implement GraphRAG by storing entities (nodes) and their relationships (edges) in a MongoDB collection. This component stores each entity as a document with relationship fields that reference other documents in your collection. It executes queries using the $graphLookup aggregation stage.

from langchain_mongodb.graphrag import MongoDBGraphStore
from langchain_openai import ChatOpenAI
from langchain_core.documents import Document
# Initialize the graph store
graph_store = MongoDBGraphStore(
connection_string="<connection-string>", # MongoDB cluster URI
database_name="<database-name>", # Database to store the graph
collection_name="<collection-name>", # Collection to store the graph
entity_extraction_model=ChatOpenAI( # LLM to extract entities
model="gpt-4o", temperature=0
),
# Other optional parameters...
)
# Add documents to the graph
docs = [
Document(
page_content=(
"MongoDB is a document database. "
"Dev Ittycheria is the CEO of MongoDB."
)
),
Document(page_content="MongoDB Atlas is the cloud platform offered by MongoDB."),
]
graph_store.add_documents(docs)
# Query the graph
query = "Who is the CEO of MongoDB?"
answer = graph_store.chat_response(query)
print(answer.content)

Os caches são usados para otimizar o desempenho do LLM, armazenando respostas repetitivas para queries semelhantes ou repetitivas para evitar seu novo cálculo. O MongoDB fornece os seguintes caches para seus aplicativos LangChain.

MongoDBCache permite armazenar um cache básico em uma coleção MongoDB .

from langchain_mongodb import MongoDBCache
from langchain_core.globals import set_llm_cache
set_llm_cache(
MongoDBCache(
connection_string="<connection-string>", # MongoDB cluster URI
database_name="langchain_db", # Database to store the cache
collection_name="cache", # Collection to store the cache
)
)

O cache semântico é uma forma mais avançada de cache que recupera prompts armazenados em cache com base na semelhança semântica entre a entrada do usuário e os resultados armazenados em cache.

MongoDBAtlasSemanticCache is a semantic cache that uses MongoDB Vector Search to retrieve the cached prompts. This component requires an MongoDB Vector Search index.

from langchain_mongodb import MongoDBAtlasSemanticCache
from langchain_core.globals import set_llm_cache
from langchain_voyageai import VoyageAIEmbeddings
set_llm_cache(
MongoDBAtlasSemanticCache(
embedding=VoyageAIEmbeddings(model="voyage-3-large"), # Embedding model
connection_string="<connection-string>", # MongoDB cluster URI
database_name="langchain_db", # Database to store the cache
collection_name="semantic_cache", # Collection to store the cache
)
)

LangChain DeepAgents é um harness de agente projetado para tarefas de várias etapas e de longa duração. Ele lida com o planejamento, o gerenciamento de contexto e a delegação de trabalho para subagentes. O harness oferece suporte a um protocolo de backend intercambiável que permite alterar onde os arquivos de um agente realmente residem. O pacote langchain-mongodb-deepagents-vfs é uma implementação desse protocolo: o Amazon S3 mantém os arquivos, um provedor de embedding (Amazon Web Services Bedrock ou OpenAI) calcula os embeddings, o MongoDB Atlas mantém as partes e os embeddings, e a classe MongoFilesystemBackend roteia cada operação de arquivo para o manipulador correto.

Use este pacote quando seu agente precisar pesquisar um grande conjunto de arquivos existentes em S3. grep é executado como uma única agregação MongoDB que combina resultados de pesquisa de texto completo e pesquisa vetorial usando o algoritmo Reciprocal Rank Fusion (RRF), portanto, ele dimensiona sem carregar cada arquivo em seu agente para aplicar filtro neles um por um. glob e ls lidam diretamente com pesquisas de nomes de arquivos e diretórios. Quando um agente chama read, write, edit, upload_files ou download_files, essas chamadas vão diretamente para S3, onde seus arquivos estão. Arquivos adicionados por outras FERRAMENTAS são automaticamente detectados e índice pelo observador do backend.

Antes de instalar o pacote, certifique-se de ter:

  • Uma string de conexão do MongoDB Atlas

  • Credenciais da AWS (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION), com uma política do IAM que concede:

    • s3:GetObject, s3:PutObject, s3:ListBucket e s3:DeleteObject no seu bucket S3

    • bedrock:InvokeModel em amazon.titan-embed-text-v2:0, na mesma região que AWS_DEFAULT_REGION, necessário se você usar o provedor Bedrock padrão

  • Sua escolha de provedor de embedding: Bedrock (o padrão, usa as credenciais da Amazon Web Services acima) ou OpenAI (defina EMBEDDING_PROVIDER=openai e forneça um OPENAI_API_KEY)

Para instalar o pacote, determine se você deseja que o MongoDB gere embedding de pesquisa usando AWS Bedrock ou OpenAI, e execute o comando correspondente:

pip install "langchain-mongodb-deepagents-vfs[bedrock]"
pip install "langchain-mongodb-deepagents-vfs[openai]"

Instancie MongoFilesystemBackend com o nome do seu bucket S3 e a string de conexão do Atlas. O exemplo a seguir grava dois arquivos em S3 e, em seguida, demonstra cada método de pesquisa:

  • grep pesquisa o conteúdo do arquivo

  • glob corresponde a caminhos de arquivo por padrão

  • ls exibe o conteúdo de um diretório

from langchain_mongodb_deepagents_vfs import MongoFilesystemBackend
# Instantiate the backend
backend = MongoFilesystemBackend(
s3_bucket_name="<bucket-name>", # S3 bucket that stores your files
mongodb_connection_string="<connection-string>", # MongoDB Atlas connection string
)
# Write two files to S3: one .txt, one .md, so glob can demonstrate
# filtering by extension
backend.write("mongodb_vfs/docs/notes.txt", "Our authentication flow uses OAuth 2.0.")
backend.write("mongodb_vfs/docs/overview.md", "This directory contains onboarding docs.")
# Search for files that mention "authentication flow"
# Newly written files can take a few seconds to become searchable
result = backend.grep("authentication flow", path="mongodb_vfs/docs/")
print("grep matches:")
for match in result.matches or []:
print(match["path"], match["line"], match["text"])
# Find files that match a glob pattern
result = backend.glob("*.txt", path="mongodb_vfs/docs/")
print("glob matches:", result.matches)
# List the contents of a directory
result = backend.ls("mongodb_vfs/docs/")
print("ls entries:", result.entries)
print("init_errors:", backend.init_errors)

Por padrão, o backend restringe todas as operações ao prefixo mongodb_vfs/ no seu bucket. Passe um valor s3_prefix diferente para MongoFilesystemBackend para alterar isso, ou s3_prefix="" para acesso a todo o bucket.

Observação

Para aprender como conectar este backend a um agente DeepAgents, consulte o Guia de início rápido do DeepAgents.

O MongoDB Agent Toolkit é uma coleção de FERRAMENTAS que você pode passar para um LangGraph React Agent para que ele possa interagir com seus recursos MongoDB.

Nome
Descrição

MongoDBDatabaseToolkit

Uma ferramenta para query de um banco de dados MongoDB .

InfoMongoDBDatabaseTool

Uma ferramenta para obter metadados sobre um banco de dados MongoDB .

ListMongoDBDatabaseTool

Uma ferramenta para obter os nomes de collection de um banco de dados MongoDB .

QueryMongoDBCheckerTool

Uma ferramenta que chama um LLM para verificar se uma consulta ao banco de dados está correta.

from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from langchain_mongodb.agent_toolkit import (
MONGODB_AGENT_SYSTEM_PROMPT,
MongoDBDatabase,
MongoDBDatabaseToolkit,
)
db_wrapper = MongoDBDatabase.from_connection_string(
"<connection-string>", database="<database-name>"
)
llm = ChatOpenAI(model="gpt-4o-mini", timeout=60)
toolkit = MongoDBDatabaseToolkit(db=db_wrapper, llm=llm)
system_message = MONGODB_AGENT_SYSTEM_PROMPT.format(top_k=5)
test_query = "Which country's customers spent the most?"
agent = create_react_agent(llm, toolkit.get_tools(), prompt=system_message)
agent.step_timeout = 60
events = agent.stream(
{"messages": [("user", test_query)]},
stream_mode="values",
)
messages = []
for event in events:
messages.extend(event["messages"])
print(messages[-1].content)

Observação

Os carregadores de documentos são FERRAMENTAS que o ajudam a carregar dados para seus aplicativos LangChain.

MongoDBLoader é um carregador de documento que retorna uma lista de documentos de um banco de banco de dados MongoDB .

from langchain_mongodb.loaders import MongoDBLoader
loader = MongoDBLoader.from_connection_string(
connection_string="<connection-string>", # MongoDB cluster URI
db_name="langchain_db", # Database that contains the collection
collection_name="documents", # Collection to load documents from
filter_criteria={"category": "ai"}, # Optional document to specify a filter
field_names=["title", "summary"], # Optional list of fields to include
metadata_names=["category"], # Optional metadata fields to extract
)
docs = loader.load()

Observação

MongoDBChatMessageHistory é um componente que permite armazenar e gerenciar históricos de mensagens de bate-papo em um banco de dados do MongoDB. Ele pode salvar mensagens geradas pelo usuário e pela IA associadas a um identificador de sessão exclusivo. Use este componente para aplicativos que acompanham interações ao longo do tempo, como chatbots.

from langchain_mongodb.chat_message_histories import MongoDBChatMessageHistory
chat_message_history = MongoDBChatMessageHistory(
session_id="<session-id>", # Unique session identifier
connection_string="<connection-string>", # MongoDB cluster URI
database_name="langchain_db", # Database to store the chat history
collection_name="chat_history", # Collection to store the chat history
)
chat_message_history.add_user_message("Hello")
chat_message_history.add_ai_message("Hi")
print(chat_message_history.messages)
[HumanMessage(content='Hello', additional_kwargs={}, response_metadata={}), AIMessage(content='Hi', additional_kwargs={}, response_metadata={}, tool_calls=[], invalid_tool_calls=[])]

Você pode usar os seguintes armazenamentos de dados personalizados para gerenciar e armazenar dados no MongoDB.

MongoDBDocStore é um armazenamento personalizado de chave-valor que utiliza o MongoDB para armazenar e gerenciar documentos. Você pode executar operações CRUD como faria em qualquer outra coleção do MongoDB.

from langchain_mongodb.docstores import MongoDBDocStore
# Replace with your MongoDB connection string and namespace
connection_string = "<connection-string>"
namespace = "<database-name>.<collection-name>"
# Initialize the MongoDBDocStore
docstore = MongoDBDocStore.from_connection_string(connection_string, namespace)

Observação

MongoDBByteStore é um armazenamento de dados personalizado que usa o MongoDB para armazenar e gerenciar dados binários, especificamente dados representados em bytes. Você pode executar operações CRUD com pares de valores-chave em que as chaves são cadeias de caracteres e os valores são sequências de bytes.

from langchain_community.storage.mongodb import MongoDBByteStore
# Instantiate the MongoDBByteStore
mongodb_store = MongoDBByteStore(
connection_string="<connection-string>", # MongoDB cluster URI
db_name="langchain_db", # Name of the database
collection_name="byte_store", # Name of the collection
)
# Set values for keys
mongodb_store.mset([("key1", b"hello"), ("key2", b"world")])
# Get values for keys
values = mongodb_store.mget(["key1", "key2"])
print(values)
# Iterate over keys
for key in mongodb_store.yield_keys():
print(key)
# Delete keys
mongodb_store.mdelete(["key1", "key2"])
[b'hello', b'world']
key1
key2

Observação

Para saber como integrar o MongoDB com o LangGraph, consulte Integrar o MongoDB com o LangGraph.

Para blocos de anotações interativos do Python, consulte Repositório de Cadernos Docs e Repositório de Casos de Uso de IA generativa.