obsidian-rag:课程笔记的检索问答系统

目录

仓库:peagothedreamer/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。查询向量与文档向量做点积,结果等于余弦相似度。

检索与精排

  1. 稠密召回:查询经 bge-m3 编码,与文档矩阵做点积,取 top-20。
  2. 稀疏召回:查询经 jieba 分词,用 rank_bm25 打分,取 top-20。
  3. 融合:两路结果用 RRF(k=60)合并排序。
  4. 精排:对两路召回的全部候选(并集,最多 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
vector0.9780.9050.7050.569
bm250.9570.8460.6670.518
hybrid0.9780.9180.6790.580
hybrid + rerank1.0000.8890.8720.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@5MRR@10
原问题0.7050.569
单段假设答案0.8460.646
问题 + 假设答案0.7950.649
多段假设答案向量平均0.8080.661

将 HyDE 接入混合检索与精排后:

配置Recall@5MRR@10
hybrid + rerank0.8720.683
HyDE + hybrid + rerank0.8720.692
HyDE + hybrid(不精排)0.7690.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/ 目录。课程笔记不随仓库分发,复现需自备同目录结构的笔记。

← learning