MongoDB 向量存储
🌐 MongoDB Vector Store
MongoDBVector 类提供了使用 MongoDB Atlas Vector Search 的向量搜索功能。它能够在你的 MongoDB 集合中实现高效的相似性搜索和元数据过滤。
🌐 The MongoDBVector class provides vector search using MongoDB Atlas Vector Search. It enables efficient similarity search and metadata filtering within your MongoDB collections.
安装Direct link to 安装
🌐 Installation
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/mongodb@latest
pnpm add @mastra/mongodb@latest
yarn add @mastra/mongodb@latest
bun add @mastra/mongodb@latest
使用示例Direct link to 使用示例
🌐 Usage Example
import { MongoDBVector } from "@mastra/mongodb";
const store = new MongoDBVector({
id: 'mongodb-vector',
uri: process.env.MONGODB_URI,
dbName: process.env.MONGODB_DATABASE,
});
自定义嵌入字段路径Direct link to 自定义嵌入字段路径
🌐 Custom Embedding Field Path
如果你需要将嵌入存储在嵌套字段结构中（例如，为了与现有的 MongoDB 集合集成），请使用 embeddingFieldPath 选项：
🌐 If you need to store embeddings in a nested field structure (e.g., to integrate with existing MongoDB collections), use the embeddingFieldPath option:
import { MongoDBVector } from "@mastra/mongodb";
const store = new MongoDBVector({
id: 'mongodb-vector',
uri: process.env.MONGODB_URI,
dbName: process.env.MONGODB_DATABASE,
embeddingFieldPath: 'text.contentEmbedding', // Store embeddings at text.contentEmbedding
});
构造函数选项Direct link to 构造函数选项
🌐 Constructor Options
id:
uri:
dbName:
options?:
embeddingFieldPath?:
方法Direct link to 方法
🌐 Methods
createIndex()Direct link to createIndex()
在 MongoDB 中创建一个新的向量索引（集合）。
🌐 Creates a new vector index (collection) in MongoDB.
indexName:
dimension:
metric?:
upsert()Direct link to upsert()
在集合中添加或更新向量及其元数据。
🌐 Adds or updates vectors and their metadata in the collection.
indexName:
vectors:
metadata?:
ids?:
query()Direct link to query()
搜索具有可选元数据过滤的相似向量。
🌐 Searches for similar vectors with optional metadata filtering.
indexName:
queryVector:
topK?:
filter?:
documentFilter?:
includeVector?:
minScore?:
describeIndex()Direct link to describeIndex()
返回有关索引（集合）的信息。
🌐 Returns information about the index (collection).
indexName:
返回：
🌐 Returns:
interface IndexStats {
dimension: number;
count: number;
metric: "cosine" | "euclidean" | "dotproduct";
}
deleteIndex()Direct link to deleteIndex()
删除一个集合及其所有数据。
🌐 Deletes a collection and all its data.
indexName:
listIndexes()Direct link to listIndexes()
列出 MongoDB 数据库中的所有向量集合。
🌐 Lists all vector collections in the MongoDB database.
返回：Promise<string[]>
🌐 Returns: Promise<string[]>
updateVector()Direct link to updateVector()
通过 ID 或元数据过滤器更新单个向量。必须提供 id 或 filter 中的一个，但不能同时提供两者。
🌐 Update a single vector by ID or by metadata filter. Either id or filter must be provided, but not both.
indexName:
id?:
filter?:
update:
update.vector?:
update.metadata?:
deleteVector()Direct link to deleteVector()
通过其 ID 从索引中删除特定的向量条目。
🌐 Deletes a specific vector entry from an index by its ID.
indexName:
id:
deleteVectors()Direct link to deleteVectors()
通过 ID 或元数据过滤器删除多个向量。必须提供 ids 或 filter 中的一个，但不能同时提供两者。
🌐 Delete multiple vectors by IDs or by metadata filter. Either ids or filter must be provided, but not both.
indexName:
ids?:
filter?:
disconnect()Direct link to disconnect()
关闭 MongoDB 客户端连接。使用完存储后应调用此方法。
🌐 Closes the MongoDB client connection. Should be called when done using the store.
响应类型Direct link to 响应类型
🌐 Response Types
查询结果以此格式返回：
🌐 Query results are returned in this format:
interface QueryResult {
id: string;
score: number;
metadata: Record<string, any>;
vector?: number[]; // Only included if includeVector is true
}
错误处理Direct link to 错误处理
🌐 Error Handling
该存储会抛出可以被捕获的类型化错误：
🌐 The store throws typed errors that can be caught:
try {
await store.query({
indexName: "my_collection",
queryVector: queryVector,
});
} catch (error) {
// Handle specific error cases
if (error.message.includes("Invalid collection name")) {
console.error(
"Collection name must start with a letter or underscore and contain only valid characters.",
);
} else if (error.message.includes("Collection not found")) {
console.error("The specified collection does not exist");
} else {
console.error("Vector store error:", error.message);
}
}
最佳实践Direct link to 最佳实践
🌐 Best Practices
- 在过滤器中使用索引元数据字段以实现最佳查询性能。
- 在元数据中使用一致的字段命名以避免意外的查询结果。
- 定期监控索引和集合统计信息，以确保搜索效率。
使用示例Direct link to 使用示例
🌐 Usage Example
使用 MongoDB 的向量嵌入Direct link to 使用 MongoDB 的向量嵌入
🌐 Vector embeddings with MongoDB
嵌入是由内存的 semanticRecall 用来根据含义（而非关键词）检索相关消息的数值向量。
🌐 Embeddings are numeric vectors used by memory's semanticRecall to retrieve related messages by meaning (not keywords).
注意：你必须使用托管在 MongoDB Atlas 上的部署才能成功使用 MongoDB 向量数据库。
此设置使用 FastEmbed，本地嵌入模型，来生成向量嵌入。
要使用此功能，请安装 @mastra/fastembed：
🌐 This setup uses FastEmbed, a local embedding model, to generate vector embeddings.
To use this, install @mastra/fastembed:
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/fastembed@latest
pnpm add @mastra/fastembed@latest
yarn add @mastra/fastembed@latest
bun add @mastra/fastembed@latest
将以下内容添加到你的代理中：
🌐 Add the following to your agent:
import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
import { MongoDBStore, MongoDBVector } from "@mastra/mongodb";
import { fastembed } from "@mastra/fastembed";
export const mongodbAgent = new Agent({
id: "mongodb-agent",
name: "mongodb-agent",
instructions:
"You are an AI agent with the ability to automatically recall memories from previous interactions.",
model: "openai/gpt-5.1",
memory: new Memory({
storage: new MongoDBStore({
id: 'mongodb-storage',
uri: process.env.MONGODB_URI!,
dbName: process.env.MONGODB_DB_NAME!,
}),
vector: new MongoDBVector({
id: 'mongodb-vector',
uri: process.env.MONGODB_URI!,
dbName: process.env.MONGODB_DB_NAME!,
}),
embedder: fastembed,
options: {
lastMessages: 10,
semanticRecall: {
topK: 3,
messageRange: 2,
},
generateTitle: true, // generates descriptive thread titles automatically
},
}),
});
相关Direct link to 相关
🌐 Related