用于LangChain深度智能体的基于MongoDB的虚拟文件系统

人们对人工智能智能体的期望已超越了简单回答问题。现在人们要求它们完成整个工作：制定多步骤计划、研究源文件、创建中间成果，并将部分任务分配给其他智能体，从而将原本需要数天的工作缩短至几小时。只有当智能体能够自信地在文件系统中操作，随时搜索、读取和更新文件时，这样的速度才能实现。LangChain Deep Agents 所用的 MongoDB 虚拟文件系统（VFS）正是为满足这一需求而设计的。它将人们熟悉的文件系统视图与 MongoDB Atlas 以及底层的对象存储（如 S3 存储桶）相结合，从而使智能体拥有一个可搜索的工作空间，其有效性可超越会话、部署和子智能体的限制。使用 Deep Agents 的开发者可以将 Atlas 视为智能体的数据平台，方便地使用全文搜索和向量搜索功能。

以下内容将解释这两个概念，展示 MongoDB 后端在智能体应用中的运作方式，并指出该模式适用于企业系统的场景。

深度智能体及其文件系统工具

深度智能体是在 LangChain 和 LangGraph 之上构建的框架，专为处理复杂的多步骤任务而设计。它内置了规划、子智能体以及类似文件系统的工具，使智能体能够将大型任务分解为多个小操作，而无需将所有内容都放入同一个上下文窗口中。内置的操作包括：

• ls：列出目录，让智能体了解内容的布局
• glob：根据路径模式匹配文件
• grep：检索文件内容
• read：读取文件内容
• write 和 edit：创建或修改文件内容

upload_files和download_files用于处理批量传输

这些工具基于后端接口运行。代理无需知道文件是存储在本地磁盘、LangGraph存储中、对象存储里，还是其他持久化层中。它只需调用相同的文件系统接口，由配置好的后端提供数据。

虚拟文件系统的作用

虚拟文件系统将数据以逻辑路径的形式呈现，同时隐藏其实际存储位置。代理可以看到如docs/、reports/或projects/customer-a/这样的目录，但实际上数据存储在对象存储中，可搜索的副本则存放在数据库里。

在文件系统中导航是分步进行的，这很适合智能体使用。智能体无需使用全量语料提示，只需列出目录，通过文件名模式进行筛选，搜索特定概念，打开相关文件，然后将查找结果记录为新的成果。每一步只获取所需信息，这样智能体就能保持在上下文限制范围内，减少资源消耗。从这个角度看，虚拟文件系统不仅是存储层，更是智能体工作过程中管理上下文的工具。

该包及其路由机制

langchain-mongodb-deepagents-vfs包以即插即用的方式实现了Deep Agents的BackendProtocol。由对象存储支持的语料库在智能体看来就像一个文件系统，而每次请求都会被路由到最能处理它的系统：

• 以搜索为导向的操作（grep、glob、ls）会在 MongoDB Atlas 上执行。
• 针对文件字节的操作（read、write、edit、upload_files、download_files）则直接作用于对象存储。
• 一个后台同步层负责确保搜索结果与对象存储中的数据保持一致。

这样一来，真实数据源与搜索索引便实现了清晰的分离。对象存储保存原始文档，而 Atlas 则存储可搜索的片段、嵌入信息以及路径元数据，这些元素共同使得整个数据集能够被检索到。

有人可能会问，为何搜索功能要独立于系统存在，而不是放在能够统一处理文本搜索、向量搜索和混合搜索的 S3 兼容平台上？这种分离是有意为之的。对象存储擅长存储持久、廉价且寿命长的文件数据，但它并非为同时维护实时索引、对混合查询进行排序以及提供低延迟的结构化元数据查询而设计。Atlas 则是一种操作型数据库，从一开始就将搜索、向量搜索和混合排序作为索引功能。因此，搜索功能运行在专为该目的设计的软件上，而对象存储则继续发挥其自身的优势。

grep 背后的混合搜索

