VINO/WANG返回博客 ←

BLOG / POST

OKF 与 LLM Wiki

探讨 Karpathy 提出的 LLM Wiki 模式与 Google 的开放知识格式 OKF，打破知识在工具间的锁定。

  • llm
  • knowledge

（本文由 AI 协助生成，经作者审校调整。）

大模型很强，但缺少上下文就是空中楼阁。组织内部真正有用的知识——表结构、指标定义、事故 runbook、系统间 join 路径、旧 API 废弃公告——散落在 metadata catalog、wiki、代码注释、几个老员工的脑子里。每个 agent 厂商都在自造 catalog、SDK、知识图谱，知识被锁死在创建它的工具里。

Karpathy 在他的 llm-wiki gist 里把这个困境讲得最直白：大多数人用 LLM 的方式本质上是 RAG——上传文件、查询时分块检索、每次都从零开始拼答案，没有累积。Google Cloud 团队随后提出的 OKF（Open Knowledge Format） 则试图把这条思路标准化成一个可移植的格式。一个是模式，一个是格式，本文聊聊两者各自讲了什么、怎么扣在一起。

Karpathy 的 LLM Wiki：一个反 RAG 的模式

gist 的核心翻转在于：让 LLM 增量地构建并维护一个持久 wiki——介于你与原始资料之间的一层 markdown 文件集合，每次查询不必再回头翻原始文档。新资料进来时，LLM 做的事远超过建索引：读、抽取、整合进已有 wiki，更新实体页、修订摘要、标注矛盾、强化或质疑正在演化的综合结论。一句话——知识编译一次，然后保持更新，查询时不再重做一遍。

三层架构

层 角色 谁写
Raw sources 不可变的原始资料（文章、论文、笔记） 人
The wiki LLM 生成的 markdown 目录（摘要、实体页、概念页、综述） LLM 独占
Schema（CLAUDE.md / AGENTS.md） 告诉 LLM wiki 怎么组织、ingest / query / lint 的工作流 人与 LLM 共同演化

三类操作

  • Ingest：投喂新资料 → LLM 读、讨论、写摘要页、更新 index、改相关实体/概念页、追加 log。单个来源可能动 10–15 个页面。
  • Query：LLM 先读 index 找到相关页，再钻进去综合答案带引用。好答案回填进 wiki 做新页面，让探索也复利。
  • Lint：周期性健康检查——找矛盾、过期声明、孤儿页、缺失交叉引用、该有自己页的重要概念。

为什么有效

维护知识库累的部分在于 bookkeeping，读和想反而轻松——更新交叉引用、保持摘要同步、标注矛盾、维护几十个页面的一致性。人类放弃 wiki 是因为维护成本增长比价值快。LLM 不会无聊、不会忘了更新交叉引用、一次能改 15 个文件。

类比很精准：Obsidian 是 IDE，LLM 是程序员，wiki 是代码库。精神源头是 Vannevar Bush 1945 年的 Memex——私人策展、文档间有关联轨迹的知识存储。Bush 解决不了的“谁来做维护”这件事，LLM 解决了。

OKF：把模式标准化成格式

Google Cloud 团队注意到同一个模式反复出现：Obsidian vault 接 coding agent、AGENTS.md / CLAUDE.md 约定文件家族、塞满 index.md / log.md 的 repo、数据团队的“metadata as code”仓。每个实例都是定制的——长得像，但不互相合作。没有约定：每篇文档该带哪些字段，文件名意味着什么。知识仍然困在原团队，新 agent 一建就要重做一遍。

OKF v0.1 就是答案。它本身只是一个格式，不提供服务——任何人都能生产、任何人都能消费、能在系统/组织/工具间迁移、活在版本控制里、人读得懂 agent 也能解析。

设计：一屏看完

一个 OKF bundle 是一个概念目录（表、数据集、指标、playbook、runbook、API 都行）。一个概念一个文件，文件路径就是身份。每个概念文件有一小块 YAML frontmatter 给结构化字段（type、title、description、resource、tags、timestamp），markdown 正文给其他一切。概念之间用普通 markdown 链接连起来，把目录变成一张比文件系统父子关系更丰富的图。可选 index.md 和 log.md。

三大原则

  1. Minimally opinionated：每个概念只要求一个 type 字段。其他一切（types 有哪些、加哪些字段、正文怎么分节）留给生产者。规范定义互操作表面，不定义内容模型。
  2. Producer/consumer independence：人手写的 bundle 能被 agent 消费；metadata 导出管道生成的 bundle 能在可视化器里浏览；一个 LLM 合成的 bundle 能被另一个 LLM 查询。格式就是契约，两端的工具可以独立替换。
  3. Format, not platform：不绑定任何云、数据库、模型、agent 框架。永远不要求专有账户或 SDK。发布为开放标准，因为知识格式的价值来自多少人会讲这种语言，而不是谁拥有它。

