2026-06-20

Google Cloud Knowledge Catalog OKF 실습: 메타데이터를 옵시디언 마크다운으로 만들고 그래프로 시각화하기

Google Cloud Knowledge Catalog의 OKF 예제 번들을 Cloud Shell에서 실행하고, HTML 그래프와 Obsidian 그래프 뷰로 확인하는 실습 기록입니다.

요약. 이 글을 30초로 요약하면 Google Cloud의 Knowledge Catalog 저장소에 들어 있는 OKF(Open Knowledge Format) 실습을 따라 합니다. OKF는 “데이터에 대한 설명(메타데이터)”을 YAML frontmatter가 붙은 평범한 마크다운 파일로 표현하는 형식이에요. 그래서 결과물을 옵시디언에 그대로 넣으면 노트가 되고, 그래프 뷰로 연결 관계까지 볼 수 있습니다. GCP 결제 설정이 없어도 “미리 만들어진 번들을 시각화”하는 부분까지는 무료로 끝까지 따라 할 수 있습니다.

0. 이번 실습으로 만들 결과물

데이터셋의 의미/스키마/지표를 설명하는 마크다운 지식 번들(OKF bundle)
그 번들을 한 개의 HTML 파일로 만든 인터랙티브 그래프 뷰(viz.html)
같은 번들을 옵시디언 보관함(vault) 에 넣어 본 모습 (프로퍼티 + 그래프 뷰)

1. OKF가 도대체 뭐예요? (개념 먼저)

Knowledge Catalog 한 줄 정의

Knowledge Catalog(예전 이름 Dataplex)는 구글 클라우드의 AI 기반 데이터 카탈로그입니다. 회사 안에 흩어진 데이터(테이블, 문서 등)가 _무엇인지, 어떤 의미인지_를 정리해 두는 “데이터 사전 + 지식 그래프”라고 보면 됩니다.

OKF는 그 지식을 담는 “그릇”

문제는, 보통 이런 메타데이터가 특정 회사 서비스 안에만 갇혀 있다는 점이에요. OKF(Open Knowledge Format) 는 이 지식을 누구나 읽을 수 있는 평범한 형식으로 빼내자는 제안입니다.

OKF의 규칙은 놀랄 만큼 단순합니다.

“YAML frontmatter가 붙은 마크다운 파일들을 폴더로 모아 놓은 것” - 그게 전부입니다.

파일 하나(=개념 하나, concept)는 이렇게 생겼어요.

---
type: BigQuery Table
resource: https://bigquery.googleapis.com/.../tables/events_*
title: Events table (Google Analytics BigQuery Export)
description: Contains Google Analytics event export data ...
tags:
  - events
  - BigQuery
  - ecommerce
timestamp: '2026-05-28T22:53:05+00:00'
---

# Overview
`events_` 테이블은 GA4 이커머스 데이터를 담은 샤딩 테이블입니다.

# Metrics
- [Event Count](../references/metrics/event_count.md) - 전체 이벤트 수
- [User Count](../references/metrics/user_count.md) - 고유 사용자 수

왜 이게 옵시디언 사용자에게 특별할까?

눈치채셨나요? 위 형식은 옵시디언 노트와 100% 똑같습니다.

맨 위 --- 사이의 YAML -> 옵시디언의 프로퍼티(Properties)
본문의 [제목](상대경로.md) 링크 -> 옵시디언이 그대로 노트 간 링크로 인식
폴더 = 카테고리, 파일 = 노트

즉 OKF 번들을 옵시디언 보관함에 넣기만 하면, 별도 변환 없이 노트가 되고 그래프 뷰에서 개념들의 연결 관계가 그려집니다. OKF 공식 문서도 소비 도구로 Obsidian, Notion, MkDocs를 직접 언급합니다.

노트. 한눈에 보는 OKF의 장점

사람도 읽고 AI도 읽는다 - SDK 없이 cat 한 번이면 끝

Git으로 버전 관리 - 메타데이터에 Pull Request/diff/리뷰가 그대로 적용

잠금(lock-in) 없음 - 그냥 폴더라서 어디든 들고 다님

2. 실습 준비물

준비물	설명
Google Cloud Shell	브라우저만 있으면 되는 무료 리눅스 터미널 + 에디터
이 저장소	`GoogleCloudPlatform/knowledge-catalog`
Python 3.11 이상	OKF 패키지 요구 버전 (README는 3.13 권장)
(선택) Gemini API 키	직접 `enrich`로 번들을 만들 때만 필요
(선택) GCP 프로젝트 + BigQuery	위와 동일 - 시각화만 할 거면 불필요

정보. 결제(billing) 설정이 없어도 괜찮아요 이 글의 1~6단계(클론 -> 설치 -> 테스트 -> 번들 구경 -> 시각화 -> 옵시디언 연동) 는 GCP 과금이 전혀 없는 경로입니다. 직접 데이터를 보강하는 7단계만 선택적으로 결제/키가 필요합니다.

