OKF 开放知识格式深度解析

你有没有遇到这样的情况：知道某个数据集或业务指标的定义存在，但就是找不到在哪里？ AI 助手给出的答案，跟内部文档的说法对不上？

OKF 不是软件，不是平台，而是一套格式约定——规定如何用 Markdown 文件加 YAML 前置元数据来表示和组织知识。

Open Knowledge Format（OKF，开放知识格式）是由 Google Cloud 于 2026 年 6 月 12 日发布的开放、供应商中立的知识表示规范。它的核心思想极其朴素：一个概念 = 一个 Markdown 文件，文件顶部加一段 YAML frontmatter 描述它是什么类型、叫什么、和哪些概念有关。就这样，知识就可以被人类用文本编辑器直接阅读，也可以被 AI 代理直接解析——不需要任何翻译层，不需要任何专有 SDK。

OKF v0.1 是其首个正式版本，定位为草稿（Draft），规范本身极为精简，全文发布在 GitHub（GoogleCloudPlatform/knowledge-catalog）。它的直接思想来源是 AI 研究员 Andrej Karpathy 提出的"LLM Wiki"概念——将机构内部知识整理成 LLM 可直接消费的结构化 wiki。OKF 的工作就是将这一模式形式化（formalize）为可移植、可互操作的开放规范。

为什么是"格式约定"而非"工具"？ 约定比工具更持久。工具会被弃用、被收购、被替代；格式只要足够简单，就能在任何环境下存活。CSV 诞生了几十年依然无处不在，Markdown 统治了技术写作十余年。OKF 选择站在"格式"而非"工具"的位置，是在赌一件事：简单格式 + 开放标准，比功能丰富的平台更有生命力。

核心价值主张可以概括为三句话：

• 格式即标准：知识的结构化方式应有公开约定，而非各自为政；
• 人机共读：同一份文件，人类用文本编辑器可读，AI 代理可解析，无需翻译层；
• 无锁定、可迁移：不依赖任何云服务商、数据库、模型提供商或代理框架，tarball、Git 仓库、文件系统挂载均可分发。

OKF 更接近 IETF RFC 的性质，而非 Google 产品的营销材料——它是一个让所有人都能参与的开放格式标准。

OKF 的出现不是因为有人觉得 Markdown 格式应该更规范，而是因为 AI 代理的普及让一个老问题变成了危机。

企业知识碎片化是一个老问题：数据目录里有表结构、wiki 里有业务定义、Git 仓库里有代码注释、共享驱动里有历史文档、Slack 频道里有口头决策。这种状态对人类尚可忍受——我们会问同事、会猜、会靠经验拼凑。但对 AI 代理来说，这是灾难。

四个核心痛点

为什么这些问题在 AI 时代被放大？ 人类可以容忍歧义——"这里的收入指含税还是不含税？"我们大概猜得到，或者一问就清楚。但 AI 代理不会猜，它会直接给出一个错误答案，而且听起来很自信。一个模糊的指标定义对人类是"可以理解的歧义"，对代理却是"直接生成错误答案的触发器"。这不是技术问题，而是知识表示问题。

AI 系统的智能程度取决于提供的上下文质量。——Google Cloud Blog

OKF 的架构如此简单，以至于你可以在 5 分钟内手写一个合规的知识包——它的复杂性不在结构，而在组织方式。

3.1 文件结构：目录即知识图谱

OKF 的基本单元是概念文件（concept file），每个 Markdown 文件代表一个概念（一张数据表、一个 API、一个业务指标、一个运行手册……）。文件路径即概念的唯一标识符，目录层级表达概念的分类关系。

knowledge-bundle/
├── index.md              # 知识包入口（保留文件名）
├── log.md                # 变更日志（保留文件名）
├── datasets/
│   ├── ga4_ecommerce.md
│   └── stackoverflow.md
├── metrics/
│   └── revenue_per_user.md
└── apis/
    └── bigquery_export.md

index.md 和 log.md 是规范保留的特殊文件名，前者提供知识包的导航入口，后者记录变更历史。

3.2 YAML Frontmatter：结构化元数据