在 grep 的背后，该软件包将 MongoDB Search 与 MongoDB Vector Search 相结合。全文匹配擅长处理精确的术语、标识符、文件名以及罕见的字符串，而向量搜索则适用于处理同义表达和自然语言问题。将二者结合后，用户可以通过同一个界面查找如 MAX_RETRIES 这样的具体值，或询问重试配置的位置。

在 MongoDB 中，这两个结果列表通过 $rankFusion 聚合阶段进行合并。由于排序操作在数据库内部完成，因此无需客户端端的重新排序模块，也就省去了相应的数据传输开销。不过这也会带来其他权衡。在兼容 S3 的平台上，实现全文排序、向量排序及混合排序通常需要整合多个专用系统：一个用于文本处理的引擎、一个用于存储嵌入向量的向量数据库，以及一个用于合并这些结果的重新排序层，每个系统都需配备用于跟踪源数据的索引流程。而在 Atlas 中，一个引擎即可覆盖所有功能，$rankFusion 通过单次原生查询就将它们合并起来。

分块、格式与嵌入向量

分块处理会考虑标记信息。支持的输入格式包括纯文本、Markdown、PDF、DOCX、XLSX、XLS、PPTX和PPT。每个分块都会保留位置元数据，即源文件路径、页码、字符偏移量以及行信息，这样输出结果就能以Deep Agents期望的以行为单位的格式呈现。

嵌入模型默认使用Amazon Bedrock，也可通过插件选项选择OpenAI，同时应用程序可以直接注入任何与LangChain兼容的嵌入实现方式。典型的配置如下：

from deepagents import create_deep_agent
from langchain_mongodb_deepagents_vfs import MongoFilesystemBackend

backend = MongoFilesystemBackend(
    s3_bucket_name="acme-docs",
    mongodb_connection_string="mongodb+srv://<user>:<password>@<cluster>/",
)

agent = create_deep_agent(
    tools=[],
    instructions="You are a research assistant over the ACME documents corpus.",
    backend=backend,
)

之后，该代理会使用普通的文件系统工具，在其推理流程中不会使用任何定制的 MongoDB 或 S3 工具。

双平面架构

可以将该系统视为两个平面：对象存储是存储文件字节的数据平面，而 MongoDB Atlas 则是负责管理元数据、数据块及检索索引的控制与搜索平面。

图示展示了后端如何通过对象存储发送文件字节，以及如何通过 Atlas 执行搜索操作。

当后端对象被创建后，初始化工作会在后台继续进行。索引构建、首次同步以及监视器启动都在守护线程中执行。直接传递的文件操作可以立即完成，而搜索操作则需等待初始同步完成。数据导入过程如下：

1. 列出配置好的 S3 存储桶及前缀下的对象。
2. 下载所有符合条件的对象。
3. 使用对应格式的解析器提取文本。
4. 将文本分割成包含位置元数据的块。
5. 生成嵌入向量。
6. 将这些块及元数据插入 Atlas 中。
7. 配置或验证搜索索引与向量搜索索引。

每个块的规模为512个标记，块与块之间有64个标记的重叠部分。ETags确保了初始同步及后续数据摄入的操作是可重做的，因此未发生变化的对象会被跳过，不会被再次下载或生成嵌入向量。

以下是每种调用的功能说明。ls会向Atlas请求路径元数据并将其整理为目录条目。glob则利用标准的路径模式规则来查找匹配的文件。grep会让Atlas在分块语料库上同时进行全文检索和向量检索，进而返回按相关性排序的搜索结果。read则直接从对象存储中获取当前数据，而非索引，这两者之间存在显著差异——搜索结果用于内容发现，而读取操作则是为了获取原始文档。

存在两种监控模式。轮询式监控器会定期检查对象存储，无需额外的AWS事件处理基础设施；而SQS监控器则通过Amazon SQS接收S3事件通知，更适合需要较低延迟的生产环境同步场景。

