AI RAG + LLM Wiki - Obsidian Plugin

一个面向 Obsidian 的 AI 知识库插件：既保留高级 RAG 检索问答，也新增持久 LLM Wiki 层，让 AI 把原始资料持续整理成可积累、可审计、可互链的 Markdown Wiki。

面向新手的中文教程

• 小白使用教程：从安装、配置 API、构建索引到日常提问、导入 Wiki、保存 FAQ。
• 底层原理图解：用流程图解释 RAG、Embedding、Wiki、FAQ、日志和隐私边界。

隐私提醒：本插件不会内置 API Key。构建索引、提问、导入 Wiki 时，会把必要文本发送到你自己配置的 AI API 服务。自动索引和自动导入默认关闭，建议确认笔记隐私范围后再开启。

✨ 核心特性

🔍 主流最佳实践检索链路

Query → Analysis → Multi-Recall → Fusion → Rerank → Compression → Results

• Query Analysis - Standalone question、Multi-query、Filter inference
• Multi-Recall - Dense + Sparse + Feedback + Meta 四路召回
• Fusion - RRF / Weighted / Distribution-based 融合算法
• Rerank - LLM-based 重排序
• Context Compression - Parent-child chunks、Sentence window、Token budget

🎯 5 个增强功能

1. ASK Vault 可复制 - 一键复制答案到剪贴板
2. 纠正按钮 + 反馈学习 - 纠正错误答案，自动向量化并加入召回
3. AI 全库总结元数据库 - AI 生成笔记摘要，作为独立召回通道
4. 自动增量索引 - 文件变化自动更新索引，2秒防抖，批量处理
5. 用户问答方式学习 - 高频术语统计，触发词选择性加载，性能优化

📊 稳定性与评测

• 日志记录 - 记录每次查询的完整链路
• 评测指标 - Retrieval Relevance、Groundedness、Citation Accuracy
• 网络容错 - 自动重试、超时控制、指数退避
• 错误处理 - 友好的错误提示和降级策略

🧠 持久 LLM Wiki

• 三层结构 - raw sources 保持只读，_wiki/ 由 LLM 维护，_wiki/CLAUDE.md 作为 schema 说明书
• 来源摘要 - 每次导入先生成 sources/ 页面，把原始笔记编译成可引用证据
• 实体/概念融合 - 新资料会融合进已有 entity/concept 页面，而不是直接覆盖旧知识
• 冲突标记 - 新旧信息不一致时保留双方说法，并记录到冲突/待核实列表
• 索引与日志 - 自动维护 index.md 和 log.md，形成可导航、可追踪的知识演化记录
• Wiki 审计 - 检查无入链孤岛、缺失交叉引用、矛盾、过时信息和知识空白

🚀 快速开始

安装

1. 下载最新版本
2. 解压到 .obsidian/plugins/ai-rag-llm-wiki/
3. 在 Obsidian 设置中启用插件

配置

1. 打开设置页

2. 填写 API 配置：

   • API Base URL（OpenAI-compatible）
   • API Key
   • Embedding Model（如 text-embedding-ada-002）
   • Chat Model（如 gpt-4）

3. 调整索引配置：

   • Chunk Size（默认 800）
   • Overlap（默认 150）
   • Top K（默认 6）
   • 文件变更时自动索引默认关闭，建议确认隐私范围后再开启

使用

1. 构建索引

运行命令：构建 AI 索引（英文命令：Build AI Index）

首次使用需要全量构建索引，之后会自动增量更新。

2. 语义搜索

运行命令：语义搜索（英文命令：Semantic Search）

输入问题，返回相关文档片段。

3. 问答

运行命令：知识库提问（英文命令：Ask Vault）

输入问题，返回答案 + 引用来源。

4. 侧边栏

运行命令：打开 AI RAG 侧边栏（英文命令：Open AI RAG Sidebar）

打开侧边栏，进行连续对话。

5. 元数据索引（可选）

运行命令：构建元数据索引（英文命令：Build Meta Index (AI Summary)）

AI 分析每篇笔记生成元数据，提升"这是什么笔记"类问题的召回。

6. 初始化 LLM Wiki

运行命令：初始化 Wiki（英文命令：Initialize Wiki）

插件会创建：

• _wiki/CLAUDE.md - Wiki 维护规则
• _wiki/index.md - 内容索引
• _wiki/log.md - 时间线日志
• _wiki/sources/ - 原始来源摘要
• _wiki/entities/ - 实体页
• _wiki/concepts/ - 概念页
• _wiki/summaries/ - 主题综述
• _wiki/syntheses/ - 高价值问答/综合分析

7. 导入来源到 Wiki

运行命令：导入当前笔记到 Wiki（英文命令：Ingest Current Note to Wiki），或右键 Markdown 文件选择 导入到 Wiki。

导入时插件会读取原始笔记但不改动原文，然后创建来源摘要页、更新相关实体/概念页、维护索引和日志。开启设置里的 自动导入 后，非 Wiki 笔记变更会在短暂防抖后自动导入。

