보강 태스크의 기본 요건 구성

Knowledge Studio에서 보강 태스크를 만들려면 먼저 보안 아키텍처 및 대상 데이터 소스에 따라 여러 기본 인프라 구성요소를 구성해야 할 수 있습니다.

이 가이드에서는 고객 관리 서비스 계정, 서드 파티 인증 제공업체, Cloud Storage 버킷, Cloud Logging 뷰를 구성하는 방법을 설명합니다.

다음 표에서는 기본 요건 구성과 이를 구성해야 하는 시기를 설명합니다.

구성 기능 구성 시기
Google Cloud API 필수 항목입니다. 보강 워크플로를 실행하려면 기본 Google Cloud API를 사용 설정해야 합니다.
고객 관리형 서비스 계정 대상 데이터 세트에 대한 읽기 및 쓰기 액세스를 제한하려고 합니다.
사용자 Identity and Access Management (IAM) 역할 워크플로 관리자와 검토자에게 메타데이터를 생성하고 승인할 수 있는 권한을 부여해야 합니다.
서드 파티 인증 제공업체 서드 파티 지식 소스 (예: Microsoft SharePoint, Atlassian Confluence, GitHub)에 연결하는 경우
Cloud Storage 버킷 비정형 비즈니스 컨텍스트 (예: PDF, 마크다운, CSV)와 평가 데이터 세트를 수집합니다.
평가 데이터 세트 시드 쿼리와 벤치마크 데이터 세트를 제공하여 에이전트 정확성을 적극적으로 추적하려고 합니다.
자율 학습을 위한 에이전트 trace 보강 에이전트가 다운스트림 Gemini Enterprise 에이전트 상호작용을 자동으로 분석하도록 하려고 합니다.
데이터 프로파일링 및 데이터 인사이트 Recommended. 자주 사용하는 테이블에 대한 통계 프로필과 기준 AI 인사이트를 생성하여 보강 품질을 개선하려고 합니다.

시작하기 전에

  1. Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Dataplex, Data Lineage, BigQuery, Cloud Storage, and IAM Credentials APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Dataplex, Data Lineage, BigQuery, Cloud Storage, and IAM Credentials APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    8.

필수 API 세부정보

보강 태스크를 구성하고 실행하기 위해 사용 설정된 API는 다음 기능을 수행합니다.

API 이름 서비스 식별자 보강 워크플로의 목적
Dataplex API dataplex.googleapis.com 기본 컨트롤 플레인 API입니다. EnrichmentTask, EnrichmentRun, 컨텍스트 세트, 변경 요청, EnrichmentChatService를 관리합니다.
BigQuery API bigquery.googleapis.com 테이블 스키마 스캔, SQL 실행 기록 수집, BigQuery 에이전트 분석 trace 테이블 쿼리에 필요합니다.
Cloud Storage API storage.googleapis.com 평가 세트를 수집하고 평가 데이터 세트 샘플을 관리하는 데 필요합니다.
IAM Service Account Credentials API iamcredentials.googleapis.com 작업 중에 실행 에이전트를 안전하게 인증하고 단기 사용자 인증 정보 (SLC)를 부여하는 데 필요합니다.

고객 관리형 서비스 계정 구성