3. [Step 1] 저장소 클론하고 폴더로 들어가기

Cloud Shell 터미널에서 저장소를 받아옵니다. (이미 받으셨다면 이 단계는 건너뛰어도 돼요.)

1 2	git clone https://github.com/GoogleCloudPlatform/knowledge-catalog.git cd knowledge-catalog/okf

okf 폴더가 이번 실습의 무대입니다. 안에 뭐가 있는지 살짝 봅시다.

1 2	ls # bundles pyproject.toml README.md samples src SPEC.md tests

bundles/ - 이미 완성된 예제 번들 3개 (ga4, stackoverflow, crypto_bitcoin)
samples/ - 각 번들을 만든 “레시피”(명령어 + 씨앗 URL)
src/ - 실제 에이전트 코드
SPEC.md - OKF 형식 명세서

4. [Step 2] Python 확인하고 가상환경에 설치하기

4-1. 먼저 파이썬 버전 확인

OKF는 Python 3.11 이상이 필요합니다. 내 Cloud Shell 버전을 확인해요.

1	python3 --version

3.11 이상이면 -> 4-2(A)로 진행
3.10 이하라면 -> 4-2(B)의 uv 방법을 쓰세요 (제가 실제로 검증한 우회로입니다)

4-2(A) 표준 방법 - 버전이 3.11+일 때

파이썬 가상환경을 만들고(=실습용 독립 공간), 그 안에 OKF를 설치합니다.

1
2
3

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

-e ".[dev]" 는 “현재 폴더의 패키지를, 테스트 도구(dev)까지 포함해 설치”하라는 뜻이에요. google-adk, google-cloud-bigquery 등 필요한 라이브러리가 자동으로 따라 들어옵니다.

4-2(B) 우회 방법 - 버전이 낮을 때 (`uv` 사용)

uv는 파이썬 자체를 원하는 버전으로 받아주는 빠른 도구입니다.

pip install uv --user        # 한 번만
uv venv --python 3.13 .venv  # 3.13 가상환경 생성
source .venv/bin/activate
uv pip install -e ".[dev]"

설치가 끝나면 프롬프트 앞에 (.venv) 가 붙습니다. 이게 “가상환경이 켜졌다”는 신호예요.

5. [Step 3] 설치가 잘 됐는지 테스트로 확인

OKF 저장소에는 자체 테스트가 들어 있어요. 한 줄로 “설치가 멀쩡한지” 확인할 수 있습니다.

1	python -m pytest -q

성공하면 이렇게 나옵니다 (제가 실제 실행한 결과):

1 2	................................. [100%] 33 passed in 0.63s

점(.) 하나가 테스트 하나예요. 33 passed 가 보이면 환경 구성 끝!

6. [Step 4] 미리 만들어진 OKF 번들 구경하기

직접 만들기 전에, 이미 완성된 번들을 열어 OKF가 실제로 어떻게 생겼는지 봅시다. GA4(구글 애널리틱스) 번들의 구조를 출력해 볼게요.

1	find bundles/ga4 -name "*.md" \| sort

bundles/ga4/index.md
bundles/ga4/datasets/ga4_obfuscated_sample_ecommerce.md
bundles/ga4/tables/events_.md
bundles/ga4/references/metrics/event_count.md
bundles/ga4/references/metrics/user_count.md
... (지표/조인 정의들)

폴더 구조 자체가 지식의 분류 체계입니다: datasets/(데이터셋), tables/(테이블), references/metrics/(지표 정의). 그리고 각 폴더에는 자동 생성된 index.md 가 있어 “한 단계씩” 탐색할 수 있어요.

이제 테이블 개념 파일 하나를 직접 열어 봅니다. Cloud Shell 에디터(연필 아이콘 또는 Open Editor)에서 bundles/ga4/tables/events_.md 를 열어 보세요. 맨 위 frontmatter(type, tags, description)와 본문의 [지표](../references/metrics/..) 링크가 보일 거예요.

터미널에서 앞부분만 보려면:

1	sed -n '1,20p' bundles/ga4/tables/events_.md

7. [Step 5] 하이라이트 - 번들을 그래프로 시각화하기

OKF 패키지에는 번들을 한 개의 자체 완결형 HTML(서버도 설치도 필요 없는)로 바꿔 주는 visualize 명령이 있습니다. 이 단계는 GCP가 전혀 필요 없습니다.

python -m enrichment_agent visualize \
    --bundle ./bundles/ga4 \
    --out ./bundles/ga4/my_viz.html \
    --name "GA4 OKF 데모"

제가 실제로 돌린 결과는 이렇게 나왔어요.

