데이터 분석

OKF와 Knowledge Catalog를 사용하여 에이전트에 컨텍스트 제공

2026년 9월 4일

Firat Elbey

Group Product Manager, Data Analytics

Sam McVeety

Tech Lead, Data Analytics

지금 Gemini 을 사용해 보세요

비즈니스 현장에서 Google AI를 만나기 위한 첫걸음

지금 시작하기

*이 콘텐츠는 AI 번역 도구를 사용하여 번역되었습니다. 정확성을 기하기 위해 노력하고 있으나, 자동 번역에는 오류나 누락이 포함될 수 있습니다. 정확한 정보는 영문 원본을 참고해 주시기 바랍니다.

Google은 LLM-wiki 패턴을 휴대 가능하고 상호 운용 가능한 형식으로 공식화하는 개방형 사양인 개방형 지식 형식 (OKF)을 계속해서 반복하고 있습니다. 하지만 여전히 중요한 질문이 남아 있습니다. 조직 전체에서 OKF 번들에 대한 액세스를 공유하고 관리하려면 어떻게 해야 할까요?

OKF v0.1은 컨텍스트 에이전트에 필요한 휴대용 형식(YAML 프런트매터가 있는 마크다운 파일, 필수 필드 1개, 규칙 5개)을 확립했습니다. 그런 다음 OKF v0.2는 신뢰할 수 있는 머신 작성 번들에 필요한 신뢰 신호 (출처, 검증, 최신성, 증명)를 추가하여 팀이 자체 에이전트에 대해 신뢰할 수 있는 번들을 게시할 수 있도록 했습니다.

그러나 OKF는 팀이 조직 전체에서 번들을 공유하는 방법에 대한 답을 제공하지 않습니다. 번들당 git 저장소는 이식 가능하지만 설명하는 데이터와 함께 검색할 수 없고, 동일한 조직 ID 및 규정 준수 정책을 사용하여 보호하고 관리할 수 없으며, 데이터팀이 이미 작업하고 있는 기술 메타데이터 (스키마, 계보, 소유권) 옆에 있지 않습니다. 모든 다운스트림 에이전트는 각 번들이 어디에 있는지 알아야 하며, 이는 소수의 번들 이상으로 확장되지 않습니다.

조직 전체에서 OKF 번들을 확장하려면 Google Cloud의 에이전트용 컨텍스트 엔진인 Knowledge Catalog를 사용하면 됩니다. 번들을 Knowledge Catalog의 기존 유형에 매핑하면 모든 개념을 검색하고 관리할 수 있으며 카탈로그에서 이미 읽고 있는 모든 에이전트가 개념에 도달할 수 있습니다.

Knowledge Catalog는 에이전트를 위한 컨텍스트 엔진입니다.

Knowledge Catalog를 쿼리하는 모든 에이전트는 조직이 BigQuery, Cloud Storage, 운영 데이터베이스, 애플리케이션에 이미 보유하고 있는 항목에 대해 하나의 관리되는 색인에서 읽습니다. 각 항목에는 스키마, 계보, 소유권, 태그가 포함되어 있으며 도메인별 필드를 추가하는 유형화된 측면으로 확장할 수 있습니다. 동일한 카탈로그는 검색 및 교차 프로젝트 조회를 노출하여 각 에이전트 쿼리에 대해 최적화된 컨텍스트를 검색합니다. 컨텍스트 검색은 안전하며 IAM 제어에 의거하여 관리되므로 에이전트는 IAM ID를 기반으로 액세스 권한이 있는 항목만 볼 수 있습니다.

OKF 번들을 Knowledge Catalog에 게시하려면 일회성 설정과 단일 푸시가 필요합니다. 두 가지 모두 Knowledge Catalog 저장소의 OKF 샘플 코드를 사용하며, 이 샘플 코드의 래퍼는 설정에 gcloud dataplex 를 호출하고 푸시를 kcmd (동일한 저장소의 Metadata-as-Code CLI)에 위임합니다.

이 설정은 번들을 보관할 EntryGroup, 개념을 위한 okf-bundle 이라는 이름의 EntryType, okf 라는 이름의 AspectType (샘플 코드의 okf-aspect.json 스키마에서 OKF 신호 필드를 전달함)의 세 가지 Knowledge Catalog 리소스를 등록합니다. 그러면 푸시가 개념당 하나의 okf-bundle 항목을 생성하며, 각 항목에는 두 가지 측면이 있습니다. 마크다운 본문에 대한 overview 측면과 구조화된 신호에 대한 okf 측면입니다. 표시 이름, 설명, 태그는 항목 자체에 있습니다. 번들의 index.md 탐색 파일과 루트 log.md 도 항목으로 게시됩니다. index 파일은 overview Aspect (OKF 프런트매터 없음)만 포함하고 log.md 는 okf_type: Log로 두 Aspect를 모두 포함합니다.