每个概念文件的顶部是 YAML 前置信息块。type 是唯一必填字段，其余均为推荐可选。这个极简主义设计是刻意的：复杂的必填约束会让规范被绕过，只要 type 存在，机器就能分类处理这个概念。

---
type: metric              # 唯一必填字段
title: 每用户收入指标
description: 以美元计的每活跃用户平均收入
resource: bq://my-project.metrics.rpu
tags: [revenue, ecommerce, kpi]
timestamp: 2026-06-12T00:00:00Z
---

# 每用户收入指标

此指标由 [GA4 电商数据集](../datasets/ga4_ecommerce.md)
中的 `purchase` 事件聚合计算。

## 计算逻辑

SUM(purchase_value) / COUNT(DISTINCT user_id)

字段规则：type 值自由定义（如 dataset、metric、api、table、runbook），规范不预设枚举。规范要求消费者容忍未知 type 和缺失的可选字段，保证向前兼容。

3.3 关系建模：普通 Markdown 链接

概念间的关系通过标准 Markdown 相对链接表达，不需要任何专有语法。链接周围的自然语言文本说明关系语义。这个设计的优雅之处在于：关系对人类是可读的自然语言，对代理是可解析的图结构，对版本控制系统是可 diff 的文本。

3.4 分发方式

OKF 知识包不需要中央注册表，支持多种分发方式：tarball（.tar.gz 打包）、Git 仓库（GitHub/GitLab 托管）、文件系统挂载（本地目录、NFS 等），以及 Google Cloud Knowledge Catalog（已原生摄入 OKF 格式并向代理提供 OKF bundle）。规范要求所有文件使用 UTF-8 编码，YAML frontmatter 必须可解析，正文 Markdown 格式宽松，无强制结构。

OKF 的"功能"不是软件特性列表，而是这个格式约定带来的能力边界。

Enrichment Agent：机器生产、人类消费

Google 随规范一同发布了一个参考实现的 enrichment agent：该代理自动遍历 BigQuery 数据集，为每张表和视图起草 OKF 概念文档，并通过第二个 LLM 遍历关联文档进行内容增强。这展示了 OKF 的"机器生产、人类消费"路径——AI 生成初稿，人类 review 后合并，最终产出对 AI 友好的知识包。

OKF 不是一个寻找用途的技术，而是一个被具体痛点召唤出来的格式。以下 8 个场景覆盖了它的主要落地路径。

高优先级场景

数据团队的指标字典是 OKF 最直接的场景。数据分析团队常面临"指标定义混乱"——同一个"收入"指标在不同报表中口径不一致。将每个指标定义为一个 OKF 概念文件，字段包含计算逻辑、数据源、负责人、更新频率，全团队共享同一份规范化来源，SQL 代理可以直接读取而无需反复询问人类。

企业内部 Copilot 的知识底座是 OKF 最核心的目标场景。运行内部 Copilot 或 RAG 系统的团队，将公司的业务流程、产品文档、系统架构整理成 OKF bundle，代理在回答问题前先检索知识包，大幅减少幻觉和答非所问。

SQL 代理和数据问答：代理在生成 SQL 前，先从 OKF 知识包中获取表结构、字段含义、关联关系、数据质量说明，生成的 SQL 准确性显著提升，减少"代理不知道这张表是什么意思"导致的错误。

延伸场景

跨团队知识共享：A 团队（数据工程）维护数据集的 OKF bundle，B 团队（分析师）、C 团队（AI 产品）直接消费，无需 A 团队为每个消费方定制集成接口——生产者写一次，消费者各取所需。

API 文档的机器可读版本：将已有的 OpenAPI 规范和人类可读的 API 文档结合，封装成 OKF 格式，代理调用 API 前可以先理解 API 的业务语义，而不仅仅是技术参数。OKF 在这里扮演"API 的周边知识层"角色，区别于 OpenAPI 的技术描述层。

运维 Runbook 的代理化：将运维手册（如"如何处理数据库慢查询"）写成 OKF 格式，关联相关的系统概念和历史事故记录，运维代理在处理告警时可以自动检索并执行相关步骤。

