1. 소개
생성형 AI 모델은 강력한 추론 기능을 갖추고 있지만 기관 컨텍스트가 부족합니다. 경영진이 AI 에이전트에게 '1분기 수익이 얼마야?'라고 물으면 에이전트는 데이터 레이크에서 '수익'이라는 이름의 표를 수십 개 찾을 수 있습니다. 엄격한 재무 보고서도 있고, 실시간 마케팅 추정치도 있으며, 지원 중단된 샌드박스도 많을 것입니다.
명시적 그라운딩이 없으면 AI 에이전트가 단순한 이름 유사성을 기반으로 테이블을 선택하므로 검증되지 않은 데이터에서 파생된 '확실히 틀린' 대답이 나올 수 있습니다.
이 Codelab은 거버넌스 인식 생성형 AI 에이전트를 빌드하는 방법을 알아보는 2부작 시리즈의 일부입니다.
이 첫 번째 파트에서는 데이터 기반을 구축합니다. BigQuery에서 현실적이고 '지저분한' 데이터 레이크를 설정하고, 엄격한 메타데이터 태그 (Dataplex 측면)를 적용하여 유효한 데이터를 노이즈와 구분하고, Gemini CLI를 사용하여 LLM이 거버넌스 규칙을 엄격하게 따르는지 로컬로 테스트합니다.
(모델 컨텍스트 프로토콜 (MCP)과 Cloud Run을 사용하여 이 로컬 프로토타입을 안전한 엔터프라이즈급 웹 애플리케이션에 배포하는 방법을 다루는 이 시리즈의 두 번째 부분을 읽어보세요. 👉 2부 읽기)
기본 요건
- 결제가 사용 설정된 Google Cloud 프로젝트.
- BigQuery, Dataplex 범용 카탈로그, Terraform에 대한 기본적인 이해와 숙지
- Google Cloud Shell에 액세스할 수 있습니다.
학습할 내용
- Terraform을 사용하여 현실적인 다중 계층 데이터 레이크를 배포합니다.
- Dataplex에서 엄격한 메타데이터 템플릿 (관점 유형)을 설계하여 공식 데이터 제품과 원시 샌드박스 테이블을 구분합니다.
- 애플리케이션 코드를 작성하기 전에 Gemini CLI를 사용하여 거버넌스 규칙을 로컬로 확인합니다.
필요한 항목
- Google Cloud Shell 액세스
- Terraform (Cloud Shell에 사전 설치됨)
- Gemini CLI (Cloud Shell에 사전 설치됨)
주요 개념
- Dataplex Universal Catalog: 통합 메타데이터 관리 서비스입니다. 비즈니스 컨텍스트 (거버넌스)로 기술 메타데이터 (스키마)를 보강하는 데 사용됩니다.
- 관점 유형: 구조화된 메타데이터 템플릿입니다. 자유 텍스트 태그와 달리 측면은 강력한 타이핑을 적용 (열거형, 불리언)하므로 머신이 평가하기에 신뢰할 수 있습니다.
2. 설정 및 요건
Cloud Shell 시작
Google Cloud를 노트북에서 원격으로 실행할 수 있지만, 이 Codelab에서는 Cloud에서 실행되는 명령줄 환경인 Google Cloud Shell을 사용합니다.
Google Cloud Console의 오른쪽 상단 툴바에 있는 Cloud Shell 아이콘을 클릭합니다.
환경을 프로비저닝하고 연결하는 데 몇 분 정도 소요됩니다. 완료되면 다음과 같이 표시됩니다.
가상 머신에는 필요한 개발 도구가 모두 들어있습니다. 영구적인 5GB 홈 디렉터리를 제공하고 Google Cloud에서 실행되므로 네트워크 성능과 인증이 크게 개선됩니다. 이 Codelab의 모든 작업은 브라우저 내에서 수행할 수 있습니다. 아무것도 설치할 필요가 없습니다.
환경 초기화
Cloud Shell을 열고 프로젝트 변수를 설정하여 모든 명령어가 올바른 인프라를 타겟팅하도록 합니다.
export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"
API 사용 설정
다음 안내를 실행하려면 필요한 Google Cloud 서비스를 사용 설정하세요.
gcloud services enable \
artifactregistry.googleapis.com \
bigqueryunified.googleapis.com \
cloudaicompanion.googleapis.com \
cloudbuild.googleapis.com \
cloudresourcemanager.googleapis.com \
datacatalog.googleapis.com \
run.googleapis.com
저장소 클론
GitHub 저장소에서 인프라 코드와 자동화 스크립트를 가져옵니다. Cloud Shell에서 디스크 공간을 절약하기 위해 이 실습에 필요한 특정 폴더만 다운로드합니다.
# 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 we need for this lab
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context
'지저분한' 데이터 레이크 빌드
실제 데이터 환경은 깨끗한 경우가 거의 없습니다. 현실을 시뮬레이션하려면 '공식' 데이터 마트와 신뢰할 수 없는 '샌드박스' 테이블이 혼합되어야 합니다.
Terraform을 사용하여 이 환경을 배포합니다. 이 구성은 두 가지 작업을 처리합니다.
- 인프라: Dataplex 측면 유형과 BigQuery 데이터 세트/테이블을 만듭니다.
- 데이터 로드: 생성 직후 샘플 데이터로 테이블을 채우기 위해 BigQuery INSERT 작업을 실행합니다.
terraform디렉터리로 이동하여 초기화합니다.
cd terraform
terraform init
- 구성을 적용합니다. 최대 1분 정도 걸릴 수 있습니다.
terraform apply -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve
체크포인트: 이제 완전히 채워졌지만 거버넌스가 전혀 적용되지 않은 데이터 레이크가 있습니다. AI에게는 모든 표가 똑같아 보입니다.
3. 거버넌스 적용
이 단계가 중요한 엔지니어링 단계입니다. 현재 테이블 finance_mart.fin_monthly_closing_internal와 analyst_sandbox.tmp_data_dump_v2_final_real은 LLM에 동일하게 표시됩니다. 열이 있는 객체일 뿐입니다.
거버넌스 엔지니어는 이러한 테이블을 구분하기 위해 측면 (인증된 메타데이터 라벨)을 테이블에 연결해야 합니다. 실제 엔터프라이즈에서는 CI/CD 파이프라인을 통해 이 작업을 자동화합니다. 스크립트를 사용하여 자동화를 시뮬레이션합니다.
거버넌스 페이로드 생성
Dataplex Aspect 키는 전역적으로 고유해야 합니다 (프로젝트 ID가 접두사로 붙음). ./generate_payloads.sh 스크립트는 YAML 메타데이터 파일을 동적으로 생성합니다.
cd ..
chmod +x ./generate_payloads.sh
./generate_payloads.sh
출력:
이렇게 하면 거버넌스 시나리오 (Gold/Internal, Gold/Public, Silver/Realtime, Bronze/Sandbox)를 정의하는 YAML 파일 4개가 포함된 './aspect_payloads' 폴더가 생성됩니다.
CLI를 통해 측면 적용
스크립트를 실행하기 전에 프로세스를 명확히 하기 위해 실제로 적용하는 내용을 살펴보겠습니다. 다음 명령어를 실행하여 내부 금융 페이로드의 구조를 확인합니다.
cat aspect_payloads/fin_internal.yaml
다음과 같은 콘텐츠가 표시됩니다.
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
이 YAML은 is_certified: true 플래그를 설정하고 GOLD_CRITICAL 등급을 할당하는 등 비즈니스 컨텍스트를 명시적으로 정의합니다. 표 이름을 기반으로 추측하는 대신 평가할 명확하고 구조화된 규칙을 AI에 제공합니다.
이제 애플리케이션 스크립트를 실행합니다. 이렇게 하면 BigQuery 테이블을 반복하고 gcloud dataplex entries update 명령어를 실행하여 이 고정 메타데이터를 연결합니다.
chmod +x ./apply_governance.sh
./apply_governance.sh
인증 (선택사항)
계속하기 전에 콘솔에서 메타데이터가 올바르게 적용되었는지 확인합니다.
- Google Cloud 콘솔에서 Dataplex Universal Catalog 페이지를 엽니다. 왼쪽 탐색 메뉴에 'Dataplex Universal Catalog'이 표시되지 않으면 Google Cloud 콘솔 창 상단의 검색창을 사용하여 Dataplex를 입력하고 '상위 결과' 또는 '제품 및 페이지' 아래의 결과를 선택합니다.
fin_monthly_closing_internal를 검색합니다. 결과에 BigQuery 테이블이 표시됩니다. 표 이름을 클릭하여 세부정보 페이지로 이동합니다.
- 표의 세부정보 페이지 하단에 있는 '선택적 태그 및 관점' 섹션을 확인합니다.
official-data-product-spec측면을 확인할 수 있습니다. 값이 적용한 '골드 내부' 시나리오와 일치하는지 확인합니다.
이제 기술적으로 동일한 BigQuery 테이블 (fin_monthly_closing_internal 및 tmp_data_dump_v2_final_real)이 머신 리더블 메타데이터에 의해 논리적으로 차별화되는 것을 확인했습니다.
4. 에이전트 구성 및 프로토타입
웹 애플리케이션을 빌드하기 전에 (2부에서 진행) 거버넌스 로직을 로컬에서 확인합니다. Dataplex 확장 프로그램을 설치하고 시스템 프롬프트를 구성해야 합니다.
확장 프로그램 설치
Cloud Shell에서 Dataplex 확장 프로그램을 설치합니다. 확인 및 설정 세부정보를 묻는 메시지가 표시됩니다.
export DATAPLEX_PROJECT="${PROJECT_ID}"
gemini extensions install https://github.com/gemini-cli-extensions/dataplex
(Y를 입력하여 설치를 수락하고 메시지가 표시되면 프로젝트 ID를 입력합니다).
정책 파일 정의
GEMINI.md 파일에는 추상적인 인간 규칙 (예: '안전한 데이터가 필요해')를 엄격한 기술 조회로 변환합니다.
이 파일은 현재 일반적입니다. 에이전트가 공개 인터넷이나 다른 컨텍스트에서 표를 환각하는 것을 방지하려면 검색할 Google Cloud 프로젝트를 정확히 알아야 합니다.
- 정책 파일에
PROJECT_ID을 삽입합니다.
envsubst < GEMINI.md > GEMINI.md.tmp && mv GEMINI.md.tmp GEMINI.md
- 파일을 검사하여 AI에 가르치는 알고리즘을 파악합니다.
cat GEMINI.md
이 파일에서 두 가지 사항을 확인하세요.
- 프로젝트 범위: 2단계를 확인하세요. projectid:
${PROJECT_ID}가 실제 프로젝트 ID(e.g., projectid:my-lab-project)로 대체되었는지 확인합니다. 이 변수를 대체하지 않으면 에이전트가 액세스할 수 있는 모든 프로젝트를 검색하여 잘못된 답변을 제공합니다. - 알고리즘: 1단계 / 2단계 논리를 확인하세요. 모델이 SQL을 추측하지 않도록 명시적으로 지시합니다. 먼저 올바른 태그 정의를 검색하고 (1단계) 그런 다음 데이터만 검색해야 합니다 (2단계).
에이전트 시작 및 시나리오 테스트
이번에는 거버넌스 정책을 시스템 컨텍스트로 로드하여 Gemini CLI 세션을 시작합니다.
gemini
참고: 여러 컨텍스트 파일이 로드될 수 있습니다 (예: GEMINI.md 등) 이는 정상적인 현상입니다. CLI는 이 프로젝트의 특정 규칙에 대한 로컬 GEMINI.md와 Dataplex 확장 프로그램 자체의 기본 안내를 로드합니다.
설치 확인
/mcp desc를 입력하여 Dataplex 확장 프로그램이 활성 상태인지 확인합니다. dataplex이 사용 가능한 도구가 있는 구성된 MCP 서버로 표시됩니다.
테스트 시나리오 (프로토타입 제작)
실행 중인 에이전트 세션에 다음 프롬프트를 하나씩 붙여넣어 규칙을 준수하는지 확인합니다.
- 시나리오 A (CFO의 데이터 인증):
"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?"
예상: 측면에서 GOLD_CRITICAL (정확함) 및 INTERNAL_ONLY (이사회 회의)와 의미적으로 일치하므로 fin_monthly_closing_internal를 쿼리합니다.
- 시나리오 B (공개):
"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?"
예상: 상담사는 월별 내부 표를 우회하고 fin_quarterly_public_report을 엄격하게 선택해야 합니다. EXTERNAL_READY 태그가 지정된 애셋은 이것뿐이기 때문입니다.
- 시나리오 C (운영 요구사항):
"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?"
예상: 에이전트는 REALTIME_STREAMING 업데이트 빈도를 식별하여 재무 데이터의 GOLD_CRITICAL 등급보다 우선시하므로 mkt_realtime_campaign_performance를 선택합니다.
- 시나리오 D (샌드박스 실험):
"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."
예상: 에이전트는 측면에서 BRONZE_ADHOC (원시 데이터) 및 is_certified: false (샌드박스 환경)과 의미적으로 일치하므로 tmp_data_dump_v2_final_real를 선택합니다.
(Gemini 세션을 종료하려면 /quit를 입력하세요.)
5. 축하합니다. 다음 단계
관리되는 데이터 기반을 성공적으로 구축하고 로컬 CLI 프로토타입을 사용하여 AI가 메타데이터 규칙을 엄격하게 따를 수 있음을 입증했습니다.
이제 체크포인트에 도달했습니다. 다음 단계를 선택하세요.
옵션 A: 지금 바로 2부로 계속하고 싶습니다.
모델 컨텍스트 프로토콜 (MCP)과 Cloud Run을 사용하여 이 로컬 프로토타입을 안전한 프로덕션 등급 웹 애플리케이션으로 전환할 준비가 되었다면 다음 단계를 따르세요.
옵션 B: 2부를 나중에 진행하거나 1부만 완료하고 싶습니다.
오늘 작업을 중단하고 클라우드 비용을 방지하려면 리소스를 정리해야 합니다.
걱정하지 마세요. 파트 2에서는 2분 만에 파트 1 환경을 완전히 다시 빌드하여 중단한 부분부터 바로 시작할 수 있는 '패스트 트랙 스크립트'를 제공합니다.
👉 정리 섹션으로 이동합니다.
6. 정리 (옵션 B만 해당)
여기서 멈추는 경우 요금이 청구되지 않도록 리소스를 삭제하세요.
데이터 레이크 삭제 (Terraform)
현재 Gemini CLI 환경에 있는 경우 Ctrl+C를 두 번 누르거나 /quit를 입력하여 세션을 종료합니다. 그런 다음 다음 명령어를 실행합니다.
cd ~/devrel-demos/data-analytics/governance-context/terraform
terraform destroy -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve
Gemini CLI 확장 프로그램 제거 및 로컬 파일 삭제
gemini extensions uninstall dataplex
cd ~
rm -rf ~/devrel-demos