보강 작업은 고객 관리 서비스 계정을 사용하여 작업을 실행합니다. 이렇게 하면 대상 데이터 세트에 대한 읽기 및 쓰기 액세스를 제한할 수 있습니다.

  1. 서비스 계정을 만듭니다.

    서비스 계정을 만들려면 프로젝트 소유자 (roles/owner) 또는 편집자 (roles/editor)이거나 서비스 계정 관리자 역할(roles/iam.serviceAccountAdmin)이 있어야 합니다.

    전용 서비스 계정은 보강 작업을 격리하여 다른 워크로드에 영향을 주지 않고 이러한 작업에 필요한 특정 읽기 및 쓰기 권한만 부여할 수 있습니다.

    서비스 계정을 만드는 방법은 다음과 같습니다.

    Google Cloud CLI

    서비스 계정을 만들려면 gcloud iam service-accounts create 명령어를 사용합니다.

    아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

    • SERVICE_ACCOUNT_NAME: 서비스 계정의 이름입니다.

    다음 명령어를 실행합니다.

    Linux, macOS 또는 Cloud Shell

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
    --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" \
    --display-name="Knowledge Catalog enrichment agent SA"

    Windows(PowerShell)

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME `
    --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" `
    --display-name="Knowledge Catalog enrichment agent SA"

    Windows(cmd.exe)

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME ^
    --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" ^
    --display-name="Knowledge Catalog enrichment agent SA"

    REST

    요청 데이터를 사용하기 전에 다음을 바꿉니다.

    • SERVICE_ACCOUNT_NAME: 서비스 계정의 이름입니다.
    • TARGET_PROJECT_ID: Google Cloud 프로젝트 ID입니다.

    HTTP 메서드 및 URL:

    POST https://iam.googleapis.com/v1/projects/TARGET_PROJECT_ID/serviceAccounts

    JSON 요청 본문:

    {
   "accountId": "SERVICE_ACCOUNT_NAME",
   "serviceAccount": {
    "displayName": "Knowledge Catalog enrichment agent SA",
    "description": "Service Account for Dataplex Knowledge Catalog enrichment agent execution"
   }
  }

    요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

    성공 상태 코드(2xx)와 빈 응답을 받게 됩니다.

  2. 대상 범위의 실행 서비스 계정에 필요한 리소스 수준 IAM 역할을 부여합니다.

    • Dataplex 카탈로그 편집자 (roles/dataplex.catalogEditor) 및 Dataplex 카탈로그 뷰어 (roles/dataplex.catalogViewer): 에이전트가 카탈로그 메타데이터를 검사하고, 스테이징된 작업 항목을 만들고, 승인된 보강을 수동으로 게시할 수 있습니다.
    • (선택사항) Dataplex 워크플로 승인 담당자 (roles/dataplex.workflowApprover): 태스크에서 자동 게시를 사용 설정하는 경우에만 필요합니다. 에이전트가 자체 메타데이터 변경 요청을 자동으로 승인하고 게시할 수 있습니다.
    • BigQuery 데이터 뷰어 (roles/bigquery.dataViewer): 에이전트가 테이블 스키마, 열 메타데이터, 에이전트 분석 trace 테이블을 읽을 수 있습니다.

    참고: 다음 코드 샘플은 쉽게 설정할 수 있도록 프로젝트 수준에서 이러한 역할을 부여합니다. 프로덕션 시스템의 경우 특정 대상 데이터 세트의 리소스 수준에서 이러한 역할을 안전하게 부여하는 것이 좋습니다.

    이러한 표준 역할을 부여하려면 다음 단계를 따르세요.

    프로젝트에 IAM 정책 바인딩을 추가하려면 gcloud projects add-iam-policy-binding 명령어를 사용합니다.

    아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

    • SERVICE_ACCOUNT_NAME: 서비스 계정의 이름입니다.
    • TARGET_PROJECT_ID: Google Cloud 프로젝트 ID입니다.

    다음 명령어를 실행합니다.

    Linux, macOS 또는 Cloud Shell

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/bigquery.dataViewer"

    Windows(PowerShell)

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/bigquery.dataViewer"

    Windows(cmd.exe)

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/bigquery.dataViewer"

  3. 사용자에게 서비스 계정 사용자 역할 (roles/iam.serviceAccountUser)을 부여하여 서비스 계정을 가장할 수 있는 권한을 부여합니다.

    콘솔에서 보강 태스크를 만드는 사용자는 이 서비스 계정을 지정하고 태스크에 연결할 수 있도록 이 권한이 있어야 합니다.

    사용자에게 서비스 계정 사용자 역할을 부여하려면 다음 단계를 따르세요.

    서비스 계정에 IAM 정책 바인딩을 추가하려면 gcloud iam service-accounts add-iam-policy-binding 명령어를 사용합니다.

    아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

    • SERVICE_ACCOUNT_NAME: 서비스 계정의 이름입니다.
    • TARGET_PROJECT_ID: Google Cloud 프로젝트 ID입니다.
    • USER_EMAIL: 사용자의 이메일 주소입니다.

    다음 명령어를 실행합니다.

    Linux, macOS 또는 Cloud Shell

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com \
    --member="user:USER_EMAIL@domain.com" \
    --role="roles/iam.serviceAccountUser"

    Windows(PowerShell)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com `
    --member="user:USER_EMAIL@domain.com" `
    --role="roles/iam.serviceAccountUser"

    Windows(cmd.exe)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com ^
    --member="user:USER_EMAIL@domain.com" ^
    --role="roles/iam.serviceAccountUser"

  4. 내부 Knowledge Catalog 서비스 에이전트에 서비스 계정 토큰 서비스 계정 토큰 생성자 역할(roles/iam.serviceAccountTokenCreator)을 부여하여 이 서비스 계정을 가장할 수 있도록 허용합니다.

    이렇게 하면 기본 Knowledge Catalog 서비스가 사용자를 대신하여 백그라운드 보강 작업을 실행할 때 이 전용 서비스 계정의 ID와 제한된 권한을 가정할 수 있습니다.

    에이전트가 서비스 계정 ID를 사용하도록 승인하려면 다음 단계를 따르세요.

    서비스 계정에 IAM 정책 바인딩을 추가하려면 gcloud iam service-accounts add-iam-policy-binding 명령어를 사용합니다.

    아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

    • SERVICE_ACCOUNT_NAME: 서비스 계정의 이름입니다.
    • TARGET_PROJECT_ID: Google Cloud 프로젝트 ID입니다.
    • TARGET_PROJECT_NUMBER: Google Cloud 프로젝트 번호입니다.

    다음 명령어를 실행합니다.

    Linux, macOS 또는 Cloud Shell

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com \
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountTokenCreator"

    Windows(PowerShell)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com `
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" `
    --role="roles/iam.serviceAccountTokenCreator"

    Windows(cmd.exe)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com ^
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" ^
    --role="roles/iam.serviceAccountTokenCreator"

