Open Knowledge Format: Markdown-файлы як пераносны пласт ведаў для агентаў

Агенты вітрачаюць токены, зноў і зноў чытаючы тыя ж внутрышні дакументы, і 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, знову ж такі, без бэкенду — проста файл, які можна апрацаваць чы прыслаць па электранямі колеге.

Прыямнікі

• Ніжэйшыя вітраты: апісанне выконваецца адназначна і чытаецца безпосерэдна, таму не трэба плаціць за яго паўторную генерацыю пяцьдзiesят разоў на дзень.
• Шырэйшы час завантажэння: на дыску знаходзіцца звычайны тэкст, без неабходнасці падключэння да сэрвісу знанняў і без крока інтэграцыі перад вікорыстаннем.

Праўя перэноснасць: клонуйце рэпазітарый, копіюйце папку або перакладзіце яе ў адобраз Докера, і ёй будзе дзейсціваць так сама на GCP, Azure, AWS чы роўнэй на ноутбуку. Няма нічога, што могла б вас прыкрэпіць.

Бесплатны кантроль версій: пакеты знаходзяцца ў git, таму працююць pull requests, diffs, аналіз вінаватых і перагляд, а кераванне ведамасцю стае звычайной інжынернай працай.

Едынага джэрага для людзей і агентаў: новы працавальнік і агент, які працуе ў рэжыме нарадчыка, ачынаюць тую ж файл, таму у вікі не можа быць адной версіі, калі агент верыць іншай.

Абмянка між камандамі і арганізацыямі: прадавець можа адправіць каталог у віглядзе пакета OKF, які ваш агент можа выкарыстоўваць безпосерэдна, без жадных робатаў з інтэграцыяй.

Магчымасць перагляду ўсё ж такі ўсё ўлучнейшы прынтэл. Падазроўваю, што агент прапанавае такую змяну:

- Revenue is recognized when an order is placed.
+ Revenue is recognized after delivery and the 30-day return window.

Гэта просты ўказчык разніцы гіта, і адгукнік бачыць абоўшчыну таго, што змянілася. Яго набагато лёгкае ацэніць, чым тыхуе апдэйт, захаванае ў прыналежнай сістэме знанняў.

Якія ў яго недастаткі

• Ён не відновляе некарэктныя ваказанні. Стандарт OKF стандартызуе кантэйнер, а не ўместа, таму якшо каманда не можа дагадацца, што значыць «актыўны корыстнік», файл у фармаце markdown не змусіць іх дасягнуць згоды.
• Хтось павінен яго падтрымваць. Файлы стаюць застарэлымі, а поля timestamp і log.md дапамагаюць толькі тады, калі людзі або агенты іх апдэюць. Застарэлыя знанні можу завдаць больш шкоды, чым ўсёўсёды ўжо няма знанняў, адтуды агенты веруюць у тое, што знаходзяць.
• Гэта молады праект, якраз не завершаны, таму поля і правілы могу змяніцца, і тыя, хто ўжо яго вжывае, должны спакою чакаць змян.
• Значэнне не прымуе прымусовага характару. Супяж паказвае, што два панявання ўзаемна асоўваны, але не як, а асоцыяцыя опісваецца ў прозе, якая ёсць гнучкай і адночасова нечыстай. Для строга тыпаваных асоцыяцый все ж патрэбна справжняя база дадзэнняя графаў.
• Паказваецца мало аднароджэнняў. Практычна всія праўодчыкі і спожывачы на момент запуску былі з Google, і фармат зможа паводзіцца ўспэшна толькі тады, калі іншыя інструменты і команды яго застосуюць.

OKF паўстае палягліва да RAG і MCP

Нічыя з элементаў чырвонай стака не выкарыстоўваецца, таму што OKF размешчаецца пад яю. RAG яшчэ і так знаходзіць relevантныя фрагменты, калі прыходзіць запіт, а 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 самі по сабе не зможу вылечыць паслабленую дакументацыю. Тое, што яны працююць, — гэта спяльны, нудны, але перэносны «дом» для хорашай дакументацыі, якаю ужо ўтрымвае команда, і гэта мае большую цэннасць, чым можа здавацца на паперы.