企业官网建设流程全解析

@langchain/mongodb 集成包全解析：从安装配置到向量搜索、缓存与开发测试实战

【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs

@langchain/mongodb是 LangChain.js 官方在 libs/providers/langchain-mongodb 目录下维护的 MongoDB 集成包，通过 MongoDB 官方 Node.js SDK 将 Atlas 的向量检索、语义缓存、聊天历史、KV 存储与嵌入能力无缝接入 LangChain 生态。本文以该包的 README.md 为骨架，结合包内全部源码模块，系统讲解安装时的依赖版本管理、五大核心 API 的用法与底层实现，以及面向贡献者的构建、测试与开发规范，帮助你既能快速上手使用，也能深入参与开发。

一、包概览：一个包，五大能力

@langchain/mongodb的核心入口在 src/index.ts，仅用四行export *向外暴露了五个功能模块：

• chat_history：基于sessionId的多轮对话历史持久化（chat_history.ts）；
• vectorstores：面向 MongoDB Atlas Vector Search 的 KNN 向量检索、MMR 检索与 Rerank 检索（vectorstores.ts）；
• cache：精确匹配的 LLM 响应缓存与基于$vectorSearch的语义缓存（cache.ts）；
• storage：通用的字节级键值存储MongoDBStore（storage.ts）；
• voyage：Voyage AI 嵌入模型客户端，用于为 Atlas 生成向量（voyage.ts）。

从 package.json 可以看出该包的技术约束：运行时要求 Node.js>=20，直接依赖mongodb@^6.20.0，并将@langchain/core声明为^1.0.0的 peer dependency（开发时通过 workspace 引用本仓库的 core 源码）。这些约束直接决定了下面的安装与版本管理方式。

二、安装与依赖版本管理：让 core 只存在一个实例

1. 基础安装

在任意 LangChain.js 项目中安装该集成：

npm install @langchain/mongodb @langchain/core

官方推荐同时显式安装@langchain/core，因为@langchain/mongodb与主包langchain都依赖@langchain/core；当多个 LangChain 包共存时，必须确保它们引用的是同一个@langchain/core实例，否则会出现类型不兼容、单例回调失效等难以排查的运行时问题。

2. 用 resolutions / overrides 锁定 core 版本

包本身提供了通用的@langchain/core版本统一方案。由于 npm、Yarn、pnpm 的强制版本机制字段各不相同，README 给出的标准做法是在项目package.json中同时声明四种字段，最大化兼容性：

{ "name": "your-project", "version": "0.0.0", "dependencies": { "@langchain/core": "^0.3.0", "@langchain/mongodb": "^0.0.0" }, "resolutions": { "@langchain/core": "^0.3.0" }, "overrides": { "@langchain/core": "^0.3.0" }, "pnpm": { "overrides": { "@langchain/core": "^0.3.0" } } }

各字段的适用场景：

• resolutions：Yarn 专用，强制所有嵌套依赖解析到指定版本；
• overrides：npm（8.3+）专用，可覆盖直接与间接依赖的版本；
• pnpm.overrides：pnpm 专用，等价于 npm 的 overrides。

README 建议为三种常见包管理器都加上对应字段。需要注意：当前仓库中该包的 peerDependencies 已声明为@langchain/core: ^1.0.0（见 package.json），因此实际使用时应将示例中的版本号替换为你锁定的 core 大版本，保持与 peer 声明一致。

三、功能模块实战：源码级用法与实现

1. 对话历史：MongoDBChatMessageHistory

聊天历史是构建有状态 Agent 的基础。在 chat_history.ts 中，MongoDBChatMessageHistory只需一个 MongoDB Collection 与一个sessionId即可使用：

const chatHistory = new MongoDBChatMessageHistory({ collection: myCollection, sessionId: 'unique-session-id', }); const messages = await chatHistory.getMessages(); await chatHistory.clear();

其底层实现要点（源码依据见 chat_history.ts）：

• getMessages()以{ sessionId: <id> }查询整条文档，将存储的messages数组经mapStoredMessagesToChatMessages还原为BaseMessage[]；
• addMessage()使用$push+upsert: true追加消息，会话文档不存在时自动创建；
• clear()直接按sessionId删除整条文档；
• 构造时调用collection.db.client.appendMetadata({ name: "langchainjs_chat_history" })，便于 MongoDB Atlas 端识别流量来源。

