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

> 一个专为Obsidian笔记库设计的混合RAG系统，融合向量检索与知识图谱技术，支持多格式文档处理、智能分块、多模型切换，以及基于知识图谱的查询扩展，为个人知识管理提供强大的AI问答能力。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-13T22:44:40.000Z
- 最近活动: 2026-06-13T22:52:45.761Z
- 热度: 150.9
- 关键词: RAG, Obsidian, 知识图谱, 向量检索, Flask, 知识管理, LLM, Python
- 页面链接: https://www.zingnex.cn/forum/thread/vaultrag-obsidianrag
- Canonical: https://www.zingnex.cn/forum/thread/vaultrag-obsidianrag
- Markdown 来源: ingested_event

---

## 原作者与来源

- **原作者/维护者：** faielli
- **来源平台：** GitHub
- **原始标题：** Python-RAG-vault / VaultRAG
- **原始链接：** https://github.com/faielli/Python-RAG-vault
- **发布时间：** 2026年6月13日

---

## 项目概述

VaultRAG 是一个专为 Obsidian 笔记库设计的混合式检索增强生成（RAG）系统，巧妙地将**向量检索**与**知识图谱**相结合，为个人知识管理场景提供了强大的AI问答能力。该系统采用 Flask 后端架构，支持多种文档格式处理，并具备智能分块、多模型切换、增量索引等高级功能。

对于使用 Obsidian 管理大量笔记、文献和学习资料的研究者、学生和知识工作者而言，VaultRAG 提供了一种将静态笔记库转化为可交互知识库的有效方案。

---

## 核心架构设计

VaultRAG 采用模块化架构，通过依赖注入模式（`VaultRagContext` dataclass）实现组件间的解耦，避免了全局变量的滥用。系统核心组件包括：

### 主要模块分工

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

这种设计使得系统各组件职责清晰，便于维护和扩展。

---

## 混合检索机制：向量+图谱

VaultRAG 的核心创新在于其**混合检索策略**，将传统的向量语义检索与知识图谱的关系推理相结合：

### 向量检索层

系统使用 `all-MiniLM-L6-v2`（384维）作为默认文本嵌入模型，针对代码内容还可切换至 `flax-sentence-embeddings/st-codesearch-distilroberta-base`。文档被切分为500字符的块，重叠50字符，确保语义连续性。

### 知识图谱层

知识图谱的构建是一个亮点功能：

1. **三元组提取**：系统从每个文档中采样3个chunk，通过LLM提取最多15个`主体|关系|客体`三元组
2. **增量构建**：支持仅处理新增文件，避免重复计算
3. **查询扩展**：当用户提问时，系统会：
   - 对查询进行分词（≥3字符的词汇）
   - 计算与图谱节点的加权重叠分数
   - 选取Top-N种子节点
   - 扩展1跳邻居（前驱+后继节点）
   - 收集关联的源文件和关系文本

这种混合策略有效解决了纯向量检索在复杂关系推理上的局限，特别适合处理笔记之间的引用、概念关联等场景。

---

## 多格式文档支持

VaultRAG 支持丰富的文档格式，使其能够处理多样化的知识库内容：

| 格式 | 处理方式 |
|------|----------|
| Markdown, TXT | 直接读取 |
| PDF | PyMuPDF提取文本；扫描版自动 fallback 到Tesseract OCR（200 DPI） |
| DOCX | python-docx解析 |
| EPUB | ebooklib + BeautifulSoup提取HTML内容 |
| ODT, ODS | odfpy解析 |
| HTML, HTM | BeautifulSoup提取纯文本 |

对于意大利语和英语混合的文档，系统配置 `ita+eng` 作为Tesseract OCR语言，展现了良好的多语言支持能力。

---

## 智能功能特性

### 增量索引机制

系统通过维护 `{path: mtime}` 映射实现智能增量索引。当文件修改时间未变化时，直接跳过处理，大幅提升了重复索引的效率。

### 重复内容检测

配置 `dup_threshold=0.97` 的余弦相似度阈值，可有效识别并处理重复上传的内容，避免知识库冗余。

### 对话历史管理

- 保留最近20轮对话历史（`max_history=20`）
- 每次交互自动保存为Markdown文件到 `_chat/` 目录
- 包含YAML frontmatter，记录问题、回答和来源链接

### 学科上下文过滤

支持按学科/文件夹设置上下文过滤，当过滤器未返回结果时自动回退到全局搜索，兼顾精确性与召回率。

---

## 技术配置要点

### 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 提供了一个功能完整、架构清晰的参考实现。