VaultRAG：面向Obsidian笔记的混合RAG系统，结合向量检索与知识图谱

VaultRAG 核心简介

VaultRAG 是专为 Obsidian 笔记库设计的混合式检索增强生成（RAG）系统，融合向量检索与知识图谱技术，为个人知识管理提供强大AI问答能力。

基础信息：

• 原作者/维护者：faielli
• 来源平台：GitHub
• 发布时间：2026年6月13日
• 项目链接：Python-RAG-vault

核心特性：支持多格式文档处理、智能分块、多模型切换、增量索引及基于知识图谱的查询扩展。

项目背景与定位

VaultRAG 针对 Obsidian 用户（研究者、学生、知识工作者）管理大量笔记、文献和学习资料的需求，提供将静态笔记库转化为可交互知识库的解决方案。作为混合式 RAG 系统，它结合向量检索与知识图谱技术，解决纯向量检索在复杂关系推理上的局限。

核心架构与混合检索机制

模块化架构

系统采用依赖注入模式实现组件解耦，核心模块分工如下：

模块	职责
app.py	Flask 入口点，负责配置、路由和前端服务
rag_core.py	核心逻辑：文本提取、分块、嵌入、ChromaDB管理、知识图谱构建、LLM调用
upload_handler.py	临时文件RAG处理的Flask蓝图（无持久化）
model_switcher.py	运行时模型切换（无需重启应用）
frontend.html	单页应用前端界面

混合检索策略

• 向量检索层：默认使用 all-MiniLM-L6-v2 嵌入模型（代码内容可切换至 flax-sentence-embeddings/st-codesearch-distilroberta-base），文档切分为500字符块（重叠50字符）。
• 知识图谱层：
  1. 从每个文档采样3个chunk，通过LLM提取最多15个三元组（主体|关系|客体）；
  2. 支持增量构建（仅处理新增文件）；
  3. 查询扩展：分词→计算节点重叠分数→选取Top-N种子→扩展1跳邻居→收集关联源文件和关系文本。

多格式支持与智能功能特性

多格式文档处理

格式	处理方式
Markdown, TXT	直接读取
PDF	PyMuPDF提取文本；扫描版 fallback 到Tesseract OCR（200 DPI）
DOCX	python-docx解析
EPUB	ebooklib + BeautifulSoup提取HTML内容
ODT, ODS	odfpy解析
HTML, HTM	BeautifulSoup提取纯文本
注：支持意大利语+英语混合文档的OCR（ita+eng语言配置）。

智能功能

• 增量索引：通过 {path: mtime} 映射跳过未修改文件；
• 重复检测：余弦相似度阈值 dup_threshold=0.97 识别重复内容；
• 对话历史：保留最近20轮，自动保存为带YAML frontmatter的Markdown到 _chat/；
• 学科过滤：按学科/文件夹过滤，无结果时回退全局搜索。

技术配置要点

LLM配置

• 默认模型：qwen-plus
• API端点：OpenRouter（兼容OpenAI API格式）
• 最大token：8192
• 支持运行时模型切换（无需重启服务）

嵌入模型建议

对于意大利语文本为主的场景，建议使用 multilingual-e5-large 替代默认的 all-MiniLM-L6-v2，以提升多语言语义理解能力。

使用场景与价值体现

VaultRAG 适用于以下场景：

1. 学术研究：快速定位文献笔记中的相关概念和引用；
2. 课程学习：整合课件、教材、笔记，构建个人学习助手；
3. 项目知识管理：统一检索技术文档和代码笔记；
4. 写作辅助：基于已有素材创作，确保引用准确。

总结与启示

VaultRAG 为个人知识管理领域的RAG应用提供了典型范式：

• 混合架构是提升检索质量的关键，弥补纯向量检索的关系推理不足；
• 增量处理和重复检测是实用系统的必备能力；
• 多格式支持降低知识库构建门槛；
• 模块化设计便于维护和扩展。

对于希望将Obsidian笔记库AI化的用户，VaultRAG 是功能完整、架构清晰的参考实现。