2026년 4월 10일부터 Dataplex Universal Catalog가 Knowledge Catalog로 변경되었습니다. API, 클라이언트 라이브러리, CLI, IAM 이름은 변경되지 않습니다. 자세한 내용은 Google Cloud Knowledge Catalog 소개를 참조하세요.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

메타데이터를 보강하는 에이전트 빌드

Knowledge Catalog (이전 명칭: Dataplex Universal Catalog)는 조직 전체의 데이터 애셋에 대한 메타데이터를 관리합니다. 이 메타데이터는 에이전트가 사용자 질문에 답변하는 데 필요한 데이터를 검색, 이해, 쿼리하는 데 사용하는 컨텍스트를 제공합니다.

Knowledge Catalog는 리소스를 자동으로 관리하고, 기술 스키마를 추적하고, 설명과 데이터 프로필을 생성하지만, 중요한 비즈니스 컨텍스트는 다음과 같은 다른 위치에 있는 경우가 많습니다.

내부 문서 및 위키
코드 저장소
Google Chat, Slack과 같은 커뮤니케이션 채널

AI 에이전트를 빌드하여 이러한 소스에서 컨텍스트를 추출하고 대규모로 메타데이터를 지속적으로 보강할 수 있습니다. 이 튜토리얼에서는 knowledge-catalog 저장소의 샘플 코드를 사용하여 다음을 수행하는 에이전트를 빌드하는 방법을 보여줍니다.

컨텍스트 추출: 기술 자료, 문서, 코드 또는 채팅에서 비즈니스 컨텍스트를 추출하여 기술 메타데이터를 보강합니다.
문서 생성: 추출된 컨텍스트 및 기타 정보 소스를 기반으로 BigQuery 테이블에 대한 문서를 생성합니다.
검색 및 탐색 개선: 생성된 문서를 Knowledge Catalog에 게시하여 검색을 통해 항목을 더 쉽게 찾고 이해할 수 있도록 합니다.

시작하기 전에

Knowledge Catalog 보강 에이전트를 실행하려면 다음 요구사항을 충족해야 합니다.

필요한 역할

보강 에이전트를 사용하는 데 필요한 권한을 얻으려면 관리자에게 Google Cloud 프로젝트 iam.gserviceaccount.com에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

샘플 BigQuery 리소스 관리: BigQuery 데이터 편집자 (roles/bigquery.dataEditor)
카탈로그 메타데이터 검색: Dataplex 뷰어 (roles/dataplex.viewer)
카탈로그 메타데이터 관리: Dataplex 카탈로그 편집자 (roles/dataplex.catalogEditor)
Vertex AI 기능 (Gemini LLM API)에 액세스: Vertex AI 사용자 (roles/aiplatform.user)
서비스 API 사용: 서비스 사용량 소비자 (roles/serviceusage.serviceUsageConsumer)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이러한 사전 정의된 역할에는 보강 에이전트를 사용하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

보강 에이전트를 사용하려면 다음 권한이 필요합니다.

bigquery.projects.get/createDatasets
dataplex.projects.search
dataplex.entryGroups.get/updateEntries
aiplatform.endpoints.predict
serviceusage.services.use

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

API 사용 설정

Knowledge Catalog 보강 에이전트를 사용하려면 프로젝트에서 다음 API를 사용 설정해야 합니다.

BigQuery API
Dataplex API
Vertex AI API
Service Usage API

API 사용 설정에 필요한 역할

API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할 부여 방법 알아보기

API 사용 설정

종속 항목 설치

샘플을 실행하려면 다음 Python 패키지와 도구가 필요합니다.

google-adk (에이전트 개발 키트 (ADK))
google-cloud-dataplex Knowledge Catalog Python 클라이언트
google-auth에서 애플리케이션 기본 사용자 인증 정보를 관리합니다.
mcp[cli]: 샘플 MCP 서버 빌드
gcloud를 인증 및 구성에 사용합니다. Google Cloud CLI를 설치하려면 Google Cloud SDK 문서를 참조하세요.

환경 설정

gcloud를 구성하고 로그인합니다.
```
gcloud auth application-default login
gcloud config set core/project PROJECT_ID
```
다음을 바꿉니다.
- PROJECT_ID를 프로젝트 ID로 바꿉니다.

knowledge-catalog 저장소를 클론하고 샘플 소스 디렉터리로 이동합니다.

git clone https://github.com/GoogleCloudPlatform/knowledge-catalog.git
cd knowledge-catalog/samples/enrichment/src

