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