图解谷歌OKF（Open Knowledge Format）仓库，理解开放知识格式的落地路径

推荐语

谷歌发布开放知识格式OKF，详解其如何将知识打包成可携带的知识包，方便智能体和目录系统直接消费。

核心内容：
1. OKF规范的核心概念与仓库结构解析
2. 从数据源到知识包的完整生成流程
3. 消费端查看器与产品集成演示

杨芳贤

53AI创始人/腾讯云(TVP)最具价值专家

前些日子 Google Cloud 发布了 Open Knowledge Format（开放知识格式：谷歌发布OKF（Open Knowledge Format）规范，它与Karpathy的LLM-wiki是什么关系？），并在GoogleCloudPlatform/knowledge-catalog仓库里一起给出了规范文件、参考写入端（智能体）、样例运行配方、已生成知识包（bundle）、查看器（viz.html），以及接入 Knowledge Catalog 的演示。当前版本还是OKF v0.1 — Draft，说明规范还在完善中。^{[1][2][3][5][6]}

本篇拆解谷歌的示例仓库，看OKF的具体落地内容：SPEC.md是规格起点，后面还有参考写入端、样例产物、消费端查看器，以及接入谷歌 Knowledge Catalog 产品适配示例。^[1][2][5][6]

按照OKF的路径，未来的知识就像一包包可携带的知识包，可直接放进项目、智能体或目录系统直接消费。它可以是一棵目录，也可以被打成压缩包分发；它是不同消费端都认同同一份契约。

把 GoogleCloudPlatform/knowledge-catalog/okf/根目录摊平看，大致是这样：

okf/├─ SPEC.md                  # OKF 最小交换约定├─ README.md                # 仓库导航、样例索引和运行说明├─ samples/                 # 复跑说明：数据集、种子网址、精确 enrich 命令├─ bundles/                 # 已生成的 OKF 知识包和 viz.html├─ src/reference_agent/     # 写入端与查看器实现│  ├─ sources/              # 数据源适配器，当前仓库只内置 BigQuery│  ├─ bundle/               # 文档写入、路径和索引生成│  ├─ web/                  # 网页抓取│  ├─ viewer/               # 知识包可视化│  └─ cli.py / runner.py    # 执行入口和流程编排├─ tests/                   # 数据源、知识包、查看器、web pass 的行为测试└─ pyproject.toml           # Python 包入口和依赖

仓库不只写了规格文件SPEC.md，还把交换约定、运行配方、写入端实现、已生成产物和消费端样板一起给出来了。^[2]

提示：文中的 BigQuery 是 Google Cloud（很多人也叫 GCP）提供的全托管、无服务器企业级云数据仓库，面向大规模数据分析；用户不用自己管理底层基础设施，就能用标准 SQL 或 Python 查询和分析 PB 级数据。后面出现的 BQ pass 里的BQ，就是 BigQuery 的缩写。按 Google Cloud 价格页当前说明，BigQuery 免费层包含每月 10 GiB 存储和 1 TiB 查询处理量。^[7][8]

不过在仔细读 SPEC.md之前，最好先把仓库里的三样东西分清。

samples/不是原始知识数据，也不是智能体自动读取的一整套配置，而是仓库附带的复跑说明：本次要跑哪个外部资料（数据集）、用什么 enrich命令，seeds.txt 则给 web pass提供种子网址。程序实际读取的是命令行参数和 seeds.txt，再由reference_agent 去读外部数据源，把结果写进bundles/。

把仓库拆开看，实际链条是样例说明数据源和运行参数 -> reference_agent 执行 -> bundles 落产物。^[2]

OKF 定的是知识包结构、概念文档和最小字段约束

这张图对应的是 OKF 的最小交换约定。

看 SPEC.md 中的规范，OKF 定义的是知识包这个分发单元：一包知识就是一棵目录树，里面放 Markdown 概念文档；每个非保留概念文档都要带 YAML 头部元数据，type 必填，文件路径就是概念 ID，index.md 和 log.md是保留文件名。对消费端的要求也写死了：遇到未知type、额外字段、失效链接，或者缺失index.md，都要尽量读取，不能轻易拒收。^[3]

这些约束只负责交换层：知识怎么打包、怎么交换、怎么再被别的系统读进去。知识平台怎么建、语义层怎么统一，都不在这份规范里。整个仓库也是按这个边界走的：先把交换层钉住，再补写入端、消费端和产品接入样板。^[2][3]

