将MongoDB与 Vercel AI SDK 集成

您可以将MongoDB与 Vercel AI SDK 集成，Vercel AI SDK 是一个用于构建AI应用程序和代理的 TypeScript框架。该集成可从 @mongodb-developer/vercel-ai-memory npm包中获取，并为代理提供由MongoDB支持的持久内存。该集成包括以下内存层：

会话内存：存储当前会话的会话轮次
语义记忆：存储有关命名实体的长期知识，例如人员和用户偏好
程序内存：存储操作知识，例如任务和工作流程
情景记忆：存储关键事件和结果的记录
暂存器内存：存储临时工作笔记，您可以将其提升为情景记忆

MongoDB集成将内存存储在MongoDB中，自动创建MongoDB Vector Search 索引，并将保留策略应用于每个内存层级。您可以使用客户端模型生成嵌入，也可以使用Atlas自动嵌入在服务器端生成嵌入。

开始体验

要完成配置 Vercel AI SDK 以使用MongoDB 的教程，请参阅开始使用MongoDB Vercel AI SDK 集成。

安装

要为 Vercel AI SDK 安装MongoDB内存提供商程序，运行以下命令：

npm install @mongodb-developer/vercel-ai-memory

该包需要 ai、mongodb 和 zod 软件包作为依赖项。此页面还引用了 Voyage AI嵌入模型，该模型需要 voyage-ai-provider包。要安装这些依赖项，运行以下命令：

npm install ai mongodb zod voyage-ai-provider

注意

该集成支持 Vercel AI SDK v6 和 v7。

使用

本节介绍如何创建使用MongoDB内存提供商代理。

创建内存提供者

要创建MongoDB内存提供商程序，请调用 createMongoDBMemory() 方法并将MongoDB连接字符串和嵌入模型作为参数传递。选择 Voyage AI 或 OpenAI标签页可查看使用相应嵌入模型提供商的示例：

要使用 Voyage AI嵌入模型，请安装 voyage-ai-provider包。您在Atlas中创建的 Voyage AI API密钥需要MongoDB Voyage AI端点，您可以使用 createVoyage() 方法的 baseURL 选项指定该端点。要学习；了解如何创建 Voyage AI API密钥，请参阅管理 Voyage AI模型API密钥。

以下示例创建了一个使用 Voyage AI嵌入模型的内存提供商：

import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'import { createVoyage } from 'voyage-ai-provider'
const voyage = createVoyage({  apiKey: process.env.VOYAGE_API_KEY,  baseURL: 'https://ai.mongodb.com/v1',})
const mongodbMemory = createMongoDBMemory({  uri: process.env.MONGODB_URI!,  embedder: voyage.embeddingModel('voyage-4'),})

以下示例创建了一个使用 OpenAI 嵌入模型的内存提供商：

import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'import { openai } from '@ai-sdk/openai'
const mongodbMemory = createMongoDBMemory({  uri: process.env.MONGODB_URI!,  embedder: openai.embedding('text-embedding-3-small'),})

提供商在首次使用工具时连接到MongoDB 。要在第一个请求之前连接并创建搜索索引，请调用 connect() 方法。要在应用程序关闭时关闭MongoDB连接，请调用 close() 方法。

Parameter	类型	必要性	说明
`uri`	`string`	必需	MongoDB 部署的连接字符串。要学习；了解有关查找连接字符串的更多信息，请参阅通过客户端库连接到集群。
`embedder`	`EmbeddingModel`	可选的	任何在客户端生成向量的 Vercel AI SDK 嵌入模型。您必须指定 `embedder` 或 `autoEmbed` 参数，但不能同时指定这两个参数。要学习；了解更多信息，请参阅“嵌入模式”部分。
`autoEmbed`	`{ model: string }`	可选的	Atlas自动嵌入配置。 `model` 值是 Voyage AI模型，例如 `voyage-4`。您必须指定 `autoEmbed` 或 `embedder` 参数，但不能同时指定这两个参数。
`userId`	`string`	Optional	当调用未指定用户标识符时应用的默认用户标识符。默认为 `'default'`。
`sessionId`	`string`	Optional	当调用未指定会话标识符时应用的默认会话标识符。默认为 `'default'`。
`topology`	`TopologyOptions`	Optional	数据库、集合和索引名称、已禁用的内存类型以及额外的过滤字段。要学习；了解更多信息，请参阅“数据拓扑”部分。
`retention`	`RetentionOptions`	Optional	每种内存类型的保留策略。要学习；了解更多信息，请参阅保留策略部分。
`filtering`	`FilteringOptions`	Optional	集成应用于每次向量搜索的筛选器，例如最小重要性和新近度窗口。
`defaults`	`DefaultsOptions`	Optional	当调用未指定默认重要性、搜索限制和相似度指标时，应用这些指标。