1	Wrote 11 concept(s), 9 edge(s), 50534 bytes -> ./bundles/ga4/my_viz.html

11개 개념(노드) 과 9개 연결(엣지) 로 이루어진 그래프가 들어 있다는 뜻입니다.

만든 HTML을 브라우저로 열기

Cloud Shell에서 HTML 그래프를 보는 가장 쉬운 방법:

왼쪽 에디터의 파일 탐색기에서 okf/bundles/ga4/my_viz.html 우클릭 -> Download
내 컴퓨터에 받아진 파일을 더블클릭해서 브라우저로 열기

또는 터미널에서 cloudshell download bundles/ga4/my_viz.html 명령을 써도 됩니다.

열면 이런 걸 볼 수 있어요.

개념들이 색깔 노드로 떠 있는 force-directed 그래프 (데이터셋/테이블/지표가 다른 색)
노드를 클릭하면 오른쪽에 frontmatter + 본문이 렌더링되는 상세 패널
검색창, 타입 필터, “Cited by”(역링크) 목록

8. [Step 6] 같은 번들을 옵시디언에서 열기

이번 실습의 백미입니다. 방금 본 그래프를, 옵시디언에서도 똑같이 볼 수 있어요. 변환이 필요 없거든요.

내 컴퓨터에 okf/bundles/ga4 폴더를 통째로 내려받습니다. (에디터에서 ga4 폴더 우클릭 -> Download, 또는 git clone 한 로컬 사본 사용)
옵시디언에서 새 보관함(vault) 을 그 폴더로 열거나, 기존 보관함 안에 폴더를 복사해 넣습니다.
아무 노트(예: tables/events_)나 열어 보세요.
- 위쪽 frontmatter가 Properties 패널로 깔끔하게 표시됩니다.
- 본문의 [Event Count](../references/metrics/event_count.md) 링크가 클릭 가능한 노트 링크가 됩니다.
오른쪽 위 Graph View(그래프 보기)를 켜면, visualize로 본 것과 같은 연결 그래프가 옵시디언 네이티브로 그려집니다.

핵심. OKF 번들 하나로 두 개의 그래프 뷰를 공짜로 얻습니다 - 패키지가 만든 viz.html, 그리고 옵시디언의 Graph View. 같은 마크다운이 도구만 바꿔 두 번 살아나는 거예요.

9. [Step 7] (선택) 직접 내 번들 만들기 - `enrich`

주의. 여기서부터는 자격 증명이 필요해요 enrich는 Gemini 모델(문서를 써 주는 AI)과 BigQuery 접근이 필요합니다.

BigQuery 비용: 이 에이전트는 주로 메타데이터/샘플 행만 읽어서 사실상 과금이 거의 없지만, 프로젝트 설정과 BigQuery API 활성화는 필요합니다.

Gemini: AI Studio 무료 API 키가 가장 간단합니다. 결제/권한이 불확실하면 이 단계는 건너뛰고 6단계까지로 마무리해도 실습은 충분합니다.

9-1. 자격 증명 설정 (Cloud Shell 기준)

Cloud Shell은 이미 로그인되어 있어 BigQuery 접근(ADC)은 대개 바로 됩니다. 프로젝트만 지정해요.

1	gcloud config set project <내-프로젝트-ID>

Gemini 키는 Google AI Studio에서 발급받아 환경변수로 넣습니다.

1	export GEMINI_API_KEY="여기에-발급받은-키"

9-2. 공개 데이터셋으로 번들 생성

구글이 공개한 GA4 데이터셋을 대상으로, 웹 보강은 끄고(--no-web) 빠르게 한 번 만들어 봅니다.

python -m enrichment_agent enrich \
    --source bq \
    --dataset bigquery-public-data.ga4_obfuscated_sample_ecommerce \
    --no-web \
    --out ./bundles/my_ga4

한 개념만 빠르게 시험하려면 --concept tables/events_ 를 붙이세요. 끝나면 ./bundles/my_ga4/ 안에 내가 만든 마크다운 번들이 생깁니다.

9-3. 내가 만든 번들도 시각화

5단계와 똑같이 시각화하면 끝!

1	python -m enrichment_agent visualize --bundle ./bundles/my_ga4

10. 자주 막히는 곳 (트러블슈팅)

증상	원인	해결
`pip install` 단계에서 버전 에러	Python이 3.10 이하	4-2(B)의 `uv` 방법으로 3.13 환경 만들기
`(.venv)` 가 안 보임	가상환경 미활성화	`source .venv/bin/activate` 다시 실행
`visualize`는 되는데 그래프가 안 열림	HTML을 Cloud Shell 안에서 열려고 함	파일을 Download 후 내 브라우저에서 열기
`enrich`에서 권한/결제 오류	BigQuery API 미활성화 또는 프로젝트 미설정	`gcloud config set project`, BigQuery API 활성화 / 또는 7단계 건너뛰기
`enrich`에서 인증 오류	Gemini 키 누락	`export GEMINI_API_KEY=...` 확인
옵시디언에서 링크가 안 걸림	“위키링크만 사용” 설정	설정 -> 파일 및 링크 -> “새 링크를 마크다운으로” 권장

