Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Gemini CLI 에이전트를 사용하여 데이터 컨텍스트 테스트

AI 에이전트는 추론할 수 있지만 특정 회사에 대한 지식은 전혀 없습니다. 에이전트에게 '1분기 수익이 얼마야?'라고 묻는다고 가정해 보겠습니다. 안내 없이 에이전트는 공식 보고서부터 정리되지 않은 테스트 데이터까지 데이터베이스에 있는 수십 개의 '수익' 테이블 중에서 선택할 수 있습니다. 에이전트가 이름이 가장 유사한 테이블을 선택하면 검증되지 않은 소스를 기반으로 설득력 있는 잘못된 답변을 반환할 수 있습니다.

이러한 맥락 문제를 해결하는 방법은 메타데이터 보강입니다. 이 튜토리얼에서는 이 컨텍스트를 제공하는 측면을 설정하고 Gemini CLI를 사용하여 데이터 컨텍스트를 테스트하고 에이전트가 신뢰할 수 있는 인증된 데이터를 기반으로 답변을 정확하게 제공할 수 있는지 확인합니다.

목표

테스트를 위해 실제와 유사한 데이터 레이크를 만듭니다.
Knowledge Catalog 측면을 사용하여 '골드' 데이터에 라벨을 지정하고 테스트 데이터와 구분합니다.
Gemini CLI를 사용하여 로컬에서 데이터 컨텍스트를 테스트합니다.

시작하기 전에

시작하기 전에 다음 사항을 확인하세요.

이 튜토리얼에 사용할 Google Cloud 프로젝트를 선택합니다.
프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

이 튜토리얼을 완료하려면 BigQuery, Knowledge Catalog, Terraform에 대한 기본적인 이해도 필요합니다.

개발 환경 준비

이 튜토리얼에서는 클라우드에서 실행되는 명령줄 환경인 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 \
  bigqueryunified.googleapis.com \
  cloudaicompanion.googleapis.com \
  cloudbuild.googleapis.com \
  cloudresourcemanager.googleapis.com \
  datacatalog.googleapis.com \
  run.googleapis.com

Google 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

데이터 레이크 빌드

현실적인 결과를 얻으려면 공식 데이터와 신뢰할 수 없는 지저분한 데이터를 혼합해야 합니다. Terraform과 튜토리얼 저장소의 사전 구성된 Terraform 구성 파일을 사용하여 빠르게 설정합니다.

Terraform 구성은 다음 두 가지 작업을 처리합니다.

finance_mart.fin_monthly_closing_internal 및 analyst_sandbox.tmp_data_dump_v2_final_real을 포함한 Knowledge Catalog 측면 유형 (메타데이터 템플릿), BigQuery 데이터 세트, 테이블을 설정합니다.
테이블에 샘플 데이터를 로드합니다.

terraform 디렉터리를 열고 초기화합니다.
```
cd terraform
terraform init
```

구성을 적용합니다. 최대 1분 정도 걸릴 수 있습니다.

terraform apply -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

이제 관리되지 않는 데이터 레이크가 생성되었습니다. AI 에이전트에게는 데이터 레이크의 테이블이 열이 있는 객체일 뿐이므로 정확히 동일하게 보입니다. 이 문제를 해결하려면 다음 단계에서 거버넌스를 적용해야 합니다.

거버넌스 적용

이 부분이 설정에서 가장 중요합니다. 현재 두 테이블은 AI 에이전트에게 동일하게 표시됩니다. 이를 구분하려면 에이전트에 필요한 컨텍스트를 제공하는 인증된 메타데이터 라벨과 같은 관점을 적용합니다. 이 섹션에서는 메타데이터를 생성하는 스크립트와 테이블에 적용하는 스크립트, 이렇게 두 개의 스크립트를 사용합니다.

거버넌스 페이로드 생성

Terraform에서 이미 관점 유형을 설정했으므로 이제 관점 유형을 채울 데이터를 생성해야 합니다.

./generate_payloads.sh 스크립트를 실행하여 aspect_payloads/ 디렉터리를 만듭니다. 디렉터리에는 다양한 거버넌스 시나리오를 정의하는 네 개의 YAML 파일이 포함되어 있으며, 다음 단계에서 이를 적용합니다.

튜토리얼 디렉터리의 루트로 다시 이동하여 ./generate_payloads.sh 스크립트를 실행합니다.

cd ..
chmod +x ./generate_payloads.sh
./generate_payloads.sh

관점 적용

