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 링크만으로 가벼운 지식 그래프를 구현하는 셈이다.

RAG와의 관계 — “잘 찾기” 위에 “잘 써두기”

RAG로 시맨틱 검색이 이미 가능한데 왜 OKF가 필요하냐는 물음이 자주 나온다. 답은 둘이 경쟁 기술이 아니라 서로 다른 레이어라는 데 있다.

• RAG = read path(잘 찾는 법) — 질의 시점에 방대한 지식에서 관련 조각을 꺼내 오는 검색 메커니즘
• OKF = write path(잘 써두는 법/포맷) — 그 지식을 애초에 어떤 양식으로 큐레이션·표현·공유할지 정한 교환 포맷

즉 “RAG는 잘 찾는 방법, OKF는 잘 써두고 공유하는 양식”이라는 이해가 정확하다. 다만 OKF의 “써두기”는 단순 저장(storage)이 아니라 구조·출처·관계까지 담아 사람과 에이전트가 함께 읽게 만드는 표현에 가깝다. 그리고 OKF 번들이 커지면 그 위에 그대로 RAG를 얹어 검색한다 — 대체가 아니라 상보 관계다.

flowchart TB
    RAW[(흩어진 원천<br/>DB · 문서 · 위키 · 머릿속)] -->|큐레이션·표준화| OKF
    subgraph W["write path — OKF가 담당 (잘 써두기)"]
        OKF[(OKF 번들<br/>markdown + YAML<br/>구조·출처·관계 보존)]
    end
    subgraph R["read path — RAG가 담당 (잘 찾기)"]
        RET[임베딩 · 벡터검색 · 리랭킹]
    end
    OKF -->|이 위에서 검색| RET
    RET --> AG[에이전트 / LLM]
    OKF -->|번들이 작으면 통째로| AG

비유하면 RAG는 관련 책장을 찾아주는 사서, OKF는 책을 어떤 양식으로 쓰고 분류해 꽂을지 정한 출판 규격이다. 사서가 유능해도 책이 낙서·중복·출처불명이면 소용없고, 좋은 사서는 잘 정리된 서가 위에서 더 잘 작동한다.

OKF가 메우는 RAG의 빈틈 5가지 (sales 번들 예시)

아래 예시는 모두 위 sales/ 번들(orders, customers, weekly_active_users)을 기준으로 한다.

① Chunking이 구조·관계를 파괴한다 RAG는 orders.md를 토큰 단위로 잘라 임베딩한다. “스키마 표”는 청크 A, “customers와 customer_id로 join” 문장은 청크 B로 흩어진다. “주문을 고객 이름과 함께 보려면?”을 물으면 청크 A만 걸려오고 join 문장을 놓쳐 반쪽 답이 나온다. OKF는 한 문서 안에 스키마 표 + # Joins + [customers](/tables/customers.md) 링크를 통째로 보존해 join path를 잃지 않는다.

② 정밀한 구조 질의를 못 한다 “revenue 관련 테이블 전부 나열해줘.” RAG는 ‘revenue’와 의미가 가까운 청크를 유사도 순으로 가져오다 weekly_active_users(매출 아님)를 딸려오고, 태그만 revenue이고 본문엔 그 단어가 없는 테이블은 놓친다 — “전부”를 보장 못 한다. OKF는 tags: [sales, revenue] frontmatter를 조건으로 필터해 정확히 그 집합을 준다.

③ 코퍼스 품질에 무관심하다 (garbage-in) “WAU 어떻게 계산해?” 코퍼스에 2년 전 폐기된 초안과 최신 정의가 함께 있으면, RAG는 유사도만 높으면 폐기된 초안을 가져와 자신 있게 틀린 답을 한다 — 어느 게 권위 있는지 모른다. OKF는 weekly_active_users.md에 공식 문서 citation과 timestamp를 붙이고, stale 초안은 애초에 번들에서 큐레이션으로 배제한다.

④ 저작·이식성을 아예 다루지 않는다 (lock-in) 팀 A가 벡터스토어에 임베딩해 둔 지식은 팀 B의 다른 스택에서 그대로 못 쓴다. 청킹 전략·임베딩 모델·벡터스토어가 달라 재색인·재통합이 필요하다 — 지식이 파이프라인에 갇힌다. OKF는 sales/ 폴더를 tarball이나 git repo로 던지면 팀 B가 clone해 자기 에이전트에 그대로 먹인다. 재통합 비용 0.

