17.06.2026 07:42
liuyi0414 0 225 Источник

12 июня 2026 года Google Cloud опубликовала Open Knowledge Format, или OKF. Это открытая спецификация для представления знаний, контекста и метаданных, которые должен читать AI-агент: через директории, Markdown-файлы и YAML frontmatter.

Оригинальная публикация: Introducing the Open Knowledge Format
Спецификация: Open Knowledge Format v0.1

Какую проблему решает OKF

Во многих agent-проектах повторяется один и тот же сценарий: модель умеет писать код, суммаризировать документы и анализировать данные, но ей не хватает бизнес-контекста.

Этот контекст обычно разбросан по разным местам:

  • table schema в каталоге данных

  • определения метрик в wiki или общих документах

  • временные пояснения в notebook

  • комментарии в коде и docstring

  • incident runbook

  • исторические договорённости, которые помнят несколько старших инженеров

Когда agent должен ответить на вопрос «как считать weekly active users», ему может понадобиться одновременно понять таблицу событий, таблицу пользователей, правила фильтрации, временное окно, историю изменений и внутренние договорённости команды. Одних параметров модели для такой задачи обычно недостаточно.

Подход OKF простой: собрать эти знания в обычные файлы, которые могут читать и люди, и agent.

Как выглядит OKF bundle

OKF bundle — это директория. Каждый concept хранится в отдельном Markdown-файле, а путь к файлу становится его identity.

Пример структуры:

sales/
├── index.md
├── datasets/
│   ├── index.md
│   └── orders_db.md
├── tables/
│   ├── index.md
│   ├── orders.md
│   └── customers.md
└── metrics/
    ├── index.md
    └── weekly_active_users.md

В начале concept document находится YAML frontmatter, дальше идёт обычный Markdown.

---
type: BigQuery Table
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, revenue]
timestamp: 2026-05-28T14:30:00Z
---

# Schema

| Column | Type | Description |
| --- | --- | --- |
| `order_id` | STRING | Globally unique order identifier. |
| `customer_id` | STRING | FK to [customers](/tables/customers.md). |

# Joins

Joined with [customers](/tables/customers.md) on `customer_id`.

В OKF v0.1 обязательным является только непустое поле type у каждого concept. Поля title, description, resource, tags, timestamp рекомендованы. Consumer должен спокойно обрабатывать неизвестные поля, отсутствие необязательных полей и битые ссылки.

Почему такой дизайн подходит для agent

У OKF есть несколько инженерных решений, которые хорошо ложатся на agent workflow.

Во-первых, Markdown можно хранить в git. Обновления знаний проходят через pull request, diff, review и blame. Если меняется бизнес-определение, команда видит, кто его изменил, когда и по какой причине.

Во-вторых, frontmatter отвечает только за небольшой объём структурированной информации. Основной текст остаётся в Markdown: schema, примеры, ссылки и пояснения не требуют тяжёлой модели данных ради agent.

В-третьих, index.md поддерживает постепенное чтение. Agent может сначала посмотреть описание директории, а потом решить, какой файл открыть. Ему не нужно сразу загружать всю базу знаний.

В-четвёртых, Markdown link может описывать отношения между concept. Таблицы, metrics, runbook и dashboard можно связывать обычными ссылками. Consumer при необходимости может разобрать эти ссылки как граф.

Что ещё опубликовала Google

Google Cloud выложила в GitHub-репозитории спецификацию OKF и reference implementation. В неё входят:

  • enrichment agent, который может проходить по BigQuery dataset и генерировать OKF concept document для table и view;

  • статический HTML visualizer, который отображает OKF bundle как навигируемый граф;

  • три sample bundle: GA4 e-commerce, Stack Overflow public dataset и Bitcoin public datasets.

Эти реализации больше похожи на proof of concept. Сам формат не привязан к BigQuery, Google Cloud, Gemini или конкретному agent framework.

В блоге Google Cloud также сказано, что Knowledge Catalog уже обновлён: он может ingest OKF и предоставлять его Google Cloud agents. За этим пунктом имеет смысл следить командам, которые используют data stack Google Cloud.

Что это даёт AI coding и внутренним agent

Многие команды уже используют похожий подход, просто не называют его OKF.

Типичные примеры:

  • AGENTS.md

  • CLAUDE.md

  • docs/ внутри repo

  • Obsidian vault

  • runbook внутри проекта

  • metadata-as-code репозиторий у data-команды

Ценность OKF в том, что он сводит такие практики к небольшому набору соглашений. Команда может не внедрять новую платформу и сначала просто привести существующие знания к более стабильной структуре.

Если команда только начинает приводить agent context в порядок, можно начать с нескольких типов файлов:

project/
├── index.md
├── api/
│   ├── endpoints.md
│   └── auth.md
├── data/
│   ├── events.md
│   └── metrics.md
├── runbooks/
│   └── deploy_failure.md
└── log.md

Затем можно явно задать правила для agent:

1. Сначала читать index.md.
2. Для задач, связанных с API, читать api/.
3. Для задач по метрикам и данным читать data/.
4. Для диагностики инцидентов читать runbooks/.
5. При изменении файлов знаний синхронно обновлять log.md.

Такие правила не гарантируют полной корректности agent, но уменьшают часть догадок, которые появляются из-за нехватки контекста.

Текущие ограничения

OKF v0.1 всё ещё находится в draft. Сейчас его рано воспринимать как зрелый отраслевой стандарт. Есть несколько вопросов, за которыми нужно наблюдать:

  • сколько инструментов за пределами Google начнут читать OKF;

  • не появятся ли у разных команд несовместимые расширения type и frontmatter;

  • как в больших базах знаний решать права доступа, поиск и инкрементальные обновления;

  • как строить review-процесс, если agent сам изменяет файлы знаний;

  • как OKF будет сосуществовать с catalog, OpenAPI, Protobuf, Avro и dbt docs.

Для маленьких команд OKF всё равно может быть полезным ориентиром при работе с agent context. Сначала можно записать ключевые знания в Markdown-файлы, которые легко читать, сравнивать через diff и цитировать. После этого уже стоит решать, нужна ли полная совместимость с OKF в конкретной toolchain.

Примечание автора: если вы используете Claude Code, Codex CLI, Cursor или другие AI-инструменты для разработки, можно следить за заметками и документацией LLMEasy.ru по API-доступу. LLMEasy.ru предоставляет единый API-доступ к Claude, GPT и другим моделям через API Key и Base URL. Это может быть удобно разработчикам, которым нужно управлять несколькими моделями, стоимостью и настройками инструментов в существующем workflow.

Комментарии (0)