obsidian-rag:课程笔记的检索问答系统
目录
《电子电路基础》的课程笔记以 Markdown 形式存放在 Obsidian 中,共 346 篇,按章节目录组织。复习时查找内容的入口是 Obsidian 全文搜索,该方法基于关键词匹配,提问用词与笔记用词不一致时无法命中。
obsidian-rag 是为这批笔记构建的本地检索问答系统。系统对笔记建立索引,检索阶段结合稠密向量与 BM25,答案由大模型生成并附引用编号,检索质量通过两套自建题集衡量。索引与检索管线由 numpy、rank_bm25 和 sentence-transformers 实现,未引入 LangChain 与向量数据库。
系统结构
索引阶段
346 篇 Markdown
├─ 清洗:移除 frontmatter 与图片嵌入,[[双链]] 还原为纯文本
├─ 切块:按标题结构切分,得到 1188 个 chunk(单块 ≤800 字,重叠 100 字)
├─ 编码:bge-m3 生成 1024 维向量,保存为 1188 × 1024 的 float32 数组(约 4.9MB)
└─ 状态:按文件记录 SHA256,供增量更新使用
查询阶段
问题 ─┬─ bge-m3 编码 → 向量召回 top-20 ─┐
└─ jieba 分词 → BM25 召回 top-20 ─┴─ RRF 融合 → 精排 top-5
├─ DeepSeek 生成带 [n] 引用的答案
└─ Streamlit 展示答案与来源
索引构建
文本清洗
索引前移除 YAML frontmatter 与图片嵌入语法,将 Obsidian 双链 [[笔记名]] 还原为纯文本,保留标题与正文。
标题感知切块
笔记的组织方式为「章目录 / 节文件 / 文件内 ## 小标题」,切块直接使用该结构。切块器按 ATX 标题分段,代码块内的 # 不参与识别。每个 chunk 的正文前缀为「笔记名 > H1 > H2」,使 embedding 保留所属章节信息。超过 800 字的章节按段落重新打包,相邻块重叠 100 字;不足 50 字的碎块并入前一块。
chunk_id 由「笔记路径 + 标题路径 + 序号」哈希得到,与正文内容无关。正文修改后 chunk ID 保持不变,评测集中按 chunk 记录的金标引用无需重写。
向量编码
全部 chunk 使用 bge-m3 编码为 1024 维向量并做归一化,以 float32 保存到 index/embeddings.npy。查询向量与文档向量做点积,结果等于余弦相似度。
检索与精排
- 稠密召回:查询经 bge-m3 编码,与文档矩阵做点积,取 top-20。
- 稀疏召回:查询经 jieba 分词,用 rank_bm25 打分,取 top-20。
- 融合:两路结果用 RRF(k=60)合并排序。
- 精排:对两路召回的全部候选(并集,最多 40 条)用 bge-reranker-base 重新打分,取 top-5。
索引检索使用 numpy 做全量点积。1188 条向量的计算在亚毫秒级完成,结果为精确最近邻,没有引入 ANN 索引。当前主要延迟来自 CPU 上的 cross-encoder 精排,单题约 7–11 秒。向量规模达到十万级时可再评估 FAISS 或 hnswlib。
增量索引
state.json 保存每篇笔记内容的 SHA256。索引时按文件比对哈希:
- 哈希未变:复用已有 chunk 与向量;
- 哈希变化:仅对该笔记重新切块与编码;
- 文件删除:对应 chunk 不再写入新索引;
- 解析失败:不写入状态,下次运行重试。
全量重建在 CPU 上约 3–5 分钟,单篇笔记更新耗时在数秒以内。
评测方法
评测题集由作者根据笔记编写,共两套:
- 基础集 46 题:题目使用笔记标题中的关键词,用于回归基线;
- 改写集 78 题:题目避开标题原词,用于衡量语义检索能力。
改写题示例:
MOS 管的源极没有和芯片衬底接到同一个电位时,开启它所需的栅压为什么会变高?漏极电流会怎样?
金标为 18-MOSFET物理基础及电路模型/1.13-体效应与大信号模型.md。
指标定义:
- Recall@5:top-5 结果按笔记去重后包含金标笔记的题目占比;
- MRR@10:top-10 结果按笔记去重后,金标笔记首次出现名次的倒数,取平均。
四种配置的对比:
| 配置 | 基础集 Recall@5 | 基础集 MRR@10 | 改写集 Recall@5 | 改写集 MRR@10 |
|---|---|---|---|---|
| vector | 0.978 | 0.905 | 0.705 | 0.569 |
| bm25 | 0.957 | 0.846 | 0.667 | 0.518 |
| hybrid | 0.978 | 0.918 | 0.679 | 0.580 |
| hybrid + rerank | 1.000 | 0.889 | 0.872 | 0.683 |
基础集中四种配置的差异较小,题目与标题的词重合度较高。改写集上纯向量的 Recall@5 为 0.705,加入精排后为 0.872。
问题记录:RRF 截断候选池
早期版本在 RRF 融合后截取前 20 条送入精排。RRF 的排名由两路名次共同决定,仅被单路召回的文档名次会被压低,可能在这一步被截掉。一个案例中,金标笔记在 BM25 中排第 17,不在向量召回的前 20;RRF 融合后排第 30,未进入精排候选。该笔记实际已被召回,失败发生在候选池截断环节。
修改后,RRF 只用于排序,精排接收两路召回的并集(最多 40 条)。该题金标笔记在修改后排到第 1 位。
HyDE 实验
HyDE(Hypothetical Document Embeddings)先用大模型生成一段假设答案,再用假设答案的向量检索。假设答案的内容可能不准确,用词与行文则更接近真实笔记,可以缩小问题与文档之间的表达差异。
改写集上对四种检索输入做对比,仅测试稠密检索:
| 模式 | Recall@5 | MRR@10 |
|---|---|---|
| 原问题 | 0.705 | 0.569 |
| 单段假设答案 | 0.846 | 0.646 |
| 问题 + 假设答案 | 0.795 | 0.649 |
| 多段假设答案向量平均 | 0.808 | 0.661 |
将 HyDE 接入混合检索与精排后:
| 配置 | Recall@5 | MRR@10 |
|---|---|---|
| hybrid + rerank | 0.872 | 0.683 |
| HyDE + hybrid + rerank | 0.872 | 0.692 |
| HyDE + hybrid(不精排) | 0.769 | 0.636 |
不精排时,HyDE 把混合检索的 Recall@5 从 0.679 提升到 0.769,第一阶段候选确有改善。加入精排后,两种配置的 Recall@5 相同,78 题中 1 胜 1 负 76 平,ΔMRR 为 +0.009,95% 置信区间包含 0。精排已覆盖第一阶段的召回缺口,HyDE 的生成开销与更大的精排候选池未带来可测收益。HyDE 代码保留在 hyde/,未接入默认问答链路。待验证的问题:将精排候选限制为 top-20 时,HyDE 的收益是否重新出现。
生成与界面
- 生成模型为 DeepSeek,prompt 要求答案中的引用标注为
[n],并在答案后列出对应的笔记路径与标题路径。 - 模型输出的
\( \)、\[ \]定界符在渲染前转换为 Streamlit 支持的$...$、$$...$$。 - 未配置 API key 时,问答自动退化为仅检索模式,评测流程不受影响。
- 界面为 Streamlit 单页应用,首次提问需加载模型,约 10–20 秒。
局限
- 数据只覆盖一门课程,结论不适用于其他领域。
- 测试题由作者编写,存在选题偏差。78 题时 1 题约等于 1.3 个百分点,差距只以趋势描述。
- 图片与 PDF 附件未解析,公式以文本形式参与检索。
- CPU 精排单题耗时 7–11 秒,交互延迟较高。
后续工作
- 将改写集扩充至 100 题以上,增加跨章节题与计算题。
- 在 top-20 精排预算下重新评估 HyDE。
- 对比 bge-large-zh-v1.5、gte-multilingual-base 等 embedding 模型。
- 使用 ONNX 或量化精排降低延迟。
- 支持从引用跳转到 Obsidian 对应笔记。
复现
git clone https://github.com/peagothedreamer/obsidian-rag.git
cd obsidian-rag
uv sync
# 将同目录结构的课程笔记放入 notes/电子电路基础/
uv run python -m rag.index
uv run python -m rag.eval --questions eval/questions.paraphrase.jsonl --out reports/eval/paraphrase.md
uv run streamlit run app.py --server.address 127.0.0.1
评测报告与设计文档存放在仓库的 reports/ 与 docs/ 目录。课程笔记不随仓库分发,复现需自备同目录结构的笔记。