这张图把角色拆开看：输入源提供上下文，写入动作通常由智能体执行；消费端不只viewer 查看器，也可以是智能体或别的 AI 应用。

这里的“写入端”和“消费端”不要按传统前后端去理解。写入端指的是把源系统知识整理并写成 OKF 知识包的一侧，真正执行写入动作的往往是知识补全智能体；BigQuery、网页资料这些更多是输入源。消费端则是任何会读取、遍历和利用这包文件的系统，不只viewer，也可以是智能体、RAG、搜索索引，或者 Knowledge Catalog 这样的目录系统。AI 在两边都参与，只是写入和消费的角色不同。^[2][3]

谷歌在示例仓库里铺了四层落地样板

第一层是规范：先把交换约定写死

仓库的 SPEC.md规范写的很克制。它不是发明一套大而全的类型体系，也没有绑定服务、数据库或界面，只把写入端和消费端之间最小的知识包交换约定定下来。^[3]

约定其实很短。写入端要写对：非保留 .md文档必须有可解析的头部元数据，type不能为空；消费端要宽读：未知字段、未知 type、断链、缺少index.md，都不能直接判死。OKF 从一开始就没有往重平台规范那边走，它先解决的是互操作。^[2][3]

一句话说，SPEC.md要求的是：写入端从严，读取端尽量宽读。

第二层是reference_agent：谷歌给出了一套 agent 应用示例

reference_agent 是样板 Agent，在真实落地或者开发中我们可以直接参考示例代码的实现逻辑。

它的定位是概念验证版应用：

• enrich
   演示怎么把源数据和网页资料写成 OKF 知识包。
• visualize
  演示怎么把这包文件消费成可交互的单文件查看器。

也就是说，谷歌这一层给出的不是 OKF 本体，而是一套覆盖写入和消费的 agent 应用示例。^[2]

这张图把 reference_agent拆成两条线：enrich 负责写入，visualize负责消费；两边都围绕同一个 OKF 知识包。

看模块分工也不复杂：^[2]

• sources/bigquery.py
   负责读 BigQuery 元数据
• agent.py
   拆成 BigQuery 智能体和网页摄取智能体
• runner.py
   串写入流程并重建 index.md
• viewer/generator.py
   负责把知识包转成viz.html，
• cli.py
   则提供 enrich 和visualize 两个入口。

注意这里别把 BigQuery 理解成 OKF 的通用名词。它不是 OKF 规范的要求，但在当前这份 reference_agent实现里，bq 也是唯一内置的数据源。^[2][3]

写入侧可以拆成两段：

1. BigQuery 轮（BQ pass）先只用 BigQuery 元数据，为每个概念生成一份 OKF 文档。
2. 网页轮（web pass）再拿显式给定的种子网址去抓权威页面，在页面预算、域名白名单和深度限制内，决定是补现有文档、单独生成references/，还是直接跳过。^[2]

这张图只压缩了 reference_agent的写入侧：enrich 负责把源数据和网页资料整理成 OKF 知识包。

这里要分开看两层。OKF 本身是厂商中立格式，不绑定特定智能体、框架、模型提供方或服务系统；而在reference_agent 这套应用示例里，写入侧是reference_agent enrich --source bq + web pass，消费侧是reference_agent visualize生成单文件查看器。^[2]

在自己项目中落地，你可以继续用这套应用，也可以换成基于 Codex、Claude Code，或者别的智能体框架的写入端和消费端；前提只有一个，就是最后写出来、读进去的知识包还守住同一份 OKF 约定。reference_agent 不是 OKF 本体，而是谷歌先交出来的最短可跑应用示例。^[2][3]

第三层是bundles 和复现配方 samples

这一层是仓库里已经生成出来的样例产物bundles/，samples/只是复跑这些样板时附带的一层配方。^[2]

仓库直接挂了三组公开样例：GA4 Google Merchandise Store、Stack Overflow、Bitcoin public datasets。每组都对应一份样例说明和一份已经生成好的知识包。^[2]

拿一组看结构就够了：

samples//├─ README.md     # 跑哪个外部数据集、用什么 enrich 命令└─ seeds.txt     # web pass 的种子网址bundles//├─ datasets/├─ tables/├─ references/├─ index.md└─ viz.html

重点不在配方本身，而在谷歌把“输入长什么样”和“产物长什么样”一起摆出来了。前者是可复现说明，后者才是 OKF 真正要交换和消费的东西。samples/ 里选用的 GA4、Stack Overflow、Bitcoin 也只是示例源。

