Назад в журнал
•3 мин чтения

Прагматичный RAG: тестирование формата открытых знаний Google (OKF)

Один лишь векторный поиск не решает проблему сборки контекста для ИИ-агентов. Рассказываю, как я структурировал документацию репозитория в виде графа markdown с помощью спецификации OKF.

Google CloudAI AgentsRAGMarkdown
Прагматичный RAG: тестирование формата открытых знаний Google (OKF)

Если вы интегрировали ИИ-агентов в реальную кодовую базу, вы, скорее всего, столкнулись с ограничениями простого векторного поиска.

Вы просите агента провести рефакторинг API, и он извлекает тело функции с помощью векторного поиска. Однако при этом отсутствуют схема базы данных, промежуточное ПО авторизации и руководство по развертыванию, поскольку они не имели достаточного семантического совпадения.

Агент терпит неудачу, так как работает в контекстном вакууме.

Чтобы решить эту проблему "сборки контекста", Google Cloud опубликовал спецификацию Open Knowledge Format (OKF). Это независимый от разработчиков стандарт для преобразования каталога текстовых файлов в семантический граф знаний, который ИИ-агенты могут обходить рекурсивно.

Вот мой практический опыт внедрения спецификации.

Концепция: что такое OKF?

OKF формализует то, что многие команды уже делали: структурирование внутренней документации в виде дерева каталогов файлов Markdown с заголовками YAML.

Вместо внедрения сложных графовых баз данных OKF опирается на два веб-стандарта:

  1. YAML Frontmatter для метаданных на уровне файлов (определение того, чем является файл).
  2. Стандартные ссылки Markdown для объявления связей между файлами.

Связывая файлы прямо в тексте, вы превращающие документацию в граф знаний. Любой агент может переходить по этим ссылкам подобно поисковому роботу.

Конкретный пример

В репозитории библиотеки UI-компонентов вы можете структурировать базу знаний OKF следующим образом:

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

Каждый из этих файлов начинается с минимального блока метаданных. Спецификация очень легкая; единственным обязательным полем является type.

Вот YAML-заголовок для interactive-modal.md:

---
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. Рекурсивный анализ: Агент анализирует документ и извлекает все относительные ссылки.
  3. Сборка контекста: Агент рекурсивно загружает связанные файлы (руководства WCAG и токены дизайна) для создания полного контекста перед написанием кода React.

Заключение: стоит ли оно того?

Преимущества:

  • Нет привязки к поставщику: Это просто Markdown.
  • Совместимость с Git: Обновления документации проходят через стандартные Pull Requests.
  • Независимость агента: Агентам нужен только стандартный парсер markdown.

Недостатки:

  • Битые ссылки: Относительные ссылки ломаются при переносе файлов. Используйте линтер в CI.
  • Затраты на поддержку: Требует обновления заголовков и ссылок при каждом изменении кода.
Share this article