사용자에게 필수 IAM 역할 부여

팀에서 보강 워크플로를 관리하고 AI 생성 제안을 검토할 수 있도록 사용자에게 적절한 IAM 역할을 부여합니다. 이러한 역할을 부여하는 방법은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

태스크를 만들고 구성하고 모니터링하는 워크플로 관리자 (예: 데이터 관리 책임자)에게는 다음 역할이 필요합니다.

  • Dataplex DataScan 편집자 (roles/dataplex.dataScanEditor) 또는 Dataplex 편집자 (roles/dataplex.editor): 사용자가 보강 태스크를 만들고, 수정하고, 트리거하고, 취소할 수 있습니다.
  • 고객 관리형 서비스 계정에 대한 서비스 계정 사용자 (roles/iam.serviceAccountUser): 서비스 계정을 태스크의 실행 ID로 연결하는 데 필요합니다.

AI 생성 메타데이터 제안을 검사, 승인, 카탈로그에 게시하는 변경 검토자 (예: 도메인 소유자 또는 주제 전문가)에게는 다음 역할이 필요합니다.

  • Dataplex 카탈로그 편집자 (roles/dataplex.catalogEditor) 및 Dataplex 카탈로그 뷰어 (roles/dataplex.catalogViewer): 변경 요청을 열고, 제안서 차이를 나란히 검사하고, 설명을 인라인으로 수정하는 데 필요합니다.
  • Dataplex 워크플로 승인 담당자 (roles/dataplex.workflowApprover): 라이브 카탈로그에 대한 변경 요청을 승인하고 게시하는 데 필요합니다.
  • Dataplex DataScan 뷰어 (roles/dataplex.dataScanViewer) 또는 Dataplex 뷰어 (roles/dataplex.viewer): 제안별 신뢰도 점수, 테스트 실패 진단, 다운스트림 평가 스코어카드를 검토하는 데 필요합니다.

서드 파티 인증 제공업체 구성

보강 에이전트를 서드 파티 지식 소스 (예: Microsoft SharePoint, Atlassian Confluence, GitHub)에 연결할 때는 Google Cloud의 에이전트 ID 서비스를 사용하여 인증 제공업체를 구성해야 합니다.

에이전트 ID는 프로젝트 내에서 서드 파티 토큰을 암호화하는 보안 사용자 인증 정보 관리자 역할을 하므로 작업 실행 중에 사람 운영자가 원시 클라이언트 보안 비밀번호를 처리할 필요가 없습니다.

필수 토큰을 생성하고 특정 외부 플랫폼의 인증 제공업체를 구성하는 방법에 대한 단계별 안내는 보강 작업을 위한 외부 커넥터 구성을 참조하세요.

인증 제공업체의 IAM 권한 설정

활성 실행 중에 보강 에이전트가 인증 제공업체 사용자 인증 정보를 동적으로 안전하게 검색할 수 있도록 하려면 관리형 Knowledge Catalog 서비스 에이전트 (service-<var>PROJECT_NUMBER</var>@gcp-sa-dataplex.iam.gserviceaccount.com)에 에이전트 ID 관리자(roles/agentidentity.admin) 역할을 부여해야 합니다. 이 역할은 인증 제공업체 리소스 수준 또는 프로젝트 수준에서 부여할 수 있습니다.

