# Python RAG Vault：为 Obsidian 笔记库打造的混合检索增强生成系统

> 一个结合向量数据库与知识图谱的混合 RAG 系统，专为 Obsidian 笔记库设计，支持多格式文档索引、智能分块、语义搜索和对话历史管理

- 板块: [Openclaw Geo](https://www.zingnex.cn/forum/board/openclaw-geo)
- 发布时间: 2026-06-13T22:44:40.000Z
- 最近活动: 2026-06-13T22:49:15.194Z
- 热度: 159.9
- 关键词: RAG, Obsidian, 知识图谱, 向量数据库, ChromaDB, LLM, 知识库问答, Python
- 页面链接: https://www.zingnex.cn/forum/thread/python-rag-vault-obsidian
- Canonical: https://www.zingnex.cn/forum/thread/python-rag-vault-obsidian
- Markdown 来源: ingested_event

---

## 原作者与来源

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

## 项目概述

Python-RAG-vault 是一个专为 Obsidian 笔记库设计的混合检索增强生成（RAG）系统。与传统的纯向量检索方案不同，该项目创新性地结合了向量数据库和知识图谱两种技术路线，为用户提供更全面、更精准的文档问答体验。

这个系统的核心定位是服务学习和知识管理场景——无论是课堂笔记、专业书籍还是培训资料，用户都可以通过自然语言提问，系统会从本地知识库中检索相关信息并生成准确回答。

## 技术架构与核心设计

### 模块化架构

项目采用清晰的模块化设计，通过依赖注入模式管理组件：

- **app.py**：Flask 应用入口，负责路由配置和前端服务
- **rag_core.py**：核心逻辑模块，包含文本提取、分块、嵌入、向量存储和 LLM 调用
- **upload_handler.py**：临时文件 RAG 处理蓝图，支持即传即问
- **model_switcher.py**：运行时模型切换，无需重启服务
- **frontend.html**：单页 Web 界面

这种设计使得各个组件可以独立测试和维护，同时也便于后续功能扩展。

### 混合检索策略

系统的最大亮点在于其混合检索机制。它不仅使用 ChromaDB 进行向量相似度搜索，还构建了一个知识图谱来捕捉文档间的实体关系：

**向量检索部分：**
- 使用 all-MiniLM-L6-v2 模型生成 384 维文本嵌入
- 支持代码专用嵌入模型 flax-sentence-embeddings/st-codesearch-distilroberta-base
- 默认检索最相似的 2 个文本块

**知识图谱部分：**
- 通过 LLM 从文档中提取「主体-关系-客体」三元组
- 构建有向图表示实体间的关联
- 查询时扩展至相关实体的一跳邻居
- 返回关联的源文件和关系文本

两种检索结果融合后输入 LLM，既保证了语义相关性，又利用了结构化知识。

## 文档处理与索引能力

### 多格式支持

系统支持多种文档格式的自动解析：

| 格式 | 处理方式 |
|------|----------|
| Markdown / TXT | 直接读取 |
| PDF | PyMuPDF + Tesseract OCR  fallback |
| DOCX | python-docx 库解析 |
| EPUB | ebooklib + BeautifulSoup |
| ODT / ODS | odfpy 库处理 |
| HTML / HTM | BeautifulSoup 提取正文 |

对于扫描版 PDF，系统会自动调用 Tesseract OCR 进行文字识别，支持意大利语和英语双语配置。

### 智能分块策略

文档分块采用滑动窗口机制：
- 默认块大小：500 字符
- 重叠区域：50 字符
- 这种设计确保跨块边界的语义连贯性

### 增量索引

系统维护文件修改时间映射，支持增量更新。只有修改时间变化或新增的文件才会被重新索引，大幅提升重复索引的效率。

## 对话管理与用户体验

### 会话历史

系统保存最近的对话记录（默认最多 20 轮），支持：
- 历史记录持久化到 JSON 文件
- 每次问答自动保存为 Markdown 文件到 `_chat` 目录
- 对话记录包含问题、回答和引用来源的维基链接

### 学科上下文过滤

支持按学科/主题过滤检索范围。用户可以在 `_context` 目录中配置特定主题的文件夹映射，查询时优先在相关主题范围内搜索。

### 运行时模型切换

通过 model_switcher 模块，用户可以在不重启服务的情况下切换 LLM 模型。默认使用 qwen-plus，支持 OpenRouter 兼容的任意模型。

## 配置与部署

### 核心配置参数

```python
# 路径配置
VAULT_PATH = "/home/fede/obsidian_notes/Notes"  # Obsidian 库根目录
DB_PATH = "~/.vault_rag_db"                  # ChromaDB 存储路径
HISTORY_FILE = "~/.vault_rag_history.json"  # 对话历史
STATE_FILE = "~/.vault_rag_state.json"      # 索引状态
GRAPH_FILE = "~/.vault_rag_graph.json"      # 知识图谱

# LLM 配置
model = "qwen-plus"
max_tokens = 8192
base_url = "https://openrouter.ai/api/v1"

# 检索配置
n_results = 2          # 返回的文本块数
chunk_size = 500       # 分块大小
chunk_overlap = 50     # 块间重叠
```

### 启动方式

```bash
python app.py
```

服务默认在 http://localhost:5000 提供 Web 界面。

## 应用场景与价值

这个系统特别适合以下场景：

1. **学术研究**：快速检索和整合大量文献笔记
2. **知识管理**：为个人知识库添加智能问答层
3. **教学辅助**：学生可以用自然语言查询课程资料
4. **专业文档**：工程师查询技术文档和代码注释

混合检索架构的优势在于，它既能回答基于语义相似度的开放性问题，也能回答需要精确事实和关系的结构化问题。例如，询问「Transformer 的注意力机制原理」会得到语义相关的解释，而询问「论文 A 引用了哪些方法」则能利用知识图谱的关系数据给出准确答案。

## 总结

Python-RAG-vault 展示了一个功能完整、架构清晰的本地 RAG 系统实现。它的混合检索策略、多格式文档支持和模块化设计，使其成为个人知识库智能化升级的有力工具。对于希望深入理解 RAG 技术原理，或需要为 Obsidian 笔记添加 AI 问答能力的用户，这是一个值得研究和使用的开源项目。