创建代理

要将内存提供商连接到代理，请调用MongoDB内存提供商并传递 userId 和 sessionId 参数。然后，将内存工具传递给您的代理。以下示例创建了一个代理，其内存工具的作用域仅限于一个用户和会话：

import { openai } from '@ai-sdk/openai'import { ToolLoopAgent } from 'ai'
const agent = new ToolLoopAgent({  model: openai('gpt-4.1'),  tools: mongodbMemory({ userId: 'alice', sessionId: 'sess-001' }),})

每个内存层级都存储和检索以这些标识符为范围的内存。要使用传递给 createMongoDBMemory() 方法的 userId 和 sessionId 值，请调用不带参数的MongoDB内存提供商。

配置内存提供者

本部分介绍如何通过设置 createMongoDBMemory() 方法参数来自定义MongoDB内存提供商。

嵌入模式

semantic_search、procedural_search 和 episodic_search 命令运行向量搜索查询来检索内存。在运行向量搜索之前，集成会嵌入查询文本。

Atlas支持两种嵌入模式：

手动嵌入：使用您指定的嵌入模型在客户端生成嵌入向量。
自动嵌入 ： MongoDB在服务器端嵌入文本，无需手动生成。要学习；了解更多信息，请参阅自动嵌入。要学习；了解更多信息，请参阅自动嵌入。

选择 Atlas Automated Embedding标签页以允许Atlas自动嵌入查询文本，或选择 Client embedding model标签页以查看默认嵌入行为：

要允许Atlas自动生成和管理嵌入，请将 autoEmbed 参数传递给 createMongoDBMemory() 方法。以下示例展示了此配置：

import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'
const mongodbMemory = createMongoDBMemory({  uri: process.env.MONGODB_URI!,  autoEmbed: { model: 'voyage-4' },})

在此模式下，集成会存储源文本，为 autoEmbed 类型创建向量索引，并发出带有纯文本字符串的 $vectorSearch 查询。 Atlas自动嵌入不需要嵌入API密钥或客户端嵌入管道。

注意

自动嵌入需要启用 Voyage AI的Atlas组织。在专用集群（M10 及更大）上，必须启用存储自动伸缩。

要在客户端生成嵌入，请将 embedder 参数传递给 createMongoDBMemory() 方法。以下示例展示了此配置并使用 OpenAI 嵌入模型：

import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'import { openai } from '@ai-sdk/openai'
const mongodbMemory = createMongoDBMemory({  uri: process.env.MONGODB_URI!,  embedder: openai.embedding('text-embedding-3-small'),})

embedder 参数接受任何实现 Vercel AI SDK EmbeddingModel 接口的模型，包括来自 OpenAI、Cohere 和 Google 的模型。您还可以通过 voyage-ai-provider包使用 Voyage AI嵌入模型。要查看可用的提供商，请参阅 Vercel AI SDK 文档中的AI SDK 提供商。集成会自动检测向量维数，因此您无需进行配置。

数据拓扑

默认下，集成会将内存存储在 agent_memory数据库中，并使用集合和索引部分中描述的默认集合和索引名称。要自定义数据库、集合和索引名称，请将 topology 参数传递给 createMongoDBMemory() 方法。

以下示例为会话层和语义记忆层提供了自定义名称：

createMongoDBMemory({  uri: process.env.MONGODB_URI!,  embedder: voyage.embeddingModel('voyage-4'),  topology: {    dbName: 'my_app',    collections: {      session: 'agent_sessions',      semantic: 'agent_facts',    },    vectorIndexNames: {      semantic: 'agent_facts_vs',    },  },})

