obsidian-yolo 是运行在 Obsidian 里的 Agent 原生 AI 助手，它的Vault RAG能力可以给你的笔记库建索引，让 AI 按语义读懂整个库，而不只是逐篇@引用。这篇教程带新手从零搭好 RAG 检索，重点是教你用免 API Key 的本地嵌入模型在设备端建索引，笔记内容不出本机。

先搞懂：没建索引会怎样

不用索引也能对话。AI 自带一个「知识库检索」工具，没索引时它会自动降级成纯关键词检索——只能找到字面匹配的笔记，找不到"说法不同、意思相近"的内容。界面上会提示"知识库索引已关闭"。

建好索引后，同一个工具自动升级为向量检索 + 关键词混合。你不需要手动切换什么"RAG 模式"，AI 判断需要查笔记时会自己调用。相关实现见 ragEngine.ts 与 vault_search 工具定义。

第一步：准备嵌入模型

索引的前提是有一个嵌入模型，否则点"开启"会被拦下。它有两种来源，任选其一。

方案 A：本地嵌入模型（免 API Key，推荐新手）

打开设置 → YOLO → 知识库，在嵌入模型区域找到「本地（设备端）」货架。模型直接跑在你电脑上，笔记内容不出本机，也不需要任何 API Key。仅支持桌面端，移动端会显示不可用。

点「下载」会显示进度，完成后自动校验文件完整性。支持CPU / GPU（WebGPU）切换，设备不支持 GPU 时该选项会被禁用。模型清单定义在 catalog.ts，本地运行依赖「嵌入引擎」这个运行时组件，未安装时设置页会提示你先去启用。

两个新手坑：

• 本地模型文件存在插件自己的目录里，不在你的库里、不参与同步。删除需在模型条目上点两次确认。
• 量化格式反直觉：q8（int8）模型只能跑 CPU，放到 WebGPU 上反而更慢。部分模型提供专供 GPU 的 fp16 变体。

方案 B：API 嵌入模型

如果想用云端模型，先切到设置 → YOLO → 模型标签页，给某个提供商添加嵌入模型（比如 OpenAI 的text-embedding-3-small），再回到知识库标签页在「API 模型」一行选中它。

选中后还要点一次「设为当前」才生效。因为切换嵌入模型会让所有已有向量失效、等于全库重建，多这一步是为了防止你手滑点错下拉框就触发一次全量重建。远端与本地两条路径的切换逻辑见 embedding.ts。

第二步：开启并建立索引

嵌入模型就位后，点状态条上的「开启并建立索引」。索引进度会实时显示在状态条和底部状态栏，包括当前正在处理哪个库、百分比、当前文件名。

建好之后：

• 卡片显示状态（已就绪 / 索引中 / 待更新 / 排队中 / 需要关注）、文档数、向量块数、占用体积。
• AI 检索时自动走混合模式，无需你干预。

进阶：多知识库与高级设置

拆分成多个知识库

把库拆成几个独立知识库，各自管不同范围（如"工作笔记"和"读书笔记"）。点「新建知识库」，每个库只配三项：

• 名称（必填、不能重名）
• 描述（建议写，这段文字会提供给模型，帮它判断该查哪个库）
• 包含 / 排除范围（可视化目录选择器，规则向子目录传递）

检索时 AI 会按名称和描述自动判断该查哪一个，不指定就合并所有库的结果。所有知识库共用同一个嵌入模型和同一套分块设置。

常用高级参数

知识库标签页底部有一组默认折叠的全局设置：

什么时候必须手动重建：换了嵌入模型、或改了分块大小，只影响之后新索引的内容，已有向量不会自动重算。改完记得全量重建，否则新旧向量混在一起，检索质量会莫名变差。

自动更新默认开启——编辑笔记后空闲约 5 分钟会同步进索引。手动入口有状态条「立即更新」、卡片菜单「重建此库」、命令面板的"更新修改文件的索引 / 重建整个库索引"。

检索是怎么发生的

你基本不需要做任何事。AI 判断需要查笔记时会自己调用「知识库检索」工具；若你要强制它看某篇具体笔记，用@引用更直接——引用是确定的，检索是概率的。

另外，侧栏「灵光写作」标签页里的相似笔记面板，基于当前打开的笔记做向量检索，列出相关笔记并可展开命中片段、插入链接。它同样依赖知识库索引，没配好时面板会给出引导按钮。相似笔记的相似度分级实现见 similarNotes.ts。

完整参数与边界情况，可继续阅读官方文档 知识库与检索 和 模型与提供商。