ai

Research Vault：开源 Agentic AI 研究助理

发布: (2026年1月9日 GMT+8 08:55)
12 min read
原文: Dev.to

I’m happy to translate the article for you, but I’ll need the full text of the post (the content you’d like translated). Could you please paste the article’s body here? Once I have that, I’ll provide a Simplified Chinese translation while preserving the source link, formatting, markdown, and any code blocks exactly as requested.

没有人谈论的问题

我被研究论文淹没了。不是比喻——我有 50+ PDFs，数十篇文章，以及一个已经变成全职工作的笔记系统。

  • 我读到关于代理记忆限制的重要内容，却忘记它出自哪篇论文，于是花一个小时在 PDF 中搜索。
  • 我会找到三个来源给出相互矛盾的说法，却没有系统的方法来比较它们。

现有工具并未解决这个问题。

  • 笔记应用需要手动组织。
  • 像 NotebookLM 这样的工具在问答方面表现出色，但不能提取我以后可以查询的结构化模式。
  • 传统的 RAG 系统只会对文本进行分块并检索——它们并不会在来源之间进行综合。

盲点： 我们把研究消费当作阅读问题来对待。其实不是，而是一个 知识架构 问题。

我构建的

Research Vault 是一个具备自主性的 AI 研究助理，能够将非结构化的论文转化为 可查询的知识库。

  • 上传论文 → 使用 Claim → Evidence → Context（主张 → 证据 → 背景）模式提取结构化模式。
  • 对这些模式进行语义嵌入。
  • 让你可以使用自然语言在整个文库中进行查询。

方法论： 提取结构化的研究发现（Claim → Evidence → Context），而不是简单地对文本进行粗糙切块。这并非全新概念——只是通过测试和错误处理实现了良好的执行。

注意： 这是一版简化的、通用的实现，基于我个人使用的更专业的研究助理。我去除了复杂性，只保留核心：结构化提取 + 混合检索 + 自然语言查询。

架构层次

层技术原因
编排LangGraph 1.0支持循环的有状态工作流
大语言模型 (LLM)Claude (Anthropic)提取 + 合成
向量嵌入OpenAI text-embedding-3-small语义搜索
向量数据库Qdrant本地优先、可投入生产
后端FastAPI + SQLAlchemy全程异步
前端Next.js 16 + React 19现代、类型安全

未显示： 641 个后端测试、23 个前端测试、完整文档、Docker 部署、CI/CD 流水线。

提取架构

许多 RAG 系统会对文档进行分块处理。有些系统采用结构化提取。Research Vault 采用结构化方法，使用 3‑pass 流水线：

第 1 步：证据清单（俳句）

  • 扫描论文，寻找具体的主张、数据、示例。
  • 将后续所有内容都基于实际的论文内容进行定位。

