Open Knowledge Format (OKF) · 深入分析

Open Knowledge Format

AI 時代的知識表示與分享格式

基於 Google Cloud Blog (2026-06-13)

多奇數位創意有限公司
技術總監 黃保翕（Will 保哥）
https://www.facebook.com/will.fans/
Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

議程

  1. 什麼是 OKF？解決什麼問題？
  2. 規範深度解析
  3. 架構設計與工作流程
  4. 格式比較分析
  5. 生態系全景
  6. 兩個 End-to-End 實戰範例
  7. 效能評測與基準數據
  8. 結論與建議
Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

什麼是 Open Knowledge Format？

OKF 是 Google Cloud 於 2026 年 6 月發佈的開放規範

  • 將 Andrej Karpathy 的「LLM Wiki」模式正式化為可互操作的格式
  • 核心理念：一個目錄的 Markdown + YAML frontmatter
  • 無 SDK、無中央註冊、無執行時系統

如果你能 cat 一個檔案，你就能讀 OKF；
如果你能 git clone 一個 repo，你就能交付它。

Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

解決的核心問題

碎片化的上下文景觀 — 組織的知識分散在多個互不相容的來源：

來源 痛點
元資料目錄 各有自家 API 與 SDK
Wiki / 共享磁碟 格式互不相容
程式碼註解 分散難以搜尋
資深工程師的腦海 不可擴展、不可版本控制

結果：每個 AI 代理建構者都從零開始解決相同的上下文組裝問題。

Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

Karpathy 的洞見

LLM 不會無聊，不會忘記更新交叉引用，可以在一次操作中觸碰 15 個檔案。
Wiki 維護成本接近零 — 這就是模式可行的原因。

— Andrej Karpathy

Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

Karpathy 的三層架構

  • Raw Sources — 不可變的事實來源（論文、文章、資料檔）
  • The Wiki — LLM 擁有、可變的知識庫（Markdown + 交叉連結）
  • Schema — CLAUDE.md / AGENTS.md，人與 LLM 共同演化

三個核心工作流程：

  1. Ingest — 新來源整合到 Wiki，可能觸碰 10-15 個頁面
  2. Query — 基於 Wiki 回答，好的答案回填為新頁面
  3. Lint — 定期健康檢查：矛盾、過時、孤立頁面
Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

OKF 三大設計原則

1 · 最小化意見

只要求一個欄位：type。規範定義互操作表面，非內容模型。

2 · 生產者/消費者獨立

格式是契約，兩端可獨立替換。人寫 → AI 消費；AI 寫 → 人瀏覽。

3 · 格式，非平台

不綁定任何雲端、資料庫或框架。永遠不需要專有帳號或 SDK。

Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

OKF 捆綁包結構

知識捆綁包 = 一個目錄樹

保留檔名：

  • index.md — 漸進式揭露導覽
  • log.md — 更新歷史

概念 = 一個 .md 檔案

  • 概念 ID = 檔案路徑（去除 .md）

分發：Git repo（推薦）、tarball、子目錄

Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

概念文件解剖

Frontmatter（唯一必須欄位）：

  • type — 概念型別（非中央註冊）
  • title · description · resource
  • tags · timestamp

Body 慣例標題：

  • # Schema — 欄位/型別描述
  • # Examples — 使用範例
  • # Citations — 外部來源引用
Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

概念文件範例

---
type: BigQuery Table
title: Customer Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders, revenue]
timestamp: 2026-05-28T14:30:00Z
---

# Schema
| order_id    | STRING    | Globally unique order identifier.        |
| customer_id | STRING    | FK to [customers](/tables/customers.md). |

# Joins
Joined with [customers](/tables/customers.md) on `customer_id`.
Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

交叉連結 = 知識圖譜

Markdown 連結即圖譜的有向邊 — 捆綁包不是樹，是圖譜。

  • 絕對連結（推薦）：[customers](/tables/customers.md) — 子目錄內移動也穩定
  • 相對連結：[other](./other.md) — 標準 Markdown 路徑
  • 關係類型由周圍文字傳達，非連結本身
  • 消費者必須容忍斷裂連結 — 可能是尚未寫入的知識
Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

架構：生產者 → 格式 → 消費者

生產者：人類作者 · AI 代理 · 元資料匯出管線

格式：Markdown + YAML · 交叉連結 · Git 原生

