Integre o MongoDB com o Mastra

Você pode integrar o MongoDB ao Mastra para construir agentes de IA. O Mastra é uma estrutura de agente TypeScript de código aberto que fornece primitivos para criar aplicativos de IA, incluindo fluxos de trabalho, RAG e avaliações.

Importante

Esta integração é mantida pela comunidade. Para saber mais, consulte a documentação do Mastra ou o repositório do Mastra GitHub.

Visão geral

Você pode usar o MongoDB com o Mastra para criar agentes de IA. Ao combinar o MongoDB Vector Search com a estrutura de agente do Mastra, você pode implementar os seguintes recursos para seus agentes:

Armazene e recupere incorporações vetoriais usando o MongoDB como banco de dados vetorial
Filtre seus resultados de pesquisa vetorial usando a sintaxe de consulta do MongoDB
Implemente o RAG como uma ferramenta em seus agentes
Armazene a memória do seu agente no MongoDB

Instalação e configurar

Para utilizar o MongoDB com Mastra, instale o pacote @mastra/mongodb :

npm install @mastra/mongodb

Para começar a usar o Mastra e saber como criar um projeto,consulte Instalar o Mastra.

Vector Store

MongoDB é um supported database <https://mastra.ai/en/docs/rag/vector-databases#supported-databases> em Mastra. A MongoDBVector classe permite armazenar e recuperar incorporações vetoriais do MongoDB . Você pode usar esse componente para implementar o RAG armazenando incorporações de seus dados e recuperando-os usando a Vector Search do MongoDB .

Esse componente exige que você crie um índice de Vector Search do MongoDB .

Uso

Para usar o armazenamento de vetores MongoDB com Mastra, importe a classe MongoDBVector , crie um objeto com a classe e especifique seus detalhes de conexão MongoDB . Por exemplo:

import { MongoDBVector } from '@mastra/mongodb'
// Instantiate MongoDB as a vector store
const mongoVector = new MongoDBVector({
  uri: process.env.MONGODB_URI,        // MongoDB connection string
  dbName: process.env.MONGODB_DATABASE // Database name
})

Métodos

Esta seção destaca os métodos mais relevantes para trabalhar com o MongoDB como um repositório de vetores. Para obter uma lista completa dos métodos, consulte a documentação do Mastra.

Antes de pesquisar suas incorporações, você deve criar um índice de pesquisa vetorial em sua collection. O parâmetro dimension deve corresponder ao número de dimensões exigidas pelo seu modelo de incorporação.

// Create a vector search index
await mongoVector.createIndex({
  indexName: "vector_index",       // Name of the index
  dimension: 1536,                 // Must match your embedding model's dimensions
});

Após criar um índice, é possível armazenar incorporações de vetor com metadados associados. Para obter um exemplo completo, consulte o exemplo de incorporações upsert do Mastra.

import { openai } from "@ai-sdk/openai";
import { MongoDBVector } from "@mastra/mongodb";
import { MDocument } from "@mastra/rag";
import { embedMany } from "ai";
// Create a document from text
const doc = MDocument.fromText("Your text content...");
// Split document into chunks
const chunks = await doc.chunk();
// Generate embeddings for each chunk
const { embeddings } = await embedMany({
  values: chunks.map(chunk => chunk.text), // Text content to embed
  model: openai.embedding("text-embedding-3-small"), // Embedding model
});
// Instantiate MongoDB as a vector store
const mongoVector = new MongoDBVector({
  uri: process.env.MONGODB_URI,   // MongoDB connection string
  dbName: process.env.MONGODB_DB_NAME, // Database name
});
// Store vector embeddings with metadata
await mongoVector.upsert({
  indexName: "vector_index",                         // Name of the vector search index
  vectors: embeddings,                               // Array of vector embeddings
  metadata: chunks?.map(chunk => ({ text: chunk.text })), // Associated metadata for each embedding
});

Para recuperar documentos semanticamente semelhantes, primeiro converta sua consulta em uma incorporação e, em seguida, consulte o armazenamento de vetores. Para saber mais, consulte Recuperação no Mastra.

import { openai } from "@ai-sdk/openai";
import { embed } from "ai";
import { MongoDBVector } from "@mastra/mongodb";
// Convert query to embedding
const { embedding } = await embed({
  value: "What are the main points in the article?",  // Query text
  model: openai.embedding("text-embedding-3-small"), // Embedding model
});
// Instantiate MongoDB as a vector store
const mongoVector = new MongoDBVector({
  uri: process.env.MONGODB_URI,        // MongoDB connection string
  dbName: process.env.MONGODB_DATABASE // Database name
});
// Query the vector store for similar documents
const results = await mongoVector.query({
  indexName: "vector_index", // Name of the vector search index
  queryVector: embedding,    // Query embedding vector
  topK: 10,                  // Number of results to return
});
// Display results
console.log(results);

