Knowledge Catalog (이전 명칭: Dataplex Universal Catalog)의 메타데이터 보강을 사용하면 구조화된 데이터 컨텍스트를 제공하여 AI 에이전트가 신뢰할 수 있고 인증된 소스를 기반으로 답변을 그라운딩할 수 있습니다. 이 튜토리얼에서는 샘플 BigQuery 테이블에 커스텀 관점을 연결하고 Antigravity CLI를 사용하여 AI 에이전트가 거버넌스 규칙을 적용하는 방법을 테스트합니다.
목표
- 테스트를 위해 BigQuery에 현실적인 다중 계층 데이터 레이크를 배포합니다.
- Knowledge Catalog에서 커스텀 메타데이터 템플릿 (관점 유형)을 설계하고 등록하여 공식 데이터 제품을 원시 샌드박스 테이블과 구분합니다.
- Antigravity CLI (
agy)를 사용하여 데이터 거버넌스 규칙 및 AI 에이전트 그라운딩을 확인합니다.
시작하기 전에
시작하기 전에 다음 사항을 수행하세요.
- 이 튜토리얼에서 사용할 Google Cloud 프로젝트를 선택합니다.
- 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.
이 튜토리얼을 완료하려면 BigQuery 및 Knowledge Catalog에 대한 기본 지식도 필요합니다.
개발 환경 준비
이 튜토리얼에서는 클라우드에서 실행되는 명령줄 환경인 Google Cloud Shell을 사용합니다. Antigravity CLI (agy)는 Google Cloud Shell에 사전 설치되어 있습니다.
Google Cloud 콘솔의 오른쪽 상단 툴바에서 Cloud Shell 활성화를 클릭합니다. 환경을 프로비저닝하고 연결하는 데 몇 분 정도 소요됩니다.
Cloud Shell에서 이후의 모든 명령어가 특정 Google Cloud 프로젝트를 타겟팅하도록
PROJECT_ID및REGION변수를 설정합니다.export PROJECT_ID=$(gcloud config get-value project) gcloud config set project $PROJECT_ID export REGION="us-central1"필요한 Google Cloud 서비스를 사용 설정합니다.
gcloud services enable \ artifactregistry.googleapis.com \ bigquery.googleapis.com \ dataplex.googleapis.com \ aiplatform.googleapis.com \ run.googleapis.com \ cloudbuild.googleapis.com \ iam.googleapis.comGoogle Cloud DevRel Demos 저장소를 클론합니다.
GitHub에서 인프라 코드와 스크립트를 다운로드합니다. 희소 체크아웃을 사용하여 이 튜토리얼에 필요한 특정 폴더만 가져옵니다.
# Perform a shallow clone to get only the latest repository structure without the full history git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git cd devrel-demos # Specify and download only the folder you need for this tutorial git sparse-checkout set data-analytics/governance-context cd data-analytics/governance-context
BigQuery에서 샘플 데이터 레이크 배포
실제 데이터 환경은 깔끔한 경우가 거의 없습니다. AI 에이전트는 추론할 수 있지만 특정 회사에 대한 지식이 전혀 없는 상태에서 시작합니다. 에이전트에게 "1분기 수익은 얼마야?"라고 묻는다고 상상해 보세요 안내가 없으면 에이전트는 공식 보고서부터 원시 테스트 데이터에 이르기까지 데이터베이스에서 '수익'이라는 이름의 수십 개의 테이블 중에서 선택할 수 있습니다. 에이전트가 가장 유사한 이름의 테이블을 선택하면 확인되지 않은 소스를 기반으로 설득력 있는 잘못된 답변을 반환할 수 있습니다.
이 시나리오를 시뮬레이션하려면 '공식' 데이터 마트와 신뢰할 수 없는 '샌드박스' 테이블을 혼합해야 합니다. 설정 스크립트를 사용하여 BigQuery 데이터 세트와 테이블을 배포합니다.
설정 스크립트를 실행 가능하게 만들고 실행합니다. 이렇게 하면 BigQuery 데이터 세트 3개 (finance_mart, marketing_prod, analyst_sandbox)가 생성되고 테이블이 샘플 데이터로 채워집니다.
chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh
이제 데이터가 완전히 채워졌지만 관리되지 않는 데이터 레이크가 있습니다. AI 에이전트에게는 모든 표가 똑같이 보입니다.
Knowledge Catalog에서 커스텀 관점 유형 정의
이제 데이터 거버넌스 규칙을 정의합니다. Knowledge Catalog에서 이 작업을 수행하려면 재사용 가능한 강력한 유형의 메타데이터 템플릿인 관점 유형을 만듭니다.
이 섹션에서는 gcloud CLI를 사용하여 이 템플릿을 등록하여 정의 방법을 확인합니다.
관점 템플릿 스키마 검사
aspect_template.json의 콘텐츠를 출력하여 스키마 정의를 확인합니다.
cat aspect_template.json
다음 JSON 구조가 표시됩니다.
{
"name": "OfficialDataProductSpec",
"type": "record",
"recordFields": [
{
"name": "product_tier",
"type": "enum",
"enumValues": [
{ "name": "GOLD_CRITICAL", "index": 1 },
{ "name": "SILVER_STANDARD", "index": 2 },
{ "name": "BRONZE_ADHOC", "index": 3 }
],
...
},
{
"name": "is_certified",
"type": "bool",
"...": "..."
}
]
}
이 스키마는 중요도 등급 (GOLD_CRITICAL, SILVER_STANDARD, BRONZE_ADHOC)에 대해 enum, is_certified에 대해 bool와 같은 엄격한 데이터 유형을 적용합니다. 이렇게 하면 메타데이터가 구조화되고 기계 가독형으로 유지됩니다.
Knowledge Catalog에 관점 유형 등록
다음 gcloud 명령어를 실행하여 Knowledge Catalog 레지스트리에 이 템플릿을 등록합니다.
gcloud dataplex aspect-types create official-data-product-spec \
--location="${REGION}" \
--project="${PROJECT_ID}" \
--description="Defines the comprehensive profile of a data product for data governance agents." \
--display-name="Official Data Product Spec" \
--metadata-template-file-name="aspect_template.json"
데이터 레이크 테이블에 거버넌스 관점 연결
이것이 중요한 엔지니어링 단계입니다. 현재 finance_mart.fin_monthly_closing_internal 테이블과 analyst_sandbox.tmp_data_dump_v2_final_real 테이블은 AI 에이전트에게 동일하게 보입니다. 열이 있는 객체일 뿐입니다.
이러한 테이블을 구분하기 위해 관점을 적용하여 인증된 메타데이터 라벨을 연결합니다. 실제 기업에서는 CI/CD 파이프라인을 사용하여 이 작업을 자동화합니다. 이 튜토리얼에서는 스크립트를 사용하여 자동화를 시뮬레이션합니다.
관점 메타데이터 페이로드 생성
Knowledge Catalog 관점 키는 전역적으로 고유해야 합니다 (프로젝트 ID가 접두사로 추가됨). ./generate_payloads.sh 스크립트는 YAML 메타데이터 파일을 동적으로 생성합니다.
chmod +x ./generate_payloads.sh
./generate_payloads.sh
이렇게 하면 다양한 데이터 거버넌스 시나리오 (fin_internal.yaml, fin_public.yaml, mkt_realtime.yaml, sandbox.yaml)를 정의하는 4개의 YAML 파일이 포함된 aspect_payloads/ 디렉터리가 생성됩니다.
BigQuery 테이블에 관점 연결
스크립트를 실행하기 전에 테이블에 연결하는 데이터를 확인합니다. 다음 명령어를 실행하여 내부 재무 데이터의 메타데이터를 확인합니다.
cat aspect_payloads/fin_internal.yamlYAML 파일은 테이블의 비즈니스 컨텍스트를 정의합니다.
your-project-id.us-central1.official-data-product-spec: data: product_tier: GOLD_CRITICAL data_domain: FINANCE usage_scope: INTERNAL_ONLY update_frequency: DAILY_BATCH is_certified: true이 프롬프트가
is_certified: true를 설정하고GOLD_CRITICAL등급을 할당하는 등 비즈니스 컨텍스트를 명시적으로 정의하는 방식을 확인하세요. 이렇게 하면 AI 에이전트가 테이블 이름을 기반으로 추측하는 대신 명확하고 구조화된 규칙을 평가할 수 있습니다.애플리케이션 스크립트를 실행합니다. 이 스크립트는 BigQuery 테이블을 반복하고
gcloud dataplex entries update명령어를 사용하여 메타데이터 페이로드를 각 테이블에 연결합니다.chmod +x ./apply_governance.sh ./apply_governance.sh
Google Cloud 콘솔에서 적용된 관점 확인
계속하기 전에 스크립트가 Google Cloud 콘솔에서 관점을 올바르게 적용했는지 확인합니다.
- Google Cloud 콘솔에서 Knowledge Catalog 페이지를 엽니다. 상단의 검색창을 사용해 찾을 수 있습니다.
fin_monthly_closing_internal을 검색합니다. 결과에서 BigQuery 테이블 이름을 선택하여 세부정보 페이지를 엽니다.- 하단의 선택적 태그 및 관점 섹션에서
official-data-product-spec관점을 찾습니다. 값이 적용한 '골드 내부' 시나리오와 일치하는지 확인합니다.
이제 기술적으로 동일한 BigQuery 테이블 (fin_monthly_closing_internal 및 tmp_data_dump_v2_final_real)이 기계 가독형 메타데이터에 의해 논리적으로 구분된다는 것을 확인했습니다.
Antigravity CLI로 데이터 컨텍스트 테스트
애플리케이션을 빌드하기 전에 Antigravity CLI를 사용하여 로컬에서 데이터 거버넌스 로직을 확인할 수 있습니다. 이렇게 하려면 Knowledge Catalog 플러그인을 설치하고 에이전트 기술을 구성합니다.
Knowledge Catalog 플러그인 설치
Cloud Shell에서 서비스 플러그인을 설치합니다.
export DATAPLEX_PROJECT="${PROJECT_ID}"
agy plugin install https://github.com/gemini-cli-extensions/dataplex
에이전트 기술 정의 검사
에이전트 기술은 .agents/skills/knowledge-catalog-governance/SKILL.md에 있는 정적이고 재사용 가능한 정의 파일입니다. 여기에는 '안전한 데이터가 필요하다'와 같은 추상적인 인간의 규칙을 구조화된 기술 조회로 변환하는 로직이 포함되어 있습니다.
스킬 설정을 확인하고 데이터 컨텍스트가 작동하는 방식을 이해하려면 SKILL.md 파일을 검사합니다.
cat .agents/skills/knowledge-catalog-governance/SKILL.md
모델이 엄격한 1단계 (메타데이터 검증) 및 2단계 (쿼리 실행) 루프를 따르도록 지시하는 것을 확인할 수 있습니다. 모델은 SQL 문을 구성하기 전에 메타데이터를 검색하고 확인해야 합니다. 이 검색 우선 로직은 에이전트가 테이블 이름을 추측하거나 확인되지 않은 소스에서 답변을 할루시네이션하는 것을 방지합니다.
Antigravity CLI 세션 시작
Antigravity CLI 세션을 시작합니다. 프로젝트 폴더에 있으므로 CLI는 .agents/skills 디렉터리에서 기술을 자동으로 검색하고 로드합니다.
agy
CLI에서 플러그인 설치 확인
Antigravity CLI 프롬프트에서 플러그인이 활성 상태인지 확인합니다. /mcp를 입력하여 구성된 도구와 플러그인을 나열합니다.
/mcp
출력에는 knowledge-catalog가 사용 가능한 도구와 함께 활성 플러그인으로 표시됩니다.
MCP Servers ... > ✓ knowledge-catalog Tools: search_entries, lookup_context, lookup_entry
데이터 컨텍스트 확인 시나리오 실행
이제 데이터 컨텍스트가 실제로 어떻게 작동하는지 살펴보겠습니다. 이러한 프롬프트를 Antigravity CLI 세션에 하나씩 붙여넣습니다.
시나리오 1: 인증된 골드 등급 데이터 검색
Antigravity CLI가 중요한 이사회 회의를 위해 가장 신뢰할 수 있는 데이터를 찾을 수 있는지 확인해 보세요.
We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?
CLI는 원시 데이터를 건너뛰고 fin_monthly_closing_internal를 찾아야 합니다. 이는 '최종' 및 '기밀' 데이터에 대한 요청을 이전에 적용한 GOLD_CRITICAL 및 INTERNAL_ONLY 태그와 일치시켜 수행합니다.
시나리오 2: 외부에서 승인된 데이터로 검색 제한
외부로 데이터를 공유한다고 가정해 보겠습니다. CLI에서 내부 비밀이 유출되지 않도록 하려고 합니다.
I need to share our quarterly financial summary with an external consulting firm. It is critical that we do not leak any raw or internal metrics. Which dataset is officially scrubbed and explicitly approved for external sharing?
내부 테이블에 가장 자세한 정보가 있더라도 CLI는 이를 우회해야 합니다. EXTERNAL_READY로 태그된 유일한 테이블이므로 fin_quarterly_public_report를 가리켜야 합니다.
시나리오 3: 실시간 스트리밍 데이터 검색
데이터 과학자는 절대적으로 최신 정보가 필요한 경우가 많습니다. Antigravity CLI가 일일 배치와 라이브 스트림의 차이를 이해하는지 확인해 보세요.
My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?
CLI에서 mkt_realtime_campaign_performance를 찾아야 합니다. 메타데이터에서 REALTIME_STREAMING 업데이트 빈도를 식별합니다.
시나리오 4: 인증되지 않은 샌드박스 데이터 살펴보기
때로는 '충분히 좋은 것'이 '완벽한 것'보다 낫습니다. Antigravity CLI가 실험용 ML 작업의 원시 샌드박스 데이터를 찾을 수 있는지 확인합니다.
I'm just playing around with some new ML models and need a lot of raw data. It doesn't need to be perfect, just a sandbox environment.
CLI에서 tmp_data_dump_v2_final_real를 찾아야 합니다. BRONZE_ADHOC 등급과 일치하고 is_certified: false로 명시적으로 표시되어 있으므로 올바른 선택이라는 것을 알 수 있습니다.
테스트가 완료되면 CLI 세션을 종료할 수 있습니다.
/quit
삭제
반복 청구를 방지하려면 다음 단계를 따르세요.
Antigravity CLI 세션에 있는 경우
Ctrl+C를 두 번 누르거나/quit를 입력하여 세션을 종료합니다.정리 스크립트를 실행하여 이 튜토리얼에서 만든 BigQuery 테이블, 데이터 세트, Knowledge Catalog 관점 유형을 삭제합니다.
chmod +x ./cleanup_data_lake.sh ./cleanup_data_lake.sh서비스 플러그인을 제거하고 로컬 데모 파일을 삭제합니다.
agy plugin uninstall dataplex cd ~ rm -rf ~/devrel-demos
다음 단계
- 다른 Knowledge Catalog 사용 사례 사용해 보기