拆解开源知识库OpenKB：Karpathy的wiki 理念，如何被PageIndex做成无向量知识库

最近VectifyAI开源了一个知识库项目OpenKB，核心逻辑和Karpathy之前提到的Wiki型知识组织思路很接近。它集成了同样是VectifyAI的开源项目PageIndex，用它解析PDF长文档、做章节树和页范围检索，再把内容编译成摘要页（summary）、概念页（concept）、实体页（entity）等Wiki页面。在AI问答召回的时候先读这层Wiki，内容不足的时候再回到原始资料。

Karpathy在他的LLM Wiki那篇笔记里写过一句很关键的话：LLM不会觉得维护Wiki很无聊，也不会忘记更新交叉引用，一次还能改掉十几个文件。人类最不擅长的那些文档维护杂务，正好是LLM最擅长的部分。

OpenKB项目做的，就是把Karpathy的这个思路落成了一条可运行的Wiki知识库。

它和传统RAG知识库有什么不同

传统RAG的主线通常是：

1、文档先切成小块

2、再做向量嵌入（embedding）

3、问答时候，召回一批相似片段

4、把这些片段塞给模型生成答案

OpenKB不是这种逻辑。它是另一种处理管道：

1、先把文档导进来

2、长文档先建树，短文档先转成Markdown文本

3、把内容编成摘要页、概念页、实体页这些Wiki页面

4、查询时先读Wiki，不够再回原文补细节

所以它不是把知识留到提问时召回再临时拼接入上下文，而是在开始的导入阶段先整理一遍。

这里有一个缺点：导入时候需要强依赖LLM进行树的构建，所以质量和LLM能力强依赖。

OpenKB和PageIndex分别做什么

PageIndex处理的是长PDF：

1、先找目录、章节和页范围

2、把整份文档组织成一棵树

3、查询时先看树，再决定去哪些页取证据

OpenKB上层知识库：

1、接收文件、目录和链接

2、把输入转成Markdown文本或者树结构（依赖PageIndex/LLM）

3、生成摘要页、概念页、实体页、索引页和日志（依赖LLM）

4、再把这些页面交给查询、聊天、技能生成、演示文稿这些能力去使用

OpenKB是基于PageIndex的上层应用。

快速安装使用

如果只是想先跑起来，其实就这几步：

开始前需要先配置模型。openkb init会把配置写入.openkb/config.yaml，模型名按LiteLLM格式填，同目录需要有.env，最少配置一个LLM_API_KEY=...。如果要接VectifyAI云端的复杂PDF处理能力，再额外加PAGEINDEX_API_KEY=...。

常用命令：

• openkb init：初始化知识库目录

• openkb add：导入文件、目录或URL

• openkb query：一次性提问

• openkb chat：多轮聊天

• openkb list / openkb status：查看知识库状态

• openkb watch：监听raw/目录，自动编译新文件

真正的文档写入入口其实是openkb add。系统会判断摄入文档的输入类型、文档长短、转换链路，以及后面该更新哪些Wiki页面。

关于PageIndex

PageIndex用来解析长PDF文档、构建目录树，它自身就是一套索引、检索引擎，不适合作为SDK使用，使用方式：

PageIndex的输出产物是JSON树结构文件。树里带标题层级、页范围、节点摘要和文档摘要。后面的智能体问答等任务中可以直接读这棵目录树，也可以把结果接回OpenKB。

Node.js / TypeScript的SDK实现

我参考官方仓库的核心业务逻辑实现了Node.js / TypeScript版本的SDK，可以接入TS技术栈的项目中。实现思路和官方的python版本一致，但接口和工程组织完全不同，这个版本是纯SDK抽象实现，不是CLI应用，适合作为npm包集成使用：

主入口是pageIndex()和mdToTree()，另外拆了两个子路径：

• @fastrag/pageindex/vector：树结果向量增强、分块、索引、搜索

• @fastrag/pageindex/retrieval：文档注册、树搜索、混合检索、自托管retrieval层

TypeScript版把LLM、文档解析等运行时完全抽象，你可以接入任意模型和文档解析器，比如MinerU等，暴露的接口为LlmProvider、DocumentParser、VectorStore、Embedder等运行时。我另外把向量增强和混合检索显式拆成了独立层，适合多文档和服务端工程接入。

OpenKB在文档导入以后的处理路径

OpenKB本地支持的输入文档：PDF、Markdown、Word文档、PowerPoint、Excel表格、HTML页面、TXT文本、CSV，也支持网页链接。

分叉主要在这里：

1、Markdown文本基本直接进后续流程

2、短PDF用pymupdf抽文本块和图片块，再拼成Markdown文本（对复杂PDF无能为力）

