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

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

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

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

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

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

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

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

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

Реальное внедрение: OKF в этом портфолио

Вместо того чтобы просто объяснять концепцию, я внедрил OKF во всей документации этого портфолио. Вы можете изучить реальную базу знаний в каталоге /knowledge/ этого репозитория.

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

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

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

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

Фактическая структура в этом портфолио

Это портфолио реализует OKF в каталоге /knowledge/. Вот фактическая структура:

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. Вот фактический заголовок YAML из /knowledge/index.md:

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).

Это создает навигационный граф, по которому могут эффективно перемещаться как люди, так и ИИ-агенты.

Как агенты перемещаются по этому реальному графу

Традиционный RAG ищет ключевые слова или семантические векторы, извлекает 5 лучших фрагментов и помещает их в промпт.

OKF позволяет использовать стратегию 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 имеют правильный заголовок frontmatter
  • Проверяет обязательные поля (type, title, description, timestamp)
  • Гарантирует существование индексного файла с типом type: "index"
  • Предупреждает о файлах без относительных ссылок (потенциальных отключенных узлах)

Эта проверка запускается автоматически во время сборки, предотвращая развертывание сломанной или некорректно оформленной документации.

Результаты на практике: стоит ли OKF того?

Внедрить OKF в реальную кодовую базу помогло мне сформулировать честную оценку на основе практического опыта:

Плюсы:

  • Никакой привязки к поставщику: Это просто Markdown. Вы можете просматривать его в VS Code, размещать на GitHub или индексировать с помощью любого провайдера LLM.
  • Версионирование в Git: Обновления документации проходят стандартный процесс Pull Request и код-ревью.
  • Независимость агента: Агентам не нужны кастомные драйверы баз данных; им нужен только парсер markdown.
  • Удобство для разработчиков: Разработчики могут перемещаться по документации так же, как по коду — следуя по явным ссылкам.

Решенные проблемы:

  • Устаревание ссылок: Наша автоматизированная проверка находит битые ссылки в процессе сборки.
  • Затраты на поддержку: Скрипты проверки гарантируют, что новая документация автоматически соответствует правилам OKF.

На практике OKF сделал документацию этого портфолио намного более удобной для навигации как для людей, так и для ИИ-агентов. Когда я задаю вопросы о структуре кодовой базы, агенты теперь могут переходить по явным ссылкам для создания полного контекста, вместо того чтобы гадать, какие документы могут быть полезны.

OKF — это прагматичный подход к сборке контекста. Если вы боретесь с галлюцинациями или неполным контекстом агента, структурирование каталога /docs или /knowledge вашего репозитория в соответствии с OKF — это малозатратное и высокоэффективное архитектурное решение.

Share this article