随规范一起发布的参考实现

  • Enrichment agent：遍历 BigQuery 数据集，为每张表/视图起草 OKF 概念文档，再用第二轮 LLM 爬取权威文档给每个概念加引用、schema、join 路径。
  • 静态 HTML 可视化器：把任意 OKF bundle 变成单文件交互图，无后端、免安装、数据不离开页面。
  • 三个示例 bundle：GA4 e-commerce、Stack Overflow、Bitcoin 公开数据集。
  • Google Cloud 的 Knowledge Catalog 已经能摄入 OKF 并喂给 agent。

两者的关系：从模式到标准

最直接的对应关系：

Karpathy LLM Wiki OKF
三层之一：raw sources / wiki / schema bundle = wiki 那一层
CLAUDE.md / AGENTS.md OKF 规范本身 + 每个 bundle 自己的 schema
index.md / log.md 可选保留文件名，语义对齐
实体页、概念页、综述 concept（每个一个文件）
手工 wikilinks 标准 frontmatter + markdown 链接
每个 instance 各自为政 生产者/消费者独立，跨工具互操作

Google 的博文里直接引用了 Karpathy 的原话——OKF 的定位就是把 Karpathy 的模式形式化为可移植、可互操作的格式。Karpathy 的 gist 故意抽象（只讲 pattern，不规定实现），OKF 把“文件路径是身份、frontmatter 必带 type、链接语义、保留文件名”这几件最小的事钉死，让不同生产者写的 wiki 能被不同消费者无翻译读取。

几个关键洞察

第一，LLM Wiki 与 RAG 的分野在量级。评论里 Shilren 给的决策树最实用：小于 50k–100k token（约 150–200 页密集内容）时，上下文完胜——检索可靠性 100%、几乎零基建、能对全局推理，免去拼零散片段的麻烦；数百万 token 以上只能 RAG；中间和生产系统走混合（核心稳定知识进上下文，海量动态数据进 RAG）。现代上下文窗口到 200k–1M+ token，纯上下文这条路的门槛一直在抬升。OKF 的 markdown bundle 天生契合“进上下文”这条路——它就是为直接读而非向量化设计的。

第二，累积性是真正的差异化。RAG 每次重新发现知识；LLM Wiki 编译一次、保持更新。矛盾已标好、交叉引用已铺好、综合结论已反映你读过的一切。wiki 随每个新来源、每个新问题持续变富。OKF 把这种“持续变富的产物”做成了可交换的格式单位。

第三，真正缺的是格式不是服务。这是 OKF 的核心论点，也是对整个 RAG / vector DB 狂热的隐性批评。组织里的知识碎片化问题，多一个知识服务解决不了，只会让每个 vendor 再造一遍数据模型。OKF 要求的恰恰相反：最小约束、纯文件、纯 markdown，价值来自互操作而非所有权。

第四，维护成本归零才让 wiki 活下来。人类放弃 wiki 是因为 bookkeeping 成本超过价值。LLM Wiki 的整个可行性建立在一个事实之上——更新交叉引用、保持摘要同步、维护多页一致性这些事，LLM 不嫌烦、不忘、一次能改很多文件。OKF 把这个“LLM 维护”行为固化成了 bundle 生命周期（ingest、enrichment、可视化），让任何生产者都能复用。

第五，安全、并发、矛盾是真实存在的工程问题，绝非 nice-to-have。这几个主题在 gist 评论里反复出现：

  • 安全：NicoBleh 指出自动摄入的 wiki 本身是一个间接提示注入面——crafted 源可以在 wiki 里植入指令毒化后续会话。不变式：不可信输入（source）永远不能到达后续被当可信处理的通道（wiki）。工具化：nonce 分隔、第二模型审查写入、按 host 分信任层、git-backed provenance、注入语料库映射。
  • 并发/写入冲突：watsonrm 精准指出 git merge 解决的是文本冲突，但真正毁掉 wiki 的是语义冲突——两个 agent 用不同措辞写同一事实，git 看到 non-overlapping addition，干净合并出一份重复。可扩展的多写入者靠“加一步 merge”撑不起来，必须把数据建模成并发写入天然可交换：append-only log、每行一条、按文件/section 分区。
  • 矛盾作为信息：pursultani 在人文领域做对了反向操作——客观认识论下矛盾是缺陷要解决，对话认识论下（文学批评、哲学、史学）矛盾本身就是知识内容。这种场景下 lint 该检查缺失的矛盾而非标记已有的。需要 typed edges（在 frontmatter 声明 relates_to: {page, rel: contradicts/extends/supersedes}）+ 配套的 lint 策略，缺一不可。

