
用 VB Notes 搭建本地 Markdown 笔记库并启用语义搜索
用 VB Notes 搭建本地 Markdown 笔记库并启用语义搜索
VB Notes 是一款把笔记直接存成 Markdown 文件、并在本机完成语义检索的免费开源笔记应用。本教程从安装、选择笔记文件夹、开启语义搜索讲到用 Ctrl+O 快速查找,并说明模型下载、相似度阈值、AI 问答配置与已知限制。
VB Notes 是一款免费、开源的笔记应用,它的两个核心设计决定了它适合谁:笔记以普通 Markdown 文件的形式保存在你自己选定的文件夹里,不依赖账号和服务器;搜索除了关键词匹配,还能按「意思」检索,即使你输入的说法和笔记里的用词一个都对不上,也能把相关笔记找出来。语义检索所用的嵌入模型在设备本地运行,首次使用时下载一次,之后检索过程不需要联网。
它适合这几类人:笔记越积越多、已经记不住标题和原话的人;不愿意把笔记放到云端的人;已经在用 Obsidian、Bear 或其他 Markdown 编辑器、希望新工具能和自己现有文件共存的人;以及想要一个没有订阅费用的长期笔记工具的人。反过来,如果你需要开箱即用的同步、分享和多人实时协作,或者需要 Web 版、iPad 版,VB Notes 目前并不提供这些,同步要交给文件夹同步工具去做。它还是一个由个人开发、发布不久的年轻项目,作者本人也提到存在「rough edges」,不要按大团队产品的完成度去预期。
下面按「安装 → 选文件夹 → 开启语义搜索 → 检索 → 可选配置 AI 问答」的顺序走一遍,最后给出一个从零到可检索的完整示例,并列出使用中容易踩到的限制。文中涉及的版本号、安装包体积、模型大小、相似度阈值等数字都可能随版本变化,实际以官网与发布页的当前信息为准。
准备工作
确认平台与安装包
VB Notes 提供 Linux、macOS、Windows、iPhone、Android 五个平台的客户端。桌面端安装包按平台区分,Linux 有 AppImage、.deb、.rpm 三种格式,macOS 是 universal 的 dmg(也可以通过 Homebrew 安装),Windows 是 exe 与 msi 两种安装器。移动端从 App Store 与 Google Play 获取,Android 的 APK 也会随发布页提供。
安装前需要准备的东西不多:
- 一个用来存放笔记的文件夹。可以是本地任意目录,也可以是 iCloud Drive 这类已经被同步工具接管的目录。这个文件夹里的 .md 文件会被直接当作笔记显示,在应用里新建的笔记也会以 .md 文件写回该文件夹。
- 约 379MB 的磁盘空间与一次联网下载。语义搜索所用的嵌入模型只在首次开启该功能时下载一次,之后检索完全在本地进行。
- 桌面端运行所需的图形库。在 Linux 上以 AppImage 方式运行时,系统需要具备 libEGL.so.1 等图形依赖,缺少这些库会导致应用无法启动。
- (可选)一个 AI 服务商的 API Key 或本地 Ollama。只有当你打算使用「就笔记内容向 AI 提问」这一功能时才需要,语义搜索本身不需要任何密钥。
安装桌面端
Linux 的 AppImage 下载后需要先赋予执行权限再运行:
chmod +x VBNotes_0.4.17_amd64.AppImage
./VBNotes_0.4.17_amd64.AppImage
如果使用 .deb 包,用系统的包管理器安装本地文件即可:
sudo apt install ./VBNotes_0.4.17_amd64.deb
macOS 除了下载 dmg 拖入应用程序目录,也可以用 Homebrew 的 cask 安装:
brew install --cask elavneet/vbnotes/vb-notes
Windows 直接运行 exe 或 msi 安装器,按向导完成即可。移动端在应用商店搜索安装。
操作步骤
第一步:指定笔记文件夹
首次启动时,应用会要求你选择一个用来存放笔记的文件夹。这一步是整个使用流程的基础,选之前想清楚两件事:
- 是否要跨设备共用同一批笔记。如果希望 iPhone 和 Mac 看到同样的内容,就把文件夹放在 iCloud Drive 里;Android 端则按官方说明配合文件夹同步应用使用。
- 是否要和其他编辑器共用。因为笔记就是普通的 .md 文件,你可以让 Obsidian、任意文本编辑器或自己写的脚本读写同一个目录,VB Notes 只是这些文件的一个前端。
选定之后,文件夹里已有的 .md 文件会立刻作为笔记出现,不需要导入操作;在应用里写下的内容也会即时保存成 .md 文件。
第二步:开启语义搜索并等待模型下载
语义搜索默认不是开着的,需要到设置(Settings)里手动打开。第一次打开时会触发一次模型下载,文件是 LFM2.5-Embedding-350M 的 Q8_0 量化版本,约 379MB。下载完成后会做 SHA256 校验,如果文件损坏会自动重新下载,因此不需要手动检查完整性。
下载结束后,应用会在后台逐条把已有笔记转成向量。这个过程是一次性的索引工作,笔记越多耗时越长,但之后新增或修改笔记时只需要处理变化的部分。索引期间可以正常使用应用,只是语义检索的结果可能暂时不完整。
第三步:用快速查找器做语义检索
桌面端按 Ctrl+O(macOS 上是 ⌘O)打开快速查找器。结果列表的第一行固定是「用这个词新建一条笔记」,下面才是命中的笔记。命中结果里同时包含关键词匹配和语义匹配两类,语义匹配的条目会带有「by meaning」标记,方便你判断这条结果是靠字面命中还是靠意思命中。
检索的内部机制值得了解,因为它解释了为什么有些结果看起来「不太对」:
- 笔记会按约 200 词切分成带标题的块(chunk),应用实际切分时上限为 512 token。
- 每个块用 LFM2.5-Embedding-350M 转成 1024 维向量,桌面端通过 llama.cpp 以 GGUF 形式在本地运行这个模型。
- 你输入的查询用同一个模型转成向量,两者用余弦相似度比较。
- 查询文本在向量化前会加上
query:前缀,笔记块会加上document:前缀,这是模型要求的输入格式。 - 语义结果与关键词结果通过 reciprocal rank fusion 合并排序,所以字面完全匹配的笔记仍然会排在前面。
换句话说,语义检索不是替代关键词检索,而是在关键词检索之外补上一条召回路径。
第四步(可选):配置 AI 问答
从 v0.4 起,应用支持就自己的笔记向 AI 提问。这个功能默认关闭,开启前需要提供自己的 API Key,支持的服务商包括 OpenRouter、OpenAI、Anthropic、Google Gemini、Groq、Mistral、DeepSeek、xAI,也可以指向本机通过 Ollama 运行的模型。
它的工作方式是:先用语义检索挑出与问题相关的笔记,只把这些笔记的内容发给模型,回答下方会列出本次用到了哪些笔记,便于核对。API Key 保存在设备本地。需要注意,语义检索本身免费且完全本地,而 AI 问答产生的调用费用由你自己的 API Key 承担。
第五步:把同步交给文件夹同步工具
VB Notes 本身不做同步,也不做分享和实时协作。跨设备使用的方式是让笔记文件夹本身被同步:iCloud Drive、Syncthing 之类的工具都可以,具体选哪个取决于你的设备组合。官方明确说明不支持 Google Drive 集成,规划方案时不要把它算进去。
一个完整示例
下面从零开始,在一台 Linux 桌面上建立一个可语义检索的笔记库,并验证检索是否生效。
1. 准备目录。先建一个专门放笔记的文件夹,并放入两条测试笔记:
mkdir -p ~/notes
cat > ~/notes/rent.md <<'EOF'
# 房租的折半
和室友同住,房租按房间面积分摊,水电按人头平摊。
每月初结算一次,用转账记录留底。
EOF
cat > ~/notes/panda.md <<'EOF'
# 大熊猫
白与黑的毛色是它最显著的特征,主要食物是竹子。
EOF
2. 安装并启动。按前面的方式安装 AppImage 或 deb 包,启动应用。
3. 选择文件夹。在首次启动的引导里选中 ~/notes。此时两条笔记应当已经出现在列表里。
4. 开启语义搜索。进入设置,打开语义搜索开关,等待约 379MB 的模型下载完成并通过校验,再等后台索引跑完。
5. 用改写过的说法检索。按 Ctrl+O 打开快速查找器,输入一个和笔记原文几乎没有共同词的说法,例如「室友应该付多少钱」。如果一切正常,「房租的折半」会出现在结果中并带有「by meaning」标记。
6. 验证关键词路径仍然可用。再输入「竹子」,应当能直接命中「大熊猫」,且这条结果来自关键词匹配而非语义匹配。两条路径同时工作,说明配置正确。
7. 接入 AI 问答(可选)。如果要用 AI 问答,在设置里填入 API Key 或指向本地 Ollama,然后针对「房租怎么分摊」提问,检查回答下方列出的引用笔记是否就是 rent.md。
注意事项
桌面端只有一个嵌入模型
桌面版固定使用 LFM2.5-Embedding-350M(Standard),没有切换模型的设置。移动端另有一个名为「Many languages」的选项,基于 paraphrase-multilingual-MiniLM-L12-v2,覆盖 50 多种语言,但桌面端没有这个选项。桌面端依赖的是 LFM2.5 所支持的 11 种语言(英语加另外 10 种),具体是哪 10 种在源码中也没有明确列出。实际使用中,中文笔记的语义检索是可以工作的,但官方并没有把「支持中文」写成明确承诺,评估时应当把这一点考虑进去。
相似度阈值会带来噪声
应用采用的相似度下限(minScore)是 0.12,低于该值的结果不会作为语义命中展示。这个阈值在笔记数量较少时容易产生误报:即使输入一个与所有笔记都无关的问题,也可能有某条笔记的得分超过 0.12 而被标成「by meaning」。因此不要把「by meaning」标记当成确定相关,把它和关键词结果对照着看更稳妥。随着笔记数量增加,无关笔记被误召回的概率通常会下降,但具体表现取决于你的笔记内容分布。
不同语言的得分水平不同
同一组语义相近的笔记与问题,在不同语言下的相似度得分并不一致,非英语内容的得分往往偏低,与 0.12 阈值之间的余量更小。这意味着在中文笔记上,语义命中的判定更容易受阈值影响。如果你的笔记以中文为主,建议在开启语义搜索后先用几条自己熟悉的笔记试一下改写查询,确认召回效果符合预期再依赖它。
长笔记会被切块
超过约 200 词的笔记会被切成多个块,每块单独向量化并带上标题。检索命中的是块而不是整篇笔记,所以一篇长笔记可能只有其中一段被召回。写长笔记时,用小标题把内容分段,有助于切块后每块的主题更集中,检索结果也更准确。
首次下载与校验
模型下载约 379MB,需要稳定的网络和足够的磁盘空间。下载完成后会做 SHA256 校验,损坏会自动重试,不需要手动干预。如果下载反复失败,先检查网络与磁盘剩余空间,而不是怀疑模型文件本身。
Linux 上的图形依赖
以 AppImage 方式运行时,如果系统缺少 libEGL.so.1 等图形库,应用会直接启动失败。这类问题属于运行环境缺失,不是应用本身的缺陷,安装对应的图形库包即可。在无图形界面的服务器或容器里,桌面应用无法正常启动,此时只能通过命令行直接调用嵌入模型来验证检索效果,无法验证界面操作。
项目尚年轻
VB Notes 是一个发布不久的个人项目,仓库采用 MIT 许可证,但使用者数量还很少,界面与操作流程都可能随版本变化。在依赖某个具体菜单路径或快捷键之前,先对照当前版本的说明确认一遍。遇到与本文描述不一致的地方,以你安装的那个版本的实际行为为准。
AI 问答与语义搜索是两件事
语义搜索免费、本地、不需要任何账号;AI 问答需要你自己的 API Key,费用自负,且只有与问题相关的笔记会被发送给模型。如果你在意数据外发,可以只用语义搜索而不开启 AI 问答,两者互不依赖。
同步需要自己搭
应用不提供同步、分享和实时协作,也不支持 Google Drive 集成。跨设备方案要自己用文件夹同步工具实现,并且要注意多设备同时编辑同一文件可能产生的冲突,这属于同步工具层面的问题,应用本身不处理。