okf knowledge-graph ai-agents markdown rag

开放知识格式：作为智能体可移植知识层的 Markdown 文件

Google Cloud的OKF可将一组Markdown文件转换为供智能体使用的知识图谱。它解决了哪些问题、如何尝试使用、存在哪些不足，以及它与RAG和MCP的关系如何。

发布者：REACTAPP.TOP加入本站 2026年10月28日阅读约 7 分钟1661 词

来源: Google’s OKF: One Field, Smarter AI Agents

智能体为了反复读取相同的内部文档而消耗大量令牌，谷歌云为此提出了一项解决方案：开放知识格式，即OKF。其0.1版本于2026年6月12日在谷歌云博客上发布。该格式的设计理念很简单：团队关心的每一个概念都会被保存为一个Markdown文件，而这些文件组成的文件夹便构成一个轻量级的知识图谱，任何智能体都能读取。它无需SDK、无需数据库，也不会造成使用绑定。持怀疑态度的人可能会认为这又是一个披着格式外衣的平台，但实际上它仅仅是文件而已，而这正是其有趣之处。当最核心的问题本应很简单——有用的知识究竟存储在何处？——各团队却不断在智能体系统中增加复杂性。

问题所在：智能体需不断重新学习

这就是常见的处理模式：智能体收到关于某个指标的查询后，会调取整个内部维基页面，嵌入相关文本并从头开始理解其含义。下次收到相同查询时也会重复这一流程。原始文本可以被缓存，但对其含义的理解却无人进行缓存。

想象一下，某个智能体每次处理查询时都不得不重新阅读定义“活跃用户”的文档，因为该定义并没有固定的存储位置，而是位于三个文件夹深处的Notion页面中。虽然每次调用的成本很低，但这种浪费会像无人监管时的细微浪费一样逐渐累积；对于每天都要处理相同类型查询的团队而言，Token消耗量其实相当可观。由于外部人士无法获取谷歌的内部数据，目前还没有公开的统计数字，但对于大多数使用智能体的人来说，这个问题都很常见。

一个更具体的例子：某分析文档将活跃用户定义为在日历月中至少执行过一次有意义产品操作的任何人。如果询问客服上个月有多少活跃用户，就需要两类信息——具体的数字，以及此处“活跃”的定义。这是两个独立的问题。数据库负责记录实际发生的情况，而知识层则用于记载公司对这些情况的定义。OKF旨在让第二部分的表达更加简便。

解决方案是采用特定格式，而非更复杂的模型

OKF的设计刻意追求极简，简单到近乎乏味。一个“包”就是一个包含多个Markdown文件的文件夹，每个文件负责描述一个概念，无论是表格、指标、API还是操作手册。每个文件都以两行标记线之间的小型YAML代码块作为开头，即前置信息。其中只有一个字段是必填的：

---
type: Metric   # required – tells the agent what kind of concept this is
---

还有五个可选字段作为补充，此处列出及其用途：

| Field         | Purpose                      |
| ------------- | ---------------------------- |
| `title`       | Human-readable name          |
| `description` | Short summary                |
| `resource`    | Link to the underlying asset |
| `tags`        | Keywords for categorization  |

0.2版本增加了用于说明来源、验证情况、新鲜度、生命周期以及已验证的计算结果的可选字段。您可以添加任何额外的键值对，而使用者应忽略那些他们不认识的键值对且不得因此出错，这正是该格式能够扩展而不破坏其他程序的原因。有两个专用文件名已被预留：index.md用于目录列表，log.md用于记录变更历史，这样您就无需自行制定规范，因为相关规范早已确定。该规范最初是以v0.1草案的形式发布的，因此预计还会继续发展，所以在进行任何重要开发之前，请先查看仓库中的最新版本。

链接构成图谱

由于这些文件是纯 Markdown 格式，概念之间通过普通的 [文本](其他文件.md) 链接相连，而这些链接便构成了该文件夹中图表的边，无需额外的数据库。一个有效的概念文件如下所示：

---
type: Metric
title: Monthly Revenue
description: Total money earned each month.
resource: https://console.cloud.google.com/bigquery?p=project&d=dataset&t=revenue
tags: [finance, monthly]
---

Revenue is counted after refunds are removed.

See also: [customer_acquisition_cost.md](customer_acquisition_cost.md)

当智能体读取 revenue.md 时，它会得知相关概念存在于 customer_acquisition_cost.md 中。这些链接的含义仍由文件编写者决定，因为该格式并不会自动为您解析其含义。

五分钟内体验

该规范附带了基于 GA4 电商数据、Stack Overflow 以及比特币区块链数据构建的实际示例包。一个能够遍历 BigQuery 数据集并自动生成 OKF 文档的参考智能体创造了这些示例，所有内容都保存在同一个 Apache 2.0 仓库中：

git clone https://github.com/GoogleCloudPlatform/knowledge-catalog.git
cd knowledge-catalog/okf