第 2 步：模式提取（十四行诗）

  • 使用 [E#] 标记提取引用证据的模式。
  • 每个模式可以引用多个证据项。
  • 不是一对一映射——模式会在证据之间进行综合。
  • 添加标签以便分类。

第 3 步：验证（俳句）

  • 检查引用是否准确。
  • 验证模式是否根植于论文内容。
  • 计算最终状态。

为什么要进行三次遍历？

  • 证据锚定可降低幻觉。
  • 验证可捕获提取错误。
  • 结构化模式支持跨文档查询。

模式模式

传统 RAG：

"Context window overflow causes..."

— 仅是一个文本块。

Research Vault 模式：

{
    "name": "Context Overflow Collapse",
    "claim": "When context windows fill, agents compress state...",
    "evidence": "[E3] 'Performance degraded sharply after 15 reasoning steps' (Table 2)",
    "context": "Authors suggest explicit state architecture, not larger windows.",
    "tags": ["state-management", "failure-mode"],
    "paper_id": "uuid-of-paper"
}

这种结构支持以下查询：

  • “作者在代理记忆方面有哪些分歧？”
  • “在多代理系统中有哪些模式会重复出现？”
  • “综合我对工具使用的学习内容。”

我在构建此项目时学到的

教训 1：测试工作流，而不仅仅是单个组件

  • 早期的单元测试覆盖率很好，但完整的流水线仍会以微妙的方式出错。
  • 解决方案： 使用集成测试，在整个工作流端到端运行，并对外部服务（LLM、向量嵌入、Qdrant）进行模拟。这捕获了约 90 % 的真实缺陷。
  • 教训： 在编排系统中，组件测试是必要的 但不足够。故障模式常出现在组件之间的空隙中。

教训 2：先写文档再写代码

我在写任何实现代码之前，先编写了六份完整的文档文件：

  • REQUIREMENTS.md
  • DOMAIN_MODEL.md
  • API_SPEC.md
  • ARCHITECTURE.md
  • OPERATIONS.md
  • PLAN.md

为什么重要：

  • 及早发现设计冲突。
  • 实现过程直截了当（没有歧义）。
  • 前端和后端可以并行开发。
  • 为贡献者提供了上手路径。

教训： 规范驱动的开发并不慢——它更快，因为你不会去构建错误的东西。

教训 3：LLM 对 JSON 会撒谎

本代码库中的每个 LLM 响应解析器都采用了防御性解析，例如：

# verification.py
status_str = response.get("verification_status", "pass")
try:
    status = VerificationStatus(status_str)
except ValueError:
    status = VerificationStatus.passed  # Fallback

我发现 LLM 常常会：

  • 在有效的 JSON 之后添加评论（“以下是我的观察……”）
  • 捏造 schema 中不存在的字段
  • 用字符串而不是枚举返回值
  • 在对象中途截断输出

解决方案： 防御性解析，依据 schema 进行校验，并回退到安全的默认值。

教训 4：本地优先也是一种特性

最初将除 LLM API 调用外的全部工作在本地运行，仅是为了简化 MVP。后来它成为了卖点。

用户需求

  • 研究数据不依赖云端
  • 能够离线工作（大多数情况下）
  • 没有订阅锁定
  • 完全的数据所有权

教训： 看似限制的约束往往可以转化为差异化优势。

没有人展示的生产现实

实际有效的测试金字塔

43 Integration Tests (full pipeline)
├─ 641 Backend Unit Tests (services, workflows, API)
└─ 23 Frontend Tests (components, hooks)

为什么这样分配

  • 集成测试捕获工作流中断
  • 单元测试捕获逻辑错误
  • 前端测试捕获 UI 回归

实际有帮助的文档

大多数项目只有一个 README 并认为完成。Research Vault 包含：

  • 用户指南 (GETTING_STARTED.md) – “我该如何使用？”
  • 运维指南 (OPERATIONS.md) – “我该如何部署/排查故障？”
  • 架构指南 (ARCHITECTURE.md) – “它是如何工作的？”
  • 领域模型 (DOMAIN_MODEL.md) – “有哪些实体？”
  • API 规范 (API_SPEC.md) – “有哪些端点？”

每个文档面向不同的受众并回答不同的问题。

没有人看到的错误处理

已内置优雅降级：

  • LLM 提取失败 → 部分成功（文稿已保存，模式重试）
  • 嵌入生成失败 → 优雅降级（模式已保存，嵌入重试）
  • Qdrant 连接失败 → 仅使用关系型数据继续
  • 查询时上下文溢出 → 优雅截断并给出警告

教训： 生产就绪意味着要处理 20 种可能的故障方式，而不是仅仅 1 种正常情况。

为什么开源

我为自己构建了它。它解决了我的研究混乱。技术并不新颖——结构化抽取、混合存储、多轮验证等都已在其他 RAG 系统中出现。

将其开源

  • 展示我如何构建生产系统
  • 可能帮助有相同问题的其他人
  • 邀请对架构决策的反馈
  • 提供贡献的机会

它展示了

  • 如何测试代理工作流（641 个测试）
  • 如何优雅地处理错误（部分成功、重试）
  • 如何为不同受众编写文档（6 份文档）
  • 如何交付，而不仅仅是原型

对重要的架构选择

决策备选方案为何选择此方案
Structured extractionText chunkingEnables synthesis across papers
3‑pass verificationSingle‑pass extractionReduces hallucination 90 %
Claim/Evidence/ContextSRAL componentsGeneric, broadly applicable
Async throughoutSync + threadingCleaner code, better resource use
SQLite → Postgres pathPostgres from startSimpler local setup, clear migration
Local‑firstCloud‑nativeData ownership, no vendor lock‑in
FastAPI + Next.jsStreamlit/GradioDecoupled, production‑ready

每个选择的优化目标：可靠性优先于功能，清晰度优先于巧妙，架构优先于工具。

接下来

Research Vault 已经可以进入 beta 版。核心工作流——上传、提取、审阅、查询——已能够可靠运行。但仍有更多功能待构建：

短期

  • 模式关系检测（冲突、协议）
  • 多文档综合报告
  • 导出到 Obsidian/Notion

长期

  • 多用户支持
  • 云部署选项
  • 本地 LLM 支持（完全离线）
  • 随时间演进的模式

但首先： 将它交到更多人手中。看看哪些会出问题。了解哪些才是关键。

试一试

The repo is live:

快速入门（≈5 分钟）

git clone https://github.com/aakashsharan/research-vault.git
cd research-vault
cp .env.example .env   # Add your API keys
docker compose up --build

打开应用并上传你的第一篇论文。

要点

RAG 系统存在。结构化抽取存在。LangGraph 项目存在。

重要的是执行：经过测试、文档化、能够处理错误、真正可用。

  • 这并非突破性创新。它只是做得很好。
  • 工具会变化，执行才重要。

交付可用的东西。记录你的学习。分享有帮助的内容。

相关阅读

  • SRAL 框架论文 – (用于代理 AI 的评估框架)
  • SRAL Github –
  • 架构文档 –
  • API 规范 –
Back to Blog

相关文章

阅读更多 »

Mixtral专家模型

概述 Mixtral 8x7B 是一种语言模型，它将任务分配给众多微小的专家，从而实现速度和智能的双重提升。它采用 Sparse Mixtu...