종속 항목을 설치하려면 Python 가상 환경과 필요한 환경 변수를 설정하는 제공된 스크립트를 사용합니다.
```
source env.sh --install
```
클라우드 프로젝트의 us 리전에 kc_sample_analytics라는 샘플 BigQuery 데이터 세트를 만들려면 create_data.py 스크립트를 실행합니다.
```
python3 ../sample/data/create_data.py
```
샘플에는 sample/docs 디렉터리에 있는 여러 문서도 포함되어 있습니다. 이러한 문서는 로컬 기술 자료를 형성합니다. 보강 에이전트는 이 기술 자료를 사용하여 정보를 추출하고 문서를 생성합니다.

메타데이터 다운로드

먼저 다운로드 도구를 실행하여 BigQuery 데이터 세트 및 테이블의 Knowledge Catalog에서 메타데이터 스냅샷을 추출합니다. 이렇게 하면 로컬 메타데이터 아티팩트가 생성됩니다.

--dir 인수는 메타데이터 파일이 작성되는 디렉터리를 지정합니다.

python3 -m enrichment.download \
  --dir ../sample/metadata.initial \
  --dataset ${KC_ENRICH_SAMPLE_PROJECT}.kc_sample_analytics

스크립트는 <project_id>.<dataset_id>.<table_id>.md 이름 지정 규칙을 사용하여 sample/metadata 디렉터리에 테이블당 하나의 마크다운 파일을 만듭니다.

메타데이터 보강

로컬 마크다운 파일을 만든 후 보강 에이전트를 실행합니다. 에이전트는 각 파일을 반복하고 표와 관련된 정보를 찾고 발견 사항을 인용과 함께 요약하여 업데이트된 마크다운 파일을 생성합니다.

--dir: 로컬 메타데이터 파일이 포함된 디렉터리를 지정합니다.
--output-dir: 업데이트된 메타데이터 파일의 대상 디렉터리를 지정합니다.
--config-dir: 에이전트 지침, MCP 도구, 기술이 포함된 디렉터리를 지정합니다.

python3 -m enrichment.enrich \
  --dir ../sample/metadata.initial \
  --output-dir ../sample/metadata.new \
  --config-dir ../sample/config

메타데이터 검토

보강된 메타데이터 파일에는 에이전트가 생성한 문서가 포함됩니다. 변경사항을 Knowledge Catalog에 게시하기 전에 필요에 따라 파일을 검토하고 수정합니다.

git diff --no-index ../sample/metadata.initial ../sample/metadata.new

메타데이터 게시

게시 도구를 실행하여 보강된 메타데이터를 Knowledge Catalog에 배포합니다.

python3 -m src.enrichment.publish --dir ../sample/metadata.new

데이터에 맞게 맞춤설정

이전 단계에서는 --config-dir 인수를 사용하여 에이전트가 구성에 ../sample/config 디렉터리를 가리키도록 했습니다. 이를 통해 에이전트는 정보를 찾을 위치와 다양한 소스와 상호작용하는 방법을 알 수 있습니다.

샘플에는 에이전트가 로컬 MCP 서버를 사용하여 로컬 기술 자료 (sample/docs)의 파일에 액세스하도록 지시하는 기본 구성이 포함되어 있습니다. 이 워크플로를 환경에 적용하려면 이러한 구성 파일을 맞춤설정하여 에이전트를 내부 위키, 코드 저장소, Google Drive 또는 기타 시스템에 연결하면 됩니다.

sample/config/ 디렉터리에는 다음 파일이 포함됩니다.

sample/config/
├─ instructions.md
├─ mcp.json
└─ skills/
    └─ kb-search/
        └─ SKILL.md

instructions.md: 특정 기술 자료를 검색하도록 지시하는 등 조직과 관련된 세부정보로 에이전트의 기본 안내를 보강합니다.
mcp.json: 에이전트가 로컬 디렉터리에서 파일을 읽는 도구와 같은 정보 소스의 도구에 액세스하는 데 사용할 수 있는 MCP 서버를 구성합니다.
SKILL.md: 에이전트가 특정 도구를 사용하여 정보 소스와 상호작용하는 방법을 설명합니다. 예를 들어 list_contents, read_file, search_content를 사용하여 로컬 문서에서 정보를 찾습니다.

샘플 Knowledge Catalog 코드 살펴보기

보강 흐름 섹션의 download 및 publish 도구는 Knowledge Catalog API를 사용하여 메타데이터를 읽고 씁니다.

이 섹션에서는 이러한 API의 작동 방식을 설명하므로 자체 통합에 맞게 샘플을 조정할 수 있습니다.