Knowledge Catalog가 기술 메타데이터에 대해 이미 수행하고 있는 모든 작업 (검색, IAM, 계보, 프로젝트 간 검색)은 설명하는 데이터와 함께 OKF 번들에도 동일하게 적용됩니다.

okf AspectType

샘플 코드의 okf-aspect.json 스키마는 AspectType을 정의합니다. OKF v0.2 사양을 포괄하는 13개의 필드가 포함되어 있습니다.

#	필드	유형	목적
1	`okf_type`	문자열	OKF 문서 유형 (자유 형식, 예: BigQuery 테이블, 측정항목, 증명된 컴퓨팅)
2	생성된	`{by, at}` 기록	마지막으로 의미 있는 변경이 발생한 행위자와 타임스탬프입니다.
3	소스	`{id, resource, title, author, usage_count, last_modified}` 배열	개념의 출처가 되는 자료(신뢰도 신호 포함)
4	확인됨	`{by, at}` 배열	인증 이벤트 인간: 행위자는 가장 높은 신뢰 등급을 나타냅니다.
5	상태	문자열	수명 주기 상태: `draft`, `stable` 또는 `deprecated`
6	`stale_after`	datetime	콘텐츠가 오래된 것으로 간주되는 시점 (명시적 오프셋이 있는 RFC3339)입니다.
7	`usage_window`	`{from, to}` 기록	소스 사용량 수가 측정된 기간입니다.
8	런타임	문자열	증명된 컴퓨팅이 실행되는 방식 (예: `bigquery`)
9	매개변수	`{name, type, required}` 배열	호출자가 채울 수 있는 유형이 지정된 명명된 홀입니다. 발신자가 변경할 수 있는 유일한 표면입니다.
10	계산	문자열	계산 본문을 포함하는 파일의 경로입니다.
11	실행자	record `{resource, receipt[]}`	계산이 어떻게 실행되고 어떤 증거를 반환해야 하는지
12	증명자	`{resource}` 레코드	영수증을 가져와 판결을 반환하는 결정적 코드입니다.
13	`extra`	문자열	템플릿이 모델링하지 않는 제작자 정의 프런트매터(JSON `[path, value]` 쌍) 왕복 손실이 없습니다.

모든 필드에는 표시 이름, 설명, 필수 색인이 주석 처리되어 있습니다. okf Aspect (okf_type, status, stale_after, runtime, computation, extra)의 모든 최상위 스칼라 필드는 Knowledge Catalog 검색 술어를 직접 구동할 수 있으므로 aspect:acme-analytics.us-central1.okf.okf_type=Metric 은 범위 내의 모든 OKF 측정항목을 반환합니다. 레코드 필드의 스칼라 하위 필드 (generated.by, usage_window.from, executor.resource, attester.resource)도 술어를 구동합니다. 배열 필드 (sources, verified, parameters)는 하위 필드에서 서버 측 검색이 불가능합니다. 상담사는 entries.get 을 view=ALL로 호출한 후 클라이언트 측에서 검색 범위를 좁힙니다. datetime형식 필드 (stale_after, generated.at, usage_window.from/.to)의 검색 술어에는 전체 RFC3339 타임스탬프가 아닌 날짜 (stale_after=2026-12-31) 또는 범위 비교 (stale_after>2026-01-01)를 사용해야 합니다.

번들 내보내기

kcmd push 는 git에서 OKF 번들을 읽고 각 개념을 대상 Knowledge Catalog EntryGroup의 항목으로 작성합니다. index.md 파일도 항목이 되며 각 개념은 그 위의 색인에 부모로 지정되므로 번들의 디렉터리 구조가 탐색 가능한 계층 구조로 유지됩니다.

kcmd 는 문서 레이아웃의 번들을 예상합니다. 즉, catalog/ 하위 디렉터리의 마크다운 파일과 스냅샷의 항목 및 측면 유형을 나열하는 번들 루트의 catalog.yaml 을 예상합니다. 샘플 코드의 setup.ts 는 --entry-group 플래그 (기본값 okf_demo )에서 catalog.yaml을 생성하므로, 샘플을 새 번들에 연결하는 독자는 catalog.yaml 을 수동으로 편집하는 대신 플래그를 전달합니다.

OKF v0.2 블로그에서 소개한 Acme Retail 번들의 엔드 투 엔드 워크플로는 다음과 같습니다.