11. 마치며 + 다음 단계

오늘 한 일을 한 줄로 정리하면: “구글 클라우드의 데이터 메타데이터를, 잠금 없는 마크다운(OKF)으로 보고 -> 그래프로 시각화하고 -> 옵시디언에 그대로 얹었다.”

OKF가 매력적인 이유는 결국 “지식 큐레이션을 소프트웨어 개발처럼” 만든다는 점이에요. 메타데이터가 Git에 들어가니 diff/리뷰/PR이 그대로 적용되고, 옵시디언/Notion/MkDocs 같은 기존 도구가 곧바로 뷰어가 됩니다.

더 해볼 거리

다른 예제 번들(stackoverflow, crypto_bitcoin)도 visualize 해서 비교해 보기
SPEC.md를 읽고 OKF의 필수 필드 규칙 이해하기
enrich에 --web-seed-file로 공식 문서 URL을 줘서 웹 보강 패스까지 돌려 보기
내 회사/개인 BigQuery 데이터셋으로 나만의 지식 번들 만들기

참고 링크

Knowledge Catalog 저장소: https://github.com/GoogleCloudPlatform/knowledge-catalog
OKF 명세(SPEC): okf/SPEC.md
Google AI Studio(Gemini 키): https://aistudio.google.com/app/apikey
Google Agent Development Kit(ADK): https://adk.dev/

AI agent 실습과 학습 노트를 운영 가능한 기록으로 남깁니다.

Google Cloud Knowledge Catalog OKF 실습: 메타데이터를 옵시디언 마크다운으로 만들고 그래프로 시각화하기

0. 이번 실습으로 만들 결과물

1. OKF가 도대체 뭐예요? (개념 먼저)

Knowledge Catalog 한 줄 정의

OKF는 그 지식을 담는 “그릇”

왜 이게 옵시디언 사용자에게 특별할까?

2. 실습 준비물

3. [Step 1] 저장소 클론하고 폴더로 들어가기

4. [Step 2] Python 확인하고 가상환경에 설치하기

4-1. 먼저 파이썬 버전 확인

4-2(A) 표준 방법 - 버전이 3.11+일 때

4-2(B) 우회 방법 - 버전이 낮을 때 (`uv` 사용)

5. [Step 3] 설치가 잘 됐는지 테스트로 확인

6. [Step 4] 미리 만들어진 OKF 번들 구경하기

7. [Step 5] 하이라이트 - 번들을 그래프로 시각화하기

만든 HTML을 브라우저로 열기

8. [Step 6] 같은 번들을 옵시디언에서 열기

9. [Step 7] (선택) 직접 내 번들 만들기 - `enrich`

9-1. 자격 증명 설정 (Cloud Shell 기준)

9-2. 공개 데이터셋으로 번들 생성

9-3. 내가 만든 번들도 시각화

10. 자주 막히는 곳 (트러블슈팅)

11. 마치며 + 다음 단계

참고 링크

댓글

0. 이번 실습으로 만들 결과물

1. OKF가 도대체 뭐예요? (개념 먼저)

Knowledge Catalog 한 줄 정의

OKF는 그 지식을 담는 “그릇”

왜 이게 옵시디언 사용자에게 특별할까?

2. 실습 준비물

3. [Step 1] 저장소 클론하고 폴더로 들어가기

4. [Step 2] Python 확인하고 가상환경에 설치하기

4-1. 먼저 파이썬 버전 확인

4-2(A) 표준 방법 - 버전이 3.11+일 때

4-2(B) 우회 방법 - 버전이 낮을 때 (uv 사용)

5. [Step 3] 설치가 잘 됐는지 테스트로 확인

6. [Step 4] 미리 만들어진 OKF 번들 구경하기

7. [Step 5] 하이라이트 - 번들을 그래프로 시각화하기

만든 HTML을 브라우저로 열기

8. [Step 6] 같은 번들을 옵시디언에서 열기

9. [Step 7] (선택) 직접 내 번들 만들기 - enrich

9-1. 자격 증명 설정 (Cloud Shell 기준)

9-2. 공개 데이터셋으로 번들 생성

9-3. 내가 만든 번들도 시각화

10. 자주 막히는 곳 (트러블슈팅)

11. 마치며 + 다음 단계

참고 링크

더 읽어보기

댓글

4-2(B) 우회 방법 - 버전이 낮을 때 (`uv` 사용)

9. [Step 7] (선택) 직접 내 번들 만들기 - `enrich`