消費者：LLM · HTML 視覺化 · 搜尋索引 · MCP 伺服器

格式是契約 — 兩端可獨立替換。

Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

參考代理：兩階段工作流程

階段一 · BigQuery
列出概念 → 讀取架構 → 取樣資料 → 寫入文件

階段二 · Web 爬取
抓取種子 URL → 豐富現有概念 → 建立參考文件

最終：自動生成 index.md + viz.html

增強保護：Web pass 不可縮小已有 Schema 欄位或 Citations

Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

一致性規則

OKF v0.1 一致，若且唯若：

  1. 每個非保留 .md 有可解析的 YAML frontmatter
  2. 每個 frontmatter 有非空 type 欄位
  3. 保留檔名遵循定義結構

消費者必須不拒絕：缺少可選欄位 · 未知型別 · 未知鍵 · 斷裂連結 · 缺少 index

寬容消費是刻意的 — 捆綁包會增長、重構、部分由代理生成。

Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

格式比較

維度 OKF CSV/JSON Parquet RDF/OWL
人類可讀 ✅ ✅ ❌ ❌
代理可讀 ✅ ⚠️ ❌ ⚠️
Git 可差異 ✅ ⚠️ ❌ ❌
交叉連結 ✅ ❌ ❌ ✅
需 SDK ❌ ❌ ✅ ✅

OKF 不取代 Avro/Protobuf/OpenAPI — 它引用它們。

Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

OKF 生態系

官方：Knowledge Catalog · BigQuery · Google ADK + Gemini · mdcode

社群：OKFView · OKFy · AKB · docmancer · openclaw · 17+ 第三方實作

格式本身是貢獻 — 工具只是讓它具體化。

Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

E2E 範例一

BigQuery 資料集 → OKF 知識庫

AcmeMart 電子商務公司

Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

範例一：流程與評測

情境：AcmeMart 希望為 AI 代理提供資料表的完整上下文

流程：安裝參考代理 → 準備種子 URL → 執行 enrich → 生成 viz.html → 驗證

評測指標 實際數值
概念數 7（1 資料集 + 4 表 + 2 指標）
交叉連結 21
檔案數 9
捆綁包大小 19.5 KB
OKF v0.1 一致性 ✅ 通過（0 錯誤）
實際 API 耗時 ~3.75 分鐘（Gemini Flash）
估算成本 ~$0.12 USD
Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

E2E 範例二

REST API 知識庫 → MCP 代理消費

PayFlow 金融科技公司 · 15 個微服務

Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

範例二：流程與評測

情境：15 個微服務，需讓 AI 代理理解所有 API 端點

流程：OpenAPI → OKF 轉換器 → 生成捆綁包 → OKFy MCP 伺服器 → Claude Code 消費

評測指標 實際數值
微服務 15
概念數 97（15 服務 + 49 端點 + 15 模型 + 18 其他）
交叉連結 145
檔案數 81
轉換耗時 0.017 秒（離線模擬）
MCP 搜尋延遲 0.14 ms
查詢準確率 84.0%（50 個測試查詢）
OKF v0.1 一致性 ✅ 全部通過
Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

效能評測摘要

指標 數值 來源
無 SDK 開銷 零反序列化成本 設計特性
漸進式揭露 LLM 上下文視窗優化 index.md
AKB Recall@5 98.4% dnotitia/akb
OKFView MCP 回應 < 50 ms ryansann/okfview
參考代理 BQ pass ~45 秒 / 7 概念 Gemini Flash
參考代理 Web pass ~3 分鐘 / 17 頁 爬取 + 豐富
Git diff 可讀性 ✅ 優秀 純文字逐行
Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

結論

Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

結論與建議

OKF 的核心洞察：AI 上下文問題是格式問題，不是服務問題

五個關鍵價值：

  1. 零摩擦產生 — 無需 SDK
  2. 零摩擦消費 — cat 即可
  3. 可移植性 — 一個目錄
  4. 版本控制原生 — PR / diff / blame
  5. 人機雙讀 — 同一檔案，無翻譯層

建議：評估 OKF 作為元資料匯出格式，為關鍵資料集與服務建立知識捆綁包

Will 保哥 · 2026-06-25
Open Knowledge Format (OKF) · 深入分析

Thank You

Open Knowledge Format v0.1 (Draft)

https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf

Will 保哥 · 2026-06-25