返回日志
•2 分钟阅读

务实的 RAG：测试 Google 的开放知识格式 (OKF)

仅靠向量搜索无法解决 AI 智能体 的上下文组装问题。本文介绍我如何使用 Google 的 OKF 规范将仓库文档结构化为可导航的 Markdown 知识图谱。

Google CloudAI AgentsRAGMarkdown
务实的 RAG：测试 Google 的开放知识格式 (OKF)

如果您曾经在真实的代码库中集成过 AI 智能体，那么您很可能已经遇到了简单向量搜索的极限。

您让智能体对某个 API 接口进行重构，它通过向量检索获取了该函数的主体。但是，它遗漏了数据库表结构、身份验证中间件逻辑以及部署手册，因为这些内容在向量空间中没有足够的语义重叠。

智能体最终执行失败，因为它是在上下文环境中操作的。

为了解决这种“上下文组装”难题，谷歌云发布了 开放知识格式 (OKF) 规范。它是一个与厂商无关的开放标准，旨在将文本文档目录转换为语义知识图谱，供 AI 智能体进行递归导航。

以下是我在实际项目中的实现与思考。

核心概念：什么是 OKF？

OKF 将许多平台工程团队已经在做的事情进行了规范化：将内部文档结构化为带有 YAML 前言的、干净的 Markdown 文件目录树。

OKF 不引入复杂的图数据库或繁琐的向量索引，而是依赖两个成熟的网页标准：

  1. YAML 前言 (Frontmatter)：用于声明文件级元数据（声明文件类型）。
  2. 标准 Markdown 链接：用于声明文件之间的关系（指向下一个节点）。

通过在文本中直接链接文件，您可以将文档目录转换为可遍历的知识图谱。AI 智能体在解析文件时，可以像网页爬虫一样直接跟随这些链接进行导航。

实例演示

在一个共享的 UI 组件库或设计系统仓库中，您可以将您的 OKF 知识库结构化如下：

/knowledge-base
  ├── components/
  │   └── interactive-modal.md
  ├── compliance/
  │   └── wcag-checklist.md
  └── tokens/
      └── theme-palette.md

使用 OKF，其中每个文件都以一个精简的前言块开始。规范非常轻量，唯一强制要求的字段是 type。

以下是 interactive-modal.md 的 YAML 头：

---
type: "ui-component"
title: "Interactive Modal Dialog"
description: "Accessibility-compliant overlay specification supporting dynamic focus trapping and theme tokens."
timestamp: "2026-07-06T12:00:00Z"
tags: ["react", "wcag", "accessibility", "design-system"]
---

在 Markdown 内容内部，我们使用标准相对链接定义与其他文档的显式关系：

The Modal component manages overlays and traps keyboard focus internally. 
For semantic HTML and ARIA attribute rules, refer to the [WCAG AA Compliance Checklist](../compliance/wcag-checklist.md).
To style backdrop filters and component states, import design tokens from the [Theme Palette Config](../tokens/theme-palette.md).

智能体如何遍历图谱

传统的 RAG 检索关键字或向量，提取前 5 个不相关的片段并填入提示词。

OKF 支持图谱遍历 RAG 策略：

  1. 入口选择：智能体通过简单的向量或关键字搜索找到初始相关文档（例如 interactive-modal.md）。
  2. 递归解析：智能体解析该文档，读取 YAML 元数据，并提取所有相对链接。
  3. 上下文组装：智能体递归加载所指向的链接文件（如 WCAG 指南和设计标记文件），在编写 React 代码之前构建出完整的上下文。

这彻底避免了提示词上下文溢出，因为智能体只加载明确相关的资产。

总结：值得采用吗？

优势：

  • 零厂商锁定：纯 Markdown 文件，可直接在 VS Code、GitHub 或 any LLM 平台上解析。
  • Git 工作流合规：知识库与代码库同步，文档变更走标准的 Pull Request 审核流程。
  • 智能体独立性：智能体不需要特定的图数据库驱动，仅需一个标准的 Markdown 解析器。

挑战：

  • 失效链接：移动或重命名文件时相对链接会断开。建议在 CI 流程中配置 markdown-link-check 等工具自动检测。
  • 维护成本：工程师在修改代码的同时，必须承诺更新 YAML 前言和相对链接，否则图谱容易失效。
Share this article