2. 键值存储：MongoDBStore

MongoDBStore 是@langchain/core中BaseStore<string, Uint8Array>的 MongoDB 实现，适合存储记忆、缓存等字节数据。它支持三个可配置项（源码默认值见 storage.ts）：

官方示例展示了其基本读写：

const client = new MongoClient(process.env.MONGODB_ATLAS_URI); const collection = client.db("dbName").collection("collectionName"); const store = new MongoDBStore({ collection }); const docs = [ [uuidv4(), "Dogs are tough."], [uuidv4(), "Cats are tough."], ]; const encoder = new TextEncoder(); const docsAsKVPairs: Array<[string, Uint8Array]> = docs.map( (doc) => [doc[0], encoder.encode(doc[1])] ); await store.mset(docsAsKVPairs);

从实现上看（storage.ts），mset通过bulkWrite批量updateOne加upsert写入；mget用$in一次取回全部键；mdelete按主键批量删除；yieldKeys(prefix)则将前缀转成正则（自动转义特殊字符、把末尾*还原为.*）后以$regex扫描并返回去前缀后的键名。

3. LLM 响应缓存：MongoDBCache 与 MongoDBAtlasSemanticCache

cache.ts 提供了两类缓存：

• MongoDBCache（精确匹配）：文档结构为{ prompt, llm, return_val }。lookup按prompt+llm精确查询，return_val内存的是序列化后的 Generation JSON 字符串；update使用updateOne+upsert覆盖写入；clear(filter)支持按条件批量清理。

• MongoDBAtlasSemanticCache（语义缓存）：核心是在聚合管道中使用$vectorSearch按查询向量检索最相似的已缓存结果（cache.ts）。构造参数包括：

  参数	说明
  collection	存放缓存的集合（含embedding向量字段）
  embeddingModel	实现EmbeddingsInterface的嵌入模型
  indexName	Atlas 向量索引名，默认"default"
  scoreThreshold	相似度阈值，低于该值的缓存命中视为未命中（默认不限制）
  waitUntilReady	写入后等待的秒数，用于等待向量索引最终一致后再查询

  它的查询管道会先$vectorSearch（limit: 1、numCandidates: 20），再用$match按模型名过滤llm_string字段，并通过extractModelName从llmString的正则匹配中提取model_name或model（cache.ts）。写入新缓存时通过waitUntilReady可选的延迟等待让向量索引刷新。此外fixArrayPrecision会把整数向量值加上1e-15微扰，避免 Atlas 向量检索时整数未被自动转换为浮点而导致精度问题。

4. 向量检索：MongoDBAtlasVectorSearch

MongoDBAtlasVectorSearch是该包最核心的类，围绕 Atlas Vector Search 实现近似最近邻（ANN / KNN）检索。构造参数（vectorstores.ts）：

两种嵌入模式（重要特性）：构造函数支持两种调用约定（vectorstores.ts）：

• 手动嵌入模式：new MongoDBAtlasVectorSearch(embeddings, args)，客户端用嵌入模型生成向量后写入，查询时也由客户端嵌入文本；
• 自动嵌入模式：new MongoDBAtlasVectorSearch(args)，省略 embeddings 参数，此时内部使用会抛错的AutoEmbeddingStub，向量完全由 MongoDB Atlas 服务端（需配置 Atlas 的自动嵌入索引）负责生成，addDocuments只写入文本，similaritySearchWithScore走query: { text }的文本型$vectorSearch（vectorstores.ts）。

检索 API：

• similaritySearch(query, k = 4, filter)：返回Document[]；
• similaritySearchWithScore(query, k = 4, filter)：返回[Document, number][]，数字为vectorSearchScore；
• maxMarginalRelevanceSearch(query, { k, fetchK = 20, lambda = 0.5, filter })：在相似性基础上引入多样性控制（lambda为 0 时多样性最大、为 1 时完全偏向相似性），内部先取fetchK个候选再经maximalMarginalRelevance精选，仅手动嵌入模式支持；
• delete({ ids })：按_id每 50 个一批分块删除；
• addVectors/addDocuments：写入向量或文档，可传入options.ids指定主键以upsert方式写入，注意options.ids长度必须与向量/文档数量一致，否则抛错。

过滤器FilterType（vectorstores.ts）支持三类组合：

