Формат открытых знаний: файлы Markdown как портативный слой знаний для агентов
OKF от Google Cloud преобразует папку файлов в формате Markdown в граф знаний для агентов. Что он решает, как его опробовать, в чём его ограничения, и как он связан с технологиями RAG и MCP.
Источники: Google’s OKF: One Field, Smarter AI Agents
Агенты тратят ресурсы на повторное чтение одних и тех же внутренних документов, и Google Cloud предложил решение: формат открытых знаний OKF. Версия 0.1 была объявлена на блоге Google Cloud 12 июня 2026 года. Суть проста: каждая концепция, важная для команды, превращается в отдельный файл в формате Markdown, а папка с этими файлами служит легким графом знаний, доступным для чтения любым агентом. Для его работы не требуются SDK, базы данных или ограничения. Скептики могут подумать, что это ещё одна платформа, маскирующаяся под формат, но на самом деле речь идет лишь о файлах, и именно это так интересно. Команды продолжают усложнять работу агентов, хотя один из самых сложных вопросов на самом деле прост: где на самом деле хранятся полезные знания?
Проблема: агенты постоянно переобучаются
Вот типичная схема: агент получает вопрос о каком-либо показателе, загружает всю внутреннюю вики-страницу, встраивает туда текст и самостоятельно пытается понять его смысл. При следующем запросе он делает точно то же самое. Чистый текст может храниться в кэше, но понимание его содержания никто не кэширует.
Представьте агента, который при каждом запросе вынужден перечитывать документ, определяющий, кто считается активным пользователем, поскольку это определение не имеет своего постоянного места и находится на странице в Notion, расположенной на трех уровнях глубже. Каждый запрос стоит недорого, но такие потери накапливаются, как и мелкие расходы, когда за ними никто не следит; у команды, ежедневно выполняющей один и тот же набор запросов, расходы на токены становятся значительными. Конкретных цифр по этому вопросу нет, поскольку посторонние не имеют внутренних данных Google, однако сама проблема хорошо знакома большинству тем, кто использует агентов.
Более конкретный пример: в документе по аналитике активным пользователем считается тот, кто совершил хотя бы одно значимое действие с продуктом в течение календарного месяца. Если спросить сотрудника, сколько было активных пользователей в прошлом месяце, ему понадобятся две разные вещи: цифры и понимание того, что здесь подразумевается под понятием «активный». Это отдельные задачи. База данных отчитывает о том, что произошло, в то время как слой знаний фиксирует, что компания имеет в виду. OKF направлен на упрощение представления этой второй части.
Решение — это формат, а не более сложная модель
OKF намеренно настолько прост, что это почти скучно. Пакет представляет собой папку с файлами в формате Markdown, каждый из которых описывает одну концепцию — будь то таблица, показатель, API или руководство. Каждый файл начинается с небольшого блока YAML — frontmatter — между двумя маркерными строками. Обязательным является только одно поле:
---
type: Metric # required – tells the agent what kind of concept this is
---
Пять дополнительных полей дополняют эту структуру; они перечислены здесь вместе с их назначением:
| Field | Purpose |
| ------------- | ---------------------------- |
| `title` | Human-readable name |
| `description` | Short summary |
| `resource` | Link to the underlying asset |
| `tags` | Keywords for categorization |
Версия 0.2 добавляет необязательные поля, касающиеся происхождения данных, проверки, свежести, жизненного цикла и выполненных вычислений. Вы можете добавлять любые дополнительные ключи; ожидается, что потребители будут игнорировать те из них, которые они не распознают, и не будут испытывать сбоев, что позволяет расширять формат без повреждения чужих агентов. Зарезервированы два имена файлов: index.md для списка содержимого каталога и log.md для истории изменений, что избавляет от необходимости создавать собственные правила, уже определённые спецификацией. Спецификация была выпущена в виде черновика v0.1, поэтому ожидается её дальнейшее развитие; перед началом серьёзной работы проверяйте репозиторий на наличие актуальной версии.
Ссылки формируют граф
Поскольку файлы представляют собой обычный Markdown, концепции связаны с помощью стандартных ссылок [текст](другой-файл.md), и эти ссылки являются рёбрами графа, находящегося в папке, без необходимости использования дополнительной базы данных. Валидный файл с концепцией выглядит так:
---
type: Metric
title: Monthly Revenue
description: Total money earned each month.
resource: https://console.cloud.google.com/bigquery?p=project&d=dataset&t=revenue
tags: [finance, monthly]
---
Revenue is counted after refunds are removed.
See also: [customer_acquisition_cost.md](customer_acquisition_cost.md)
Агент, читающий revenue.md, узнаёт, что связанная с ним концепция находится в customer_acquisition_cost.md. Значение ссылки по-прежнему определяется тем, кто написал файлы, поскольку формат не предусматривает автоматического понимания этого значения.
Попробуем за пять минут
В спецификации сопровождаются реальные примеры пакетов, созданные на основе данных электронной коммерции GA4, данных Stack Overflow и блокчейна Bitcoin. Референтный агент, анализирующий наборы данных BigQuery и составляющий документы OKF, автоматически генерирует их, причём всё это находится в одном репозитории под лицензией Apache 2.0:
git clone https://github.com/GoogleCloudPlatform/knowledge-catalog.git
cd knowledge-catalog/okf
# Add your own concept
cat > new_metric.md <<'EOF'
---
type: Metric
title: Net Promoter Score
description: Measure of customer loyalty.
resource: https://console.cloud.google.com/bigquery?p=company&d=metrics&t=nps
tags: [customer, loyalty]
---
EOF
Каждый пакет образцов включает файл viz.html. Откройте его в любом браузере, чтобы увидеть интерактивную диаграмму пакета с узлами, связями, возможностями поиска и фильтрации — без необходимости использования бэкенда или сервера. Есть один недостаток: для генерации viz.html для собственного пакета необходимо запустить небольшой инструмент на Python, находящийся в репозитории. Этот инструмент преобразует пакет в одну самодостаточную HTML-страницу, построенную на Cytoscape.js и marked.js, также без бэкенда — просто файл, который можно отправить коллеге по электронной почте.
Преимущества
- Ниже затраты: определение записывается один раз и считывается напрямую, поэтому не нужно платить за его повторную генерацию пятьдесят раз в день.
- Быстрее загрузка: на диске хранится простой текст, нет необходимости в сетевых запросах к сервису знаний и этапах встраивания перед использованием.
- Настоящая портативность: скопируйте репозиторий, перенесите папку или поместите её в образ Docker — программа будет работать одинаково на GCP, Azure, AWS или ноутбуке. Ничто не связывает вас по рукам и ногам.
- Бесплатный контроль версий: все ресурсы хранятся в git, поэтому возможны pull-запросы, сравнения изменений, определение автора правок и их рассмотрение, а управление знаниями превращается в обычную инженерную работу.
- Единый источник информации для сотрудников и агентов: новый сотрудник и агент, находящийся в режиме дежурства, открывают один и тот же файл, поэтому вики не может содержать противоречивую информацию, в то время как агент верит в другое.
- Обмен между командами и организациями: поставщик может отправить каталог в формате пакета OKF, который ваш агент может использовать напрямую без какой-либо работы по интеграции.
Ещё одним преимуществом является возможность рассмотрения изменений. Предположим, агент предлагает следующее изменение:
- Revenue is recognized when an order is placed.
+ Revenue is recognized after delivery and the 30-day return window.
Это обычный git diff, и рецензент точно видит, что было изменено. Это гораздо проще для оценки, чем тихое обновление, скрытое в проприетарной системе знаний.
Его недостатки
- Он не исправляет некорректные определения. OKF стандартизирует контейнер, а не его содержимое, поэтому если команда не может договориться о значении понятия «активный пользователь», файл в формате markdown не сможет добиться единого мнения.
- Кто-то должен им управлять. Файлы могут устаревать, а поля
timestampи файлlog.mdпомогают лишь в том случае, если люди или агенты их обновляют. Устаревшие знания могут нанести больший вред, чем их отсутствие, поскольку агенты верят всему, что находят. - Это молодой проект, явно незавершённый, поэтому поля и правила могут изменяться, и те, кто использует его рано, должны ожидать изменений.
OKF наряду с RAG и MCP
Ничто из текущей стек-структуры не удаляется, поскольку OKF располагается внизу. RAG по-прежнему находит релевантные фрагменты при поступлении запроса, а OKF предоставляет ему более чистый, заранее структурированный текст, что делает эмбеддинги более точными и дешевыми в создании. MCP — протокол контекста модели от Anthropic — передает контекст во время разговора, а OKF может служить его источником для этих инструментов. MCP управляет потоком данных, в то время как OKF хранит определения, так что их не приходится пересчитывать каждый раз. Три слоя выглядят следующим образом:
OKF
↓
"What does this concept mean?"
RAG
↓
"Which pieces of knowledge should I retrieve?"
MCP
↓
"How does the agent interact with the tools and context?"
Каждый слой решает свою задачу, поэтому OKF лучше рассматривать как общий слой знаний, находящийся под обоими, а не как конкурента. Файлы в формате Markdown вряд ли можно назвать инструментом для запуска продукта, однако иногда именно самый простой вариант оказывается наиболее эффективным.
Стоит ли его использовать?
Для любого агента, который отвечает на вопросы о ваших данных, показателях или системах, ответ — да, стоит попробовать. Попытка не стоит выеденного яйца: достаточно написать три файла, связать их между собой, указать агенту путь к папке, и уже к концу дня станет ясно, помогает ли это решение. Если ваши знания хранятся только в голове одного человека или в беспорядочном вики-сайте, OKF предоставляет простое, версионируемое место для их записи, что может оказаться полезным как с использованием агента, так и без него. Если вам нужны строгие схемы, типизированные связи или жесткий контроль, сегодня этот инструмент слишком гибкий, поэтому лучше сохранить свой каталог и, возможно, позже экспортировать его в виде пакета.
Не начинайте с всей базы знаний компании. Выберите одну небольшую область, например:
metrics/
active-user.md
revenue.md
conversion-rate.md
systems/
payments-api.md
orders-api.md
runbooks/
payment-failure.md
Свяжите файлы вместе, передайте их одному агенту и измерьте, какие изменения произошли. Это гораздо лучший эксперимент, чем три месяца на разработку платформы OKF для корпораций, прежде чем доказать её необходимость.
Одно обязательное поле и папка с файлами в формате Markdown сами по себе не решат проблему плохой документации. То, что они предлагают, — это общее, скучное, но удобное хранилище для хорошей документации, уже имеющейся у команды, что имеет большую ценность, чем кажется на бумаге.
Связанные статьи
- Практические заметки: создание автономного критика интерфейса с использованием новых технологий Google — Подробное руководство по созданию автономного критика интерфейса с использованием новых технологий Google: контракты, проверки и готовые блоки кода для команд, использующих эту модель.