메타데이터 검색 및 가져오기

이 샘플은 다음 API를 사용하여 메타데이터를 검색하고 가져옵니다.

SearchEntries: 데이터 세트의 항목 및 위치 메타데이터를 검색합니다.
ListEntries: 카탈로그 EntryGroup 내의 BigQuery 테이블을 열거합니다.
GetEntry: 각 BigQuery 테이블의 특정 메타데이터를 가져옵니다.

다음 코드는 데이터 세트를 검색하여 항목 그룹을 찾고, 포함된 모든 테이블을 나열하고, 특정 메타데이터를 검색하는 방법을 보여줍니다.

import google.cloud.dataplex_v1 as dataplex

BIGQUERY_TABLE_TYPE = "projects/dataplex-types/locations/global/entryTypes/bigquery-table"
OVERVIEW_ASPECT_TYPE = "projects/dataplex-types/locations/global/aspectTypes/overview"

catalog = dataplex.CatalogServiceClient()

dataset_reference = '...'   # project_id.dataset_id
project_id, dataset_id = dataset_reference.split('.')

# 1. Search for dataset to determine its location
search_response = catalog.search_entries(
    request=dataplex.SearchEntriesRequest(
        name=f"projects/{project_id}/locations/global",
        query=f"type=dataset name={dataset_id}",
        page_size=1
    )
)
dataset_entry = search_response.results[0].dataplex_entry
location_id = dataset_entry.entry_source.location

# 2. List resources in the underlying group
entry_group_name = f"projects/{project_id}/locations/{location_id}/entryGroups/@bigquery"
entry_filter = f'parent_entry="{dataset_entry.name}"'
list_response = catalog.list_entries(
    request=dataplex.ListEntriesRequest(
        parent=entry_group_name,
        entry_filter=entry_filter,
    )
)

# 3. Retrieve metadata for each table in the list
for table_entry in list_response.entries:
    entry = catalog.get_entry(
        request=dataplex.GetEntryRequest(
            name=table_entry.name,
            view="CUSTOM",
            aspect_types=[OVERVIEW_ASPECT_TYPE]
        )
    )

테이블 메타데이터 업데이트

다음 코드는 생성된 문서를 테이블의 개요 관점에 게시하고 메타데이터를 업데이트하는 방법을 보여줍니다.

import google.cloud.dataplex_v1 as dataplex
import google.protobuf.field_mask_pb2 as field_mask_pb2
import google.protobuf.json_format as jsonpb

OVERVIEW_ASPECT_TYPE = "projects/dataplex-types/locations/global/aspectTypes/overview"
OVERVIEW_ASPECT_KEY = "dataplex-types.global.overview"

catalog = dataplex.CatalogServiceClient()

table_reference = "..."    # project_id.dataset_id.table_id
project_id, dataset_id, table_id = table_reference.split('.')

entry_data = {
    "name": f"bigquery.googleapis.com/projects/{project_id}/datasets/{dataset_id}/tables/{table_id}",
    "aspects": {
        OVERVIEW_ASPECT_KEY: {
            "aspectType": OVERVIEW_ASPECT_TYPE,
            "data": {
                "content": "...", # content parsed from local markdown file
                "contentType": "MARKDOWN"
            }
        }
    }
}

entry = dataplex.Entry()
jsonpb.ParseDict(entry_data, entry._pb)

catalog.update_entry(
    request=dataplex.UpdateEntryRequest(
        entry=entry,
        update_mask=field_mask_pb2.FieldMask(paths=["aspects"]),
        aspect_keys=[OVERVIEW_ASPECT_KEY],
    )
)

다음 단계

메타데이터 작업에 대해 자세히 알아보세요.
Antigravity CLI를 사용하여 데이터 컨텍스트를 테스트합니다.
관점 관리 및 메타데이터 보강 알아보기
Python용 Knowledge Catalog 클라이언트 라이브러리에서 사용할 수 있는 다른 클래스와 메서드를 살펴봅니다.
다른 Knowledge Catalog 사용 사례 사용해 보기

메타데이터를 보강하는 에이전트 빌드 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

필요한 역할

필수 권한

API 사용 설정

종속 항목 설치

환경 설정

메타데이터 다운로드

메타데이터 보강

메타데이터 검토

메타데이터 게시

데이터에 맞게 맞춤설정

샘플 Knowledge Catalog 코드 살펴보기

메타데이터 검색 및 가져오기

테이블 메타데이터 업데이트

다음 단계

메타데이터를 보강하는 에이전트 빌드