로드 중...

다른 EntryGroup 이름을 선택하거나 다른 번들을 푸시하려면 --entry-group your-name 을 setup.ts 에 전달하고 --bundle path/to/your/bundle 을 push.ts에 전달합니다. 예: bun run setup.ts --entry-group acme-bundle 에 이어 bun run push.ts를 실행합니다. 이렇게 하면 매니페스트가 재생성되므로 이후의 push, pull, cleanup 은 모두 새 EG를 타겟팅합니다. 이전 EG는 gcloud dataplex entry-groups delete <name> --project <your-project> --location <your-location>를 사용하여 수동으로 삭제합니다.

Acme Retail 번들은 미국 소매업체의 BigQuery 환경을 위한 합성 OKF 번들입니다. 여기에는attesters, tables, metrics, computations, policies, skills의 6개 디렉터리에 걸쳐 9개의 리프 개념이 포함되어 있으며, 각 디렉터리에는 자체 index.md가 있고 번들 루트에는 자체 index.md 와 log.md가 있습니다. 총 17개의 항목이 푸시됩니다. Dataplex는 <eg>_entry 를 자동으로 생성하므로 gcloud dataplex entries list 는 18개의 행을 반환합니다.

푸시가 완료된 후:

모든 개념 Markdown 파일은 Knowledge Catalog 항목이며, IAM 구성에 따라 전체 프로젝트 또는 조직에서 검색을 통해 찾을 수 있습니다.
승인된 SQL, 실행기, 증명자, 검증 기록, 전체 개념 본문과 함께 revenue-ytd 증명된 계산이 콘솔에 표시됩니다.
분석가가 Knowledge Catalog에서 '수익'을 검색하면 Acme Retail의 비즈니스 정의와 이를 계산하는 BigQuery 테이블이 모두 하나의 권한 모델 아래에서 발견됩니다.
BigQuery 테이블 항목에 대해 LookupContext를 이미 호출하는 다운스트림 에이전트는 OKF 항목 이름을 resources 목록에 추가하여 번들의 컨텍스트를 검색합니다.

또한 metrics/revenue.md 는 두 가지 측면을 가진 항목이 됩니다. 전체 entries.get 응답 ( view=ALL)은 다음과 같습니다.

로드 중...

{
  "name": "projects/acme-analytics/locations/us-central1/entryGroups/acme-retail/entries/metrics/revenue",
  "entryType": "projects/acme-analytics/locations/us-central1/entryTypes/okf-bundle",
  "createTime": "2026-08-15T00:48:39.123456Z",
  "updateTime": "2026-08-15T00:48:57.234567Z",
  "parentEntry": "projects/acme-analytics/locations/us-central1/entryGroups/acme-retail/entries/metrics/index",
  "entrySource": {
    "displayName": "Revenue",
    "description": "Recognized revenue for a period, per Acme's FY2026 revenue-recognition policy. Backed by an Attested Computation.",
    "labels": {
      "finance": "true",
      "revenue": "true",
      "headline-metric": "true"
    },
    "location": "us-central1"
  },
  "aspects": {
    "dataplex-types.global.overview": {
      "aspectType": "projects/dataplex-types/locations/global/aspectTypes/overview",
      "createTime": "2026-08-15T00:48:57.111111Z",
      "updateTime": "2026-08-15T00:48:57.111111Z",
      "aspectSource": {},
      "data": {
        "content": "# Definition\n\nRevenue for a fiscal year is the sum of `net_amount` over orders that (a) reached `order_status = 'delivered'`, (b) completed the 30-day return window, and (c) fall in the fiscal year by `order_ts`. Multi-currency orders are converted to USD at the `order_ts` daily reference rate. [^revenue-policy]\n\nThe sanctioned computation is [`computations/revenue-ytd.md`](../computations/revenue-ytd.md). Consumers MUST run and attest that computation rather than composing their own SUM. The attester rejects any receipt whose executed SQL does not match the sanctioned form.\n\n# Reporting cuts\n\n- **By fiscal year:** the sanctioned computation takes `year` as its sole parameter.\n- **By channel or category:** these are approved narrations, not new metrics. Join the receipt's row-level result to `orders.channel` or to `order_lines` × `products.category` client-side. Do NOT rewrite the sanctioned SQL.\n\n# Trust and freshness\n\n- **Verified:** VP Finance sign-off on 2026-07-01, against the FY2026 policy.\n- **Stale after 2026-12-31:** Finance re-issues the revenue recognition policy each January. Consumers of this concept after 2027-01-01 MUST re-verify the definition against the new policy before serving.\n\n[^revenue-policy]: Revenue Recognition Policy (FY2026)",
        "contentType": "MARKDOWN"
      }
    },
    "acme-analytics.us-central1.okf": {
      "aspectType": "projects/acme-analytics/locations/us-central1/aspectTypes/okf",
      "createTime": "2026-08-15T00:48:57.222222Z",
      "updateTime": "2026-08-15T00:48:57.222222Z",
      "aspectSource": {},
      "data": {
        "okf_type": "Metric",
        "generated": { "by": "reference_agent/gemini-2.5-pro", "at": "2026-06-30T14:00:00Z" },
        "verified": [ { "by": "human:jsmith@acme", "at": "2026-07-01T09:00:00Z" } ],
        "status": "stable",
        "stale_after": "2026-12-31T00:00:00Z",
        "sources": [
          {
            "id": "revenue-policy",
            "resource": "policies/revenue-recognition.md",
            "title": "Revenue Recognition Policy (FY2026)",
            "author": "human:jsmith@acme",
            "last_modified": "2026-06-15T00:00:00Z"
          }
        ]
      }
    }
  }
}