apply_governance.sh 스크립트를 실행하기 전에 테이블에 연결될 데이터를 살펴보세요. 다음 명령어를 실행하여 내부 재무 데이터에 정의된 메타데이터를 확인합니다.
```
cat aspect_payloads/fin_internal.yaml
```
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
```
이렇게 하면 데이터가 is_certified: true로 명시적으로 표시되고 GOLD_CRITICAL 등급이 할당됩니다. 이렇게 하면 AI 에이전트가 따라야 할 명확하고 구조화된 규칙이 제공됩니다.
apply_governance.sh 스크립트를 실행합니다. 이 스크립트는 BigQuery 테이블을 반복하고 gcloud CLI를 사용하여 YAML 페이로드의 메타데이터를 각 테이블에 '스탬프'합니다.
```
chmod +x ./apply_governance.sh
./apply_governance.sh
```

메타데이터 확인

계속하기 전에 스크립트가 측면을 올바르게 적용했는지 확인하세요.

Google Cloud 콘솔에서 Knowledge Catalog 페이지를 엽니다. 상단의 검색창을 사용해 찾을 수 있습니다.
fin_monthly_closing_internal을 검색합니다. 결과에서 테이블 이름을 선택하여 세부정보 페이지를 엽니다.
선택적 태그 및 관점 섹션에서 official-data-product-spec 관점을 찾습니다. 값이 적용한 '골드 내부' 시나리오와 일치하는지 확인합니다.

이제 메타데이터를 사용하여 이러한 테이블을 구분하고 AI 에이전트가 동일한 작업을 수행할 수 있는 방법을 제공했습니다.

Gemini CLI로 데이터 컨텍스트 테스트하기

전체 웹 애플리케이션을 빌드하기 전에 모델 컨텍스트 프로토콜 (MCP) 환경을 사용하여 거버넌스 로직을 로컬에서 테스트할 수 있습니다. 이 설정에서 Gemini CLI는 클라이언트 (사용자가 대화하는 인터페이스)로 작동하고 Knowledge Catalog 확장 프로그램은 로컬 서버로 작동합니다.

Knowledge Catalog 확장 프로그램 설치

Cloud Shell에서 Knowledge Catalog 확장 프로그램을 설치합니다.

export DATAPLEX_PROJECT="${PROJECT_ID}"

gemini extensions install https://github.com/gemini-cli-extensions/dataplex

규칙 정의

GEMINI.md 구성 파일에는 '안전한 데이터가 필요해'와 같은 선언적 규칙을 올바른 거버넌스 라벨이 있는 테이블만 반환하는 정확한 검색으로 변환하는 로직이 있습니다.

현재 구성 파일은 템플릿일 뿐입니다. CLI를 실행할 때 관리 대상 데이터를 올바르게 타겟팅할 수 있도록 규칙에 특정 Google Cloud 프로젝트 ID를 추가해야 합니다.

구성 파일에 PROJECT_ID을 추가합니다.

envsubst < GEMINI.md > GEMINI.md.tmp && mv GEMINI.md.tmp GEMINI.md

변경사항을 확인하고 데이터 컨텍스트가 작동하는 방식을 이해하려면 GEMINI.md 파일을 간단히 살펴보세요.
```
cat GEMINI.md
```
파일이 규칙을 1단계와 2단계로 분할합니다. 이렇게 하면 엄격한 작업 순서가 적용됩니다. 에이전트는 데이터 자체를 처리하기 전에 (2단계) 먼저 올바른 거버넌스 라벨을 찾아야 합니다 (1단계). 이 '검색 우선' 로직은 에이전트가 테이블 이름을 추측하거나 검증되지 않은 소스에서 대답을 환각하는 것을 방지합니다.

2단계에 실제 Google Cloud 프로젝트 ID가 포함되어 있는지 확인합니다. 이 정보가 올바르지 않으면 상담사가 데이터를 어디에서 찾아야 하는지 알 수 없습니다.

Gemini CLI 시작 및 시나리오 테스트

새 Gemini 세션을 시작합니다. 프로젝트 폴더에 있으므로 CLI가 로컬 GEMINI.md를 시스템 컨텍스트로 자동 감지하고 로드합니다.

gemini

설치 확인

지식 카탈로그 확장 프로그램이 활성 상태인지 확인합니다. dataplex이 구성된 MCP 서버 도구 목록에 표시됩니다.

/mcp desc

사용해 보기

이제 데이터 컨텍스트가 실제로 작동하는지 확인해 보겠습니다. 이 프롬프트를 CLI에 하나씩 붙여넣습니다.

시나리오 1: '골드' 표준 데이터 찾기

Gemini 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: 실시간 운영 요구사항

데이터 과학자는 최신 정보가 필요한 경우가 많습니다. Gemini 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: 샌드박스 탐색

때로는 '완벽'보다 '적당'이 더 나을 수 있습니다. Gemini 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

삭제

반복 청구를 방지하려면 다음 단계를 따르세요.

Terraform 리소스를 폐기합니다.

cd ~/devrel-demos/data-analytics/governance-context/terraform
terraform destroy -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

Knowledge Catalog 확장 프로그램을 제거하고 로컬 데모 파일을 삭제합니다.
```
gemini extensions uninstall dataplex
cd ~
rm -rf ~/devrel-demos
```

결론

탄탄한 데이터 기반을 구축하고, 메타데이터를 사용하여 엄격한 컨텍스트를 적용하고, Gemini CLI를 사용하여 모든 것이 로컬에서 작동하는지 확인했습니다.

다음 단계

다른 Knowledge Catalog 사용 사례를 사용해 보세요.