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

OpenKB把Karpathy的Wiki理念落地成了一个可运行的开源项目，核心思路是用PageIndex构建一个无向量的知识库。简单说，它给知识管理提供了一条新路子。

一句话概括：OpenKB把Karpathy的Wiki型知识组织思路，变成了一条可运行的开源链路，这条链路和传统RAG的路线完全不同。

最近VectifyAI开源了一个叫OpenKB的知识库项目，它的核心逻辑跟Karpathy之前提到的Wiki型知识组织思路非常接近。这个项目集成了同样来自VectifyAI的开源项目PageIndex，用它来解析PDF长文档、构建章节树和页范围检索，然后再把内容编译成摘要页（summary）、概念页（concept）、实体页（entity）等Wiki页面。当需要AI问答召回信息时，先读这一层Wiki，内容不够了再回到原始资料里找。

Karpathy在他的LLM Wiki那篇笔记里写过一句很到位的话：LLM不会觉得维护Wiki无聊，也不会忘记更新交叉引用，一次还能改掉十几个文件。人类最不擅长做的那些文档维护杂活，恰好是LLM最擅长的部分。OpenKB项目做的，就是把Karpathy的这个思路，变成了一条可以跑起来的Wiki知识库。

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

传统RAG的思路通常是：先把文档切成小块，然后做向量嵌入，问答的时候召回一批相似片段，最后把这些片段塞给模型生成答案。

OpenKB走的是另一条路：先把文档导进来，长文档先建树，短文档先转成Markdown文本，然后把内容编成摘要页、概念页、实体页这些Wiki页面；查询时先读Wiki，不够再回原始文档补细节。

所以它不是把知识留到提问时召回再临时拼接入上下文，而是在一开始的导入阶段就先整理一遍。当然，这个设计也有短板：导入时需要强依赖LLM来构建树，因此质量跟LLM的能力关系很大。

OpenKB和PageIndex分别做什么

PageIndex专注处理长PDF：先找出目录、章节和页范围，把整份文档组织成一棵树；查询时先看树，再决定去哪些页取证据。

OpenKB是上层知识库：它接收文件、目录和链接，把输入转成Markdown文本或者树结构（依赖PageIndex/LLM），然后生成摘要页、概念页、实体页、索引页和日志（依赖LLM），最后把这些页面交给查询、聊天、技能生成、演示文稿等能力使用。

简单说，OpenKB是基于PageIndex的上层应用。

快速安装使用

如果只是想先跑起来，步骤其实很简单：

pip install openkb

mkdir my-kb && cd my-kb
openkb init

openkb add paper.pdf
openkb query "What are the main findings?"
openkb chat

开始前需要先配置模型。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用。使用方式如下：

git clone https://github.com/VectifyAI/PageIndex.git
cd PageIndex
pip3 install --upgrade -r requirements.txt

OPENAI_API_KEY=your_openai_key_here

python3 run_pageindex.py --pdf_path /path/to/your/document.pdf

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

Node.js / TypeScript的SDK实现

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

npm i @fastrag/pageindex

主入口是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长度超过阈值（默认20页）就单独分流到PageIndex处理

注意，这里没有一条类似传统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一把拉进上下文

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

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

适用场景和边界

1. 本地开源版更适合个人知识库、研究资料库、小规模团队知识库，不太像能直接拿去做大型企业RAG的成品。
2. 短板主要在文档解析，尤其是复杂PDF：扫描件、图表、公式、表格、多栏版面，都不是它最稳的输入。
3. 如果场景里是数万、百万级文档，光有单文档树还不够，还得再补一层语料库级检索和治理系统。

前两条来自当前OpenKB开源仓库本身。第三条要单独说明一下：这不是说这条路线天然做不大，而是当前开源版还没把那一层放出来。PageIndex团队在2026年5月3日发布的《PageIndex File System》里，给出的企业级扩展路径，是在单文档树之上再加一层语料库树（corpus tree）/文件系统树（file-system tree），再用虚拟节点、按查询动态组织层级，以及动态展平（dynamic flattening）去处理百万级文档检索。但这套能力目前属于企业版/云端路线，不在现在这个OpenKB开源仓库里。

结论

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

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