개요 관점은 revenue.md의 전체 본문을 보유합니다. okf 관점은 구조화된 신호 필드를 전달하므로 에이전트는 마크다운을 파싱하는 대신 직접 필터링할 수 있는 형식으로 출처, 소스, OKF 유형을 가져옵니다. 최상위 스칼라 필드와 레코드 필드의 스칼라 하위 필드에 대한 서버 측 searchEntries 필터, 항목 후 클라이언트 측에서 배열 요소 하위 필드에 대한 에이전트 추가 축소(entries.get) (Aspects 및 EntryTypes는 실제 API 응답 및 검색 술어에서 프로젝트 번호로 키가 지정됩니다. acme-analytics 프로젝트 ID는 가독성을 위해 전체적으로 표시됩니다.)

OKF를 Knowledge Catalog로 푸시하면 어떤 이점이 있나요?

번들이 Knowledge Catalog에 있으면 카탈로그에서 읽는 모든 에이전트에 두 가지 기능을 제공합니다.

조직 전반의 검색 가능성 에이전트는 이미 카탈로그화된 데이터에 사용 중인 동일한 searchEntries 및 LookupContext API를 통해 번들 개념을 찾으므로 OKF 번들은 일치하는 모든 쿼리에서 BigQuery 테이블 및 기타 리소스와 함께 표시됩니다.
거버넌스. 번들 항목은 EntryGroup에서 IAM을 상속하므로 단일 에이전트 호출은 호출자가 읽을 수 있는 권한이 있는 항목만 반환하며 유지관리할 병렬 권한 모델이 없습니다.

조직 전반의 검색 가능성OKF 번들 항목은 BigQuery 테이블 및 기타 카탈로그화된 리소스와 함께 검색 항목 결과에 표시되므로 카탈로그를 이미 쿼리 중인 에이전트가 새 번들을 자동으로 선택합니다. 일치 항목에서 개념의 본문, 신뢰 신호 또는 연결된 개념을 검색하기 위해 에이전트는 LookupContext로 이동하여 entries.get을 호출합니다.

LookupContext 호출은 다음과 같습니다.

로드 중...

응답은 사전 형식화된 YAML 블록이 포함된 단일 context 필드입니다. 이 블록에는 항목의 catalogEntry, 유형, 설명, 라벨로 사용되는 태그, 개요(신뢰도 및 최신 상태 섹션을 포함한 개념의 전체 마크다운 본문)가 포함됩니다. LookupContext는 커스텀 Aspect를 렌더링하지 않으므로 구조화된 OKF 신호 필드 (okf_type, generated, sources, 기타 10개)가 필요한 에이전트는 LookupContext 호출과 함께 entries.get 및 view=ALL 을 사용하여 이를 읽습니다.

저장소 클론, 수동 Aspect 병합, 프런트매터 재파싱이 없습니다. 에이전트는 이미 Knowledge Catalog 클라이언트가 수행하는 것과 동일한 API 호출을 사용합니다.

OKF 번들을 순회하는 에이전트는 일반적으로 3단계 흐름을 따릅니다. 필요한 특정 항목 이름을 이미 알고 있는 에이전트는 1단계를 건너뜁니다. 대상 EntryGroup을 이미 알고 있고 번들을 철저히 열거하려는 에이전트는 entryGroups.entries.list 를 1단계로 대체합니다.