3、docx、pptx、xlsx、html这类文件主要交给MarkItDown转成Markdown文本，再把嵌入图片拆出来另存

4、链接如果是网页，就用trafilatura抽正文；如果远端返回的是PDF，就先下载到本地，再按PDF处理

5、PDF长度超过阈值就单独分流到PageIndex处理，默认是20页

注意，这里没有一条类似传统RAG的"先分块再进库"的总流水线。短文档先统一成Markdown文本，长文档先统一成树结构。

导入后，原始输入进入raw/或source/目录，短文档整理成Markdown文本，长文档落成逐页JSON文件和树摘要，后面的编译流程再决定要更新哪些摘要页、概念页、实体页、索引页和日志。

PageIndex怎么处理长PDF

1、先按页抽文本

2、看前几页里有没有目录

3、有目录就把目录转成层级结构，再对齐真实物理页码；没有目录，就从正文里生成一套层级结构

4、每个节点会记录标题、节点ID、起止页范围、摘要这些信息

5、查询时先读树，再去对应页范围取内容

这套结构不是为了喂向量库，而是为了让模型先读目录树，再决定往哪一段页范围继续下钻。

这里不是完全不切分，而是按章节边界递归下钻。某个章节节点如果覆盖页数和词元量都太大，代码会继续往下拆。它的主索引单元不是固定分块，而是树节点和页范围。

本地开源版的边界在PDF解析层

问题也在这。PageIndex本地开源链路更接近PyPDF2这一类基础文本抽取。原生文本PDF问题不大，阅读顺序比较规整的文档也还可以。到了扫描件、多栏论文、复杂表格、公式密集、跨栏版面这些场景，基础抽取精度就不算稳了。

更强的光学字符识别（OCR）、复杂PDF处理和更快的结构生成，走的是PageIndex Cloud这条能力线，不在当前本地开源链路里。

对应到实际使用上，这套方案更适合两种输入：一类是本身就干净的原生文档，另一类是前面已经做过专业解析的文档。遇到扫描件、图表密集PDF、公式和表格很多的材料，前面最好接MinerU这类专业解析器，或者直接用官方云能力。前面的抽取一旦歪掉，后面的树和Wiki基本也很难稳。

OpenKB怎么把文档编译成Wiki

文档进来以后，OpenKB干的不是"存起来等检索"，而是继续编Wiki。大概分两步。

1、先给单篇文档落source和摘要页。长文档路径里，至少会生成wiki/sources/

2、再把新内容并进现有Wiki。编译流程会生成摘要页，读取现有概念页和实体页，决定哪些页面要新建、哪些页面要更新，再回写交叉链接、索引页和日志

所以新文档进来以后，不一定只是多一个摘要页，它还可能把已有概念页、实体页和索引页一起改掉。

如果把这一步拆开看，就是先拿新文档生成一份局部摘要，再和现有知识页做比对，然后决定哪些主题和对象值得沉淀，最后把页面之间的链接补回去。这一步更像在改Wiki，不像传统RAG那样只是多了一批可召回片段。

摘要页、概念页、实体页各自干什么

1、摘要页（summary）负责单文档压缩。短文档路径里，模型直接看全文生成摘要。长文档路径里，模型先看PageIndex产出的结构化摘要，再往下继续处理

2、概念页（concept）负责跨文档主题。抽象主题、机制、方法、模式这类内容，会被沉淀成概念页，而不是每次都只留在单篇文档里

3、实体页（entity）负责具体命名对象。人、组织、地点、产品、作品、事件这类对象，不是看见一次就开页，只有对当前文档足够核心、或者后面大概率会重复出现的对象，才值得单独沉淀

查询时先读哪一层

查询时一般按这个顺序走：

1、先读index.md

2、再读相关摘要页、概念页和实体页

3、这些还不够，再回原始文档取证据

4、如果原始文档是长PDF，就按页范围调用get_page_content，不是把整篇PDF一把拉进上下文

原文在这里更像证据层，不是第一跳。

如果问题问的是抽象主题，系统往往会先停在概念页这一层；如果问题问的是具体对象，实体页往往会更早介入。只有页面层解释不了的细节，才需要回源文档取证。

结论

所以更适合把OpenKB看成一个很有意思的开源样板。它把一条不同于传统RAG的路线先跑通了：长PDF先做树索引，知识再编成Wiki，查询先读Wiki，再回原文取证。

如果目标是个人知识库、论文和报告的长期积累，这条路是成立的。如果目标是一套开箱即用的大型企业知识库，当前开源版还差复杂文档解析、语料库级检索、权限和治理这几层。