给 AI 编码助手建一个「聪明」的文档数据库

直接把整站文档扔给 AI，就像让它在干草堆里找针。法律声明、更新日志、导航页，全都成了干扰信号。NameOcean 最近在琢磨怎么把文档「喂」给 AI 更高效，下面分享一套实操方法。

问题：不是每页都值得保留

很多技术站里，有一大半页面其实只是为了「摆造型」。比如首页导航、隐私政策、更新日志、API 列表——人看网站时需要它们，但 AI 学东西时基本没用。

把这些页面一股脑塞进向量库，只会让检索变慢、结果变差，甚至让 AI 引用到完全无关的内容。

两步分类，先粗后精

最省事的做法是「先用规则筛，再用 LLM 挑」。

第一步：规则快速过滤

先看 URL 和页面结构，马上就能干掉一大批：

• 法律页：URL 里带 /legal/、/privacy、/terms 之类的
• 导航页：字数少于 200 且大多是链接
• 更新日志：URL 通常有固定规律
• 参考页：结构单一，一眼就能认出来

这步在本地跑，零成本，能过滤掉 40-60% 的页面。

第二步：LLM 再分类

剩下的页面再交给本地 LLM（别走 API）。只传三样东西：

• URL
• 标题
• 前 200 字正文 + 标题层级

让它按 Diátaxis 框架打标签，分成「概念」「教程」「操作指南」「示例」「结构页」五类。LLM 只处理规则没搞定的部分，既快又省钱。

智能切分再嵌入

过滤干净后，嵌入效果会明显变好。但文档页经常超长，不能直接截断。

我们的做法是按标题切块，再把各块的向量平均。这样既保留了语义结构，又不会丢掉代码块或列表里的关键信息。

本地跑 sentence transformer 模型就够了，不用花 API 钱，效果也完全够用。

混合知识图谱

真正厉害的地方在于把两种关系叠在一起：

• 显式链接：作者自己写的超链接，可信度高
• 语义边：向量相似度超过 0.75 的页面，就算没直接链接也算相关

把这两种关系存成有向图。语义边带权重，链接边不带权重。同时限制每个页面最多连 20 个邻居，避免出现超级枢纽。最后把导航页、法律页、参考页从语义图里剔除，免得污染信号。

最终成果：一个 SQLite 数据库

所有东西打包进一个 SQLite 文件：

• 清理后的 markdown 正文
• 页面分类标签
• 向量嵌入
• 图关系和权重
• URL 和元数据

好处很直接：

• 随身带，走哪用哪
• AI 可以直接写 SQL 查询
• 能按「只看教程类」「只看认证相关」来过滤
• AI 还能沿着图关系跳到相关页面

完整流程

1. 爬取文档站（处理跳转、遵守 robots.txt）
2. 把 HTML 转成干净的 markdown
3. 先规则分类，再 LLM 补漏
4. 本地模型嵌入，长页按标题切块
5. 建混合知识图谱
6. 全部塞进 SQLite

做完之后，你的 AI 助手拿到的就是一份「精修过的知识库」，而不是一堆原始 HTML。

为什么值得做

不管你是做内部代码助手、给 IDE 加 AI 功能，还是给团队搭知识检索系统，文档质量都是决定性因素。提前把文档整理好，AI 就不用在噪音里浪费算力，响应更快，也更准。而且全程本地运行，没有 API 费用，也没有把内部文档发给第三方的隐私风险。

这套方法从小站到多产品文档都能用。核心就一句话：上游把文档筛干净，下游 AI 才不会被噪音淹没。