또한Google Cloud 콘솔에서 태스크에 인증 제공업체를 연결하는 사용자에게는 인증 제공업체에 대한 agentidentity.authProviders.get 권한(에이전트 ID 뷰어 (roles/agentidentity.viewer)에 포함됨)이 있어야 합니다.

Cloud Storage 버킷 준비

Cloud Storage는 지식 보강 워크플로를 위한 기본 파일 기반 스테이징, 컨텍스트 수집, 아티팩트 내보내기 레이어 역할을 합니다.

하나 이상의 입력 버킷에서 파일을 수집하여 엔터프라이즈 도메인 지식을 기반으로 추론하도록 에이전트를 구성할 수 있습니다. 지원되는 컨텍스트 유형은 다음과 같습니다.

  • 도메인 문서 및 데이터 사전: 테이블 정의, 비즈니스 용어집, 표준 운영 절차 (SOP), 데이터 파이프라인 아키텍처 또는 열 이름 지정 가이드라인이 포함된 마크다운, 일반 텍스트, PDF, HTML 또는 CSV 파일

  • 평가 데이터 세트: 시드 쿼리와 홀드아웃 검증 쿼리 세트를 저장하는 JSONL 또는 CSV 파일입니다. 자세한 내용은 평가 데이터 세트 형식 지정을 참조하세요.

  • 참조 SQL 및 변환 스크립트: 테이블 조인 패턴 및 비즈니스 계산에 관한 문맥 시그널을 제공하는 저장된 SQL 스크립트, dbt 모델 정의 또는 ETL 변환 로직입니다.

구성된 경우 보강 에이전트는 구조화된 번들을 내보내고 아티팩트를 출력 버킷으로 실행할 수도 있습니다. 지원되는 출력 아티팩트는 다음과 같습니다.

  • 상세 평가 보고서: 쿼리별 정확성 델타, 테스트 실패 진단, 신뢰도 분포 측정항목을 보여주는 포괄적인 스코어카드입니다.

보강 에이전트가 버킷에서 작동할 수 있도록 실행 서비스 계정에 필요한 권한이 있는지 확인합니다.

  • 에이전트가 스테이지 문서 및 구성 파일을 읽을 수 있도록 입력 버킷에 객체 뷰어 역할 (roles/storage.objectViewer)을 부여합니다.
  • (선택사항) 에이전트가 실행 아티팩트 및 검증 로그를 저장하도록 하려면 출력 버킷에 객체 생성자 역할 (roles/storage.objectCreator)을 부여합니다.

서비스 계정에 Cloud Storage 버킷에 대한 액세스 권한을 부여하려면 다음 단계를 따르세요.

스토리지 버킷에 IAM 정책 바인딩을 추가하려면 gcloud storage buckets add-iam-policy-binding 명령어를 사용합니다.

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

  • CUSTOMER_BUCKET: Cloud Storage 버킷 이름
  • SERVICE_ACCOUNT_NAME: 서비스 계정의 이름입니다.
  • TARGET_PROJECT_ID: Google Cloud 프로젝트 ID입니다.

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

Windows(PowerShell)

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/storage.objectViewer"

Windows(cmd.exe)

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/storage.objectViewer"

평가 데이터 세트 형식 지정

보강 워크플로는 예시 없이 정보를 자동으로 추출할 수 있습니다. 하지만 평가 데이터 세트를 제공하면 에이전트가 자체적으로 테스트하고 정확성을 개선할 수 있습니다.

다음 두 가지 유형의 데이터 세트를 제공할 수 있습니다.

  • 선별 세트: 샘플 사용자 질문과 예상 SQL 쿼리 목록입니다. 상담사는 이 목록을 사용하여 더 나은 표 요약을 연습하고 작성합니다.

  • 평가 세트: 에이전트의 성능을 평가하는 데 사용되는 별도의 질문 목록입니다. 에이전트의 성능이 저조한 경우 이 평가 세트는 성능이 저조한 업데이트가 카탈로그에 게시되지 않도록 방지합니다.

또는 통합된 단일 데이터 세트를 제공할 수 있습니다. 보강 서비스는 데이터를 선별 세트와 평가 세트로 자동으로 파티션을 나눕니다.