选项	类型	说明
`dbName`	`string`	保存内存集合的数据库的名称。默认为 `'agent_memory'`。
`collections`	`Partial<Record<MemoryType, string>>`	每种内存类型的集合名称。要查看默认值，请参阅以下“集合和索引”部分。
`vectorIndexNames`	`Partial<Record<VectorMemoryType, string>>`	使用向量搜索的每个层级的MongoDB Vector Search索引名称。相应层的默认值为 `semantic_vector_index`、`procedural_vector_index` 和 `episodic_vector_index`。
`disable`	`MemoryType[]`	要禁用的内存类型。集成不会为这些类型创建集合或索引，并会从内存工具中删除其命令。
`hideToolCommands`	`MemoryType[]`	集成从模型中隐藏其命令的内存类型。这些内存类型的集合和存储方法仍然可用。将此选项与钩子驱动的会话内存模式一起使用。
`extraFilterFields`	`Partial<Record<VectorMemoryType, string[]>>`	用于作为MongoDB Vector Search 筛选器进行索引的额外标量字段，例如 `tenant_id`，用于多租户部署。

保留策略

要控制内存何时过期，可以为每种内存类型设立保留策略。将 retention 参数传递给 createMongoDBMemory() 方法以配置保留策略。

配置策略时，请指定 mode字段和模式所需的其他字段。下表描述了可用模式及其字段：

模式	字段	说明
`none`	必需： `mode`	记忆永不过期。
`ttl`	必需：`mode`、`ttlSeconds` 可选：`field`	内存在 `ttlSeconds`字段指定的秒数后过期，从索引的 `Date`字段中的时间戳开始计数。
`ttl+importance`	必需：`mode`、`ttlSeconds`、`minImportance` 可选：`field`	生存时间 (TTL) 仅适用于 `importance` 值低于 `minImportance`字段值的内存。
`dynamic`	必需：`mode`、`computeExpireAt` 可选：`refreshOnRead`	`computeExpireAt()` 函数在集成写入内存时计算每个内存的过期时间，并在读取内存且 `refreshOnRead`字段为 `true` 时重新计算该时间。使用此模式可以比很少使用的记忆保留更长时间的重要和经常检索的记忆。

以下示例为语义记忆配置了保留策略，仅在一周后存储重要记忆：

createMongoDBMemory({  uri: process.env.MONGODB_URI!,  embedder: voyage.embeddingModel('voyage-4'),  retention: {    semantic: { mode: 'ttl+importance', ttlSeconds: 604800, minImportance: 6 },  },})

内存类型	默认策略
`session`	`ttl`模式，在文档的 `created_at`字段中的时间戳后 24 小时使内存过期
`scratchpad`	`ttl`模式，使内存在文档的 `created_at`字段中的时间戳后 1 小时过期
`episodic`	`ttl`模式，使内存在文档的 `stats.last_retrieved`字段中的时间戳 1 年后过期
`semantic`	`none`模式，因此内存永不过期
`procedural`	`none`模式，因此内存永不过期

会话内存模式

会话内存支持以下两种模式，这两种模式均由同一集合支持：

工具驱动模式：模型决定何时保存和调用会话轮流
钩子驱动模式：运行时会自动保存和调用会话

选择 Tool-driven 或 Hook-driven标签页，查看相应的代码示例：

在工具驱动模式下，模型通过内存工具调用 session_append 和 session_recent 命令来保存和读取会话轮次。此模式配置最简单，但模型可能选择不保存回合或加载之前的回合。使用工具驱动模式进行原型和演示，在这种模式下，简单性比完整的对话记录更优先级。

以下示例生成响应并允许模型决定何时保存回合：

const result = await agent.generate({  prompt: 'My name is Alice and I am a marine biologist. Remember that.',})

在钩子驱动模式下，运行时会在每次模型调用之前读取先前的轮次，并在工具循环完成后写入每个用户、助手和工具轮次，无论模型做出什么决定。我们建议您在生产中使用此模式。

要在模型中隐藏会话命令，同时保持会话集合可用，请将 topology 参数的 hideToolCommands 选项设立为 ['session']。以下示例在 prepareCall 钩子中恢复会话副本，并在 onFinish 钩子中的每个回合中保留：

