Назад до журналу
•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