# Add your own concept
cat > new_metric.md <<'EOF'
---
type: Metric
title: Net Promoter Score
description: Measure of customer loyalty.
resource: https://console.cloud.google.com/bigquery?p=company&d=metrics&t=nps
tags: [customer, loyalty]
---
EOF

每个样本包都包含一个 viz.html 文件。在任意浏览器中打开它，即可查看包含节点、链接以及搜索和过滤功能的交互式图表，全程无需后端或服务器支持。需要注意的是，要为自己的样本包生成 viz.html，就需要运行仓库中的小型 Python 参考工具。该工具会将样本包整合为一个基于 Cytoscape.js 和 marked.js 构建的独立 HTML 页面，同样无需后端，生成的文件可直接发送给同事。

优势

成本更低：定义只需编写一次即可直接使用，无需每天重复生成数十次。
加载更快：文件为纯文本形式存储在磁盘上，无需向知识服务发送网络请求，使用前也无需进行嵌入处理。

真正的可移植性：复制仓库、拷贝文件夹或将其放入 Docker 镜像中，它在 GCP、Azure、AWS 或笔记本电脑上的表现都一致，没有任何限制。

免费的版本控制：所有内容都存储在 git 中，因此可以运用拉取请求、差异对比、问题追溯和代码审查等功能，将知识管理转化为常规的工程工作。

面向人和智能体的统一信息源：新员工和值班智能体都可以查看同一份文件，这样就不会出现维基上写的是一种情况，而智能体却认为另一种情况的情况。

跨团队和组织的交流：供应商可以将产品目录以 OKF 包的形式提供，您的智能体可直接使用，无需任何集成工作。

可审查性是另一个优势。假设某智能体提出了这样的修改建议：

- Revenue is recognized when an order is placed.
+ Revenue is recognized after delivery and the 30-day return window.

那只是普通的 Git 差异对比，审阅者可以清楚地看到哪些内容发生了变化。相比那些隐藏在专有知识系统中的无声更新，这种方式要容易判断得多。

其不足之处

它无法修正有问题的定义。OKF 只对容器进行标准化处理，而非内容本身；因此如果团队无法就“活跃用户”的含义达成一致，Markdown 文件也无法强制统一标准。
需要有人持续维护它。文件容易过时，只有当相关人员或自动化工具定期更新timestamp字段和log.md文件时，这些信息才有用。过时的知识反而可能造成更大危害，因为自动化工具会相信它们找到的任何信息。
这只是一个处于初期阶段的草案，显然尚未完成，因此相关字段和规范可能会发生变化，早期采用者应做好不断调整的准备。

并未强制规定其含义。链接仅表明两个概念之间存在关联，但并未说明关联方式，而这种关联关系体现在文字描述中，因此既灵活又模糊。对于需要严格类型定义的关联关系，仍需使用真正的图数据库。

目前采用该技术的团队很少。在最初推出时，几乎所有的生产者与消费者都来自谷歌，只有当其他工具和团队也开始使用该格式时，它才能真正流行起来。

OKF与RAG、MCP并存

当前架构中的任何内容都不会被丢弃，因为OKF会将其嵌入其中。当有查询到来时，RAG仍能找到相关段落，而OKF则会为其提供更整洁、结构化的文本，从而使嵌入结果更加准确，生成成本也更低。Anthropic的模型上下文协议MCP会在对话过程中传递上下文信息，OKF则可作为这些工具的数据来源存在于其下方。MCP负责处理流程，OKF则存储定义，这样就无需每次都重新推导这些定义了。这三层结构如下所示：

OKF
↓
"What does this concept mean?"

RAG
↓
"Which pieces of knowledge should I retrieve?"

MCP
↓
"How does the agent interact with the tools and context?"

每一层负责解决不同的问题，因此应将OKF视为两者之下的共享知识层，而非竞争对手。Markdown文件听起来并不像是一种产品发布方式，但有时最朴实的选择反而是最有效的。

你应该使用它吗？

对于任何能够回答有关你的数据、指标或系统问题的工具，答案都是：试试看吧。尝试的成本几乎为零：只需编写三个文件，将它们关联起来，让工具指向该文件夹，一个下午的时间就能告诉你它是否有用。如果你的知识仅存在于某个人的头脑中或杂乱无章的维基页面里，OKF则提供了一个简单且可版本控制的场所来将其记录下来，无论是否有相关工具，这都可能是值得的。如果你需要严格的架构、类型化的关系或严格的管控机制，目前的OKF还过于宽松，因此可以先保留你的目录，以后再考虑导出相关数据。

不要从整个公司的知识库开始。选择一个较小的领域，例如：

metrics/
  active-user.md
  revenue.md
  conversion-rate.md

systems/
  payments-api.md
  orders-api.md

runbooks/
  payment-failure.md

将文件关联起来，交给单个智能体，然后观察会发生哪些变化。这比花费三个月时间设计企业级OKF平台，却仍无法证明其必要性，要高效得多。

一个必填字段和一个Markdown文件夹本身无法解决文档质量差的问题。它们所提供的，是一个共享的、略显乏味但便于携带的存储空间，用于存放团队已有的优质文档，其实际价值远超纸面上的描述。