⑤ 사람이 못 읽는다 벡터DB를 열면 [0.023, -0.19, ...] 부동소수 배열뿐이라 사람이 검수하려면 별도 위키를 또 유지해야 한다(이중 비용). OKF의 orders.md는 GitHub에서 열면 사람이 읽는 문서 그대로이고, 에이전트가 먹는 것과 동일한 한 벌이다.

요약: RAG는 *“어떻게 관련 텍스트를 컨텍스트 창에 넣지?”*를, OKF는 *“그 텍스트가 뭐여야 하고 누가 큐레이션하며 어떻게 공유되지?”*를 푼다. 검색은 이미 잘 풀렸고, 큐레이션된 지식이 새 병목이라 OKF가 각광받는다.

실제로 RAG에 어떻게 저장되나 — ingestion 어댑터가 필수

벡터스토어(Pinecone·Weaviate·Qdrant·pgvector 등)는 청크마다 (id, 벡터, 메타데이터 key-value)를 저장하고, 이 메타데이터 key-value로 빠른 필터링을 한다. OKF의 frontmatter는 바로 이 메타데이터 필드로 승격돼 들어간다 — 청크마다 손으로 태그를 달 필요 없이, 이미 정리된 key-value를 그대로 얹는 것이다.

단, concept 단위 청킹과 이 승격은 저절로 되지 않는다. OKF 구조를 인식하는 ingestion 어댑터를 반드시 거쳐야 한다. 재료가 좋아도 “태우는 건 파이프라인 몫”이다.

flowchart TB
    OKF[(OKF 번들<br/>markdown + frontmatter + 링크)]
    OKF ==>|"필수: OKF-aware 어댑터"| PIPE
    OKF -.->|"어댑터 없이 그냥 태우면"| NAIVE

    subgraph PIPE["ingestion 어댑터가 하는 일"]
        direction LR
        A1[concept 단위 청킹] --- A2["frontmatter →<br/>메타데이터 승격"] --- A3["링크 →<br/>그래프 인덱스"]
    end

    NAIVE["512토큰 막자르기<br/>frontmatter·링크 유실"]
    PIPE ==> GOOD[("벡터스토어<br/>완결 청크 + key-value 필터 + 그래프")]
    NAIVE -.-> POOR[("벡터스토어<br/>텍스트 조각만 → 반쪽 검색")]

OKF 없이 — raw 위키 문서를 512토큰 막자르기

원본에서 스키마와 join 설명이 한 문단씩 떨어져 있으면, 경계가 그 사이를 갈라버린다.

// chunk c1
{ "id": "c1", "vector": [0.02, -0.19, ...],
  "text": "Orders 테이블. 완료 주문 1건당 1행. order_id(string, 전역 고유), customer_id(string) ...",
  "metadata": { "source": "wiki/page-317" } }        // 태그·타입 없음
 
// chunk c2  ← join 설명이 여기로 잘려나감
{ "id": "c2", "vector": [0.05, 0.11, ...],
  "text": "... customers 테이블과 customer_id로 join해 고객 이름·지역을 얻는다.",
  "metadata": { "source": "wiki/page-317" } }

• “주문을 고객 이름과 함께 보려면?” → c1(스키마)만 걸리고 join이 담긴 c2를 놓쳐 반쪽 답
• “revenue 테이블 전부” → metadata에 태그가 없어 필터 불가, 유사도 추측뿐
• 출처 wiki/page-317이 최신인지 폐기본인지 알 수 없음

OKF 적용 — concept 단위 청킹 + frontmatter 승격

orders.md 한 장이 완결된 한 레코드로 들어간다.

{ "id": "orders", "vector": [0.02, -0.19, ...],
  "text": "# Schema\n| order_id | STRING | 전역 고유 |\n| customer_id | STRING | FK→customers |\n# Joins\ncustomers와 customer_id로 join.",
  "metadata": {
    "type": "BigQuery Table",
    "title": "Orders",
    "tags": ["sales", "revenue"],
    "resource": "https://console.cloud.google.com/.../orders",
    "timestamp": "2026-05-28T14:30:00Z",
    "links": ["customers"]
  } }

