langchain/mongodb 集成包全解析从安装配置到向量搜索、缓存与开发测试实战【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjslangchain/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.tsvectorstores面向 MongoDB Atlas Vector Search 的 KNN 向量检索、MMR 检索与 Rerank 检索vectorstores.tscache精确匹配的 LLM 响应缓存与基于$vectorSearch的语义缓存cache.tsstorage通用的字节级键值存储MongoDBStorestorage.tsvoyageVoyage AI 嵌入模型客户端用于为 Atlas 生成向量voyage.ts。从 package.json 可以看出该包的技术约束运行时要求 Node.js20直接依赖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 } } }各字段的适用场景resolutionsYarn 专用强制所有嵌套依赖解析到指定版本overridesnpm8.3专用可覆盖直接与间接依赖的版本pnpm.overridespnpm 专用等价于 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.tsgetMessages()以{ sessionId: id }查询整条文档将存储的messages数组经mapStoredMessagesToChatMessages还原为BaseMessage[]addMessage()使用$pushupsert: true追加消息会话文档不存在时自动创建clear()直接按sessionId删除整条文档构造时调用collection.db.client.appendMetadata({ name: langchainjs_chat_history })便于 MongoDB Atlas 端识别流量来源。2. 键值存储MongoDBStoreMongoDBStore 是langchain/core中BaseStorestring, Uint8Array的 MongoDB 实现适合存储记忆、缓存等字节数据。它支持三个可配置项源码默认值见 storage.ts参数默认值作用collection必填目标 MongoDB CollectionprimaryKey_id文档主键字段namespace无键名前缀实际键为namespace/keyyieldKeysScanBatchSize1000yieldKeys批量扫描的游标 batchSize官方示例展示了其基本读写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.tsmset通过bulkWrite批量updateOne加upsert写入mget用$in一次取回全部键mdelete按主键批量删除yieldKeys(prefix)则将前缀转成正则自动转义特殊字符、把末尾*还原为.*后以$regex扫描并返回去前缀后的键名。3. LLM 响应缓存MongoDBCache 与 MongoDBAtlasSemanticCachecache.ts 提供了两类缓存MongoDBCache精确匹配文档结构为{ prompt, llm, return_val }。lookup按promptllm精确查询return_val内存的是序列化后的 Generation JSON 字符串update使用updateOneupsert覆盖写入clear(filter)支持按条件批量清理。MongoDBAtlasSemanticCache语义缓存核心是在聚合管道中使用$vectorSearch按查询向量检索最相似的已缓存结果cache.ts。构造参数包括参数说明collection存放缓存的集合含embedding向量字段embeddingModel实现EmbeddingsInterface的嵌入模型indexNameAtlas 向量索引名默认defaultscoreThreshold相似度阈值低于该值的缓存命中视为未命中默认不限制waitUntilReady写入后等待的秒数用于等待向量索引最终一致后再查询它的查询管道会先$vectorSearchlimit: 1、numCandidates: 20再用$match按模型名过滤llm_string字段并通过extractModelName从llmString的正则匹配中提取model_name或modelcache.ts。写入新缓存时通过waitUntilReady可选的延迟等待让向量索引刷新。此外fixArrayPrecision会把整数向量值加上1e-15微扰避免 Atlas 向量检索时整数未被自动转换为浮点而导致精度问题。4. 向量检索MongoDBAtlasVectorSearchMongoDBAtlasVectorSearch是该包最核心的类围绕 Atlas Vector Search 实现近似最近邻ANN / KNN检索。构造参数vectorstores.ts参数默认值说明collection必填存储文档与向量的集合indexNamedefaultAtlas 搜索索引名textKeytext对应pageContent的纯文本字段embeddingKeyembedding向量字段名primaryKey_idupsert 文档使用的主键rerankOptions无{ model, path? }启用 Atlas$rerank语义重排两种嵌入模式重要特性构造函数支持两种调用约定vectorstores.ts手动嵌入模式new MongoDBAtlasVectorSearch(embeddings, args)客户端用嵌入模型生成向量后写入查询时也由客户端嵌入文本自动嵌入模式new MongoDBAtlasVectorSearch(args)省略 embeddings 参数此时内部使用会抛错的AutoEmbeddingStub向量完全由 MongoDB Atlas 服务端需配置 Atlas 的自动嵌入索引负责生成addDocuments只写入文本similaritySearchWithScore走query: { text }的文本型$vectorSearchvectorstores.ts。检索 APIsimilaritySearch(query, k 4, filter)返回Document[]similaritySearchWithScore(query, k 4, filter)返回[Document, number][]数字为vectorSearchScoremaxMarginalRelevanceSearch(query, { k, fetchK 20, lambda 0.5, filter })在相似性基础上引入多样性控制lambda为 0 时多样性最大、为 1 时完全偏向相似性内部先取fetchK个候选再经maximalMarginalRelevance精选仅手动嵌入模式支持delete({ ids })按_id每 50 个一批分块删除addVectors/addDocuments写入向量或文档可传入options.ids指定主键以upsert方式写入注意options.ids长度必须与向量/文档数量一致否则抛错。过滤器FilterTypevectorstores.ts支持三类组合preFilter进入$vectorSearch.filter的 Atlas Search 预过滤条件postFilterPipeline$vectorSearch之后追加的聚合管道如$matchincludeEmbeddings为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.relevanceScorevectorstores.ts。自动嵌入模式下亦可组合文本检索与 Rerank。5. 嵌入模型VoyageEmbeddingsVoyageEmbeddings 是对 Voyage AI 嵌入 API 的封装主要参数参数默认值说明modelNamevoyage-3嵌入模型名apiKey环境变量VOYAGE_API_KEY/VOYAGEAI_API_KEY未提供时构造抛错basePathhttps://api.voyageai.com/v1若使用 Atlas UI 创建的 key应改为https://ai.mongodb.com/v1batchSize8单次请求最多嵌入文档数Voyage 上限为 8inputType/truncation/outputDimension/outputDtype/encodingFormat无透传给 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/mongodb2. 测试规范测试文件必须放在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_URIatlas URI pnpm test:int自动启动本地 Atlastestcontainers未设置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 format4. 新增入口点若要导出新文件两种方式任选其一在 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考