OKF：用 Markdown 管理知识图谱，AI Agent 时代的元数据新范式

qhvssonic

883人浏览 · 2026-06-18 08:00:00

qhvssonic · 2026-06-18 08:00:00 发布

引言

在大语言模型（LLM）驱动的 AI Agent 逐步渗透数据工程与分析领域的背景下，一个长期被忽视的问题开始浮出水面：传统数据目录的知识表示方式对 AI 并不友好。

无论是 Google Dataplex、Collibra 还是 Unity Catalog，元数据都被封装在专有 API 背后，消费方需要 SDK、查询语言乃至 GUI 才能触达。而 LLM 最擅长处理的格式——自然语言文本——恰恰是这些系统最不擅长输出的东西。

2024 年底，Google Cloud 在其开源项目 knowledge-catalog 中提出了一种新的知识表示格式：Open Knowledge Format（OKF）。它的核心主张极为简洁——用普通 Markdown 文件加 YAML frontmatter 来表示知识。

本文将从格式设计、技术规范、与现有方案的对比三个维度对 OKF 进行系统性分析。

一、OKF 的设计动机

OKF 规范文档（SPEC.md v0.1）开篇即阐明了其基本立场：

“知识最好以人类无需工具即可阅读、Agent 无需 SDK 即可解析、在版本控制中可 diff、跨工具和组织可移植的格式来表示。”

这一立场直接针对当前元数据管理领域的几个结构性痛点：

痛点	具体表现
可读性差	元数据被锁在 API/UI 背后，工程师无法快速浏览
LLM 不友好	结构化三元组（RDF/OWL）需转换才能进入 context window
协作困难	元数据变更无法走 Pull Request 流程，缺乏 review 机制
厂商锁定	知识与平台绑定，迁移成本高

OKF 的解决思路是：将元数据从"服务"降维为"文件"，使其天然具备版本控制、可读性、可移植性和 AI 亲和力。

二、核心规范解析

2.1 Knowledge Bundle（知识包）

OKF 以 Bundle 为分发单位。一个 Bundle 就是一个目录树：

my_bundle/
├── index.md                  # 目录索引（可选）
├── log.md                    # 变更日志（可选）
├── datasets/
│   ├── index.md
│   └── sales.md
└── tables/
    ├── index.md
    ├── orders.md
    └── customers.md

Bundle 可以作为 git 仓库分发、作为 tarball 归档、或作为大型仓库的子目录存在。目录组织不受限制，生产者按领域自行规划。

2.2 Concept（概念文档）

每个 .md 文件代表一个 Concept——知识图谱中的一个节点。其结构由两部分组成：

---
type: BigQuery Table              # 必填
title: Customer Orders            # 推荐
description: 每行一个已完成的客户订单  # 推荐
resource: https://...             # 推荐（底层资产 URI）
tags: [sales, orders, revenue]    # 推荐
timestamp: 2026-05-28T14:30:00Z   # 推荐
---

# Schema
| Column | Type | Description |
|--------|------|-------------|
| order_id | STRING | 全局唯一订单标识符 |
| customer_id | STRING | 外键，关联 [customers](customers.md) |

# Common query patterns
```sql
SELECT customer_id, SUM(total_usd)
FROM `project.sales.orders`
GROUP BY customer_id
ORDER BY 2 DESC
LIMIT 10

Citations

[1] BigQuery 表结构文档


**唯一的硬性约束**是 frontmatter 中必须包含 `type` 字段。其余字段均为推荐项，Consumer 必须容忍缺失。

### 2.3 交叉链接

Concept 之间通过标准 Markdown 链接建立关系：

```markdown
外键关联到 [customers](customers.md) 表。
属于 [sales 数据集](../datasets/sales.md)。

规范明确指出：链接语义由周围的自然语言文本表达，链接本身不携带 predicate。这意味着 OKF 构建的是一个无类型有向图，而非形式化本体。

2.4 渐进式暴露（Progressive Disclosure）

index.md 文件为目录提供概览式导航：

# Tables

* [Orders](orders.md) - 每行一个已完成的客户订单
* [Customers](customers.md) - 客户主数据表