供应链领域专用：GitHub 上已有 helpfulengineering/OKF-SCIS 项目，将 OKF 规范应用于供应链互操作性（Open-Knowledge-Framework for Supply Chain Interoperability Specification），展示 OKF 在垂直领域的适配能力——通用格式可以作为领域专用知识标准的基础层。

网站内容结构化（AI 发现）：对于内容型网站，OKF 可以作为"给 AI 爬虫读的 sitemap 增强版"——保留内部链接结构、提供内容摘要和标签，使 AI 代理无需全量爬取即可理解网站知识结构。已有免费 Web 工具支持爬取 100 页以内的网站内容生成 OKF bundle，以及 WordPress 插件（需 WP 6.0+、PHP 7.4+）自动化生成。

OKF 定位于"开放格式标准"，与现有知识管理工具的关系是互补而非替代——但理解其差异，是判断是否采纳的前提。

OKF vs. Notion

Notion 擅长团队实时协作和数据库视图，OKF 擅长AI 代理消费和跨工具知识流动。两者可以共存：Notion 作为人类编辑界面，导出 Markdown 即 OKF 兼容格式。

OKF vs. Obsidian

Obsidian 与 OKF 的兼容性最高：其 vault 几乎可以直接转换为 OKF bundle，只需规范 frontmatter 字段。Obsidian 是优秀的个人知识管理工具，OKF 更聚焦团队和机器消费。

OKF vs. RAG 系统

RAG 是检索机制，OKF 是知识组织格式，两者不在同一层次。OKF 可以作为 RAG 的更优质数据源：预结构化的 OKF 文档比原始 PDF/HTML 片段更容易切分、嵌入和检索，减少语义丢失。OKF 解决的是"喂给 RAG 的知识质量"问题，而非替代 RAG。

OKF vs. OpenAPI / 数据目录

OpenAPI 描述 API 的技术接口（端点、参数、返回格式），数据目录（如 Google Data Catalog、Datahub）描述数据资产的技术元数据（schema、lineage）。OKF 填补的是这两者之上的业务语义层：这个 API 是做什么的？这张表在业务上意味着什么？谁负责？如何使用？三者是互补的分层关系，而非竞争关系。

OKF 不是"选它还是选 Notion"，而是"在现有工具之上加一层开放格式约定"的叠加关系。

OKF 的入门门槛极低——不需要安装任何软件，不需要注册账号，文本编辑器足够。

三种上手路径

路径一：手动创建（最简单，推荐试验）

# 创建知识包目录
mkdir my-knowledge-bundle
cd my-knowledge-bundle

---
type: index
title: 我的知识包
description: 包含产品数据集和核心指标定义
---

# 知识包目录

- [DAU 指标](./metrics/dau.md)
- [用户事件数据集](./datasets/user_events.md)

路径二：从企业数据目录导出（最快的存量迁移）

若已有 BigQuery、Datahub 等数据目录，可以使用 Google 提供的 enrichment agent 参考实现，自动遍历数据集生成 OKF 文档草稿，人工 review 后合并。这是企业存量知识最快的迁移路径。

路径三：Web 工具自动生成

已有免费 Web 工具支持爬取 100 页以内的网站内容并生成 OKF bundle，适合内容型网站快速构建知识包。WordPress 用户可使用专用插件（需 WP 6.0+、PHP 7.4+）自动化生成。

分发和托管

# 方式一：Git 托管（推荐，自带版本控制）
git init
git add .
git commit -m "初始化 OKF 知识包"
git push origin main

# 方式二：打包分发
tar -czf my-bundle.tar.gz my-knowledge-bundle/

# 方式三：静态 HTML 可视化（Google 提供工具）
# 将 bundle 渲染为可浏览 HTML，无需服务器

实践建议

采用渐进式采纳策略：

1. 从最关键的 5–10 个概念开始（核心指标、最常被问到的数据集）；
2. 保持 frontmatter 字段简洁，避免过度设计 type 分类；
3. 优先建立内部链接，让知识图谱自然生长；
4. 配合 Git PR 流程 review 知识变更，保持准确性。

OKF v0.1 于 2026 年 6 月 12 日发布，截至本文撰写日（2026 年 6 月 23 日）仅发布 11 天。但已有多个社区响应值得关注。

开源状态

