返回日志
•2 分钟阅读

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

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

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

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

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

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

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

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

实际落地：在此组合中实现 OKF

不仅是理论介绍，我已经在整个作品集文档中实现了 OKF。您可以在本仓库的 /knowledge/ 目录下探索实际的知识库。

OKF 规范了许多平台团队已经在做的事情：将内部文档结构化为一个由纯 Markdown 文件和 YAML 前言（frontmatter）组成的清晰目录树。

OKF 不需要引入私有的图数据库或复杂的向量索引管道，而是依赖于两个 Web 标准：

  1. YAML Frontmatter：用于文件级元数据（声明文件类型）。
  2. 标准 Markdown 链接：用于声明文件之间的关系（引导智能体前往下一个节点）。

通过在正文中直接链接文件，您可以将文档目录转化为知识图谱。任何解析文件的 LLM 智能体都可以像网页爬虫遍历 HTML 锚点一样跟踪这些链接。

本作品集中的实际落地结构

本作品集在 /knowledge/ 目录中实现了 OKF。以下是实际结构：

TEXT
/knowledge/
  ├── index.md                    <-- Entry point with type: "index"
  ├── architecture/
  │   └── directory-layout.md     <-- Architecture documentation
  ├── guidelines/
  │   ├── journal-publishing.md   <-- Blog publishing guidelines
  │   ├── cover-art.md            <-- Cover art guidelines
  │   └── ...                     <-- Additional guidelines

每个文件都以正确的 OKF 前言开始。以下是 /knowledge/index.md 的实际 YAML 头部：

YAML
---
type: "index"
title: "dds.com Codebase Knowledge Base"
description: "Entry point for Google OKF-compliant repository knowledge graph describing layout and journal workflows."
timestamp: "2026-07-06T13:10:00Z"
tags: ["OKF", "documentation", "architecture", "guidelines"]
---

内容中包含了文档之间的显式关系。例如，在 journal-publishing.md 中，您会发现：

MARKDOWN
For information on creating cover art for your posts, see the [Cover Art Guidelines](./cover-art.md). For an overview of the entire codebase architecture, refer to the [Directory Layout](../architecture/directory-layout.md).

这创建了一个可导航的图谱，人类和 AI 智能体都可以高效地遍历它。

智能体如何遍历这个真实的图谱

传统的 RAG 搜索关键字或语义向量，获取前 5 个分块并将其倾倒在提示词中。

OKF 启用了**图遍历 RAG（traversal RAG）**策略：

  1. 入口选择：智能体运行轻量级的向量搜索或关键字查询来找到初始的相关文档（例如 journal-publishing.md）。
  2. 递归解析：智能体解析文档，读取 YAML 头部以确定文档类型，并提取所有相对链接。
  3. 上下文组装：根据任务，智能体递归加载链接的文件以构建完整的上下文。

例如，如果一个智能体需要了解在此作品集中如何验证博客文章，它可能会：

  1. 从 journal-publishing.md 开始（通过搜索找到）
  2. 跟踪链接到 ../architecture/directory-layout.md 以了解代码库结构
  3. 在架构文档中发现验证脚本
  4. 加载相关的指南文件如 blog-validation-tools.md 以获取具体实现细节

这消出了上下文窗口溢出的问题，因为智能体只拉取显式相关的文档，完全绕过了通用搜索的噪声。

自动化验证

为了确保 OKF 结构保持完整，我实现了自动化验证：

  • 脚本检查所有 Markdown 文件是否具有正确的前言
  • 验证必填字段（type、title、description、timestamp）
  • 确保索引文件存在且类型为 type: "index"
  • 对没有相对链接的文件发出警告（潜在的孤立节点）

此验证在构建过程中自动运行，防止部署损坏或格式错误的文档。

实际效果：OKF 值得吗？

在实际代码库中实现 OKF 后，以下是基于真实经验的诚实评估：

优势：

  • 零厂商锁定：纯 Markdown 文件。您可以在 VS Code 中查看、在 GitHub 上托管，或使用任何 LLM 提供商进行索引。
  • Git 兼容的版本控制：文档更新通过标准的 Pull Request 和合并审查进行。
  • 智能体独立性：智能体不需要自定义的数据库驱动程序；它们只需要一个 Markdown 解析器。
  • 开发者体验：工程师可以像阅读代码一样阅读文档——通过跟随显式链接进行导航。

解决的挑战：

  • 链接失效：我们的自动化验证会在构建过程中捕获断开的链接。
  • 维护成本：验证脚本确保新文档自动遵循 OKF 约定。

在实践中，OKF 让本作品集的文档对人类和 AI 智能体都变得更加易于导航。当我提出关于代码库结构的问题时，智能体现在可以跟随显式链接来构建完整的上下文，而不需要猜测哪些文档可能是相关的。

OKF 是组装上下文的一种务实方法。如果您正在为幻觉或智能体上下文不完整而苦恼，将仓库的 /docs 或 /knowledge 目录结构化为符合 OKF 规范，是一项低成本、高回报的架构决策。

Share this article