技术人积累的笔记越多，检索和复用就越难。本文记录了我如何用开源嵌入模型、向量数据库和 ChatGPT/Claude 的 API，花两个周末把自己的 2000+ 条技术笔记搭建成一套可对话、可自动关联、可辅助写作的个人知识库系统。不含任何商业推广，只有选型思路、踩坑记录和真实效果数据。
一、为什么传统的笔记方式在 2026 年彻底不够用了
我过去 5 年用 Notion/Obsidian 积累了大约 2000 多条技术笔记，涵盖后端架构、数据库调优、前端工程化、运维脚本等。量变引起质变——有三个痛点越来越不能忍：
- 搜索只能匹配关键词，无法理解意图：搜“如何优雅处理 Go 里的超时”，只能搜到标题或正文含这几个词的笔记，但一篇关于 context 包最佳实践的笔记虽然完美回答了问题，却不会出现在搜索结果里。
- 记过的笔记重复造轮子：常常写了一半代码才隐约想起“这个问题以前在某个项目里遇到过”，但翻笔记要 10 分钟，不如直接 StackOverflow 重搜。
- 笔记之间缺乏关联：一篇讲 MySQL 死锁的文章和另一篇讲分布式事务的文章明明有逻辑联系，但躺在不同的文件夹里，永远不会互相引用。
2026 年，本地运行嵌入模型和向量搜索的门槛已经足够低，我决定把自己的笔记升级成一个真正的“第二大脑”。
二、系统架构：极简但够用
整个系统的设计原则只有一个：所有数据留在我自己的机器上，AI 只参与“理解”和“检索”，不托管我的笔记内容。
选型如下：
- 笔记源数据：Obsidian 本地仓库（全是 .md 文件，带 YAML front matter 标签）
- 嵌入模型：BGE-M3（本地部署，通过 Ollama 调用，中文 + 代码混合场景表现优异）
- 向量数据库：Chroma（本地运行，Python 一键启动，零配置）
- 检索 + 对话：自定义 Python 脚本调用 Claude Sonnet 4 API（只传检索到的摘要，不传原文，进一步保护隐私）
- 前端：个人用，直接跑在终端里的命令行 REPL，没有 GUI
三、落地四步走，每一步都踩了坑
步骤 1：笔记清洗与分块
原始 markdown 里充斥着各种代码块、链接、图片引用、甚至个人碎碎念。直接整篇喂给嵌入模型，检索精度会大幅下降。
做法：
- 解析所有 .md 文件，按 ## 标题拆分成块，每个块 500-1500 token 左右。
- 去掉图片链接、HTML 标签，但保留代码块（代码块的语义信息对技术检索很重要）。
- 给每个块生成一个带标题路径的 ID（如
Go/并发/context包避坑.md#3-超时控制），方便定位回原文件。
坑：一开始用固定 500 字符切分，导致很多代码块被切碎，丧失了语法结构的完整性。后来改为先按标题拆分，再对过长段落按语义边界（如空行、代码块边界）切分，效果好非常多。
步骤 2：生成嵌入并存入 Chroma
BGE-M3 对中英文混合和代码段的处理相当不错。本地用 Ollama 跑，一张 RTX 4060 就够，2000 多个文本块的嵌入生成大约花了 15 分钟。
注意：嵌入生成时要去掉 front matter 里我自己写的非技术标签（如心情、待办状态），只保留技术关键词标签，否则向量空间里会混入奇怪的维度。
步骤 3：构建检索 + 重排序
用户输入问题后：
- 用 BGE-M3 生成问题嵌入，在 Chroma 里召回 Top 10 个最相似文本块。
- 用 Claude Sonnet 4 做重排序（Cross-encoding），输入问题是“请从以下 10 个片段中选出与问题最相关且能回答问题的 3 个”，省去了部署重排序模型的成本。
实测：两步式检索的命中率比纯向量检索提升了约 35%。而且 Claude 做重排序的开销很小（每次不到 0.01 美元），完全可接受。
步骤 4：对话式回答生成
拿到 Top 3 相关片段后，把片段内容 + 用户问题传给 Claude Sonnet 4，设定一个简洁的 System Prompt：
“你是一个基于用户个人技术笔记回答问题的助手。请仅根据以下提供的笔记片段回答问题，如果片段中不包含答案，请直接说‘笔记中未找到相关信息’，不要编造。回答时在末尾注明引用的笔记文件名。”
这样既避免了幻觉，又做到了溯源。
四、两个周末后的真实体验
这个系统跑了三周，下面是几个让我觉得“这时间花得值”的瞬间：
- 解决生产问题时：半夜遇到一个 MySQL 间隙锁的问题，模糊记得自己写过实验笔记。在终端里敲了一行“MySQL 间隙锁 什么时候会锁住不存在的行”，系统直接给出了我一年前记的实验结论和复现 SQL，省去了重新构造测试环境的时间。
- 写技术文章时：正在写一篇 Go 性能优化的稿子，问系统“我之前关于 pprof 的调试记录”，它列出了 6 条相关笔记，包括一次真实的内存泄漏排查过程，直接成为了文章案例素材。
- 关联发现：系统回答时偶尔会“顺便”提示：“还有一篇笔记与你的问题间接相关，是关于分布式锁的”，这种被动的知识串联是过去纯文件夹结构做不到的。
五、几个让你少踩坑的建议
- 不要追求全自动同步。笔记质量参差不齐时，自动增量索引会把很多“半成品笔记”也灌进去，检索质量不升反降。建议手动触发索引，并只对加了
#published标签的笔记生成嵌入。 - 代码块保留原始语法，不要摘要化。嵌入模型对代码的语义理解已经很好了，不要画蛇添足地把代码翻译成自然语言再嵌入，那样反而丢失细节。
- 选择一个好用的嵌入模型比调参数重要。BGE-M3 在技术内容上比通用模型效果好很多，如果纯英文可以考虑 text-embedding-3-large，但成本和隐私不如本地方案。
- 终端 REPL 就够用了。不需要花时间搭 Web UI，技术人打命令行的效率远高于点鼠标。一个简单的 argparse + 彩色输出，体验很好。
目前这套系统还在持续优化中，关于嵌入模型选型的更多横向对比数据，以及不同向量数据库在个人规模的性能差异，gpt108上有来自开发者的实测记录和讨论，感兴趣的可以自行查阅。
你有尝试过把自己的笔记做成可对话的知识库吗？用的是什么方案？欢迎评论区分享你的实践。