• “주문을 고객 이름과 함께?” → 스키마 와 join이 한 청크에 → 완결 답 (① 청킹)
• “revenue 테이블 전부” → WHERE 'revenue' IN tags 정확 필터 (② 메타데이터 key-value)
• links:[customers]로 customers 레코드까지 확장 (③ 그래프)
• resource·timestamp로 출처·신선도 확인 (provenance)

같은 지식이라도 — OKF 없이는 “텍스트 조각 + 빈 메타데이터”로, OKF 있으면 “완결 청크 + 질의 가능한 key-value”로 저장된다. RAG 엔진은 동일하고, 먹인 재료의 모양만 다르다.

그럼 질의는 어떻게 달라지나 — “tags로 걸러라”는 누가 정하나

저장이 달라졌으니 **꺼내는 방식(질의)**도 달라진다.

OKF가 없을 때는 순수 의미검색뿐이다.

query = "이번 분기 매출 관련 테이블"
→ embed(query) → 벡터 유사도 top-k → 청크

“매출 관련”도 “이번 분기”도 전부 임베딩 유사도로 추측한다. 구조화 필터가 없어 최신/태그를 거를 수 없다.

OKF가 있으면 의미검색과 구조화 필터를 함께 쓰는 하이브리드가 된다.

query = "이번 분기 매출 관련 테이블"
→ 질의 해석 (사용 가능 필드: type, tags, timestamp 를 앎)
   → { semantic: "매출 테이블",
       filter: { tags: {$in: ["revenue","sales"]},
                 type:  "BigQuery Table",
                 timestamp: {$gte: "2026-04-01"} } }
→ 벡터검색(semantic) WHERE filter → 정확 + 최신 청크

여기서 자연스레 떠오르는 의문 — “tags·timestamp를 확인해 걸러라”는 걸 어디서, 누가 정하나? 그냥 LLM에게 판단을 맡기는 건가?

먼저 확실히 할 것: OKF는 이걸 정하지 않는다. OKF는 “format, not platform”이라 필드를 제공만 하지, “질의 때 tags로 필터하라”는 규칙은 명세에 없다. 그 규칙은 소비하는 쪽(retriever/에이전트)의 질의 레이어에 산다. 방식은 셋 중 하나다.

방식	필터를 누가 고르나	LLM 판단	예
① 규칙 기반	개발자가 코드/설정에 고정	없음	태그 드롭다운, filter={"type":"BigQuery Table"} 하드코딩
② self-query	LLM이 선언된 필드 스키마 안에서 자연어→필터 번역	있음(제약됨)	LangChain SelfQueryRetriever
③ 에이전트 tool-calling	LLM이 정의된 도구 계약 안에서 호출 결정	있음(제약됨)	query(semantic, filters) 툴의 파라미터로 필드 노출

그래서 “단순히 LLM에 위임하나?”의 답은 — 아니다, ‘제약된 위임’이다. ②③처럼 LLM에 맡기더라도 어떤 필드가 있고 무엇을 뜻하는지(field schema / 도구 파라미터)는 개발자가 먼저 선언한다. LLM은 그 울타리 안에서 값만 채울 뿐, 없는 필드를 발명하지 못한다. ①은 아예 LLM 판단이 0이다.

OKF다운 보너스가 하나 있다. 번들의 index.md가 “이 폴더엔 무슨 concept·필드·태그가 있다”를 사람이 읽는 문장으로 적어두므로, 에이전트가 번들을 직접 읽어 사용 가능한 필터를 스스로 파악할 수도 있다. 그래도 그것을 실제 필터로 바꾸는 로직은 여전히 소비 측 몫이다 — OKF는 재료, 질의 전략은 파이프라인.

sequenceDiagram
    autonumber
    actor U as 사용자
    box RAG = 질의 해석기 + 벡터스토어
    participant Q as 질의 해석기(질의구성·답생성)
    participant V as 벡터스토어(검색)
    end
    Note over Q: 개발자가 선언한 필드 스키마(type·tags·timestamp)를 앎
    U->>Q: "이번 분기 매출 관련 테이블"
    Q->>Q: 자연어 → semantic 문구 + 구조화 필터로 분해
    Q->>V: 벡터검색(semantic) WHERE tags has revenue AND timestamp >= Q2
    V-->>Q: 완결 청크(정확·최신)
    Q-->>U: 답변 + 출처(resource)