规范本身在 GitHub 开源：GoogleCloudPlatform/knowledge-catalog，规范文档（SPEC.md）、参考实现代码、样本数据集均公开可访问。

Google 提供的官方样本 bundle 包括三类场景：GA4 电商数据集（分析型）、Stack Overflow 数据集（问答型）、比特币区块链数据集（金融型），可作为格式参考。

社区贡献

规范发布数天内已有多个开源工具和验证器出现：

• W4G1/okf：纯 Rust 实现的零依赖 OKF 解析器，可作为嵌入式场景的参考实现；
• helpfulengineering/OKF-SCIS：供应链互操作性领域的 OKF 适配规范；
• 多个 conformance checker 和可视化工具（GitHub Topics 聚集中）。

GitBook 专门发布博客文章解读 OKF，这表明主流文档工具厂商已开始关注 OKF 兼容性——一个生态信号意义的表态。

工具生态的天然兼容性

由于 OKF 使用的是通用 Markdown + YAML 格式，已有大量工具天然兼容：VS Code、Obsidian 等任何支持 Markdown 的编辑器；GitHub、GitLab 等版本控制平台；Hugo、Jekyll 等静态站点生成器；LangChain、LlamaIndex 等 RAG 框架；Google Cloud Knowledge Catalog 原生支持。生态的天然兼容性是 OKF 格式设计的刻意选择——不发明新格式，在已有工具链的最大公约数上建立规范。

一个简单的判断：如果你的场景里有 AI 代理作为知识消费者，OKF 就值得考虑；如果没有，它的价值大幅降低。

最适合的用户群体

采纳时机判断

判断是否现在入场的简单框架——如果至少两项成立，OKF 值得现在投入试点：

• AI 代理经常给出与内部数据/流程不符的答案
• 同一指标在不同文档中有不同定义
• 新员工需要数周才能找到"哪个数据集是权威来源"
• 跨团队共享数据文档需要大量沟通成本

全部不成立，可以观察生态成熟后再入场——v0.1 是 draft，现在重度投入有迁移风险。

OKF 是一个来得正是时候的规范——不是因为 Markdown 格式需要标准化，而是因为 AI 代理的普及让"知识对机器可读"从锦上添花变成了基础设施需求。

五个核心判断

OKF 解决了一个真实存在的结构性问题。企业知识碎片化不是新问题，但它在 AI 代理时代被放大了。代理比人类更难容忍非结构化信息，一个模糊的指标定义对人类是"可以理解的歧义"，对代理却是"直接生成错误答案"。OKF 出现的时机与 AI 代理的普及同步，这不是巧合，而是需求驱动。

格式的极简主义是其最大优势。"只有 type 是必填字段"这个设计决策看似激进，实则深思熟虑：复杂的必填字段会提高生产成本，导致规范被绕过；极简的必填约定让任何团队都能在一小时内产出合规内容，降低了首次采纳的摩擦。规范的价值在于被广泛采纳，而非设计精妙。

供应商中立是其可信度的基石。Google 发布的规范，但明确声明不锁定任何云、数据库、模型或框架，且在 GitHub 开源。这个定位让 OKF 更接近 IETF RFC 的性质，而非 Google 产品的营销材料。Rust 零依赖实现、供应链领域适配等社区贡献印证了其开放性。

主要风险需要正视。Type 词汇表可能碎片化（类似早期 XML namespace 的混乱）；v0.1 是 Draft，破坏性变更可能发生；工具链不成熟，企业推广存在阻力；Google 的长期维护意愿存在不确定性（Google 有历史上放弃项目的记录）。

正确的采纳姿势是叠加而非替代。最低风险的采纳路径：用现有工具（Obsidian、Notion、GitHub）生产 Markdown，用 OKF 规范约束 frontmatter 字段，用 Git 作为分发和版本控制机制。这样既保留现有工具体验，又在不知不觉中构建了 OKF 兼容的知识库。

OKF 代表了一种认识论转变：知识不仅要被人读懂，还要被 AI 直接使用——而这两个目标，现在可以同时满足。

技术事实与信息均核实于 2026 年 6 月 23 日；OKF v0.1 为 Draft 规范，后续版本可能变更，以 GitHub 官方仓库为准。