上个月我写一篇带引用来源的行业梳理稿翻了一个半小时浏览器收藏夹最终发现最早想用的那篇公众号文章收藏时的标题叫《把数据做成产品》等真要引用时怎么搜都搜不出来。不是没收藏是收藏之后根本没有检索入口。后来跟几个朋友聊发现这种挫败感是通用的知识囤得越多越找不到。于是我开始认真搭一套个人知识库核心思路就两条——本地 embedding 和每日自动同步。这篇文章就是这次搭建的完整踩坑记录。我尽量把每一步的选型理由、参数依据、失败现场都写清楚适合那种“收藏了几千篇文章但从来不看第二遍”的人也适合对数据隐私敏感、想离线跑通 RAG 检索链路的人。全文不做架构表演只讲在一台普通 MacBook 上怎么把知识库从 0 建到能每天自己更新。1. 先算账为什么我坚持把 embedding 放在本地跑动手之前我先盘了一下需求我的知识库主要是中文长文、微信公众号截图、PDF 摘录、以及 Obsidian 里的日常笔记。检索高频场景是“我记得读过一篇讲 A 和 B 关系的文章但想不起来关键词”。这个需求本质上只需要把文本向量化然后在向量库里做相似度召回不需要本地跑大模型生成答案。但“向量化”这一步就有两种走法调云端 embedding 服务或者本地跑开源模型。我最终选了本地理由不是情怀是实打实的账。1.1 云端 embedding 的三笔隐形账单第一笔是全量重灌费。个人知识库会不断调整分块策略、模型版本、清洗规则每调整一次就需要把全部文档重新向量化。我当时的语料大概 5000 篇 markdown平均每篇抽出来 1500 个 token一次全量就是 750 万 token。头一个月我改了三版分块逻辑相当于烧了三次全量。云端按 token 计费单次不贵但一年下来累积到几十上百块钱钱倒还在其次关键是每次重灌要排队等接口几百个请求慢慢跑很磨人。第二笔是频控和超时。批量 embedding 的时候有些服务单账号有 QPS 限制个人脚本一不小心就撞限流然后就要自己写退避重试。我一个周末的晚上调同步脚本日志里全是 429 超时重试那一刻真的很想砸电脑。第三笔是隐私。笔记里全是个人日记、工作草稿、未发布的文章片段我实在不想为了一个检索功能把家底都发给第三方接口。哪怕接口说数据不留存心理那关也过不去。1.2 本地模型凭什么能打中文实测结论决定走本地之后我用三个开源模型试了同样的 200 条中文检索测试集结论很直接bge 系列的 zh 版本对中文的理解已经够用而且本地 CPU 推理的速度完全扛得住个人知识库规模。我当时最担心的是本地模型把“苹果”理解成水果而不是公司实测下来 bge-base-zh-v1.5 在大多数场景下语义召回是靠谱的。对比同一条查询“知识库的权限设计”云端通用模型的返回结果和本地 bge 的返回结果在前五条里重合了三到四条。对于个人检索这种“够用就行”的场景本地模型的劣势基本可以忽略。另外本地 embedding 有个隐藏优势完全离线可用。在高铁上、在没网的会议室里照样能检索我的知识库。这一点在出差场景里体验非常好。1.3 明确边界本地 embedding 不等于本地大模型这里要先泼一盆冷水。本地 embedding 解决的只是“召回”问题就是帮你找到相关的那几段文本。它不负责“读懂”和“总结”那种能力需要 LLM 生成层。如果期待搭完知识库之后问一个问题它就能自动写一篇综述那还需要再接入一个生成模型这是另一套工程。我的方案里先不碰生成模型。检索阶段用本地 embedding召回到原文之后我自己读或者扔给编辑器里的 AI 插件处理。先跑通“找得到”再去想“读得懂”这是我认为最务实的路线。提示决定走本地方案前先想清楚你的语料量级。几千篇文档的纯文本检索本地单机完全足够如果到几十万篇再考虑分布式向量库和云端资源。2. 整体架构与一次性选型顺序决定了后面少折腾知识库搭建最怕的是反复推翻重来。我踩过的最大坑就是前期选型没过脑子导致后面同步脚本改了四次。这里我把一次性决策里最关键的四个选择拆开讲。2.1 数据源选型为什么拿 Obsidian 仓库当底座我的知识库数据源不是一个东西是好几类Obsidian 里的笔记、微信公众号收藏的文章、浏览器剪藏、PDF 摘录。但最后我统一把它们都转成 markdown 放进 Obsidian 仓库再用这个仓库作为唯一的数据源。选 Obsidian 当底座的核心理由有三个markdown 是纯文本解析、分块、增量对比都极其方便不需要处理 docx 或者 pdf 的复杂格式。仓库本身就是目录结构天然有分类维度可以直接拿路径当 metadata。双链和标签体系在检索结果回显时可以跳转回原文形成“检索→溯源→编辑”的闭环。微信公众号文章入库我单独处理过抓取正文之后转成 markdown图片下载到附件目录正文里的代码块和引用块尽量保留。这一步的转换脚本很啰嗦但一次性投入后面的收益是持续的。注意不要在数据源里混入 Word、在线网页这些格式。收藏一时爽入库火葬场。所有来源一律先归一化成 markdown否则后面每一步都会为格式差异买单。2.2 向量库对比Chroma、LanceDB、Qdrant、FAISS 四选一向量库是最容易纠结的选型。我花了一个晚上把主流选项列了一张表最终用排除法选出来的。选项部署方式单机易用性全量重灌速度典型问题ChromaPython 库本地目录持久化极好中等版本升级偶发存储格式变化LanceDB单文件/目录嵌入式极好快生态相对年轻QdrantDocker 服务端一般快个人场景偏重FAISS库不是数据库差快元数据管理要自己写我最后选了 Chroma。原因是社区资料最多、踩坑记录最好找配合 PersistentClient 的本地目录模式不需要额外起服务也不用 Docker。后来也确实在版本升级上踩了一个坑后面第 6 章详说但整体可控。如果你更在意文件级便携LanceDB 也是个好选择一个目录拷走就能迁移特别适合喜欢同步整个文件夹的人。我当时没选它主要是想先用生态最成熟的方案把链路跑通。2.3 同步触发机制cron、launchd 还是 watchman同步脚本多久跑一次、用什么触发我反复改过三轮。第一轮用 watchman 做实时监听文件一变就触发索引。结果 Obsidian 的自动保存加上实时监听一个下午触发了上百次索引把 CPU 打满了而且分块经常索引到写了一半的文件。实时监听在“个人笔记随手改”的场景里是伪需求纯浪费资源。第二轮用 cron但我的工作机是 macOScron 在休眠唤醒后经常错过执行时间时间不准最后放弃。第三轮换成了 launchd 的 StartCalendarInterval固定每天凌晨两点半跑一次增量索引。实测下来很稳休眠唤醒之后也能补跑。对个人知识库来说“每天同步一次”完全够用没必要追求实时。2.4 知识库工程目录一开始就按这样摆最后是我的目录结构这个结构撑住了后面所有迭代~/vault/ # Obsidian 仓库数据源 notes/ # 日常笔记 inbox/ # 微信文章、剪藏统一落这里 assets/ # 图片附件 ~/kb/ # 知识库工程目录 pipeline/ sync.py # 每日同步主脚本 chunker.py # markdown 分块 search.py # 命令行检索 config.yml # 模型、路径等配置 data/ chroma/ # 向量库持久化目录 meta.sqlite3 # 文件元信息 logs/ # 同步日志关键原则是数据源目录和工程目录分开。Obsidian 只需要看到 vault知识库的脚本、向量库、日志全部放在 kb 目录互不污染。这样就算哪天向量库坏了你的原始笔记也毫发无损。3. 本地 embedding 链路模型、参数与 CPU 实测算账选型定了之后真正动手是从 embedding 模型开始的。这一节的价值在于把模型选择的逻辑掰开揉碎顺带给出我实测的 CPU 性能数据。3.1 模型怎么选bge-small-zh、bge-base-zh 还是 bge-m3我试了三个模型最后用的是 bge-base-zh-v1.5理由看这张对比表模型向量维度最大输入长度中文效果模型体积CPU 实测表现bge-small-zh-v1.5512512够用长难句略弱约 100MB很快5 万 chunk 约 15 分钟bge-base-zh-v1.5768512明显更好长文语义稳定约 400MB5 万 chunk 约 40 分钟bge-m310248192最强支持多语言约 2GB慢但可接受适合超长文档bge-small-zh 速度最快但对“那句其实是在讲链路设计而非权限”这种绕一点的语义召回排名明显靠后。bge-m3 最强但我的文档大多在几千字以内512 个 token 的窗口配合分块已经完全够用没必要上 8192 的超长窗口。最终选择 bge-base-zh-v1.5是“中文理解力”和“CPU 推理速度”之间的最佳平衡点。五个小时全量重灌这种代价我不愿意付十五分钟的 small 我又嫌效果不够base 正好卡在中间。3.2 必须注意的 embedding 参数维度、归一化、批量大小调 embedding 有三组参数是不能瞎来的归一化写入向量库之前一定要对向量做 L2 归一化。向量库计算余弦相似度时归一化能保证距离排序正确否则检索结果的排序会被向量的模长干扰。批量大小CPU 推理时 batch size 不是越大越好。我实测 batch size 从 16 提到 64单条延迟没降多少内存占用却涨了四倍。个人笔记本上用 32 比较稳。线程数设置合理的 CPU 线程数别让它默认占满所有核。后台跑同步的时候如果还开着 IDE 和浏览器全核占满会导致整个系统卡到鼠标都飘。3.3 用 CPU 做全量 embedding 的实测数据我用的是一台 M1 MacBook Air 8GB 内存第一次全量索引 5000 篇文档分块后得到约 4.8 万个 chunkbge-base-zh-v1.5 在 CPU 上跑完花了 38 分钟。这个数字让我彻底放心了以后每次重灌最多 40 分钟完全可以在夜里定时跑。内存占用方面4.8 万个 chunk 的向量768 维 float32大约占用 150MB加上模型本身 400MB整体不到 800MB在 8GB 内存的机器上完全可玩。3.4 查询端必须与索引端同一套模型这是一个听起来像废话、但实际最容易翻车的原则。查询向量和索引向量必须由同一个模型生成否则就是两种语言在对话。我后面做过一个对照组索引用 bge-base-zh查询用 nomic-embed-text返回结果的前五条没一条靠谱的。原因是不同模型训练目标不同向量空间根本不重合。很多人第一阶段折腾完就忘了这回事等到换模型时不清库也是同样的坑。解决方案很简单把模型名写进配置索引和查询都从同一个配置读。embedding 的核心代码大概长这样from sentence_transformers import SentenceTransformer model_name BAAI/bge-base-zh-v1.5 model SentenceTransformer(model_name) def embed(texts): return model.encode( texts, normalize_embeddingsTrue, batch_size32, show_progress_barFalse, )4. 分块策略检索效果好坏的大半都藏在这里embedding 模型选完了检索效果一定好吗不一定。我第一版分块逻辑是按固定 300 字硬切切完之后的召回结果惨不忍睹。分块策略才是决定检索质量的隐藏大头。4.1 按 Markdown 结构切而不是按字数硬切Markdown 天然有结构#、##、###标题是章节边界列表、引用、代码块是语义完整的单元。按字数硬切会把一个概念切到两块里导致检索时哪一块都缺一半。我的分块逻辑是先按二级标题把整篇文档切成大段再在大段内按空行分成小段最后对小段做长度检查。超过 512 token 的再按句子边界细分。这样每个 chunk 都是一个相对完整的最小语义单元标题信息还可以单独存成 metadata 供溯源用。4.2 重叠窗口与中文断句的配合纯按标题和段落切还会漏掉一种情况一段话的末尾是下一段的开头铺垫只检索前半段会丢掉关键结论。解决办法是做重叠窗口前一个 chunk 的最后一句作为后一个 chunk 的第一句。中文分块相比英文有个特别需要注意的点不能用空格做词边界一定要以句号、问号、感叹号、分号、换行作为切分点。否则一个长句可能被从中间劈开比如“知识库的维护成本比想象中高很多”被切在“维”和“护”之间后半截单独成 chunk 之后检索质量崩得没法看。为了防止这种残句我在切分前会先做一轮“句子完整性检查”任何以标点结尾的候选句才允许作为切分点。4.3 metadata 清单给每条向量留好“身世信息”分块的同时必须记录 metadata否则检索到一段话根本不知道它来自哪篇文档的哪个位置。我的 metadata 字段设计如下source文件相对路径用来溯源和增量删除。heading所在章节标题的路径比如## 分块策略 ### 重叠窗口。chunk_indexchunk 在文档内的序号方便查看上下文。modelembedding 模型名做版本管理时用得上。这份“身世信息”带来的直接好处是检索结果可以直接渲染成“文档路径章节路径原文摘要”的列表我点开就能跳回 Obsidian 里的准确位置不用在几千篇文档里重新找。5. 每日自动同步管道收集、转换、增量索引三件套同步管道是知识库的“新陈代谢系统”。我的核心诉求很简单每天早上醒来昨天的收藏已经躺在知识库里而不是等我想起来才手动跑。5.1 管道整体设计三个环节各管一件事整个管道拆成三个阶段各管一件事互不越权收集collect扫描 vault 下所有 markdown记录路径、mtime、文件 hash与元信息库比对找出新增和修改的文件。转换convert对变更文件做 markdown 解析、分块生成 chunk 列表和 metadata。索引index对 chunk 做 embedding写入向量库并更新元信息库。三个环节之间用文件路径做关联不共享内存状态。好处是任何一个环节挂了其他环节的记录还在重新跑一遍即可。5.2 增量判断用 mtimehash 而不是无脑全量重灌这是日均同步的关键。全量重灌四万多个 chunk 要 40 分钟但每天真正变更的文件往往只有几十个增量索引应该只需要几十秒。我的判断逻辑是“mtime 加 hash 双重校验”mtime 变了才读文件读到文件后计算 SHA-256跟元信息库里的旧 hash 比对hash 没变就跳过。为什么 mtime 变了还不够因为 Obsidian 的某些插件会在你每次打开文件时自动修改内部属性导致 mtime 变化但正文完全没动。只用 mtime 会做大量无效 embed加一层 hash 就能滤掉。核心代码如下def build_change_list(vault: Path, conn) - list: changed [] for md in vault.rglob(*.md): rel str(md.relative_to(vault)) mtime md.stat().st_mtime_ns h sha256_of(md) row conn.execute( SELECT mtime, hash FROM files WHERE path?, (rel,) ).fetchone() if row is None or row[0] ! mtime or row[1] ! h: changed.append((rel, md, mtime, h)) return changed然后对变更文件重新分块、删除该文件在向量库里的旧 vector、整体重灌for rel, md, mtime, h in changed: chunks chunk_markdown(md.read_text(encodingutf-8)) old collection.get(where{source: rel}) if old[ids]: collection.delete(idsold[ids]) collection.add( ids[f{rel}::{i} for i in range(len(chunks))], documents[c.text for c in chunks], metadatas[ {source: rel, heading: c.heading, chunk: i} for i, c in enumerate(chunks) ], ) conn.execute( INSERT OR REPLACE INTO files VALUES (?,?,?), (rel, mtime, h), ) conn.commit()这套逻辑跑下来日常增量同步在 20 秒以内完成稳定得不像我自己写的代码。5.3 删除、重命名与微信公众号文章的入库处理增量处理还有一个容易被忽略的角落删除和重命名。如果某篇文档被删除或移动向量库里还留着它的旧 vector检索时就会搜出一篇不存在的文章。我的做法是在 collect 阶段把当前扫描到的路径集合和元信息库里的路径集合做差集。差集里的路径先按source条件把向量库里的旧 vector 删掉再删元信息记录。重命名则表现为一个旧路径消失、一个新路径出现两个操作一前一后执行完数据就干净了。微信公众号文章入库是另一个常见需求。我的处理链路是在手机上把文章“分享→复制链接”电脑端脚本抓正文转成 markdown 后落到 vault 的 inbox 目录。第二天凌晨同步管道会自动把它索引进去。整个过程我不用碰任何向量库配置只在 Obsidian 里看到文件进来了就行。5.4 用 launchd 挂定时任务从崩溃现场捡日志macOS 上 launchd 是比 cron 可靠得多的方案休眠唤醒后也能准确补跑。我的 plist 配置长这样?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringcom.me.kb-sync/string keyProgramArguments/key array string/usr/bin/python3/string string/Users/me/kb/pipeline/sync.py/string /array keyStartCalendarInterval/key dict keyHour/key integer2/integer keyMinute/key integer30/integer /dict keyStandardOutPath/key string/Users/me/kb/data/logs/sync.log/string keyStandardErrorPath/key string/Users/me/kb/data/logs/sync.err/string /dict /plist重点在最后那两行标准输出和标准错误一定要重定向到日志文件。没有日志的定时任务等于裸奔脚本半夜崩了第二天早上你只会发现知识库没更新却不知道发生了什么。提示加载 launchd 任务用launchctl load改过 plist 之后先 unload 再 load。我因为没 unload 直接 load遇到过一个同名任务反复触发的问题。6. 踩坑实录三条典型故障的完整排查链路前面是流程这一节是真的掉坑记录。每一条我都按“现象→排查→根因→修复”的顺序写希望你能直接复用我的排查思路。6.1 换 embedding 模型没清库检索质量直接崩现象某天我想试试 bge-m3 的效果就把配置里的模型名从 base 换成了 m3然后只对新增文档做了索引。结果当天检索时不管查什么返回结果都像被随机打乱了一样。排查过程先查日志索引没有报错再检查向量库发现 collection 里同时存在两个模型产生的向量。我这才意识到换模型只影响新写入的向量旧向量还是 base 模型的空间两个模型的空间不一致检索距离完全失去意义。根因query 向量来自 m3索引里绝大部分旧向量来自 base两者不在同一个向量空间内。修复办法也不复杂把 collection 里的旧数据全部清掉用新模型全量重灌。从此之后我把 model 名作为 metadata 写进每条向量每次切换模型前先按 model 字段做条件删除。注意换模型 全量重灌不存在“新老共存”这种中间态。谁想省这 40 分钟谁就会付出检索崩溃的代价。6.2 中文句子被拦腰斩断召回的全是残句现象检索“自动化同步失败处理”时召回结果里有大量形如“同步脚本在凌晨跑挂”和“了第二天知识库”这种前后不搭的碎片。排查过程我把当年的 chunk 预览导出来看发现切分点是纯字符数硬切根本不管句子语义。一个完整句子被切成两半前半句可能还包含关键词后半句完全是无意义残句。关键是这个残句自己也能被向量库索引成一条“合法向量”查询时经常会撞上这些碎片。根因分块逻辑缺少中文断句边界。修复是重写分块函数优先按。和换行切分切完再分段合并到接近 512 token 的长度保证任何一条 chunk 的末尾都是完整句子。6.3 同步脚本和 Obsidian 同时写文件索引进了一半现象某天凌晨的同步日志显示脚本执行成功但我白天打开知识库检索时发现某篇昨晚编辑的笔记内容只有一半而且后半段还是旧版本。排查过程这题隐蔽在“Obsidian 正在打开该文件”这个前提里。Obsidian 的自动保存会在用户停止输入几秒后写盘如果凌晨 2 点你电脑没关机但 Obsidian 还开着某个文件同步脚本读到的是保存到一半的中间状态。脚本读完文件后开始 embeddingObsidian 紧接着又写了一次完整版本——于是向量库里就留下了半个内容。根因读写并发没有做文件一致性保证。修复分两步第一读取文件后立刻计算 hash和读取前记录的 stat 信息做二次匹配不一致就跳过本次留到下一轮同步第二在同步脚本入口加文件锁flock防止手动执行和定时任务同时跑。从那以后我再没见过半截笔记入库。7. 最后分享一个让我每天省时间的习惯现在整个系统跑了大半年我已经养成了固定节奏睡前把当天读到的公众号文章和网页剪藏丢进 inbox第二天早上先瞄一眼同步日志确认昨晚的任务正常完成然后直接在命令行里python search.py或打开 Obsidian 搜索框就能找到东西。回头再看这套知识库真正帮到我的不是“能搜索”而是“搜索有稳定的入口”。本地 embedding 让我不用担心隐私和额度每日自动同步让我不用再手动整理每次检索都能顺着 metadata 跳回原始笔记。如果你也打算搭一套我的建议很直白先从一个几百篇 markdown 的小仓库开始用最简单的 Chroma 加 bge-base-zh 跑通整条链路再去折腾更复杂的索引和同步。别一开始就上大而全的流水线你的知识库应该从一台普通笔记本上安静地跑起来而不是变成另一个要维护的复杂系统。