第六，上下文 vs 权重也是一道岔路。mikhashev 的实验很有警示意义：在小于 10M 参数的小模型上，LoRA / test-time-training 注入知识 600 组组合全部失败——因为 p(fact) 在 LoRA 之前就低于 0.5 阈值，基模型梯度比 LoRA 梯度大 600–5000 倍，adapter 根本撼动不了模型。结论：在可消费级硬件上的小模型，“知识即权重”路线走不通，LLM Wiki 这类“知识即外部结构”反而是个人规模上更现实的方向。

落地建议

如果你想用这套东西，落到 Karpathy 的三层结构最自然：

  1. Schema 层：直接用 OKF 作为 schema 的互操作部分（强制 type 字段、文件路径即身份、链接语义），自定义部分（domain-specific 的字段、body 结构、lint 规则、ingest 工作流）写到 CLAUDE.md / AGENTS.md。
  2. Raw 层：用 Obsidian Web Clipper 抓网页、本地存图片、用 git 做版本和分支——这些都是免费的。
  3. Wiki 层：OKF bundle 形态的 markdown。中规模（约 100 sources、几百页）下 index.md + LLM 先读 index 再钻页的做法很够用，不需要 embedding/RAG 基建。规模上来再上 qmd 这类本地 BM25+vector+LLM 重排搜索引擎或 MCP server。
  4. 从第一天就把 provenance、矛盾检测、安全门做进 schema：别等 wiki 长大再补，后期补会很痛。

附：一个迷你 OKF bundle

为了把抽象格式变具体，下面给一个 GA4 电商场景的目录结构：

ga4-ecommerce/
├── index.md                 # 内容索引（progressive disclosure 入口）
├── log.md                   # 时间日志（append-only）
├── datasets/
│   └── ga4-events.md        # type: dataset
├── tables/
│   ├── events.md            # type: table
│   └── items.md             # type: table
├── metrics/
│   ├── total-revenue.md     # type: metric
│   └── weekly-active-users.md  # type: metric
└── playbooks/
    └── compute-wau.md       # type: playbook

要点：一个概念一个文件，文件路径就是身份；每个文件 frontmatter 只强制 type 一个字段；概念之间用普通 markdown 链接连成图；index.md / log.md 是可选保留文件名。

挑一个 table 概念文件看真实形态：

---
type: table
title: events
description: GA4 行级事件表，每行一个 event。按天分区 events_YYYYMMDD。
resource: bigquery://bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_*
tags: [ga4, table, events]
timestamp: 2026-06-13T09:12:00-03:00
---

# events

GA4 的核心事件表。一行 = 一个 event。嵌套 RECORD 字段承载 user / ecommerce / items 等维度。

## 关键字段

| 字段 | 类型 | 说明 |
|---|---|---|
| event_date | STRING | YYYYMMDD，分区键 |
| event_timestamp | INT64 | 事件发生的微秒时间戳 |
| event_name | STRING | 事件类型，如 purchase、page_view、refund |
| user_pseudo_id | STRING | 匿名用户标识，基于 cookie |
| ecommerce | RECORD | 电商字段，含 transaction_id、purchase_revenue 等 |
| items | REPEATED RECORD | 关联商品，详见 items |

## Join 路径

- 与 items：同一行内 items 是 repeated，直接 unnest 即可，无需 join key。
- 与自身跨天：按 event_date 分区扫描，`_TABLE_SUFFIX BETWEEN '20240101' AND '20241231'`。

## 陷阱

- 退款要排除：算 total-revenue 时，event_name = 'refund' 会产生负的 purchase_revenue。
- user_pseudo_id 不跨设备：同一真人多设备会被当多个用户。
- 嵌套字段查询时务必 UNNEST，否则 items 整组当作单值。

OKF 的概念文件就是普通 markdown + 一小块 frontmatter——人读得懂、agent 能解析、跨工具无翻译。type 是唯一强制字段，其余按需。这正是“最小约束、生产者/消费者分离、格式而非平台”三大原则在文件层的落地。

总结

Karpathy 的 LLM Wiki 把“LLM 做知识库维护工”这件事讲清楚了——知识编译一次、持续更新、累积复利。OKF 把这件事标准化了——一个 markdown + YAML frontmatter 的极简格式，让不同生产者写的 wiki 能被不同消费者无翻译读取。一个是模式，一个是格式，合在一起就是从“每人各自搭一套”走向“知识作为可交换的 lingua franca”。

参考资料