OKF (Open Knowledge Format)

• **OKF(Open Knowledge Format)**는 LLM-wiki 패턴을 이식 가능한(portable) 형식으로 표준화한 개방형 명세(open specification)
• 메타데이터·컨텍스트·정제된 지식을 표현하는 벤더 중립(vendor-neutral)·에이전트/사람 친화적 표준
• YAML frontmatter를 가진 markdown 파일들의 디렉터리 구조
• 누가 쓰는지(producer)와 누가 읽는지(consumer)를 분리한 교환 포맷(lingua franca)

쉽게 이해하기

동아리 운영 정보를 떠올려 보자. 선배들이 각자 카톡·구글닥스·머릿속에 정보를 흩어 놓으면, 새로 들어온 후배(또는 새 AI 비서)는 매번 “그건 누구한테 물어봐야 해?”를 반복하게 된다.

OKF는 “모든 정보를 똑같은 양식의 메모 카드(맨 위에 제목·태그 라벨 + 본문은 마크다운)로, 한 폴더에 모아두자”는 약속이다. 카드 양식이 통일돼 있으니 — 누가 썼든 상관없이 — 사람도 읽고 AI 비서도 번역 없이 그대로 읽는다. 요리로 치면 세상의 모든 레시피를 똑같은 카드 양식(제목 / 재료 / 순서)으로 써둔 레시피 박스 와 같다. 사람도 보고, 요리 로봇도 본다.

해당 개념이 필요한 이유

• 조직의 지식이 메타데이터 카탈로그·위키·코드 주석·“몇몇 시니어 엔지니어의 머릿속”에 흩어져 있는 파편화(fragmentation)
• 모든 에이전트 빌더가 동일한 context-assembly 문제를 매번 처음부터 푸는 중복 비용
• 지식이 그것을 만든 surface(도구/플랫폼)에 묶이는 벤더 lock-in

AS-IS — 파편화된 지식, 에이전트마다 재조립