8. 查询与审计 Wiki

• 查询 Wiki - 基于已整理的 Wiki 页面回答问题，可将高价值答案归档为 synthesis 页面
• 浏览 Wiki - 浏览、搜索、筛选 Wiki 页面
• 审计 Wiki - 生成 Wiki 体检报告
• 自动修复孤立页面 - 为无入链页面补充相关链接和入口

📖 功能详解

检索链路

Query Analysis

• Standalone Question - 处理追问，改写为独立问题
• Multi-Query - 生成查询变体，提升召回覆盖率
• Filter Inference - 推断标签和路径过滤条件

Multi-Recall

• Dense Recall - 向量检索（主要）
• Sparse Recall - BM25 词法检索（主要）
• Feedback Recall - 反馈记忆召回（辅助，权重 0.5）
• Meta Recall - 元数据召回（辅助，权重 0.6）

Fusion

• RRF - Reciprocal Rank Fusion
• Weighted - 加权融合
• Distribution-based - 基于分布的融合

Rerank

• LLM-based - 使用 LLM 重排序候选结果

Context Compression

• Parent-Child Chunks - 扩展到父级 chunk
• Sentence Window - 提取包含关键词的句子窗口
• Token Budget - 控制总字符数

增强功能

1. 复制按钮

• 位置：Ask Vault 和侧边栏的答案区域
• 功能：一键复制答案到剪贴板

2. 纠正 + 反馈学习

• 位置：答案区域的"✏️ 纠正"按钮
• 功能：
  • 输入正确答案
  • 关联相关笔记（可选）
  • 自动向量化并保存
  • 作为独立召回通道参与检索

3. 元数据库

• 命令：构建元数据索引（英文命令：Build Meta Index (AI Summary)）
• 生成内容：
  • summary - 一句话总结
  • userRelation - 这是用户的什么
  • autoTags - 自动标签
  • noteCategory - 笔记分类
• 用途：提升"这是什么笔记"类问题的召回

4. 自动增量索引

• 监听文件变化（create/modify/delete/rename）
• 2秒防抖，避免频繁索引
• 批量处理（每批 5 个文件）
• 配置变化时提示重建

5. 用户模式学习

• 高频术语统计
• 触发词识别（词频 > 5）
• 选择性加载（命中触发词才使用高级分析）
• 性能优化：普通问题 0 次 LLM 调用

评测与日志

评测指标

• Retrieval Relevance - 召回相关性
• Groundedness - 答案基于上下文的程度
• Citation Accuracy - 引用准确性（基于用户纠正率）
• Response Time - 平均响应时间

查看指标

运行命令：Show Evaluation Metrics

查看日志

运行命令：Show Recent Query Logs

🛠️ 开发

构建

npm install
npm run build

开发模式

npm run dev

部署

# 复制文件到 Obsidian 插件目录
cp main.js manifest.json styles.css "path/to/.obsidian/plugins/ai-rag-llm-wiki/"

📊 性能优化

触发词选择性加载

场景	原方案	优化后
普通问题	3次 LLM	0次 LLM
命中触发词	3次 LLM	3次 LLM
追问	3次 LLM	1次 LLM

防抖与批处理

• 文件变化 2 秒防抖
• 每批处理 5 个文件
• 避免 API 限流

网络容错

• 自动重试（最多 3 次）
• 超时控制（30 秒）
• 指数退避（Rate Limit）

🔒 隐私与数据发送

• 插件不会内置任何 API Key；用户需要在本地 Obsidian 设置中自行配置。
• 构建向量索引会把笔记分块发送到你配置的 Embedding API。
• 提问、导入 Wiki、生成摘要会把问题和必要上下文发送到你配置的 Chat API。
• 自动索引和 Wiki 自动导入默认关闭，建议确认笔记隐私范围后再开启。
• 遇到疑似密码、密钥、令牌等敏感内容时，插件会提示跳过或标记为私密。

📝 数据文件

所有数据存储在 .obsidian/plugins/obsidian-ai-rag-plugin/data/：

• manifest.json - 索引元信息
• chunks.json - 文档分块
• embeddings.json - 向量数据
• files.json - 文件元数据
• feedbacks.json - 反馈记录
• feedback-embeddings.json - 反馈向量
• meta-notes.json - 元数据记录
• meta-embeddings.json - 元数据向量
• user-patterns.json - 用户模式
• query-logs.json - 查询日志

⚙️ 配置项

API 配置

• apiBaseUrl - API 地址
• apiKey - API 密钥
• embeddingModel - 向量模型
• chatModel - 对话模型

索引配置

• chunkSize - 分块大小（默认 800）
• overlap - 重叠大小（默认 150）
• autoIndexOnFileChange - 自动增量索引（默认 false）

检索配置

• topK - 返回结果数（默认 6）
• enableHybridSearch - 混合检索（默认 true）
• maxContextChars - 最大上下文长度（默认 6000）

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可

MIT License

🙏 致谢

本插件基于主流 RAG 最佳实践构建，参考了多个开源项目和论文。