”소비 측 질의 레이어” 풀어보기 — self-query가 도는 순서

용어부터 풀자. 소비(consume)하는 쪽이란 사용자 입력을 받아 → 검색을 요청하고 → 돌아온 청크로 답을 만들어 돌려주는 앱/에이전트 전체다 (OKF를 쓰는 producer 반대편의, 읽어 쓰는 consumer와 같은 말). 그 앱 안에서 자연어를 실제 검색 요청으로 바꾸는 단계가 질의 레이어다.

한 가지 짚을 것 — RAG와 벡터스토어는 층이 다르다. 벡터스토어(Pinecone·Qdrant·pgvector 등)는 임베딩·메타데이터를 저장하고 유사도 검색·필터를 해주는 *컴포넌트(검색 DB)*다. RAG는 그 검색 결과를 LLM에 먹여 답을 만드는 **retrieve + generate 패턴(파이프라인)**이다. 즉 벡터스토어는 RAG의 ‘검색’ 단계가 쓰는 도구 하나이고(검색을 BM25·SQL·그래프로 해도 여전히 RAG), 질의를 만드는 LLM도 그 패턴 안에 있다 — “LLM이 밖에서 RAG를 부른다”가 아니라 한 파이프라인에서 LLM이 질의를 만들고 → 벡터스토어에서 검색하고 → 다시 LLM이 답을 쓴다.

	벡터스토어	RAG
정체	컴포넌트 — 저장+검색 DB	패턴/파이프라인 — 검색+생성
하는 일	임베딩·메타데이터 저장 → 유사도 검색 + 필터	retrieve(검색) → LLM generate(답 작성)
LLM 포함?	없음	있음 (생성 단계)
예	Pinecone · Qdrant · pgvector · FAISS	문서 찾아 답하는 챗봇 전체
서로의 관계	RAG의 검색 단계가 쓰는 도구 하나	벡터스토어를 쓰는 상위 절차

RAG는 벡터스토어 없이도(BM25·SQL·그래프 검색) 성립하고, 벡터스토어는 RAG 밖(추천·중복탐지·이미지 유사검색)에서도 쓰인다 — 같은 것이 아니라 포함 관계다.

②self-query 기준으로 순서를 보면:

1. 사용자 자연어 질의가 들어온다.
2. [A] 질의 구성 LLM 호출 — 어떤 tags·type·기간으로 걸러야 하는지를 LLM이 뽑는다. 이때 LLM이 그걸 알 수 있는 이유는, 개발자가 “쓸 수 있는 필드 목록과 의미”를 프롬프트(또는 함수/tool 파라미터 스키마)에 미리 주입했기 때문이다.
3. 그 결과(semantic 문구 + 구조화 필터)로 벡터스토어에 검색한다.
4. 돌아온 완결 청크로 답변 생성 LLM이 최종 답을 쓴다.

2단계에서 실제로 오가는 것:

# 개발자가 프롬프트/스키마에 주입해 두는 "쓸 수 있는 필드"
filterable_fields:
  tags:      "비즈니스 도메인 목록 (sales, revenue, marketing ...)"
  type:      "리소스 종류 (BigQuery Table, Metric ...)"
  timestamp: "마지막 갱신 시각"

// 위 스키마를 보고 LLM이 자연어 질의를 번역한 출력
{ "semantic": "매출 테이블",
  "filter": { "tags": {"$in": ["revenue","sales"]},
              "type": "BigQuery Table",
              "timestamp": {"$gte": "2026-04-01"} } }

정리하면 — A(어떤 값을 뽑을지 판단)는 2단계에서 LLM이 하고, A를 가능케 하는 “필드 목록·의미”는 개발자가 프롬프트로 설정한다. LLM은 그 목록 안에서만 값을 채우므로 “제약된 위임”이다. 단, ①규칙 기반에는 이 2단계 LLM이 없고(개발자가 필터를 고정), self-query의 LLM은 질의를 만드는 역할(2단계) 과 답을 쓰는 역할(4단계) 로 두 번 등장한다(같은 모델이든 아니든).

실전: 우리 문서를 OKF로 RAG화하기 — 무손실 + 최적화