데이터 세트 스키마 요구사항

평가 데이터 세트는 JSONL 파일 형식이어야 하며 Cloud Storage에 저장되어야 합니다. 파일의 각 줄에는 예상 정답 SQL 쿼리와 쌍을 이루는 자연어 질문이 포함되어야 합니다.

파일이 Gemini Enterprise Agent Platform에서 규정한 평가 데이터 세트 스키마와 일치하는지 확인합니다. 다음 표에는 허용되는 형식 필드가 나와 있습니다.

필드 이름 유형 설명
display_name STRING (선택사항) 평가 요청의 식별자 또는 이름입니다.
evaluation_request.prompt.text STRING 자연어 질문 또는 사용자 프롬프트입니다.
evaluation_request.golden_response.candidate STRING 골든 응답을 식별합니다. golden로 설정합니다.
evaluation_request.golden_response.text STRING 질문에 답변하는 검증된 정답 SQL 쿼리입니다. 스코어러는 데이터에 대해 이 SQL을 실행합니다.

다음 스니펫은 유효한 .jsonl 평가 파일을 보여줍니다.

{"display_name": "revenue-2026", "evaluation_request": {"prompt": {"text": "What is total revenue for customer C100 in 2026?"}, "golden_response": {"candidate": "golden", "text": "SELECT SUM(amount) FROM `project.dataset.orders` WHERE customer_id = 'C100' AND EXTRACT(YEAR FROM order_date) = 2026;"}}}
{"display_name": "monthly-subscribers", "evaluation_request": {"prompt": {"text": "List active subscribers on monthly billing"}, "golden_response": {"candidate": "golden", "text": "SELECT user_id, email FROM `project.dataset.subscriptions` WHERE status = 'ACTIVE' AND plan_type = 'MONTHLY';"}}}

고품질 평가 데이터 세트를 만드는 방법에 대한 자세한 내용은 Gemini Enterprise Agent Platform 문서를 참조하세요.

자체 학습을 위한 에이전트 trace 구성

보강 에이전트가 다운스트림 Gemini Enterprise 에이전트 상호작용 (또는 커스텀 Gemini Enterprise Agent Platform 애플리케이션)을 자동으로 분석하도록 하려면 선택적으로 애플리케이션의 상호작용 trace에 대한 읽기 액세스 권한을 제공하면 됩니다.

이러한 trace를 수집하면 에이전트가 궤적 마이닝을 수행할 수 있습니다. 이 에이전트는 컨텍스트 누락으로 인해 다운스트림 에이전트가 어려움을 겪는 부분을 파악하고, 자주 발생하는 사용자 질문을 영향력이 큰 쿼리 클래스로 클러스터링하며, 이러한 격차를 해소하는 데 필요한 정확한 테이블 요약, 열 시맨틱스, 비즈니스 용어집을 자동으로 선별합니다.

엔터프라이즈 아키텍처에 따라 다음 두 가지 설정 방법 중 하나를 선택합니다.

  • 범위가 지정된 로그 뷰를 사용한 직접 로깅: 애플리케이션의 원격 분석으로만 제한된 로그 뷰를 만들어 최소 권한 읽기 액세스 권한을 부여합니다. Recommended.
  • BigQuery 에이전트 분석: 조직에서 상호작용 로그를 BigQuery 로그 싱크로 기본적으로 라우팅하는 경우 내보낸 BigQuery 데이터 세트에 대한 읽기 액세스 권한을 부여합니다.

범위가 지정된 로그 뷰를 사용한 직접 로깅 (권장)

