데이터 애셋의 컨텍스트 가져오기

데이터를 둘러싼 컨텍스트는 AI 애플리케이션에 데이터 애셋에 대한 깊은 이해를 제공하여 LLM 생성 응답의 정확성과 관련성을 개선합니다.

lookupContext 메서드는 단일 API 요청을 사용하여 컨텍스트 격차를 해소하여 대화형 에이전트 워크플로에 최적화된 사전 형식화된 데이터 애셋 메타데이터 번들을 가져옵니다. 이 간결하고 LLM 지원 컨텍스트를 사용하여 에이전트가 데이터 애셋을 평가하고 사용하는 데 기반을 둘 수 있습니다.

Knowledge Catalog에 저장된 모든 데이터 애셋(예: BigQuery 테이블, 데이터 세트 또는 기타 항목)에 lookupContext 메서드를 사용할 수 있습니다.

lookupContext 메서드로 애셋의 컨텍스트를 가져오는 방법

  1. 에이전트는 Knowledge Catalog 시맨틱 검색을 사용하는 등 컨텍스트 검색과 관련이 있을 수 있는 데이터 애셋을 검색합니다.
  2. 에이전트는 lookupContext 메서드를 사용하여 특정 애셋의 컨텍스트를 가져오는 단일 API 호출 또는 MCP 도구 요청을 실행합니다.

  3. 이 메서드는 사전 형식화된 텍스트 블록이 포함된 응답을 반환합니다. 요청에 지정한 format 매개변수에 따라 문서는 YAML, XML 또는 JSON 형식일 수 있습니다.

    대답에는 다음 컨텍스트 요소가 포함됩니다.

    컨텍스트 요소 설명
    기술 메타데이터 BigQuery 파티션 및 클러스터링 전략과 같은 리소스 스키마 및 실제 구성
    운영 메타데이터 이전 쿼리 로그 및 데이터 통계를 기반으로 한 조인 및 기타 관계 자세한 내용은 데이터 관계 보기를 참고하세요.
    비즈니스 설명 관련 비즈니스 용어, 개요, 카탈로그 주석, 소스 시스템에서 캡처되고 Knowledge Catalog에서 자동 생성된 설명, 가이드라인

    참고: 데이터 애셋의 가이드라인 측면을 사용하여 상담사가 데이터 애셋을 검색, 검사 또는 사용할 때 유용한 추가 컨텍스트를 캡처할 수 있습니다.
    데이터 프로필 분포 통계, 고유 값 수, null 비율, 샘플 값
    데이터 품질 사전 정의된 규칙에 따라 자동 데이터 품질 검사 출력이 이루어집니다.
    관련 데이터 애셋에 관한 컨텍스트 용어집 용어 또는 자주 조인되는 테이블과 같은 기타 관련 애셋과 같은 관련 데이터 애셋에 관한 컨텍스트 관련 애셋에 대해 반환되는 컨텍스트에는 기본 애셋과 동일한 범위의 요소가 포함됩니다.

  4. 상담사는 이 응답을 사용하여 관련 애셋의 선택 또는 사용을 안내합니다.

시작하기 전에

lookupContext 메서드를 사용하기 전에 필요한 역할이 있고 필요한 API가 사용 설정되어 있는지 확인하세요.

필요한 역할

lookupContext 메서드를 호출하는 데 필요한 권한을 얻으려면 관리자에게 Google Cloud 프로젝트 iam.gserviceaccount.com에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

  • 항목, 항목 그룹, 용어집을 비롯한 카탈로그 리소스에 대한 읽기 액세스 권한: Dataplex 카탈로그 뷰어 (roles/dataplex.catalogViewer)

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

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

API 사용 설정

lookupContext 메서드를 사용하려면 프로젝트에서 다음 API를 사용 설정하세요.

  • Knowledge Catalog API

API 사용 설정에 필요한 역할

API를 사용 설정하려면 serviceusage.services.enable 권한이 포함된 서비스 사용량 관리자 IAM 역할(roles/serviceusage.serviceUsageAdmin)이 필요합니다. 역할 부여 방법 알아보기

API 사용 설정하기

데이터 애셋의 컨텍스트 가져오기

데이터 애셋의 컨텍스트를 가져오려면 Dataplex API를 사용하여 lookupContext 메서드에 직접 액세스하거나 Knowledge Catalog 원격 모델 컨텍스트 프로토콜 (MCP) 서버 또는 데이터베이스용 MCP 도구 상자를 사용합니다.

lookupContext 메서드는 권한을 기준으로 리소스를 필터링합니다. 대답에는 ID에 액세스하는 데 필요한 Identity and Access Management (IAM) 권한이 있는 애셋의 데이터만 포함됩니다. 요청된 리소스에 대한 권한이 없으면 메서드는 빈 응답을 반환합니다.

REST

데이터 애셋의 컨텍스트를 가져오려면 다음 요청을 전송하세요.