flowchart LR
    MC[Metadata Catalog] --> A1[Agent A]
    WK[Wiki / Drive] --> A1
    CC[Code comments] --> A1
    SE[Senior eng's head] --> A1
    MC --> A2[Agent B]
    WK --> A2
    CC --> A2
    SE --> A2
    A1 -. 각자 context 조립 재구현 .-> X((중복))
    A2 -. 각자 context 조립 재구현 .-> X

TO-BE — 공유 OKF 번들을 누구나 소비

flowchart LR
    P[Producer<br/>사람 or 에이전트] -->|writes| OKF[(OKF bundle<br/>markdown + YAML)]
    OKF --> A1[Agent A]
    OKF --> A2[Agent B]
    OKF --> H[Human reader]

OKF 설계 원칙 3가지

1. Minimally Opinionated (최소한의 규약)

모든 concept에 단 하나, type 필드만 요구한다. 나머지는 전부 producer의 자유에 맡긴다.

2. Producer/Consumer Independence (생산자·소비자 분리)

지식을 쓰는 주체와 읽는 주체를 깔끔하게 분리한다. 사람이 손으로 작성한 bundle을 AI 에이전트가 그대로 소비할 수 있다.

3. Format, not Platform (플랫폼이 아닌 포맷)

특정 클라우드·DB·모델 제공자·에이전트 프레임워크에 묶이지 않는다. 읽고·쓰고·서빙하는 데 독점 계정이나 SDK가 절대 필요하지 않다.

OKF의 3가지 핵심 속성

• Just markdown — 어떤 에디터에서도 읽히고, GitHub에서 렌더링되며, 어떤 검색 도구로도 인덱싱됨
• Just files — tarball로 배포, 모든 git repo에 호스팅, 모든 파일시스템에 마운트 가능 (번들 패키징·구조·병합 규칙은 OKF Bundle (번들링))
• Just YAML frontmatter — type, title, description, resource, tags, timestamp 같은 질의 가능한 구조화 필드

OKF 디렉터리 & 문서 포맷 예시

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

---
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`.

위 예시처럼 metric·table·join을 문서로 정의하는 방식은 시맨틱 레이어와 문제 영역이 겹친다. 다만 OKF는 실행 가능한 쿼리 엔진이 아니라 지식을 표현·교환하는 포맷이라는 점이 다르다 — “이 metric이 무엇을 의미하는지”를 전달하지, 직접 숫자를 계산해 주지는 않는다.

파일 시스템을 넘어서는 “지식 그래프”

concept들이 일반 markdown 링크로 서로를 참조하면서, 디렉터리는 단순한 부모/자식 관계를 넘어 관계의 그래프가 된다 — OKF는 무거운 RDF·triple store 없이 markdown 링크만으로 가벼운 지식 그래프를 구현하는 셈이다.

레퍼런스 구현 (v0.1)

• Enrichment agent — BigQuery 데이터셋을 순회하며 테이블/뷰마다 OKF concept 문서를 초안 작성하고, 2차 LLM 패스로 공식 문서를 크롤링해 citation·스키마·join path로 보강
• Static HTML visualizer — 백엔드 없이 동작하는 시각화 도구
• 3개 샘플 번들 — GA4 e-commerce, Stack Overflow, Bitcoin 데이터셋
• Google Cloud Knowledge Catalog가 OKF를 ingest해 에이전트에 서빙하도록 업데이트됨

실제 적용 사례

① BigQuery 데이터셋을 OKF 번들로 자동 변환 — enrichment agent

가장 구체적인 적용은 Google이 레퍼런스로 공개한 enrichment agent(enrichment_agent)다. 공식 구현은 두 개의 패스로 동작한다.

1. BQ Pass (1차) — BigQuery 메타데이터만 사용해 소스가 광고하는 concept마다 OKF 문서 한 장을 생성한다 (“writes one OKF doc per concept the source advertises, using BigQuery metadata alone”). frontmatter에 type: BigQuery Table, title, resource(콘솔 링크)를 채우고 본문에 스키마 표를 넣는다.
2. Web Pass (2차, LLM) — seed URL 목록(--web-seed-file)을 받아 fetch_url로 공식 문서를 크롤링하고, 권위 있는 문서로 보이는 outbound 링크를 따라간다. 페이지마다 ⓐ 기존 concept에 citation·스키마·join path 보강, ⓑ references/<slug> 새 문서 생성, ⓒ skip 중 하나를 선택한다. --web-max-pages 상한과 same-domain 필터로 크롤링 폭주를 막는다.

실행은 한 줄이다.

python -m enrichment_agent enrich \
    --source bq \
    --dataset <project>.<dataset> \
    --web-seed-file seeds.txt \
    --out ./bundles/<name>

AS-IS — 수작업 문서화 + 흩어진 컨텍스트

flowchart LR
    DS[(BigQuery Dataset<br/>수백 개 table/view)] --> ENG[엔지니어<br/>수작업 문서화]
    ENG --> WK[Wiki]
    ENG --> CAT[Metadata Catalog]
    ENG --> CM[코드 주석]
    ENG -. 누락·방치 .-> SE[(시니어 머릿속)]
    Q["에이전트 질문<br/>'WAU 어떻게 계산?'"] --> ST{흩어진 곳에서<br/>컨텍스트 재조립}
    WK --> ST
    CAT --> ST
    CM --> ST
    SE --> ST
    ST -. 불완전·불일치·stale .-> X((답 신뢰도 낮음))

TO-BE — enrichment agent 2-pass 자동 생성

flowchart TB
    DS[(BigQuery Dataset)] --> BQ
    SEED[seed URLs<br/>--web-seed-file] --> WEB
    subgraph BQ["BQ Pass (1차)"]
        BQ1[테이블·뷰 순회] --> BQ2[concept마다 OKF 문서 초안<br/>메타데이터만 사용]
    end
    BQ --> WEB
    subgraph WEB["Web Pass (2차, LLM)"]
        W1[fetch_url로 공식 문서 크롤링] --> W2{페이지별 판단}
        W2 -->|enrich| W3[citation·스키마·join path 보강]
        W2 -->|mint| W4["references/&lt;slug&gt; 새 문서"]
        W2 -->|skip| W5[건너뜀]
    end
    WEB --> OUT[(OKF 번들<br/>./bundles/name)]
    OUT --> HUMAN[사람: GitHub 렌더링]
    OUT --> AGENT[에이전트: 번역 없이 소비]

이점 — 수백 개 테이블의 의미·조인 관계를 사람이 일일이 문서화하던 작업이 자동화된다. 더 중요한 건 결과물이 사람이 GitHub에서 읽는 문서와 에이전트가 소비하는 컨텍스트가 같은 마크다운 한 벌이라는 점이다. “에이전트용 메타데이터”와 “사람용 위키”를 따로 관리하던 이중 비용이 사라진다.

② Knowledge Catalog가 OKF를 ingest해 에이전트에 서빙

Google Cloud는 Knowledge Catalog가 OKF 번들을 ingest하도록 업데이트했다 — “We have also updated Google Cloud’s Knowledge Catalog to be able to ingest Open Knowledge Format and serve it to our agents.” OKF로 정리한 지식을 카탈로그에 올리면 GCP의 에이전트들이 그 컨텍스트를 번역·변환 레이어 없이 그대로 받아 쓴다.

AS-IS — 에이전트마다 surface별 커넥터 직접 구현

flowchart LR
    subgraph SRC[흩어진 지식 surface]
        MC[Metadata Catalog<br/>독자 API]
        WK[Wiki / Drive]
        CC[코드 주석]
        SE[(시니어 머릿속)]
    end
    A1[Agent A] --> MC
    A1 --> WK
    A2[Agent B] --> MC
    A2 --> CC
    MC -. 카탈로그 벤더마다<br/>데이터 모델 재발명 .-> X((통합·재사용 안 됨))

TO-BE — OKF 번들을 카탈로그가 ingest → 에이전트에 serve

flowchart LR
    P[Producer<br/>사람 or enrichment agent] -->|OKF 번들 작성| OKF[(OKF bundle<br/>markdown + YAML)]
    OKF -->|ingest| KC[Google Cloud<br/>Knowledge Catalog]
    KC -->|serve| A1[Agent A]
    KC -->|serve| A2[Agent B]
    KC -->|serve| A3[Agent C]

이점 — 이미 GCP를 쓰는 팀은 “지식 작성 → 카탈로그 적재 → 에이전트 소비”를 표준 포맷 하나로 연결할 수 있다. 카탈로그 벤더가 매번 자체 데이터 모델을 재발명하던 문제(블로그가 지적한 “every catalog vendor is reinventing the same data models”)를 우회한다.

③ 살아있는 예시 — 공개 샘플 번들 3종 + 비주얼라이저

GA4 e-commerce / Stack Overflow / Bitcoin 공개 데이터셋을 enrichment agent로 변환한 번들이 GitHub에 커밋돼 있다. 백엔드 없이 도는 static HTML visualizer로 concept 간 링크 그래프를 바로 둘러볼 수 있어, “OKF 번들이 실제로 어떤 모양인지”를 클론 한 번으로 확인할 수 있다.

이점 — 새 도입 팀이 “표준이 의도한 적용 방식”을 추상적 명세가 아니라 동작하는 conformant 번들로 학습할 수 있다. 명세서가 한 페이지에 들어갈 만큼 작고, 샘플이 곧 튜토리얼 역할을 한다.

참고: OKF는 2026-06-12 공개된 v0.1 신생 표준이라, 아직은 외부 대규모 도입 사례보다 위 레퍼런스 구현이 “표준이 의도한 적용 방식”을 보여주는 중심 예시다.

참고 문서

• How the Open Knowledge Format can improve data sharing (Google Cloud Blog)
• OKF spec & sample bundles (GitHub)
• Google Cloud Introduces OKF: A Vendor-Neutral Markdown Spec (MarkTechPost)
• Open Knowledge Format Guide — Examples, Validator & Templates