searchEntries는 후보 항목 이름과 설명을 반환합니다. 범위 는 프로젝트 또는 조직을 허용하며, 이 범위 내에서 좁히기는 aspect:acme-analytics.us-central1.okf.okf_type=Metric과 같은 측면 술어를 포함한 쿼리어를 통해 이루어집니다.
상위 몇 개의 항목 이름 (호출당 최대 10개)에 대한 LookupContext는 사전 형식화된 YAML로 전체 개념 본문을 반환합니다. context_budget 은 응답 크기를 제한합니다.
entries.get 에 view=ALL 을 지정하면 모든 항목에 대해 구조화된 OKF 신호 (okf_type, generated, sources, 기타 10개)가 직접 반환되므로 에이전트가 이를 필터링하거나 증명할 수 있습니다.

개념의 sources[] 가 경로를 통해 다른 개념을 참조하는 경우 에이전트는 해당 항목 이름에 대해 LookupContext를 호출하여 참조를 탐색합니다.

수익 항목에 대한 전체 응답:

로드 중...

resources:
 -
  catalogEntry: projects/acme-analytics/locations/us-central1/entryGroups/acme-retail/entries/metrics/revenue
  type: OKF Document
  description: Recognized revenue for a period, per Acme's FY2026 revenue-recognition
    policy. Backed by an Attested Computation.
  overview: |-
    # Definition

Revenue for a fiscal year is the sum of `net_amount` over orders that (a) reached `order_status = 'delivered'`, (b) completed the 30-day return window, and (c) fall in the fiscal year by `order_ts`. Multi-currency orders are converted to USD at the `order_ts` daily reference rate. [^revenue-policy]

The sanctioned computation is [`computations/revenue-ytd.md`](../computations/revenue-ytd.md). Consumers MUST run and attest that computation rather than composing their own SUM. The attester rejects any receipt whose executed SQL does not match the sanctioned form.

# Reporting cuts

- **By fiscal year:** the sanctioned computation takes `year` as its sole parameter.
    - **By channel or category:** these are approved narrations, not new metrics. Join the receipt's row-level result to `orders.channel` or to `order_lines` × `products.category` client-side. Do NOT rewrite the sanctioned SQL.

# Trust and freshness

- **Verified:** VP Finance sign-off on 2026-07-01, against the FY2026 policy.
    - **Stale after 2026-12-31:** Finance re-issues the revenue recognition policy each January. Consumers of this concept after 2027-01-01 MUST re-verify the definition against the new policy before serving.

[^revenue-policy]: Revenue Recognition Policy (FY2026)
  labels:
    finance: 'true'
    revenue: 'true'
    headline-metric: 'true'

거버넌스

EntryGroup에 대한 권한은 표준 Knowledge Catalog IAM을 사용합니다. 하나의 호출에서 번들 개념과 BigQuery 테이블을 모두 지정하는 에이전트는 각각 자체 액세스 제어 목록 (ACL)의 적용을 받으므로 호출자가 이미 읽을 수 있는 권한이 있는 항목만 응답에 포함됩니다. 유지관리할 병렬 권한 모델이 없습니다.

읽기 에이전트는 roles/dataplex.catalogViewer를 사용하며, 이 역할은 entries.get, LookupContext, searchEntries의 읽기 경로를 부여합니다. kcmd push 를 실행하는 ID는 roles/dataplex.catalogEditor를 사용하며, 이 역할은 entries.create 및 entries.patch쓰기 경로를 부여합니다. 번들을 소유한 팀당 하나의 EntryGroup이 있는 멀티팀 패턴이며, EntryGroup의 IAM이 항목으로 캐스케이드됩니다.

LookupContext는 호출당 최대 10개의 항목 이름을 단일 위치 내에서 확인합니다. 개념 본문에서 링크를 따라가지 않으므로 참조된 개념을 원하는 에이전트는 명시적으로 이름을 지정해야 합니다. 번들의 EntryGroup을 설명하는 데이터와 동일한 위치에 배치하여 한 번의 호출로 둘 다 가져옵니다.

수명 주기

kcmd push 는 멱등적인 upsert입니다. 다시 실행해도 안전하지만 (중복 없음, 오류 없음) 푸시할 때마다 모든 항목이 작성됩니다. 개념 삭제에는 항목에 대한 명시적인 kcmd delete 또는 cleanup.ts 가 필요하며, cleanup.ts 는 EntryGroup과 항목만 삭제하므로 공유된 okf AspectType과 okf-bundle EntryType은 이를 참조하는 다른 번들에 그대로 유지됩니다. For continuous ingestion in production, wire a CI job to kcmd push on every commit to the bundle repository, using a service-account credential with roles/dataplex.catalogEditor on the target EntryGroup.

게시 위치