curl --request POST \
   'https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "resources": RESOURCES
  "options": OPTIONS
  }' \
--compressed

다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID
  • LOCATION: 애셋이 있는 리전 (예: us-central1)
  • RESOURCES: 컨텍스트를 가져올 항목 이름(최대 10개)입니다. projects/{project}/locations/{location}/entryGroups/{entryGroup}/entries/{entry} 형식으로 지정됩니다. 여러 리소스의 경우 API는 요청된 리소스 간의 관계(예: 자주 발생하는 스키마 조인)를 설정하고 컨텍스트에 관계 정보를 반환합니다.
  • OPTIONS: 컨텍스트를 정의할 수 있는 옵션입니다.
    • format은 환경설정 파일의 형식입니다. 예를 들면 yaml입니다.
    • context_budget은 대답이 제한되는 문자 수입니다. all_schema_fields 매개변수를 true로 설정하면 API는 context_budget 값과 관계없이 모든 스키마 필드를 반환합니다.

BigQuery 테이블의 컨텍스트를 가져오는 요청의 예는 다음과 같습니다.

curl --request POST \
'https://dataplex.googleapis.com/v1/projects/test-project/locations/us:lookupContext?key=[YOUR_API_KEY]' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "resources":
    ["projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/test-dataset/tables/test-table"],
    "options":
    {
      "format":"yaml",
      "context_budget":"4000"
    }
  }' \
--compressed

응답은 다음과 유사한 사전 형식의 텍스트 블록입니다.

{
"context": "resource: \"projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/sales_data/tables/orders\"\ntechnical_metadata:\n  schema:\n    - name: order_id\n      type: STRING\n      description: \"Primary key for the order.\"\n    - name: customer_id\n      type: STRING\n    - name: total_amount\n      type: NUMERIC\n  partitioning:\n    type: TIMESTAMP\n    field: order_date\nbusiness_descriptions:\n  overview: \"Historical record of all customer transactions.\"\n  related_terms:\n    - \"Revenue\"\n    - \"Sales Transactions\"\n  guidelines: \"Always filter by 'order_date' to optimize query costs due to partitioning.\"\ndata_profile:\n  columns:\n    - name: total_amount\n      null_ratio: 0.001\n      distinct_values: 52340\n      sample_values: [45.99, 120.00, 15.50]\ndata_quality:\n  summary:\n    - rule: \"positive_amounts\"\n      status: PASSED\n      description: \"Ensures total_amount is greater than zero.\"\noperational_metadata:\n  frequent_joins:\n    - table: \"projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/sales_data/tables/customers\"\n      join_key: \"customer_id\"\n"
}

Python

Python

이 샘플을 사용해 보기 전에 Knowledge Catalog 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 Knowledge Catalog Python API 참고 문서를 참고하세요.

Knowledge Catalog에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요. 

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import dataplex_v1


def sample_lookup_context():
    # Create a client
    client = dataplex_v1.CatalogServiceClient()

    # Initialize request argument(s)
    request = dataplex_v1.LookupContextRequest(
        name="name_value",
        resources=["resources_value1", "resources_value2"],
    )

    # Make the request
    response = client.lookup_context(request=request)

    # Handle the response
    print(response)

다음 예에서는 BigQuery 테이블의 컨텍스트를 가져오는 방법을 보여줍니다.

 from google.cloud import dataplex_v1

 # Initialize the client
 client = dataplex_v1.CatalogServiceClient()

 # Define the request with a seed resource
 request = dataplex_v1.LookupContextRequest(
     name="projects/test-project/locations/us",
     resources=["projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/test-dataset/tables/test-table"],
     options={"format": "yaml", "budget": "4000"}
 )

 # Retrieve the LLM-ready context
 response = client.lookup_context(request=request)
 context_yaml = response.context

 print(f"Retrieved Context: \n{context_yaml}")

lookupContext 메서드 관련 권장사항

lookupContext 메서드를 사용할 때 결과를 최적화하려면 다음 권장사항을 고려하세요.

  • context_budget 매개변수를 사용하여 선택한 출력 컨텍스트 길이를 요청합니다. lookupContext 메서드는 매개변수에 의해 규정된 한도 내에서 최대한 가까운 출력에 가장 관련성 높은 컨텍스트를 맞추는 것을 목표로 합니다.
  • resources 목록에는 최대 10개의 데이터 애셋을 나열할 수 있습니다. 예를 들어 resources 목록에 여러 테이블을 포함하면 API는 해당 테이블뿐만 아니라 테이블 간의 가능한 조인 경로에 대한 컨텍스트를 제공하므로 이러한 테이블을 함께 사용하는 방법에 관한 필요한 안내를 제공합니다.
  • LLM 또는 에이전트의 파싱 로직과 가장 잘 맞는 format 옵션(예: yaml 또는 json)을 사용하여 비용이 많이 드는 변환을 방지하세요.

다음 단계