애플리케이션에 상호작용 로깅이 사용 설정되면 실행 로그가 Logging으로 직접 스트리밍됩니다. 최소 권한의 원칙을 따르려면 특정 애플리케이션으로 제한된 전용 로그 뷰를 만들고 실행 서비스 계정에 해당 뷰에 대한 읽기 액세스 권한만 부여합니다.

  1. 범위가 지정된 로그 뷰를 만들어 로그를 격리합니다. 이렇게 하면 보강 서비스가 구성된 특정 애플리케이션의 원격 분석만 읽고 (예: resource.type="aiplatform.googleapis.com/Agent" 필터링) 더 광범위한 Cloud 로그에 대한 무단 액세스를 방지할 수 있습니다.

    gcloud CLI

    범위가 지정된 로그 뷰를 만들려면 gcloud logging views create 명령어를 사용합니다.

    아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

    • LOG_VIEW_NAME: 로그 뷰의 이름
    • YOUR_GEMINI_ENTERPRISE_APP_ID: Gemini Enterprise 애플리케이션 ID

    다음 명령어를 실행합니다.

    Linux, macOS 또는 Cloud Shell

    gcloud logging views create LOG_VIEW_NAME \
    --location=global \
    --bucket=_Default \
    --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'

    Windows(PowerShell)

    gcloud logging views create LOG_VIEW_NAME `
    --location=global `
    --bucket=_Default `
    --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'

    Windows(cmd.exe)

    gcloud logging views create LOG_VIEW_NAME ^
    --location=global ^
    --bucket=_Default ^
    --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'

    REST

    요청 데이터를 사용하기 전에 다음을 바꿉니다.

    • LOG_VIEW_NAME: 로그 뷰의 이름
    • TARGET_PROJECT_ID: Google Cloud 프로젝트 ID입니다.
    • YOUR_GEMINI_ENTERPRISE_APP_ID: Gemini Enterprise 애플리케이션 ID

    HTTP 메서드 및 URL: 

    POST https://logging.googleapis.com/v2/projects/TARGET_PROJECT_ID/locations/global/buckets/_Default/views?viewId=LOG_VIEW_NAME

    JSON 요청 본문:

    {
 "filter": "resource.type=\"aiplatform.googleapis.com/Agent\" AND resource.labels.agent_id=\"YOUR_GEMINI_ENTERPRISE_APP_ID\""
}

    요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

    성공 상태 코드(2xx)와 빈 응답을 받게 됩니다.

  2. 로그 뷰를 만든 후 실행 서비스 계정에 읽기 액세스 권한을 부여합니다. 이렇게 하면 보강 작업이 자체 학습 단계에서 필요한 애플리케이션 원격 분석을 가져올 수 있습니다.

    로그 뷰에 IAM 정책 바인딩을 추가하려면 gcloud logging views add-iam-policy-binding 명령어를 사용합니다.

    아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

    • LOG_VIEW_NAME: 로그 뷰의 이름
    • SERVICE_ACCOUNT_NAME: 서비스 계정의 이름입니다.
    • TARGET_PROJECT_ID: Google Cloud 프로젝트 ID입니다.

    다음 명령어를 실행합니다.

    Linux, macOS 또는 Cloud Shell

    gcloud logging views add-iam-policy-binding LOG_VIEW_NAME \
    --location=global \
    --bucket=_Default \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/logging.viewAccessor"

    Windows(PowerShell)

    gcloud logging views add-iam-policy-binding LOG_VIEW_NAME `
    --location=global `
    --bucket=_Default `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/logging.viewAccessor"

    Windows(cmd.exe)

    gcloud logging views add-iam-policy-binding LOG_VIEW_NAME ^
    --location=global ^
    --bucket=_Default ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/logging.viewAccessor"

자세한 내용은 로그 버킷에서 로그 뷰 구성을 참조하세요.

BigQuery 에이전트 분석

조직에서 Logging 로그 싱크를 사용하여 상호작용 로그를 BigQuery로 스트리밍하거나 BigQuery 에이전트 분석 테이블에 직접 쓰는 경우 대신 데이터 세트에 대한 액세스 권한을 부여할 수 있습니다.

상호작용 로그가 지정된 BigQuery 데이터 세트로 스트리밍되도록 구성되어 있는지 확인하고 실행 서비스 계정에 해당 특정 데이터 세트에 대한 BigQuery 데이터 뷰어 역할 (roles/bigquery.dataViewer)이 부여되었는지 확인합니다. 이렇게 하면 에이전트가 BigQuery에서 직접 내보낸 원격 분석을 읽을 수 있습니다.

로그 내보내기에 대한 자세한 내용은 지원되는 대상으로 로그 라우팅을 참조하세요.

데이터 프로파일링 및 데이터 인사이트 사용 설정

보강 작업을 실행하기 전에 자주 사용하는 대상 테이블에서 데이터 프로파일링 및 AI 데이터 인사이트를 사용 설정하는 것이 좋습니다. 데이터 프로파일링은 일반적인 값, 데이터 분포, null 수와 같은 통계적 특성을 제공하는 반면 데이터 인사이트는 기준 테이블 설명과 샘플 쿼리를 생성합니다. 이러한 신호를 제공하면 보강 에이전트가 더 정확한 메타데이터 제안을 생성하는 데 도움이 됩니다.

다음 단계