搜索的最终一致性

搜索功能被设计为最终一致性机制。首先在 S3 中完成写入操作，随后监控机制会检测到变化，将对象重新分块并嵌入，同时更新索引。因此读取操作能够立即反映 S3 的状态，而 grep、glob 和 ls 等操作则可能需要等到同步与索引生成完成才能得到结果。

在共享工作场景中有一些实用原则：当数据处于高活跃度且被多人共享时直接读取；对于共享文件，可利用 edit 实现乐观并发控制；等到数据集稳定后再使用搜索功能来查找内容。为每个处理节点分配独立的输出命名空间，例如 shared/outputs//，可以进一步减少并行处理节点之间的冲突。

该模式的适用场景

代码探索。编码代理无需面对海量代码，而是可以逐步浏览大型代码库：列出目录结构，使用glob查找特定文件，针对某个概念或标识符运行混合grep查询，读取具体文件内容并进行受ETag保护的编辑。其典型应用包括帮助用户熟悉代码库、调查故障、分析依赖关系与配置、查找需要修复的测试用例，以及从代码中生成文档。

文档语料库。政策、合同、流程、操作手册、产品文档以及客户资料常常堆积在对象存储中，而后端为代理程序提供了类似文件系统的访问方式。文档代理可以搜索针对企业客户的退款政策，找出表述不同的相关段落，打开原始的PDF或DOCX文件，并引用其他路径的内容撰写总结。这适用于需要导航功能的检索增强生成场景，而不仅仅是简单的查询。

多智能体团队。协调员可以在一个共享的文档集中为各专业子智能体分配具体任务。安全智能体负责查找有风险的代码模式，文档智能体负责收集部署步骤和配置参考信息，测试智能体负责寻找相关的测试文件并撰写覆盖率说明，而综合智能体则读取所有内容并生成报告。所有智能体共享同一个命名空间，Atlas则作为发现层存在。

动态文档存储。企业内容一直在变化：报告不断产生，政策有所调整，运营文档也会被修订。由于监控机制能确保Atlas与对象存储保持同步，后期启动的代理无需每次运行都重新构建索引即可查询当前内容。这有助于运行手册辅助工具、合规性与政策监控系统、基于实时更新数据的研究辅助工具、处理产品相关文档及故障排除的客服人员，以及基于共享实施文档工作的合作伙伴辅助人员。

持久化工作空间。深度代理可以将计划、草稿笔记、总结内容及最终成果以文件形式保存下来。将这些文件存储在对象存储中并在Atlas中进行索引，就能形成一种即便系统重启也能保留且可供人员或其他代理查看的工作空间。

生产环境限制与扩展点

在生产环境中使用时，需要通过应用程序、存储配置以及元数据模型来实施访问控制、租户隔离、数据驻留要求、数据保留策略和审计规则。该软件包本身负责Deep Agents文件系统接口的实现，以及从对象存储到Atlas搜索的数据传输路径。

该系统还有很大的扩展空间：可以支持更多类型的对象存储，如Azure Blob Storage或Google Cloud Storage；增加更多的嵌入服务提供商和可配置的策略；添加更多的文档解析器以提高数据导入速度；优化监控机制以实现数据回填并保证数据更新及时；提升搜索质量、过滤功能、排序算法以及元数据管理能力；同时提供更完整的示例、基准测试和部署建议。一个良好的设计原则是将所有与存储相关的功能都封装在对象存储接口之后，这样数据分块器、嵌入器、同步逻辑和搜索路由器只需处理路径、字节、元数据和搜索相关内容，而无需直接调用某个特定提供商的API。

关注点分离是核心理念。智能体看到的是一个简单统一的虚拟文件系统，应用程序将大量各类文档存储在对象存储中作为数据的真实来源，Atlas则将这些数据转换为带有元数据、全文索引、向量索引及混合排序功能的可搜索层，而同步层则确保发现的内容与实时数据集保持一致。