회사의 스펙 문서 A(예: 기능 X 명세)를 RAG화한다고 하자. 흔한 오해가 “OKF화 = 요약이라 원문이 유실된다”인데 그렇지 않다. OKF는 markdown + frontmatter일 뿐이라 A의 원문 전체를 body에 그대로 두고 그 위에 메타데이터·구조만 얹으면 유실이 0이다. 유실은 오직 “요약·재작성하기로 선택”했을 때만 생기는 파이프라인 선택이며, 그래도 resource 링크가 원문으로 가는 안전망이 된다. 스펙처럼 정확한 조항이 생명인 문서는 verbatim 보존을 권장한다.

naive 전체텍스트 RAG와 무엇이 다른가 — 두 개의 레버

원문을 양쪽 다 똑같이 담는다면, 달라지는 건 딱 두 가지다.

• ⓐ 자르는 위치(청킹 경계) — 길이 단위(512토큰)는 표·절차를 중간에서 갈라 청크 벡터가 여러 주제의 흐릿한 평균이 된다(유사도 매칭 악화). 헤딩 등 의미 단위로 자르면 청크가 완결되고 임베딩이 선명해진다.
• ⓑ 붙는 라벨(메타데이터) — 길이 청킹은 보통 source뿐이라 여러 문서·버전이 뒤섞인다. frontmatter를 메타로 승격하면 feature·version·tags로 정밀 필터·스코핑·관계 확장이 된다.

함정: 원문 위에 메타데이터만 얹고 청킹은 여전히 길이 단위로 하면 ⓑ(필터)만 얻고 ⓐ(완결 청크)는 못 얻는다. 이점을 다 가지려면 의미 단위 청킹 + 메타 승격 둘 다 필요하다.

언제 OKF-RAG가 값을 하나

• 문서가 하나뿐이고 자유 Q&A만 하면 → naive 전체텍스트 RAG로 충분(OKF는 오버헤드).
• 문서가 많고·길고·버전이 갈리고·서로 참조할수록 → 필터·그래프·정규화·유지보수 이점이 커진다. OKF의 진짜 값은 여러 문서·생산자에 걸쳐 두 레버를 일관되게 강제하는 양식이라는 점이다. (메타데이터 자체는 naive RAG에도 붙일 수 있으나, 일관성·유지보수를 포맷이 보장하지 않는다.)

무손실 유지하며 검색을 최적화하는 대표 기법

단계	대표 기법	무엇을 해결
청킹	Recursive split · Markdown/헤딩 인식 split · Semantic chunking · Proposition	의미 단위 경계
맥락 보존	Parent-Document(small-to-big) · Sentence-window · Contextual Retrieval(Anthropic) · Late chunking · RAPTOR	작은 청크가 문서 맥락을 잃는 문제
검색	Hybrid(BM25+벡터)+RRF · Reranking(cross-encoder) · self-query 메타필터 · HyDE·multi-query · GraphRAG	정확 토큰·정밀도·복합 질의·관계

스펙 문서 A 추천 스택: 헤딩 청킹(원문 보존) + feature/version 메타 → small-to-big 또는 Contextual Retrieval → 질의 시 Hybrid + Reranker + version=latest 필터 → 참조는 링크로 확장, 못 찾으면 resource로 원문 fallback. 어느 조합이 나은지는 데이터·질의마다 다르니 RAGAS 등으로 측정해 고른다.

업데이트 flow — A 스펙이 바뀌면

OKF화해 저장한 뒤 원문이 바뀌면, 전체 재색인이 아니라 바뀐 청크만 upsert + 사라진 청크는 delete하는 증분 색인을 한다.

flowchart TB
    U[사용자 A가 스펙 원문 변경] --> D{변경 인지<br/>웹훅 · 해시 폴링 · git diff}
    D --> RC[재청킹<br/>MarkdownHeaderTextSplitter<br/>timestamp·version 갱신]
    RC --> DIFF{청크 단위 diff<br/>안정 ID + 콘텐츠 해시}
    DIFF -->|해시 같음| SKIP[skip · 재임베딩 0]
    DIFF -->|해시 다름| UP[재임베딩 → upsert]
    DIFF -->|없어짐| DEL["delete ★유령청크 제거★"]
    DIFF -->|새로 생김| INS[임베딩 → insert]
    UP --> VS[(벡터스토어 갱신)]
    DEL --> VS
    INS --> VS
    SKIP -.-> VS