Filtragem de metadados

O armazenamento de vetores do MongoDB oferece suporte à filtragem de metadados em seus resultados de query de pesquisa vetorial:

Use a sintaxe de consulta do Mastra , sem limitações.
Use operadores padrão de comparação, array, lógico e elemento
Usar campos e arrays agrupados em metadados
Filtre os metadados e o conteúdo dos documentos originais

O exemplo de uso a seguir demonstra a sintaxe de filtragem:

// Query with metadata filters
const results = await mongoVector.query({
  indexName: "vector_index",           // Name of the vector search index
  queryVector: queryVector,            // Query embedding vector
  topK: 10,                            // Number of results to return
  filter: {
    category: "electronics",           // Simple equality filter
    price: { $gt: 100 },               // Numeric comparison
    tags: { $in: ["sale", "new"] },    // Array membership
  },
});

Dica

Para obter o desempenho ideal, crie índices em campos de metadados que você filtra com frequência. Para saber mais, consulte Índices de Vector Search do MongoDB .

Para saber mais,consulte Filtros de Metadados.

RAG com agentes de IA

Você pode usar o MongoDB como um armazenamento de vetor dentro dos agentes de IA da Mastra para implementar o RAG agente. Isso permite que seus agentes usem a pesquisa vetorial do MongoDB como uma ferramenta para ajudar a concluir tarefas.

A Mastra também fornece uma MONGODB_PROMPT constante que você pode incluir nas instruções do agente para otimizar a forma como o agente usa o MongoDB para recuperação. Para saber mais, consulte Prompts da Vector Store.

Uso

O exemplo a seguir mostra como criar um agente de IA com recursos de RAG usando o MongoDB como um armazenamento de vetor:

import { Agent } from '@mastra/core/agent';
import { openai } from '@ai-sdk/openai';
import { MONGODB_PROMPT } from "@mastra/mongodb";
import { createVectorQueryTool } from "@mastra/rag";
// Create a vector query tool for the agent
const vectorQueryTool = createVectorQueryTool({
  vectorStoreName: "mongoVector",                    // Name of MongoDB vector store
  indexName: "vector_index",                         // Name of Vector Search index
  model: openai.embedding("text-embedding-3-small"), // Embedding model
});
// Define an AI agent with RAG capabilities
export const ragAgent = new Agent({
  name: 'RAG Agent',                 // Agent name
  model: openai('gpt-4o-mini'),      // LLM model
  instructions: `
  Process queries using the provided context. Structure responses to be concise and relevant.
  ${MONGODB_PROMPT}
  `,
  tools: { vectorQueryTool },        // Tools available to the agent
});

Memória com agentes de IA

Você pode usar o sistema de memória do Mastra com o MongoDB como backend de armazenamento. Isso permite que você, seu agente, se lembre de interações passadas e use essas informações para informar decisões futuras.

Para obter um tutorial completo, consulte Memória com MongoDB.

Uso

O exemplo a seguir demonstra como usar a memória com agentes de IA. Este exemplo usa memoryOptions para fazer o recall da solicitação. Defina lastMessages: 5 como para limitar a recuperação baseada em recenticidade. Use semanticRecall para buscar as mensagens mais relevantes do topK: 3, incluindo messageRange: 2 mensagens adjacentes para o contexto em torno de cada correspondência.

import "dotenv/config";
 
import { mastra } from "./mastra";
 
const threadId = "123";
const resourceId = "user-456";
 
const agent = mastra.getAgent("mongodbAgent");
 
const message = await agent.stream("My name is Mastra", {
  memory: {
    thread: threadId,
    resource: resourceId
  }
});
 
await message.textStream.pipeTo(new WritableStream());
 
const stream = await agent.stream("What's my name?", {
  memory: {
    thread: threadId,
    resource: resourceId
  },
  memoryOptions: {
    lastMessages: 5,
    semanticRecall: {
      topK: 3,
      messageRange: 2
    }
  }
});
 
for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

Recursos adicionais

Para saber mais sobre como usar o Mastra com o MongoDB, consulte:

Voltar

Crie um agente de IA

LangChain JS/TS