Integre o MongoDB com o Mastra

Você pode integrar o MongoDB ao Mastra para construir agentes de IA. O Mastra é um framework 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 aprender mais, consulte a documentação da Mastra ou o repositório do GitHub da Mastra.

Visão geral

Você pode usar o MongoDB com o Mastra para criar agentes de IA. Ao combinar o MongoDB pesquisa vetorial com o framework de agente do Mastra, você pode implementar as seguintes funcionalidades 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 query 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 aprender como criar um projeto, veja Instalar Mastra.

Vector Store

MongoDB é um banco de dados suportado no Mastra. A classe MongoDBVector permite armazenar e recuperar incorporações vetoriais do MongoDB. Você pode usar esse componente para implementar RAG armazenar embeddings de seus dados e recuperá-los usando a pesquisa vetorial do MongoDB.

Esse componente exige que você crie um Índice de Pesquisa Vetorial do MongoDB.

Uso

Para usar o armazenar 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 coleção. 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 aprender 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 ao filtro 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 aninhados em metadados
Filtro nos metadados e no conteúdo dos documentos originais

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

// 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 Pesquisa Vetorial 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 Mastra para implementar 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 constante MONGODB_PROMPT 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 Armazenar.

Uso

O exemplo a seguir mostra como criar um agente de IA com funcionalidades 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 aprender mais sobre o uso do Mastra com o MongoDB, consulte:

Voltar

Crie um agente de IA

Amazon Bedrock