聊聊 Google 的 OKF
但凡自己动手给 LLM 接过点内部数据的人，大概都被同一件事恶心过：上下文到处都是，就是没法用。表结构在元数据目录里，藏在某个有专有 API 的系统后面；指标的口径写在某个 Wiki 页面，链接还时不时失效；运维手册在网盘，注释在代码里，剩下一半干脆只在某个老同事脑子里。你想做个能回答”上周活跃用户怎么算的”的 agent，光是把这些上下文拼起来就得脱层皮，而且换个数据源、换个团队，这套拼装逻辑还得从头再来一遍。
Google 最近发了个东西想治这个病，叫 OKF（Open Knowledge Format，开放知识格式），目前是 v0.1。我看完第一反应是：这不就是给”内部知识”定了个通用文件格式嘛——类比一下，有点像知识界的 Markdown，或者说，想成为 Git 之于代码那样的存在。
OKF 到底是个啥
说穿了特别朴素：一堆带 YAML frontmatter 的 Markdown 文件，按目录组织起来，就这么点东西。没有复杂的压缩、没有运行时、不强制你装任何 SDK。一个 OKF 的 bundle（知识包）就是一个目录，每个概念对应一个 .md 文件：
|
1 2 3 4 5 6 7 8 |
sales/ ├── datasets/ │ └── orders_db.md ├── tables/ │ ├── orders.md │ └── customers.md └── metrics/ └── weekly_active_users.md |
每个文件头上用 YAML 写结构化字段，正文用 Markdown 写说明、schema 之类。比如一张订单表，用Google自己的例子，大概长这样：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
--- type: BigQuery Table title: Orders description: One row per completed customer order. resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders tags: [sales, revenue] timestamp: 2026-05-28T14:30:00Z --- # Schema | Column | Type | Description | |--------|------|-------------| | `order_id` | STRING | Globally unique order identifier. | | `customer_id` | STRING | FK to [customers](/tables/customers.md). | ...... |
注意最后那行——customer_id 直接用 Markdown 链接指向了 customers 表。文档之间这么互相一引用，整个知识包其实就织成了一张图。人能读，agent 也能顺着链接爬。
很克制
我个人比较欣赏它的一点是”少管闲事”。整个规范里强制要求的字段只有一个：type。其余全交给生产者自己定。这意味着它不会因为你的场景特殊就用不了。
围绕这点，它立了三条原则，我觉得是整个设计的魂：
1. 极简约束——只认 type，绝不替你过度规定。
2. 生产者和消费者解耦——格式本身就是契约。谁来生成这些文件、谁来消费它们，两边可以各自独立替换，互不绑死。
3. 是格式，不是平台——没有厂商锁定，不依赖某朵云，不要专有 SDK。这条是它跟那些”元数据目录产品”最本质的区别。
这三条凑一块，好处就很实在了：人可读（任意编辑器能打开，GitHub 能直接渲染），可移植（打成 tarball、塞进 git、挂任意文件系统都行），可互操作（A 团队产的知识包，B 团队的 agent 不用翻译直接就能吃）。而且因为就是一堆文本文件，它可以躺在版本控制里，跟代码放一起，agent 能读也能改，团队像 review 代码一样 review 知识。
Google 顺手给了几个轮子
光发个规范是空的，所以这次还附带了配套，降低上手门槛：一个参考用的”富化 agent”，能从 BigQuery 数据集自动生成 OKF 文档；一个纯静态的 HTML 可视化器，不需要任何后端，打开就能看那张知识图谱长啥样；外加三个示例 bundle——GA4、Stack Overflow、Bitcoin 数据集，拿来照着学格式正好。
这里头我觉得最值得单拎出来说的是那个富化 agent，因为它远不只是”导出元数据”那么简单。
富化 agent：让 LLM 去读文档
名字里”富化”（enrichment）这俩字是关键。光靠 BigQuery 的元数据，你能拿到的只是表名、列名、类型这些骨架；可 customer_id 到底什么含义、orders 和 customers 怎么关联、某个枚举值代表哪种业务状态——这些”肉”通常只长在人写的文档里。富化 agent 干的就是把骨架和肉缝起来。它的做法是两段式（two-pass）：
第一段，BigQuery Pass。扫源数据集，光靠 BigQuery 自身元数据，给每个发现的概念（表、字段、数据集）生成一份初始 OKF 文档。这步是机械的、确定的，产出骨架。
第二段，Web Pass，这段才是精华——它把一个 LLM（Gemini，走 AI Studio 或 Vertex AI）当成一个会自主决策的爬虫：你丢给它几个种子 URL（--web-seed，一般是官方文档地址），agent 用一个 fetch_url 工具去抓页面，然后 LLM 自己判断每页”看起来像不像权威文档”，再决定怎么处理——是拿来丰富某个已有的概念文档，还是单独建一份参考文档，还是这页没用直接跳过。它不是傻爬，是带着”我手里有哪些概念、这页能补哪个”的目标在选择性吸收。
既然是放 LLM 出去爬网，缰绳得备好：--web-max-pages 限制最多抓多少页，防止跑飞；--web-allowed-host 上域名白名单，只许它在你信任的站点里转悠。
最后吐出来的，就是一组分层组织好、带 frontmatter、能直接进版本控制的自包含 bundle。说白了，这个 agent 是 Google 给的一份”如何把现有系统改造成 OKF 生产者”的样板：结构化元数据打底，再让 LLM 读人类文档来富化——你完全可以照着这套路，给自家的数据系统写个类似的生产者。
可视化器：一个 HTML 文件就是查看器
如果说富化 agent 是”生产端”的样板，那这个可视化器就是”消费端”的样板，而且它把 OKF “是格式不是平台”那套哲学贯彻得相当彻底——连查看器都拒绝引入后端，就一个静态 HTML 文件。生成命令是富化 agent 的一个子命令：
|
1 2 |
.venv/bin/python -m reference_agent visualize --bundle ./bundles/stackoverflow # 写出 bundles/stackoverflow/viz.html |
它在生成时把整个 bundle 当成一段 JSON 直接嵌进 HTML 里，所以产物是个自给自足的单文件，可以分享、可以丢任意静态服务器、也可以跟 bundle 一起 commit。Google 就是这么干的——仓库里直接躺着三个生成好的 viz.html（GA4 50KB、Stack Overflow 122KB、Bitcoin 28KB），双击就能在浏览器里打开，看的人那边什么都不用装。
打开后是个左图右文的单页：左边一张力导向图，每个概念是个节点，颜色按 type 区分（table / dataset / reference…），节点之间的有向边就是文档正文里那些 Markdown 互链——前面说的那张”知识图谱”，在这儿被画了出来；点某个节点，右边详情面板就用 marked 把那份 .md 的 frontmatter 和正文实时渲染出来，正文里的内部链接还被改写成”在查看器里跳转”，点了不会把你甩走，而是切到对应节点。顶上一排是搜索框（匹配标题、ID、tags）、type 过滤、还有好几种图布局可切（cose、concentric、breadth-first、circle…）。图用 Cytoscape.js 渲染，全程在浏览器里跑，数据不出本地。
光说没用，我把 Stack Overflow 那个样例的 viz.html 直接搬到了自己博客下，你点开就能玩：stackoverflow_viz.html。其实我这个动作本身就是 OKF “好传播”的一个现成注脚——一个别人生成的知识查看器，我啥都不改、原样拷过来挂上就能用，这要是搁个需要起后端、连数据库的”平台”，可没这么轻巧。
几个我会留意的点
新东西总归要泼点冷水，几个我看完留了心眼的地方：
1. 目前才 v0.1。规范号摆在这，意思是接口和约定都还可能动，真要拿去做生产，得做好跟着升级的准备。
2. “只强制 type”是把双刃剑。约束少确实灵活，但也意味着不同团队产出的字段可能五花八门，跨组织互操作时，光有格式统一、字段语义不统一，照样得对齐。这部分活儿规范帮不了你。
3. 它解决的是”知识怎么存、怎么传”，不解决”知识怎么保证是对的、是新的”。frontmatter 里那个 timestamp 写得再漂亮，背后没人维护，照样会过期。说到底它是个格式，不是个能自动保鲜的系统。
说点本质的
抛开这些细节，我觉得 OKF 真正想干的事很清楚：在这个人人都在拿内部数据喂 agent 的当口，给”知识”这件东西定一个最朴素、最不挑食的通用载体。用最普通的文件约定，换跨工具、跨组织、跨时间的可移植性——这套思路，过去在代码上是 Git 干成的，在文档上是 Markdown 干成的。OKF 想在”知识”这一层复刻同样的故事。
能不能成，要看有多少人愿意给自己的系统写”生产者”、给自己的 agent 写”消费者”，把生态滚起来。但方向我是认的：与其每家都把知识锁在自己那套不兼容的专有系统里，不如先在格式上达成一致。毕竟，朴素的东西才传得开。
就此，完毕。