这使得 Agent 可以先读取 index 了解全局结构，再按需深入特定 Concept——避免将整个 Bundle 一次性加载进有限的 context window。

2.5 合规性判定

规范采用极为宽松的合规定义：

每个非保留 .md 文件包含可解析的 YAML frontmatter
每个 frontmatter 包含非空 type 字段
保留文件名（index.md、log.md）遵循规定格式

Consumer 不得因为缺失可选字段、未知类型值、断裂链接或缺失 index 而拒绝 Bundle。这一设计确保了格式的容错性和渐进式采用的可行性。

三、与现有方案的对比

3.1 OKF vs 本体论（OWL/RDF）

维度	OWL/RDF	OKF
形式化程度	严格（Class、Property、Range、Restriction）	极弱（仅 `type` 必填）
推理能力	支持自动推理（传递性、继承、一致性）	无
关系表达	显式 predicate	隐式，靠自然语言
可读性	需 Protégé 等工具	`cat file.md`
LLM 亲和力	低（需转换）	高（原生 Markdown）

OKF 并非本体论的竞争者，而是面向不同消费方的互补层。本体论服务于机器推理，OKF 服务于人类阅读和 LLM 消费。

3.2 OKF vs 个人知识管理工具（Obsidian/Notion）

Obsidian 等工具同样采用 Markdown + 交叉链接的模式，但存在关键差异：

OKF 有规范：type 字段为必填项，frontmatter 结构有约定，确保跨系统互操作
OKF 面向数据资产：设计上假定 Concept 描述的是可标识的资源（表、API、指标），而非个人笔记
OKF 支持自动化生产：规范预期 Agent 和脚本作为主要生产者，人类作为审校者

3.3 OKF vs Metadata-as-Code（dbt docs / kcmd）

dbt 的 schema.yml 和该项目中的 kcmd 都属于"元数据即代码"范式。OKF 的区别在于：

更通用：不绑定特定工具链（dbt 绑定 dbt，kcmd 绑定 Dataplex）
更丰富：body 可容纳任意长度的自然语言描述、SQL 示例、引用来源
更面向消费：结构设计考虑了 LLM 的 context 加载需求

四、OKF 的生产与消费生态

4.1 生产端

OKF 规范不绑定任何生产方式。目前已知的生产路径包括：

AI Agent 自动生成：该项目提供了基于 Google ADK + Gemini 的参考实现，从 BigQuery 元数据 + 网页爬取自动生成 Bundle
人工编写：任何文本编辑器即可
脚本导出：从现有目录系统（Dataplex、Collibra）批量导出

4.2 消费端

LLM 直接加载：作为 RAG 数据源或 prompt context
知识管理 UI：Obsidian、MkDocs、Hugo 等天然兼容
图可视化：项目自带 Cytoscape.js 驱动的单文件 HTML viewer
搜索引擎：frontmatter 提供结构化过滤条件

五、适用场景与局限性

适用场景

为 AI Agent 提供数据上下文：Text2SQL、数据分析 Agent 需要理解表的业务含义
团队知识沉淀：将口口相传的"部落知识"固化为可版本控制的文档
跨系统元数据交换：作为不同目录系统之间的中间格式
数据资产文档化：比 Wiki 更结构化，比 RDF 更易写

局限性

无推理能力：无法自动推导"A 依赖 B，B 依赖 C，故 A 间接依赖 C"
关系语义模糊：同一个 Markdown 链接可能表示 join、dependency 或 see-also
无 Schema 强制：不同文件的 frontmatter 结构可能完全不一致
实时性依赖人工维护：数据源 schema 变更后需重新 enrich

六、结语

OKF 的价值不在于它发明了什么新技术——Markdown、YAML、目录树都是存在了数十年的原语。它的贡献在于在 AI Agent 时代为知识表示找到了一个务实的平衡点：足够结构化以支持自动化处理，足够自由以容纳丰富的自然语言描述，足够简单以实现零门槛的生产与消费。

对于正在构建数据平台 AI 能力的团队而言，OKF 提供了一种值得关注的思路：与其让 Agent 适配复杂的目录 API，不如让知识以 Agent 最擅长消费的形式存在。

参考资料