가장 흔한 버그는 삭제 누락 — 원문에서 지운 섹션의 옛 청크가 남아 “유령 지식”으로 검색되는 것. 그래서 “바뀐 것 upsert”보다 “사라진 것 delete”가 본질이다.

이 diff·삭제는 직접 짤 필요 없다 — LangChain Indexing API + RecordManager(cleanup=incremental/full), LlamaIndex refresh_ref_docs, 또는 Knowledge Catalog re-ingest가 처리한다. 단 변경 유형별 한계가 다르다.

변경 유형	도구가 해결?	실제 동작
섹션 삭제	✅ 완전	cleanup이 사라진 청크 자동 delete
순서 변경	✅ 조건부	콘텐츠 기반 해시면 내용 같을 때 skip. 위치를 ID/해시에 넣으면 delete+insert
헤딩 리네임	⚠️ 정확성만	delete+insert로 KB는 맞지만 리네임 인식은 안 됨(불필요 재임베딩·옛 ID 참조 깨짐)

진짜 리네임 추적이 필요하면 옛/새 청크의 임베딩 유사도로 ID를 승계하는 커스텀 매핑이 필요하며, 대개 delete+insert(재임베딩 1회)가 더 싸서 감수한다.

참고 사례: FinSage — 금융 공시 멀티포맷 RAG (실제 배포)

표·차트가 섞인 금융 공시 PDF를 QA하는 시스템. 온라인 미팅 QA 에이전트로 1,200명+ 서비스, CIKM 2025 채택. 위에서 정리한 조각들이 한 파이프라인에 다 들어있어 좋은 레퍼런스다.

• Ingestion(정규화) — MinerU로 PDF→구조화 JSON(reading order, text/table/image 타입), 표·차트는 GPT-4o가 “텍스트 서술문”으로 변환해 임베딩 가능하게. + 중복제거·상호참조 해소·섹션 요약 메타 생성. 청크 = (text, metadata, dense·sparse·metadata 임베딩) 5-튜플. → canonical화(=OKF화)의 구체 구현
• Chunking — 챕터 + 토큰 길이, 섹션 제목을 가로질러 자르지 않음. → 헤딩 인식 청킹
• Retrieval — 4경로 합집합: BM25 + Dense(BGE-M3/FAISS) + Metadata(헤딩+요약 임베딩, 걸리면 세그먼트 전체 회수) + HyDE(가상답변 3개). → Hybrid + self-query + small-to-big + HyDE를 동시에
• Rerank — bge-reranker-v2-Gemma + time·metadata 보너스(신선도·출처 반영) + DPO 파인튜닝. → 리랭킹 + timestamp 신선도
• 평가 — FinanceBench + 전문가 75문항, recall 92.51%, 베이스라인 대비 +24.06%, 리랭커로 precision 5.6%→18.5%. → “반드시 측정”의 실증

한계: 4경로 점수 융합 가중치는 논문에 미명시(재현 시 튜닝 필요). 원문: FinSage — arXiv 2504.14493 (CIKM 2025)

레퍼런스 구현 (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”)를 우회한다.

레이어로 보면 — 앞의 box RAG = 질의 해석기(Q) + 벡터스토어(V)에서 Knowledge Catalog가 V 자리(OKF ingest = 적재·색인, serve = 검색 서빙), 에이전트가 Q(질의 구성·답 생성)다. enrichment agent는 이 질의 루프 밖의 오프라인 write path — 카탈로그를 채우는 쪽이다. 정리: BigQuery = 원천(실제 값), OKF = 교환 포맷, KC = 적재·서빙(≈V), agent = 질의·생성(≈Q).

두 한계도 분명히 — ⓐ KC에 담기는 건 원문 행 데이터가 아니라 데이터에 대한 지식(스키마·의미·join·정의)이라, “매출이 얼마냐” 같은 실제 값은 여전히 BigQuery에서 쿼리를 실행해야 나온다(OKF는 쿼리 엔진이 아니다). ⓑ KC는 적재된 것만 검색한다 — 원문의 정보 X가 OKF 문서에 안 담겼으면 KC 질의로 X는 안 나온다(LLM이 지어내면 hallucination). 빠진 X는 write path를 다시 돌려 담거나 resource 링크로 원천에 돌아가 얻는다.

③ 살아있는 예시 — 공개 샘플 번들 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