从 OKF 的设计边界看，如果你自己实现写入端，完全可以换成 API 文档、数据库模式、产品帮助中心，或者内部知识页面。^[2][3]

查看器（viewer）本身也没被做成重产品。src/reference_agent/viewer/generator.py生成的是一个单文件、自包含的 HTML 页面，包括图结构、头部元数据、渲染后的 Markdown、反向链接、搜索、类型筛选。它就是 reference_agent这套应用里的概念验证版消费端，用来证明知识包一旦生成，已经能被浏览、跳转和消费。^[2]

这就是 viz.html的实际样子：左侧把知识包渲染成概念图谱，右侧直接展开当前文档的头部元数据、正文、模式和示例查询。

[可选] 第四层：通过 mdcode 把知识包接进 Knowledge Catalog

这一层讲的是怎么消费 OKF 的知识包。你知不知道 Knowledge Catalog 本身并不重要，先把它理解成 Google Cloud / Dataplex 里的一种目录型消费端就够了；关键在于它不直接读知识包，而是要先过一层mdcode 桥接。前面三层已经够你理解 OKF，也够你把知识包写出来并直接消费；这一层只是“接特定产品”的可选分支。^[4][5][6]

到这里，其实可以把消费端分成两类：

• 直接消费知识包：像viz.html、智能体、RAG、搜索索引这种，本身就认 OKF 的目录、Markdown、头部元数据和链接，不需要桥接层。
• 映射后再消费：像 Knowledge Catalog 这种有自己对象模型的产品，不直接吃“裸知识包文件夹”，中间要先过一层桥接或映射。^[2][4][5][6]

第四层是这条桥：先把知识包映射成目录模型，再通过kcmd push 发布到 Knowledge Catalog。

mdcode demo展示的就是第二种（映射后再消费）。catalog/ 里预放了一套 GA4 知识包，setup.ts 创建 Dataplex EntryGroup并写出 catalog.yaml，再把知识包里的 Markdown 文档映射成 Dataplex 的 entry / aspect 模型：每个 .md对应一个 entry，entry 名镜像文件路径，正文进入dataplex-types.global.overview，头部元数据里的自定义type: 如果不是合法的 Dataplex 类型引用，就回退到dataplex-types.global.generic。^[5][6]

所以这条链真正闭合时，走的是：

OKF 知识包 -> mdcode 目录快照 -> kcmd push -> Dataplex EntryGroup / aspects

如果你的消费端能直接读知识包，第四层就可以跳过；只有消费端不直接认知识包，或者你真要接目录产品、治理系统和现有目录系统时，才需要继续走这层适配。^[2][4][5][6]

总结：怎么落地？

在我们自己的项目中落地或者搭配其他Agent使用，不要着急搭平台，也别先搞什么大一统知识体系。最短路径就两段：先把知识包做出来，再判断消费端是直接读，还是要桥接后再读。

如果放到 Codex、Claude Code 这类智能体环境里，我更倾向于把 OKF 做成一组 skill：写入 skill 负责按约定生成概念文档、补头部元数据、维护index.md 和链接；读取 skill 负责遍历知识包、按类型筛选、追踪反向链接，再把相关概念装进上下文。这样 OKF 就不只是“文件夹格式”，而会变成智能体可以反复调用的一套知识读写动作。

先写出最小知识包，再决定是不是要接桥接层；平台接入应该放在最后，不该放在最前。

1. 先挑一个边界清楚的知识子域和数据源，数据库、API 文档、帮助中心、内部知识页都可以。
2. 先决定写入端怎么来。想复用现成样板，就从reference_agent enrich --source bq 这条链起；如果你的源不是 BigQuery，就保留同样的知识包约定，自己补数据源适配器，或者在 Codex / Claude Code 里封装成 OKF 写入 skill。^[2][3]
3. 先把一包最小可用的知识包写出来，重点不是写满，而是先把头部元数据、链接、index.md和类型约定跑通。
4. 先用 viz.html、智能体、RAG 或搜索去直接消费它，检查这包文件能不能读、能不能跳、能不能查。
5. 如果消费端能直接读知识包，这里就够了；只有消费端不直接认知识包，或者你必须接目录产品、治理系统和现有目录系统时，再加桥接层，比如mdcode 或自己的适配器。^[2][4][5][6]