先说几个前提。这篇文章里的所有观点，都基于作者个人的技术实践和独立思考，核心目标就是分享经验。
好，进入正题。
从一个知识库检索“超级微服务高级skill”的示例说起——这件事背后，藏着一个更深的问题。
知识库，到底困在哪儿？
RAG 的天花板
提到知识库方案，大家最熟悉的恐怕就是 RAG（Retrieval-Augmented Generation）了。流程很简单：文档切成块 → 做嵌入（embedding） → 用户提问时向量检索 Top-K → 喂给大语言模型生成答案。这套打法在简单的问答场景里确实够用，但在工程知识库的场景下，有三个结构性的硬伤。
第一个缺陷，就是每次都得从零开始推导。 Karpathy 在 LLM Wiki 的设计文档里说得挺直白——“LLM 在每个问题上都从头重新发现知识，没有任何积累。” 想象一下，一个需要综合 5 篇文档才能回答的问题，LLM 每次都得把这 5 个片段重新找出来、拼接好，没有任何中间成果可以被保留下来。
第二个缺陷，是无法“连点成线”。 Microsoft 的 GraphRAG 研究直接指出了 baseline RAG 的两个失败模式：一是“struggles to connect the dots”，答案需要跨越分散信息时，平坦的向量检索完全无能为力；二是“performs poorly when being asked to holistically understand summarized semantic concepts over large data collections”，面对大规模语料，无法做全局性的语义理解。
第三个缺陷，是粒度混乱。 一个 chunk 可以是“系统设计原则”，也可以是“某个函数的第 42-143 行实现”。向量空间根本不区分这些抽象层次——“设计原则”和“代码实现”在语义上可能很近（比如都包含了“单一职责”这个词），但它们服务的认知需求截然不同。
四个我们再熟悉不过的症状
不管团队规模大小，知识库多多少少都会出现这些症状：
- “搜什么都是那几篇” —— 高词频的长文档直接垄断了 Top-K 结果。
- “找到了，但不是我要的层次” —— 想知道“是什么”，返回的却是“怎么实现”。
- “改了一个地方，不知道会影响什么” —— 文档之间完全没有关联关系。
- “新人来了，根本不知道从哪看起” —— 没有清晰的阅读路径和导航结构。
这些症状的根源其实指向同一点：知识库缺少结构。 向量检索把知识当成“一袋词”来处理，但工程知识是“一棵树”、是“一张图”。
知识库方法论全景：从“平铺”到“结构化”
目前主流的构建方法论大致可以分成四个范式，每个范式都代表了对于“知识应该如何组织”这个问题的不同回答。
范式一：Naive RAG —— 平铺直叙的向量检索
核心思想： 文档 → 分块 → 嵌入 → 向量数据库 → 相似度检索。
它的优势很明显：实现简单，几乎不需要预处理，开箱即用。但局限也很突出：默认配置下没有积累、没有关联、没有层次、没有角色区分。每次查询都是一次性的，知识并不会因为使用而变得更好。（当然，现代的 RAG 可以通过 metadata filter、rerank、hybrid search、query routing 等手段来弥补一部分缺陷，但这都需要额外的工程投入。）
代表产品包括大多数企业知识库、ChatGPT 的文件上传、NotebookLM 的基础模式等。
范式二：LLM Wiki —— 持续编译的知识“工件”
核心思想： LLM 不再只是检索者，而是知识的维护者。知识被“编译一次并持续维护”，而不是每次查询时都重新推导。
这是 Andrej Karpathy 提出的模式。其核心洞察在于：wiki 是一个持续积累的工件。交叉引用已经建好，矛盾已经被标记，综合分析已经反映了所有已读内容。
它的架构分三层：
| 层 | 职责 | 谁维护 |
|---|---|---|
| Raw Sources | 不可变的源文档集合（论文、文章、数据文件） | 人类策展 |
| Wiki | LLM 生成的结构化 markdown 页面（实体页、概念页、综合页） | LLM 完全拥有 |
| Schema | 定义 wiki 结构、约定和工作流的配置文件 | 人类 + LLM 共同演进 |
这个模式有三个核心操作：
- Ingest： 新源文档进入后，LLM 通读、写摘要页、更新索引、修订所有相关的实体和概念页面。一次 ingest 可能触及 10-15 个 wiki 页面。
- Query： 通过 index.md 定位相关页面 → 读取 → 综合带引用的回答。关键机制在于，好的回答可以反哺为新的 wiki 页面，让探索本身也变成知识积累。
- Lint： 定期健康检查——发现矛盾、过期声明、孤立页面、缺失概念、断裂的交叉引用。
Karpathy 特别指出，人类维护 wiki 失败的根本原因是“维护负担的增长快于价值的增长”。而 LLM 显著降低了这个瓶颈——它做摘要、交叉引用、归档、记账，维护成本远低于人工。当然，LLM 维护也不是万能的，可能会有过期引用、内容冲突、错误归档甚至幻觉的风险，需要人类定期审核。人类的角色转变为策展、方向指引、深度思考和质量把关。
局限： wiki 页面之间的关联是通过 wikilink 手动维护的，没有自动的关系推断和社区检测。比较适合中等规模（约 100 篇源文档）的知识库。
范式三：Graphify —— 代码即图谱
核心思想： 把代码库、文档、配置文件、设计稿等异构资源，统一映射成一张可查询的知识图谱。
Graphify 采用双管道提取：
- AST 管道（离线）： 通过 tree-sitter 对多种编程语言做本地解析，提取函数、类、模块、导入等代码实体。不调用任何外部 API。
- 语义管道（LLM）： 对文档、PDF、图片、视频等非代码内容做 LLM 语义提取，生成概念节点和关系边。
它产出三样东西：graph.html（浏览器可视化）、GRAPH_REPORT.md（洞察报告）和 graph.json（完整图谱数据）。
它的独特能力包括：自动发现连接度最高的“God Nodes”（概念枢纽）、识别意料之外的跨模块关联（按“意外程度”排序）、自动发现知识缺口，以及为每条关系标记置信度（EXTRACTED / INFERRED / AMBIGUOUS），保证可追溯性。
与传统文档的本质区别在于，传统文档是线性的、静态的、按文件隔离的。而 Graphify 把代码、数据库、配置、设计文档、媒体统一到一张图里——一个 SQL schema 节点可以直接连接到查询它的应用代码，以及解释它设计理由的 PDF。
局限： 图谱擅长关联分析（“A 和 B 有什么关系”），但不擅长直接问答（“这个接口的参数是什么”）。图谱是知识的骨架，不是知识本身。
范式四：GraphRAG —— 图谱增强的检索
核心思想： 先构建知识图谱 → 社区聚类 → 生成分层摘要 → 查询时结合图结构和社区摘要来回答。
Microsoft 的 GraphRAG 是对 Naive RAG 的结构化升级：源文档 → 实体/关系提取 → 构建知识图谱 → Leiden 算法社区聚类 → 分层社区摘要 → 查询时（Global Search / Local Search）。
它有两种查询模式：
- Global Search： 利用社区摘要做全局推理，比如“整个代码库的设计模式有哪些？”
- Local Search： 从特定实体出发，沿图谱边扩展到邻域，比如“UserService 关联了哪些组件？”
这正好解决了 Naive RAG 的两大痛点：通过图结构“连点成线”，通过社区摘要实现“全局理解”。
局限： 构建成本高（需要大量 LLM 调用做实体提取），增量更新困难，对源文档质量也比较敏感。
四种范式的理论对比
| 维度 | Naive RAG | LLM Wiki | Graphify | GraphRAG |
|---|---|---|---|---|
| 知识表示 | 向量空间中的 chunk | 结构化 wiki 页面 | 有向图（节点+边） | 知识图谱+社区摘要 |
| 知识积累 | ❌ 无 | ✅ 持续积累 | ✅ 增量更新 | 部分（需重建） |
| 知识关联 | 默认无 | 手动 wikilink | ✅ 自动推断 | ✅ 自动推断 |
| 层次感知 | 默认无 | 按主题分页 | 按社区分组 | 分层社区 |
| 角色适配 | 默认无 | ❌ 无 | ❌ 无 | ❌ 无 |
| 适合规模 | 大（1000+篇） | 中（~100篇） | 大（整个代码库） | 大（但构建贵） |
| 维护成本 | 低（自动索引） | 中（LLM维护） | 低（git hook自动） | 高（需重建） |
| 核心能力 | 语义相似度检索 | 综合编译+导航 | 关联分析+缺口发现 | 全局理解+局部精确 |
金字塔：一种新的知识工程范式
金字塔解决了什么
仔细看上面四种范式，每一种都有自己明确的强项，但都缺失了一个关键能力：层次感知 + 角色适配。
- Naive RAG 没有层次
- LLM Wiki 有主题分页，但没有抽象层级
- Graphify 有社区，但没有稳定性/粒度的区分
- GraphRAG 有分层社区，但没有角色映射
所以，金字塔知识库补上了这一环：把知识按稳定性和抽象度分成 5 层，每层服务不同的认知需求和角色。
五层分层设计
为什么是 5 层？这五层正好对应了软件工程中常见的抽象层次划分——从不变的原则，到易变的经验：
| 金字塔层 | 软件工程对应 | 稳定性 | 类比 |
|---|---|---|---|
| L1 原则 | SOLID / KISS / YAGNI | 最高（年） | 宪法 |
| L2 架构 | 架构决策记录（ADR） | 高（季度） | 法律 |
| L3 规范 | 编码标准（ESLint 规则） | 中（月） | 规章 |
| L4 实现 | 代码模板、SDK 文档 | 低（周） | 手册 |
| L5 经验 | 故障复盘、运维日志 | 最低（天） | 判例 |
分层的核心价值在于：检索时先确定“用户在问哪个层次的问题”，再在该层内精确定位。这能显著降低粒度混乱——很大程度上避免了“回答‘为什么’的时候，返回了‘怎么实现’”这种尴尬。
知识图谱：跨层关联
金字塔不只是 5 个独立的文件夹。每篇文档是一个节点，文档之间通过 7 种有向边关联：
| 边类型 | 方向 | 含义 |
|---|---|---|
governs |
L1→L2 | 原则约束架构决策 |
defines |
L1→L2/L3 | 概念定义域边界 |
constrains |
L2→L3 | 架构约束编码规范 |
implements |
L2/L3→L4 | 架构/规范的具体实现 |
validates |
L4→L5 | 实现产生运维经验 |
feedback |
L5→L3/L4 | 经验反馈改进规范和实现 |
cross_ref |
任意 | 同层或跨层的横向引用 |
这形成了一个有向图，可以支持：
- 上溯： 从实现追溯到它遵循的原则和架构。
- 下探： 从原则推导出应该怎么实现。
- 反馈环： 运维经验反哺，改进规范和实现。
- 场景路径： 预定义的跨层阅读路径，比如“新人 Onboarding：L1→L2→L3→L5”。
角色感知：不同人看不同层
金字塔的另一个独有设计是角色-层级访问矩阵。
同一个知识库里，架构师看到的是 L1+L2（原则和架构），开发者看到的是 L2+L3+L4（架构、规范和实现）。每个角色都有独立的 context_budget 和 priority_order，系统会按优先层顺序逐层填充内容直到预算用完，确保有限的 context window 里优先塞入该角色最需要的知识。
检索机制：结构化路由 vs 向量相似度
金字塔的检索方式与传统向量检索有本质区别。向量检索是“从所有文档里找最像的”，而金字塔是“先确定去哪层找，再精确定位”。
当前实现：分层关键词打分 + 图谱扩展
关键是，所有检索都在本地完成，无需任何网络调用。分层结构将搜索空间从全量文档缩小到角色可访问的层级子集，图谱扩展则自动补充上下游关联。
Roadmap：未来计划引入 layer-registry 索引机制（服务名/概念关键词 → 文档 ID 的速查表），实现摘要直答和更精确的结构化路由，进一步减少对全文扫描的依赖。
与向量检索的机制对比
| 维度 | 向量检索 | 金字塔分层检索 |
|---|---|---|
| 定位方式 | 语义相似度（embedding 距离） | 分层关键词打分 + 图谱扩展 |
| 搜索空间 | 全量文档 | 角色可访问层的子集 |
| 粒度控制 | 默认无（原则和代码混在一起返回） | 先按层过滤再定位 |
| 关联能力 | 默认单文档匹配 | 图谱边自动关联上下游 |
| API 调用 | 每次 1 次 embedding 调用 | 0 次（纯本地） |
| Token 消耗 | 较高（返回 raw chunk） | 较低（budget 截断 + 摘要级内容） |
| 冷启动 | 无需预处理 | 需要先 ingest 构建金字塔 |
| 代码级深度 | ★★★★★（函数签名/行号） | ★★★（架构级，需穿透补深度） |
核心优势： 金字塔通过分层 + 角色过滤将搜索空间大幅缩小，再通过图谱扩展补充关联上下文，全程无网络调用。代价是需要预先构建金字塔结构。
最优组合： 金字塔做分层定位（0 API 调用）→ 向量检索补代码级深度（1 API 调用）= 结构化导航 + 精确细节的互补。
金字塔与其他范式的关系
金字塔不是要替代其他范式，而是在顶层增加了一个结构化的路由和导航层。
简单来说，金字塔的 19 篇文档，是 831 篇源文档（这是一个还在不断补充的团队基础知识库）的“索引 + 摘要 + 导航图”，让 AI 知道该去哪里找、按什么顺序读、给谁看哪些。
同步机制：知识库，不是一次性的
知识库的“腐烂”问题
知识库最大的敌人不是“没有内容”，而是“内容过期”。
腐烂有三种常见形式：
| 类型 | 表现 | 危害程度 |
|---|---|---|
| 静默过期 | 文档描述的接口签名已变，但文档没更新 | ★★★★★ |
| 层级漂移 | 当初的架构决策（L2）已降级为历史背景（L5），但还放在 L2 | ★★★ |
| 覆盖盲区 | 新服务上线了 3 个月，L4 实现参考里完全没有它 | ★★★★ |
一个简单的判断标准：如果团队新人按知识库操作后会踩坑，那这篇文档就已经腐烂了。
知识保鲜的方法论
解决腐烂的关键不是“定期检查所有文档”（这根本做不到），而是让知识的新鲜度变得可度量。
原则一：每层有不同的保鲜周期
不是所有知识都需要同频维护。越接近塔顶越稳定，越接近塔底越需要更新：
| 层 | 合理的审查周期 | 过期信号 |
|---|---|---|
| L1 原则 | 年度 | 团队内部对某条原则产生分歧 |
| L2 架构 | 季度 | 系统拓扑图与文档不一致 |
| L3 规范 | 月度 | Lint 规则和文档描述的规则不同 |
| L4 实现 | 周/天级 | 代码模板跑不通或依赖版本过期 |
| L5 经验 | 天级 | 故障排查 SOP 中提到的命令/路径不存在 |
原则二：用审计发现问题，而非人工巡检
人工巡检不可持续。正确的做法是建立可自动化的审计指标：
| 审计维度 | 检查什么 | 健康标准 |
|---|---|---|
| 覆盖率 | 每层是否有条目、核心服务是否被覆盖 | 无空层，已知服务 100% 覆盖 |
| 新鲜度 | 条目最后更新时间 | 无超过 90 天未更新的 L4/L5 条目 |
| 图谱连通 | 是否存在孤立节点 | 所有条目至少有 1 条边 |
| 层级平衡 | 每层条目数是否合理 | L1 ≤ 10，无单层占比超过 50% |
原则三：变更驱动更新，而非日历驱动
最有效的触发机制不是“每月检查一次”，而是把它绑定到已有的工作流里：
| 触发事件 | 应更新的层 | 为什么 |
|---|---|---|
| 架构评审通过 | L2 | 新的架构决策产生了 |
| Lint 规则变更 | L3 | 编码规范变了 |
| 依赖大版本升级 | L4 | 实现参考可能失效 |
| 故障复盘完成 | L5 | 新的经验知识产生 |
| 新服务上线 | L2 + L4 | 需要补架构描述和实现参考 |
| 新人入职提问 | L3 / L5 | 新人问到的问题说明文档有缺口 |
增量同步机制
金字塔通过一套流程来解决同步问题：
Phase 1 审计 → 扫描覆盖率 / 检测过期文档 / 输出 gaps
Phase 2 摄入 → 加载源文档 / 分块 / 分类 / 去重（skip/update/move/write）
Phase 3 后审计 → 对比 Before/After 覆盖率改进
去重采用四策略（checksum + entry ID 双重校验）：
| 场景 | 动作 |
|---|---|
| 内容不变、同层 | skip |
| 内容变了、同层 | update（保留 createdAt） |
| 层级变了 | move（删旧写新） |
| 全新内容 | write |
测评结果
实验条件
- 知识库规模： 831 篇源文档，覆盖 14 个代码服务、5 个业务域，源自内部一个中等规模工程团队的技术文档。
- 评测数据集： 200 条 QA pair，覆盖服务定位、架构概念、代码细节、运维排障、跨服务关联、导航 6 个维度。由 LLM 生成后人工审核，每条都标注了 ground truth 文档 ID。
- 评测指标： 采用 RAGAS 标准框架，包含 Hit@K、MRR、Context Precision、Context Recall 四项检索指标，以及估算的 Faithfulness 和 Answer Relevancy 两项生成指标。
- 检索模拟： C/D/E/F 模式使用关键词匹配模拟各系统的检索逻辑（非实际部署的检索引擎）。A 模式基于 8 条 searchDocChunk API 实测样本估算。
局限性声明
- 单评估者（项目作者）、非盲评。
- 评测集由 LLM 生成，可能存在分布偏差。
- 仅在单一团队知识库上测试，结论是否跨团队通用需要进一步验证。
测试模式
| 代号 | 模式 | 检索机制 | 类型 |
|---|---|---|---|
| A | Naive RAG | 纯向量语义召回 | Vector Store |
| B | Pipeline Skill | 7 阶段 pipeline + 6 层路由 | Agentic Pipeline |
| C | Pyramid KB | 分层关键词 + 同义词扩展 + 图谱增强 | Hierarchical KB |
| D | Pyramid + RAG | Hybrid：金字塔路由 → 向量检索穿透 | Hybrid Retrieval |
| E | LLM Wiki | 23 篇编译 wiki + wikilink 导航 | Linked KB |
| F | Knowledge Graph | 86 节点 / 214 边图谱遍历 + 社区聚类 | KG Query |
Query 类型分布
| 类型 | 数量 | 占比 | 说明 |
|---|---|---|---|
| 代码细节 | 80 | 40% | 具体实现方式、函数用法、配置方法、设计模式应用 |
| 运维排障 | 40 | 20% | 线上故障排查、告警处理、发布回滚、容量规划 |
| 架构概念 | 30 | 15% | 系统设计原理、技术选型依据、模块间通信方式 |
| 跨服务关联 | 25 | 12.5% | 服务间依赖关系、数据流转路径、故障影响面分析 |
| 导航 | 15 | 7.5% | 文档阅读路径、学习顺序、知识覆盖度查询 |
| 服务定位 | 10 | 5% | 服务职责、技术栈、规模等基础信息（非入门级问题） |
检索指标结果
| 模式 | Hit@1 | Hit@3 | Hit@5 | MRR | Ctx Prec | Ctx Recall |
|---|---|---|---|---|---|---|
| D: Pyramid+RAG | 32.5% | 89.0% | 89.5% | 53.7% | 0.405 | 0.636 |
| A: Naive RAG | 55.0% | 75.0% | 75.0% | 61.6% | 0.218 | 0.320 |
| F: Knowledge Graph | 64.5% | 71.0% | 71.0% | 67.5% | 0.574 | 0.317 |
| C: Pyramid KB | 32.5% | 58.5% | 64.5% | 44.8% | 0.272 | 0.480 |
| B: Pipeline Skill | 44.5% | 54.5% | 54.5% | 49.3% | 0.419 | 0.457 |
| E: LLM Wiki | 31.0% | 40.0% | 40.0% | 35.4% | 0.242 | 0.400 |
分维度表现（Hit@3）
| 查询类型 | n | D:Pyr+RAG | C:Pyramid | B:Pipeline | F:Graphify | E:Wiki | A:RAG |
|---|---|---|---|---|---|---|---|
| 代码细节 | 80 | 98.8% | 87.5% | 61.3% | 75.0% | 66.3% | ~100%* |
| 运维排障 | 40 | 82.5% | 47.5% | 17.5% | 67.5% | 22.5% | ~100%* |
| 架构概念 | 30 | 86.7% | 36.7% | 43.3% | 70.0% | 23.3% | ~100%* |
| 跨服务关联 | 25 | 68.0% | 36.0% | 96.0% | 92.0% | 4.0% | 0.0% |
| 导航 | 15 | 93.3% | 40.0% | 46.7% | 33.3% | 33.3% | 0.0% |
| 服务定位 | 10 | 90.0% | 20.0% | 90.0% | 60.0% | 50.0% | 0.0% |
总结
以上结果初步体现了分层结构 + 向量检索混合方案在检索精度上的优势（Pyramid+RAG 的 Hit@3=89%，而 Naive RAG 约为 75%）。但这仍然是在 200 条样本、单一团队知识库上得到的观察，而且 Mode A 的数据是估算值。更大规模的数据集、真实的 API 全量调用、多评估者交叉验证、跨团队的复现，是后续的工作方向。
金字塔思路的核心价值，不在于替代任何一种知识库，而在于给知识加上结构——让不同角色的 AI 知道该去哪里找、按什么顺序读、给谁看哪些。
最终的目标很简单：程序员问一个问题，AI 能在 3 秒内返回正确层次、正确角色、正确关联的答案——而不是 5 段不相关的文本。
参考文献
Karpathy, A. (2025). LLM Wiki Pattern: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
Shamsi, S. (2025). Graphify: Knowledge Graphs for Code: https://github.com/safishamsi/graphify
Microsoft Research. (2024). GraphRAG: Graph-based Retrieval-Augmented Generation: https://microsoft.github.io/graphrag/