import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'import { openai } from '@ai-sdk/openai'import { ToolLoopAgent, isLoopFinished } from 'ai'import { z } from 'zod'
const mongodbMemory = createMongoDBMemory({  uri: process.env.MONGODB_URI!,  embedder: openai.embedding('text-embedding-3-small'),  topology: { hideToolCommands: ['session'] },})
const agent = new ToolLoopAgent({  model: openai('gpt-4o-mini'),
  callOptionsSchema: z.object({    userId: z.string(),    sessionId: z.string(),    prompt: z.string(),  }),
  prepareCall: async ({ options, prompt: _p, messages: _m, ...settings }) => {    const { userId, sessionId, prompt } = options!    const history = await mongodbMemory.loadSession({ userId, sessionId })    return {      ...settings,      tools: mongodbMemory({ userId, sessionId }),      messages: [...history, { role: 'user', content: prompt }],      experimental_context: { userId, sessionId, prompt },    }  },
  onFinish: mongodbMemory.onFinish(),  stopWhen: isLoopFinished(),})

loadSession() 方法返回之前的用户和助手轮次，您可以将其添加到 messages字段的开头。 onFinish() 方法会保留用户提示符以及每条助手和工具消息。集成会将工具轮次存储为脚本记录，但不会将其作为工具结果重放。

在这两种模式下，其他内存层仍受模型控制。模型应选择要保存和调用的语义、程序和情节记忆，而不是每次都写入记忆。

内存工具命令

该集成提供了一个 memory 工具，该工具接受 command字段并将命令发送到相应的内存层级。下表描述了每个层级的可用命令：

内存层级	命令	说明
会话	`session_append` `session_recent`	`session_append` 命令保存回合，`session_recent` 命令返回最近的回合。
semantic	`semantic_save` `semantic_search`	`semantic_save` 命令保存实体知识，`semantic_search` 命令运行向量搜索来检索实体知识。语义记忆是暂时版本化的，并且它们的历史记录会被保留。
过程式	`procedural_save` `procedural_search`	`procedural_save` 命令保存过程，`procedural_search` 命令运行向量搜索来检索该过程。程序记忆具有临时版本性，并且其历史记录得到保留。
偶发性	`episodic_save` `episodic_search`	`episodic_save` 命令记录事件，`episodic_search` 命令运行向量搜索来检索事件。
Scratchpad	`scratchpad_write` `scratchpad_read` `scratchpad_promote`	`scratchpad_write` 命令写入临时注释，`scratchpad_read` 命令读取当前注释，`scratchpad_promote` 命令将注释提升到情节内存中。
任何层级	`memory_forget`	`memory_forget` 命令标记要删除的特定内存。此命令始终可用，当用户要求代理忘记某项记忆时，您可以使用该命令。

模型会选择要调用的命令，因此您无需显式设立command字段。不过，您可以参考助手的说明中的命令。以下示例显示了一个代理，其指令指定了要使用的命令：

const agent = new ToolLoopAgent({  model: openai('gpt-4.1'),  tools: mongodbMemory({ userId: 'alice', sessionId: 'sess-001' }),  instructions: `You are an assistant with persistent memory.    At the start of each session, call session_recent to restore    context. Save important facts with semantic_save. If the user    asks you to forget something, call memory_forget.`,})

集合和索引

首次使用时，集成会在数据库中创建以下集合：

Collection	默认保留政策	向量索引
`session_memory`	`ttl`模式，在文档的 `created_at`字段中的时间戳后 24 小时使内存过期	无
`semantic_memory`	`none`模式，因此内存永不过期	`semantic_vector_index`，它使用余弦相似度并自动检测嵌入的向量维度
`procedural_memory`	`none`模式，因此内存永不过期	`procedural_vector_index`，它使用余弦相似度并自动检测嵌入的向量维度
`episodic_memory`	`ttl`模式，使内存在文档的 `stats.last_retrieved`字段中的时间戳 1 年后过期	`episodic_vector_index`，它使用余弦相似度并自动检测嵌入的向量维度
`scratchpad_memory`	`ttl`模式，使内存在文档的 `created_at`字段中的时间戳后 1 小时过期	无