• preFilter：进入$vectorSearch.filter的 Atlas Search 预过滤条件；
• postFilterPipeline：$vectorSearch之后追加的聚合管道（如$match）；
• includeEmbeddings：为true时结果中保留embeddingKey字段（MMR 检索内部依赖此字段）。

同时fromTexts/fromDocuments静态工厂方法同样兼容手动嵌入与自动嵌入两种调用约定（vectorstores.ts），例如自动嵌入模式下可写作fromTexts(texts, metadatas, dbConfig)。

Rerank 支持：传入rerankOptions（模型如rerank-2、rerank-2.5-lite等）后，检索管道会在$vectorSearch后追加$rerank与$addFields: { rerankScore: { $meta: "score" } }，最终把 rerank 得分写入文档metadata.relevanceScore（vectorstores.ts）。自动嵌入模式下亦可组合文本检索与 Rerank。

5. 嵌入模型：VoyageEmbeddings

VoyageEmbeddings 是对 Voyage AI 嵌入 API 的封装，主要参数：

实现上，embedDocuments按batchSize分批并Promise.all并发请求；请求经由AsyncCaller管理重试，非瞬态的 4xx 错误会携带status从而跳过重试（voyage.ts）。该嵌入模型既可作为手动嵌入模式下的embeddings，也能与语义缓存、向量检索组合使用。

四、开发指南：从零构建、测试到新增入口点

如果你想为@langchain/mongodb贡献代码或本地调试，README 给出了完整的开发流程。

1. 安装依赖与构建

仓库采用 pnpm workspace + turbo 管理（见仓库根目录 package.json 与 turbo.json）。在包目录内：

pnpm install pnpm build

若在仓库根目录，可用 turbo 过滤器只构建该包：

pnpm build --filter @langchain/mongodb

2. 测试规范

测试文件必须放在src/下的tests/目录中：单元测试以.test.ts结尾，集成测试以.int.test.ts结尾。例如本包中 voyage.test.ts 为单元测试，vectorstores.int.test.ts、cache.int.test.ts、chat_history.int.test.ts、storage.int.test.ts 均为集成测试。运行命令：

pnpm test # 单元测试 pnpm test:int # 集成测试（需 MongoDB Atlas）

集成测试需要一个 Atlas 实例，二选一：

• 指定远程/本地 Atlas URI：通过环境变量MONGODB_ATLAS_URI指向已有集群，且该用户需要对langchain_test数据库具备 readWrite 权限：

  MONGODB_ATLAS_URI='<atlas URI>' pnpm test:int

• 自动启动本地 Atlas（testcontainers）：未设置MONGODB_ATLAS_URI时，测试套件会尝试用 testcontainers 在容器中拉起本地 Atlas。从 tests/setup.ts 的实现可见，它使用mongodb/mongodb-atlas-local:preview镜像，并自定义了ReadyWhenMongotEstablished启动检查策略——通过尝试创建并删除一个knnVector搜索索引来确认 mongot 进程就绪（setup.ts），这要求本机装有 Docker 等容器引擎。容器启动失败时会给出明确错误提示，引导你改用MONGODB_ATLAS_URI。另外该镜像会读取宿主机的VOYAGE_API_KEY或VOYAGEAI_API_KEY以启用自动嵌入测试（setup.ts）。

3. Lint 与格式化

提交代码前运行：

pnpm lint && pnpm format

4. 新增入口点

若要导出新文件，两种方式任选其一：

• 在 src/index.ts 中 import 并 re-export；
• 或者在 package.json 的exports字段中补充新入口（当前 exports 已提供 ESM 与 CJS 双格式产物，分别对应dist/index.js与dist/index.cjs，并附带.d.ts类型声明），然后运行pnpm build让 tsdown 生成新入口。

五、小结

@langchain/mongodb把 MongoDB Atlas 的能力完整映射到了 LangChain.js 的核心抽象上：BaseListChatMessageHistory、BaseStore、BaseCache与VectorStore均有开箱即用的 MongoDB 实现，叠加 Atlas 原生向量检索、语义缓存与 rerank，可以在一套基础设施上同时支撑对话记忆、KV 存储、LLM 缓存与 RAG 检索。本文既覆盖了 README 中的安装依赖管理与开发测试流程，也深入到 cache.ts、vectorstores.ts 等源码，帮助你在实际项目中正确选型与排障，并顺畅地参与到该包的后续开发中。

【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs