Google开放知识格式规范 Open Knowledge Format (OKF)

什么是 OKF？

Open Knowledge Format (OKF) 是Google Cloud 数据云团队在2026年6月推出的一项开放规范。它旨在为AI智能体（AI Agents）和大语言模型（LLMs）提供一种标准化、供应商中立、人类与机器均可读的知识表示方法。简单来说，OKF的目标是成为AI时代的“知识通用货币”，解决企业知识分散、格式不统一，导致AI难以有效利用的难题。

它的核心思想极简： 用一个目录的 Markdown 文件 + YAML 前置元数据 (frontmatter)，把组织知识包装成既能让人类阅读、又能让 AI Agent 直接解析和消费的”知识包”。

OKF的设计哲学是极简和开放，它不是一个需要安装的复杂软件或运行库，而是一套约定俗成的规范。其核心构成非常简单：

• 一个知识包 (Knowledge Bundle)：就是一个普通的文件夹。
• 每个知识点 (Concept)：就是一个 Markdown (.md) 文件。文件名即知识点ID，文件路径构成了知识图谱中的唯一地址。
• 文件结构：由两部分组成:
  • YAML Frontmatter (元数据)：文件顶部的YAML格式数据，用于存放可供查询和过滤的结构化字段。
  • Markdown Body (主体内容)：标准的Markdown文本，用于详细描述知识，可以包含标题、表格、代码块等。

这种设计带来了几个关键优势：

• 人类可读，机器可解析：任何文本编辑器都能打开，Git能直接做版本控制。AI智能体可以直接读取Markdown内容，无需专有SDK。
• 供应商中立，无锁定：OKF不绑定任何特定平台、框架或模型提供商。知识包可以存放在任何Git仓库、文件系统或以压缩包形式分发。
• 知识即代码：知识的创建、修改、审核可以像管理代码一样，通过Pull Request、Code Review等流程进行。

为什么需要 OKF？

现代 LLM 的推理能力已不再是瓶颈，真正的瓶颈在于”它们对你的世界知道什么”。组织中有价值的知识散落在各处：

这种从 A × S（每个 Agent 需要为每个知识源定制连接器）到 A + S（每个 Agent 学一次 OKF，每个源输出一次 OKF）的复杂度坍缩， 和 USB、HTTP 等所有成功标准的经济学逻辑完全一致。

三大核心规则

OKF v0.1 的规范性要求极其精简 —— 只有三条硬性规则，其余一切皆可选：

宽容忍设计：消费者 (Consumer) 必须容忍未知 type 值、未知扩展字段、缺失的可选元数据、缺失的 index.md 以及断链。 部分生成或不断演进的 Bundle 仍然应该是有用的 —— 这是任何活的知识库的现实状态。

知识包 (Knowledge Bundle) 结构

Knowledge Bundle 是 OKF 的分发单位。它可以是 Git 仓库、ZIP 包、tarball 或大型仓库中的一个子目录。

okf-bundle/
├── index.md              # 入口文件：列出 Bundle 中所有概念
├── log.md                # 变更日志：按时间倒序记录更新
├── tables/
│   ├── index.md          # 子目录索引（无 frontmatter）
│   ├── subscriptions.md  # 概念：数据表
│   └── orders.md         # 概念：数据表
├── metrics/
│   ├── monthly-recurring-revenue.md  # 概念：指标
│   └── weekly-active-users.md       # 概念：指标
└── playbooks/
    └── revenue-review.md  # 概念：运维手册

保留文件

概念文件 (Concept File) 详解

每个 Concept 是一个 Markdown 文档，由两部分组成：YAML Frontmatter（结构化元数据）和 Markdown Body（自由文本知识）。

概念 ID = 文件路径去掉 .md 后缀。例如 tables/orders.md 的概念 ID 是 tables/orders。

---
type: Metric
title: Monthly Recurring Revenue
description: Recurring subscription revenue normalized to a monthly period.
resource: dashboard://revenue/mrr
tags: [revenue, saas, finance]
timestamp: 2026-06-13T00:00:00Z
---

# Calculation

MRR is the predictable recurring revenue generated by active
subscriptions in the [subscriptions table](../tables/subscriptions.md).

Include active subscriptions with recurring billing. Exclude one-time
setup fees, refunds, and usage-only charges unless normalized into a
recurring plan.

# Examples

select sum(monthly_amount_usd) as mrr
from analytics.subscriptions
where status = 'active';

# Citations

[1] [Revenue dashboard](dashboard://revenue/mrr)

前置元数据 (Frontmatter) 字段一览

设计哲学：只有一个必填字段 + 无限可选字段 + 消费者必须保留未识别的键。 这个决定让手写的 Bundle 和机器生成的 Bundle 共享同一格式 —— 格式奖励的是策展 (curation)，不是工程。

链接与引用 —— 隐形的知识图谱

OKF 使用普通的 Markdown 链接。一个概念到另一个概念的链接隐含地声明了一种关系，由周围文字解释关系的类型。

链接形式

• Bundle-root 链接：/tables/orders.md—— 从 Bundle 根目录开始的绝对路径，文档在目录内移动时链接仍然有效。
• File-relative 链接：../tables/orders.md—— 相对路径，在 GitHub / Obsidian / MkDocs / 浏览器中渲染更通用。

引用 (Citations)

当 Body 中的声明来自外部来源时，添加 # Citations 段落。引用可以指向外部 URL、Bundle 内的相对路径，或 Bundle 内存储的参考概念。

AI Agent 如何消费 OKF

因为 Bundle 就是文件，Agent 不需要 SDK 来读取 —— pathlib、正则表达式和一个 YAML 解析器就够了：

import pathlib, re, yaml

def load_bundle(root: str) -> dict:
    concepts = {}
    for path in pathlib.Path(root).rglob("*.md"):
        text = path.read_text(encoding="utf-8")
        # 分离 YAML frontmatter 和 markdown body
        fm = re.match(r"^---\n(.*)\n---\n(.*)$", text, re.DOTALL)
        meta = yaml.safe_load(fm.group(1)) if fm else {}
        body = fm.group(2) if fm else text
        # 提取所有出向链接（知识图谱的边）
        links = re.findall(r"\]\(([^)]+\.md)\)", body)
        concepts[str(path)] = {"meta": meta, "body": body, "links": links}
    return concepts

加载后，Bundle 就是一张图，Agent 按需遍历 —— 只跟随与当前任务相关的边，而不是把所有文档塞进 prompt：

OKF v0.2: 企业级信任与合规

v0.2 在 v0.1 基础上引入了五大信任维度，面向企业级场景：

v0.2 关键变更

v0.2 的信任分层：

• Unverified：无verified 字段 —— 默认信任级别
• Machine-Confirmed：仅由非人类 Agent 验证
• Human-Reviewed：至少有一个human:<id> 验证记录

OKF vs RAG vs MCP vs llms.txt

OKF 诞生在”为 AI 提供上下文”的标准的拥挤空间里，容易以为它们在竞争。实际上它们处于不同层次，干净地组合在一起：

实战示例：从零创建一个 Bundle

完整示例：SaaS 知识包

my-saas-knowledge/
├── index.md
├── tables/
│   ├── subscriptions.md
│   └── orders.md
├── metrics/
│   └── mrr.md
└── playbooks/
    └── revenue-review.md

---
okf_version: "0.1"
title: My SaaS Knowledge Bundle
---

# My SaaS Knowledge

本 Bundle 包含 SaaS 产品核心知识，供人类和 AI Agent 消费。

## 概念列表

- [订阅表](tables/subscriptions.md) — 活跃订阅记录
- [订单表](tables/orders.md) — 已完成订单
- [月度经常性收入](metrics/mrr.md) — MRR 指标定义
- [收入复盘手册](playbooks/revenue-review.md) — 月度收入审查流程

---
type: BigQuery Table
title: Orders
description: 每个已完成的客户订单一行记录。
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, revenue]
timestamp: 2026-06-13T00:00:00Z
---

# Schema

| Column      | Type   | Description           |
|-------------|--------|-----------------------|
| order_id    | STRING | 全局唯一订单标识符    |
| customer_id | STRING | 外键 → [customers](customers.md) |
| total_usd   | NUMERIC| 订单总金额 (美元)     |

# Joins

与 [customers](customers.md) 通过 customer_id 关联。

# Citations

[1] [BigQuery table](https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders)

生态工具

OKF 规范本身是极简的，但围绕它正在构建一套工具生态：

官方提供的参考实现

• Reference Producer Agent— 让 Claude / Codex / Cursor 等 Agent 自动产出合规的 Bundle
• Reference Visualizer— 将 Bundle 渲染为可视化目录和图谱浏览器
• Sample Bundles— 覆盖 SaaS 应用、数据仓库、Laravel、WordPress、API 文档、公司知识、AI Agent 上下文等场景
• Browser Validator— 零后端、零安装，在浏览器中验证 Bundle 合规性
• OKF Skill— 可安装的 Skill，让 Agent 直接产出符合规范的输出

如何开始使用

两分钟创建你的第一个 Bundle

• 在项目目录中创建 okf/ 文件夹
• 添加根md，列出第一批概念组
• 为每个重要资产或想法创建一个概念文件
• 添加 Frontmatter —— 至少有 type，有条件时加 title、description、resource、tags、timestamp
• 用 Markdown 链接关联相关概念，为有来源的声明添加 # Citations
• 提交到 Git 仓库，打包为归档，或暴露给 Agent / Catalog

关键提醒：格式的难点从来不在语法上，而在于决定什么值得写下来，以及保持它的真实性。 OKF 奖励的是策展 (curation)，不是工程 (engineering)。

适合使用 OKF 的场景

• 指标定义
• 数仓表文档
• API 文档
• 系统架构
• 运维手册
• 业务规则
• 产品概念
• 决策记录
• 文档地图
• Agent 上下文
• 安全约束
• 计算逻辑证明

OKF 不适合：它不是平台、SaaS、数据库、专有 Agent 框架、SEO 捷径、固定分类法，也不是替代 OpenAPI / Protobuf / Avro / 数据目录的方案。 它是在这些系统之上添加的周围知识层 —— 回答”资源意味着什么、属于哪里、如何与其他概念连接”。

进阶实战：OKF 驱动 LLM 间 Token 级知识交换

2026 年 8 月，Towards Data Science 发表了一篇极具启发性的文章 “How to Utilize OKF Efficiently to Enable Knowledge Exchange Among LLMs”， 展示了 OKF 的一个超出原始设计意图的创新用法： 用 OKF frontmatter 作为多 Agent 流水线中 Token 级知识交换的元数据载体，在同家族不同尺寸的 LLM 之间共享预分词结果，实现 28–37% 的首 Token 延迟（TTFT）降低。

来源： Towards Data Science 原文 · GitHub: inter-llm-tokf · 使用 Qwen2.5-Coder-7B/3B/1.5B-Instruct 三模型流水线 · 2026 年 8 月 13 日发布

总结

OKF 的设计哲学可以浓缩为一句话：格式本身 —— 而非另一个平台 —— 才是缺失的那块拼图。用 Markdown 写知识，用 YAML 标注类型，用 Git 管理版本，用链接构建图谱。 人能读，Agent 能解析也能更新。没有 SDK，没有数据库，没有厂商锁定。 当知识像代码一样被 diff、branch、review，它就不会在上下文之外腐烂。

参考资源：

• 官方规范站点：https://openknowledgeformat.com
• 简化版规范：https://okf.md
• GitHub 仓库：GoogleCloudPlatform/knowledge-catalog