데이터 엔지니어링 에이전트 개요

데이터 엔지니어링 에이전트를 사용하면 자연어 프롬프트를 사용하여 BigQuery에서 데이터 파이프라인을 빌드, 수정, 문제 해결할 수 있습니다. 데이터 엔지니어링 에이전트는 BigQuery로 데이터를 수집하는 데이터 엔지니어링 워크플로를 간소화하기 위해 다음과 같은 기능을 제공합니다.

• Dataform 통합: 에이전트가 Dataform 저장소 및 작업공간 내에서 직접 데이터 파이프라인 코드를 생성하고 정리합니다.
• 계획 생성: 에이전트가 자신의 생각을 요약하고 계획을 생성하여 사용자가 계속 진행하기 전에 에이전트의 계획을 검토하고 확인할 수 있습니다.
• 코드 검증: 에이전트가 생성된 코드의 컴파일 오류를 자동으로 검증하고 수정하여 데이터 파이프라인이 작동하는지 확인합니다.
• 자동 데이터 랭글링: 에이전트가 데이터 랭글링을 실행하고 수동 개입 없이 원시 데이터를 구조화된 표로 변환합니다.
• 맞춤 요청 사항: 에이전트는 자연어로 특정 규칙과 재사용 가능한 가이드라인을 정의할 수 있는 맞춤 에이전트 요청 사항을 지원합니다.
• 외부 컨텍스트: 에이전트가 추가 컨텍스트를 위해 Knowledge Catalog와 통합됨
• 파이프라인 제어: 작업이 실행되기 전에 생성된 에이전트 계획을 검토하고 맞춤설정할 수 있습니다.
• 최적화: 에이전트는 데이터 파이프라인의 성능을 최적화할 수 있습니다.
• 문제 해결 및 복구: 에이전트는 파이프라인 실패를 해결하고 코드를 수정할 수 있습니다.
• 대화형 추천: 에이전트가 세션 시작 시점과 세션 전반에 걸쳐 대화형 컨텍스트 인식 추천을 제공합니다.
• Knowledge Catalog 메타데이터 보강: 에이전트는 테이블 구성에서 Knowledge Catalog 메타데이터를 자동으로 생성할 수 있으며 파이프라인 실행 중에 메타데이터를 Knowledge Catalog로 전송할 수 있습니다.

데이터 엔지니어링 에이전트를 사용할 수 있는 위치

다음 방법으로 데이터 엔지니어링 에이전트를 사용할 수 있습니다.

• BigQuery 파이프라인 인터페이스 또는 Dataform에서 데이터 파이프라인을 빌드합니다.
• Visual Studio Code에 Google Cloud Data Agent Kit 확장 프로그램 설치를 통해 통합 개발 환경 (IDE)에서 데이터 파이프라인을 빌드합니다.
• Data Engineering Agent API를 사용합니다.

데이터 엔지니어링 에이전트가 사용자의 데이터를 사용하는 방식

데이터 엔지니어링 에이전트는 더 높은 품질의 에이전트 응답을 생성하기 위해 BigQuery 테이블의 샘플 행과 Knowledge Catalog에서 생성된 데이터 스캔 프로필을 비롯한 추가 데이터와 메타데이터를 BigQuery 및 Knowledge Catalog에서 가져올 수 있습니다. 에이전트는 이 데이터를 학습에 사용하지 않습니다. 에이전트 대화 중에만 응답에 필요한 추가 컨텍스트로 데이터를 사용합니다.

데이터 엔지니어링 에이전트가 데이터를 처리하는 위치

데이터 엔지니어링 에이전트가 데이터를 처리하는 위치에 대한 자세한 내용은 BigQuery의 Gemini에서 데이터를 처리하는 위치를 참고하세요.

제한사항

데이터 엔지니어링 에이전트에는 다음과 같은 제한사항이 있습니다.

• 데이터 엔지니어링 에이전트는 다음 파일 형식에 대한 자연어 명령어를 지원하지 않습니다.
  • 노트북
  • 데이터 준비
• 데이터 엔지니어링 에이전트가 파이프라인을 실행할 수 없습니다. 파이프라인을 검토하고 실행하거나 예약해야 합니다.
• 데이터 엔지니어링 에이전트는 안내 또는 직접 프롬프트를 통해 제공된 웹 링크나 URL을 검색할 수 없습니다.
• 에이전트 명령 파일에서 파일을 가져올 때 @ 가져오기 구문은 ./, / 또는 문자로 시작하는 경로만 지원합니다.
• 데이터 미리보기 기능은 hasOutput 플래그가 true로 설정된 테이블, 선언 또는 쿼리에만 지원됩니다.
• 데이터 엔지니어링 에이전트에는 AI 기술의 일반적인 제한사항이 적용됩니다.
• Lakehouse 런타임 카탈로그 (이전 명칭: BigLake Metastore)에서 관리하는 Apache Iceberg 외부 테이블을 통해 파이프라인을 만들 때는 모든 Lakehouse 런타임 카탈로그 제한사항이 적용됩니다. 특히 에이전트는 Iceberg 테이블에서 쓰기 변이 (예: INSERT, UPDATE, DELETE, MERGE) 또는 DDL 문 (예: CREATE TABLE, DROP TABLE)을 생성할 수 없습니다. 자세한 내용은 Apache Iceberg REST 카탈로그 엔드포인트 개념을 참고하세요.

상담사 기능 및 맞춤설정

다음 섹션에서는 추가 에이전트 기능과 데이터 엔지니어링 에이전트를 맞춤설정하는 기타 방법을 설명합니다.

에이전트 요청 사항

에이전트 요청 사항은 데이터 엔지니어링 에이전트를 위한 자연어 요청 사항으로, 에이전트가 사전 정의된 맞춤 규칙을 따르도록 영구 요청 사항을 저장할 수 있습니다. 조직 전체에서 에이전트의 결과가 일관되도록 하려면(예: 명명 규칙을 사용하거나 스타일 가이드를 적용) 에이전트 지침을 사용하세요.

데이터 엔지니어링 에이전트의 에이전트 명령어를 만들려면 GEMINI.MD 컨텍스트 파일을 에이전트 명령어 파일로 만듭니다.

에이전트 요청 사항 파일 관련 권장사항

에이전트 안내를 사용할 때는 다음을 권장합니다.

• Dataform의 모든 파일 경로는 저장소의 루트를 기준으로 합니다. @file.md 구문에 상대 경로를 사용하여 GEMINI.md에 안내를 올바르게 가져옵니다.
• GEMINI.md에서 가져온 파일 자체에 가져오기가 포함될 수 있으며, 이로 인해 중첩된 구조가 생성될 수 있습니다. 무한 재귀를 방지하기 위해 GEMINI.md의 최대 가져오기 깊이는 5단계입니다.
• 데이터 파이프라인 간에 안내를 공유하려면 중앙 Dataform 저장소에 안내를 저장하고 작업 Dataform 저장소에 연결하세요. 로컬 명령어를 사용하여 파이프라인별 동작에 대한 중앙 규칙을 재정의할 수 있습니다.
• 프로젝트의 일관성을 유지하기 위해 이름 지정 규칙 파일이나 스타일 가이드에 연결하고 데이터 파이프라인을 사용할 때 이러한 가이드를 따르도록 에이전트에게 지시할 수 있습니다.
• 안내 파일에서 데이터 레이어를 제안하여 다양한 유형의 데이터를 함께 그룹화할 수 있습니다.
• 에이전트 안내 파일에 제목과 목록을 사용하면 데이터 엔지니어링 에이전트의 안내를 정리하고 명확하게 할 수 있습니다.
• 의미 있는 파일 이름을 지정하고 유사한 안내를 하나의 파일로 그룹화합니다. 마크다운 제목을 사용하여 카테고리, 기능 또는 기능별로 규칙을 논리적으로 정리합니다.
• 명령어 충돌을 방지하려면 각 명령어가 적용되는 특정 조건을 명확하게 정의하세요.
• 프롬프트와 워크플로를 반복하고 미세 조정합니다. 에이전트 동작은 에이전트 출시 및 모델 업그레이드에 따라 시간이 지남에 따라 변경되므로 다양한 프롬프트로 규칙을 반복하여 개선이 필요한 영역을 파악하는 것이 좋습니다. 데이터 파이프라인의 변경사항에 맞춰 규칙 파일을 동기화하세요.

다음 예시는 데이터 엔지니어링 에이전트를 효과적으로 사용하기 위한 권장사항을 활용하는 GEMINI.md라는 에이전트 요청 사항 파일을 보여줍니다.

  ### Naming Conventions

  * Datasets: [business_domain]_[use_case] (e.g., ecommerce_sales)

  * Tables:
      - Raw/External: raw_[source_name]
      - Staging: stg_[business_entity]
      - Dimension: dim_[dimension_name]
      - Fact: fct_[fact_name]

  * Dataform Folders:
      - sources
      - staging
      - marts
      - dataProducts

  * Views: vw_[view_name]

  * Columns: snake_case (e.g., order_id, customer_name)

  ## Cloud Storage data load
  * When ingesting data from Cloud Storage, create external tables.

  ## Null handling
  * Filter out null id values

  ## String normalization
  * Standardize string columns by converting to lower case

  ## Data Cleaning Guidelines
  @./generic_cleaning.md

추가 로컬 파일을 에이전트 안내로 가져오기

@file.md 구문을 사용하여 데이터 엔지니어링 에이전트의 다른 명령 파일도 GEMINI.md 파일로 가져올 수 있습니다. 자세한 내용은 메모리 가져오기 프로세서를 참고하세요.

자동 데이터 랭글링

데이터 엔지니어링 에이전트를 사용하여 처리되지 않은 원시 데이터를 데이터 분석에 적합한 구조화된 테이블로 변환할 수 있습니다. 요청이 있으면 에이전트는 먼저 각 표준 테이블 또는 외부 테이블에서 최대 1,000,000개의 레코드를 샘플링합니다. 그런 다음 에이전트는 이 샘플에 프로파일링 쿼리를 실행하여 심층 데이터 분석을 실행합니다. 데이터 변환을 생성한 후 에이전트는 이 샘플링 및 프로파일링 프로세스를 반복하여 변환의 품질을 평가합니다. 이러한 데이터 랭글링 변환에는 데이터 불일치, 이상치 또는 유형 불일치 수정이 포함될 수 있습니다. 그러면 데이터 엔지니어링 에이전트가 제안된 데이터 정리 단계를 간략하게 설명하는 계획을 만들어 사용자가 검토하고 수정할 수 있도록 합니다.

또한 데이터 엔지니어링 에이전트는 CSV 기반 외부 테이블과 같은 원시 테이블을 추가할 때마다 데이터 랭글링 분석을 시작합니다. 데이터 랭글링 계획을 검토하고 대화형 명령어로 조정할 수 있습니다.

데이터 샘플링 및 프로파일링에는 BigQuery 리소스가 사용되며 BigQuery 가격 책정이 적용됩니다.

데이터 엔지니어링 에이전트는 다음 데이터 랭글링 변환을 지원합니다.

• 데이터 정리 에이전트는 원시 데이터를 분석하고 이상치 삭제, 누락되거나 일관되지 않은 값 채우기(데이터 대치), 중복 데이터 수정, 데이터 형식 표준화(예: 전화번호 또는 주소)와 같은 정리 기회를 제안할 수 있습니다.
• 구조적 변환 타겟 스키마가 제공되면 에이전트는 JSON, ARRAY 또는 STRUCT 유형에서 값을 중첩 해제하거나 추출하고, 여러 열을 하나로 병합하거나, 하나의 열을 여러 열로 분할할 수 있습니다.
• 데이터 유형 감지 및 변환 에이전트는 데이터를 분석하여 적절한 필드 유형을 결정할 수 있습니다. 그러면 에이전트가 보안 유형 변환을 실행하여 날짜, 시간, datetime 또는 타임스탬프 필드 내의 형식 불일치를 해결할 수 있습니다.
• 단위 변환 에이전트는 필드 내의 다양한 단위를 하나의 일관된 단위로 자동 변환하여 데이터를 표준화할 수 있습니다.

정확성을 보장하기 위해 에이전트는 데이터의 대표 샘플을 사용하여 문제를 감지하고 변환 로직을 검증합니다.

에이전트 계획 생성 및 검토

데이터 엔지니어링 에이전트는 요청을 완료하기 위해 취하는 목표와 단계의 요약 및 개요를 제공하는 에이전트 계획을 생성할 수 있습니다. 많은 변경사항이 필요한 복잡한 요청으로 에이전트에게 프롬프트를 표시하는 경우 에이전트가 작업을 실행하기 전에 에이전트의 의도를 검토할 수 있도록 에이전트 계획을 제공해 달라고 요청하는 것이 좋습니다. 데이터 엔지니어링 에이전트 계획은 일반적으로 다음으로 구성됩니다.

• 특정 요청에 대한 에이전트의 목표
• 에이전트가 취할 계획인 단계의 개략적인 개요
• 에이전트가 만드는 가정
• 에이전트가 수정할 계획인 파일
• 실행할 최적화 또는 정리 단계
• 단계별 실행 계획

프롬프트에 계획을 검토하고 승인해야 한다는 내용을 포함하여 에이전트가 명시적인 승인 없이 조치를 취하지 않도록 할 수 있습니다. 예를 들면 다음과 같습니다.

Create a plan for a pipeline that finds the
top N pick up and drop off locations in NYC. I want to review the plan and
approve it before you create the pipeline.

에이전트가 에이전트 계획을 자동으로 생성하고 승인을 요청할 수도 있습니다. 프롬프트가 너무 모호하거나 에이전트가 요청을 처리하기 위해 더 명확한 정보가 필요한 경우 이러한 결과가 발생할 수 있습니다.

에이전트 계획 사용에 관한 권장사항은 권장사항을 참고하세요.

Knowledge Catalog에서 컨텍스트 추가

데이터 엔지니어링 에이전트는 용어집 용어를 BigQuery 테이블 및 열에 연결하고 데이터 프로필 스캔을 생성하여 Knowledge Catalog를 사용합니다. 용어집 용어는 특별한 처리 지침이 필요한 개인 식별 정보 (PII)가 포함된 열과 같이 추가 컨텍스트가 필요한 열에 태그를 지정하거나 테이블 간에 이름이 다른 일치하는 열을 식별할 수 있습니다.

Knowledge Catalog는 데이터 프로파일링도 활용합니다. 이를 통해 에이전트는 표 열 내의 데이터 분포를 더 잘 이해하고 에이전트가 더 구체적인 데이터 품질 어설션을 만들 수 있습니다.

에이전트는 Knowledge Catalog를 사용하여 Apache Iceberg 테이블을 검색하고 쿼리할 수도 있습니다. 자세한 내용은 Apache Iceberg 테이블을 통해 파이프라인 만들기를 참고하세요.

기존 테이블에 데이터 품질 확인 추가

에이전트에게 품질 검사를 추가하라고 프롬프트하면 에이전트는 스키마와 샘플을 기반으로 테이블에 적합한 검사를 추론합니다. 프롬프트의 일부로 의견이 포함된 어설션을 추가할 수도 있습니다. 예를 들면 다음과 같습니다.

  Add data quality checks for bigquery-public-data.thelook_ecommerce.users.

파이프라인 실행 중에 Dataform 어설션 결과가 Knowledge Catalog(미리보기)에 자동으로 게시됩니다. 이러한 결과는 Knowledge Catalog 데이터 품질 스코어카드에 통과 또는 실패 상태를 표시합니다. 실행할 때마다 이전 Dataform 실행에서 게시한 기존 데이터 품질 스코어카드가 덮어쓰이지만 Knowledge Catalog 데이터 스캔으로 생성된 스코어카드에는 영향을 미치지 않습니다.

자동 데이터 보강

미리보기

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제품 또는 서비스 약관'이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

참고: 이 기능에 대한 의견을 제공하거나 지원을 요청하려면 [e-mail]으로 이메일을 보내세요.

BigQuery의 표준 메타데이터(예: 데이터 세트, 테이블, 뷰)는 Knowledge Catalog에서 자동으로 사용할 수 있습니다.

.sqlx 파일의 구성 블록에서 테이블과 뷰의 맞춤 메타데이터를 직접 정의할 수도 있습니다. 작업이 완료되면 Dataform이 자동으로 Knowledge Catalog에 메타데이터 동기화를 시작합니다. 이 보강 프로세스는 SQLX 구성에 정의된 시맨틱 메타데이터로 Knowledge Catalog를 업데이트합니다.

메타데이터 키를 사용하여 Knowledge Catalog의 정보를 지정합니다. 강화 프로세스는 다음 메타데이터 구조를 지원합니다.

• 개요: 항목의 문서 및 요약 텍스트입니다. Dataform 핵심 버전 3.0.37 이상이 필요합니다.
• 일반적인 측면: 테이블 시스템 및 유형 정보와 같은 시맨틱 세부정보입니다. Dataform 핵심 버전 3.0.52 이상이 필요합니다.

다음 예시 구성은 Knowledge Catalog의 테이블 구성에 개요 및 일반 메타데이터 측면을 추가하는 방법을 보여줍니다.

config {
  type: "table",
  metadata: {
    overview: "This table provides standardized trip data.",
    extraProperties: {
        generic: {
              system: "BigQuery",
              type: "table"
        }
      }
  }
}

메타데이터 업데이트 상태를 확인하려면 Dataform 워크플로의 경우 작업공간 실행 로그 검사를, BigQuery 파이프라인의 경우 이전 수동 실행 보기를 참고하세요.

동기화된 메타데이터를 확인하려면 Knowledge Catalog에서 애셋을 검색하면 됩니다. 자세한 내용은 리소스 검색을 참고하세요.

데이터 파이프라인 최적화

에이전트에게 데이터 파이프라인을 최적화하라고 요청할 수 있습니다. 새 테이블의 DDL을 생성할 때 데이터 엔지니어링 에이전트는 분석된 데이터 사용 패턴을 기반으로 파티셔닝 및 클러스터링을 추천합니다. 또한 에이전트는 다른 파이프라인 최적화를 자동으로 적용할 수 있습니다. 가능한 최적화의 예는 다음과 같습니다.

• 스토리지에서 읽어오는 데이터를 줄여 기본 비용 및 성능 드라이버 역할을 하는 열 가지치기
• 실행 계획 초기에 데이터를 필터링하여 후속 작업에서 처리하는 볼륨을 크게 줄이는 조건자 푸시다운
• 공통 하위 표현식을 제거하여 공유 변환 로직을 한 번만 식별하고 계산함으로써 효율성을 개선하고 대규모 테이블을 여러 번 스캔하고 조인하는 것과 같은 비효율적인 관행을 방지합니다.
• 실행할 때마다 전체 테이블을 다시 빌드하는 대신 마지막 실행 이후의 새 데이터 또는 변경된 데이터만 처리하는 증분 모델

Apache Iceberg 테이블을 기반으로 파이프라인 만들기

데이터 엔지니어링 에이전트는 Lakehouse 런타임 카탈로그 (이전 명칭: BigLake metastore)에서 관리하는 Apache Iceberg 테이블을 통해 Dataform 파이프라인을 생성하고 컴파일하는 것을 지원합니다. 이 기능을 사용하면 BigQuery 테이블과 함께 Cloud Storage에 저장된 지역 오픈소스 형식 테이블을 직접 쿼리하고 조인할 수 있습니다. 자세한 내용은 Apache Iceberg REST 카탈로그 엔드포인트 개념을 참고하세요.

예를 들어 에이전트가 Lakehouse 런타임 카탈로그에서 Apache Iceberg 테이블을 쿼리하도록 프롬프트를 지정할 수 있습니다.

Include the stackoverflow_post_history_iceberg table in this pipeline.

프롬프트에서 정규화된 4부 경로(예: project.catalog.dataset.table)를 지정할 필요는 없습니다. 표준 자연어 이름이나 논리적 식별자(예: the StackOverflow post history table 또는 post_history)를 사용하여 Apache Iceberg 테이블을 참조할 수 있습니다. 에이전트는 Knowledge Catalog를 사용하여 시맨틱 카탈로그 검색을 자동으로 호출하여 올바른 Apache Iceberg 테이블을 파이프라인 작업공간에 확인하고 바인딩합니다.

이 기능을 사용하려면 Dataform 저장소에서 Dataform Core 버전 3.0.33 이상을 사용해야 합니다.

대화형 추천

데이터 엔지니어링 에이전트는 워크스페이스 컴파일 상태, 실행 기록, 활성 대화 상태를 분석하여 채팅 인터페이스에서 바로 활용 가능한 추천을 제공합니다. 이러한 추천은 워크스페이스를 열 때와 세션 전체에서 자동으로 표시되어 워크플로를 안내하는 설정, 문제 해결, 최적화에 관한 추천을 제공합니다.

추천을 사용하려면 AI 추천 아래의 추천 중 하나를 클릭합니다. 그러면 프롬프트가 채팅 입력 표시줄에 로드되며, 이를 수정하거나 맞춤설정한 후 상담사에게 보낼 수 있습니다. 추천 위로 마우스를 가져가면 정확한 프롬프트를 확인할 수도 있습니다.

권장사항

데이터 엔지니어링 에이전트 및 Dataform을 사용할 때 결과를 개선하려면 다음을 수행하는 것이 좋습니다.

일반적인 요청에 에이전트 안내 사용 특정 기법을 자주 적용하거나 에이전트에 동일한 수정을 자주 적용하는 경우 에이전트 요청 사항을 사용하여 일반적인 요청 사항과 요청을 저장하는 중앙 집중식 위치로 사용하세요.

에이전트 계획 활용: 에이전트 계획은 복잡한 파이프라인 작업을 분류하는 데 유용합니다. 상담사 계획에는 상담사의 가정과 의도도 표시되므로 상담사에게 올바른 컨텍스트가 제공되도록 계획을 검토하는 것이 좋습니다.

계획을 검토한 후에는 피드백과 변경사항을 사용하여 데이터 엔지니어링 에이전트에게 프롬프트를 표시하여 계획을 수정할 수 있습니다. 예를 들면 다음과 같습니다.

In the plan, ensure that all of the intermediate tables are views.

경우에 따라 에이전트에게 명시적인 승인이 필요하지 않은 계획을 생성해 달라고 요청하는 것이 유용할 수 있습니다. 에이전트가 계획을 세우도록 하면 데이터 엔지니어링 에이전트가 작업을 세분화하게 되며, 이는 종종 더 나은 결과로 이어집니다. 에이전트가 계획을 생성하고 자동으로 실행하도록 강제할 수 있습니다. 예를 들면 다음과 같습니다.

Create a plan for a pipeline that finds the
top N pick up and drop off locations in NYC. You have my explicit pre-approval
to go ahead and execute this plan.

명확하게 작성합니다. 요청을 명확하게 서술하고 모호하게 표현하지 마세요. 가능한 경우 프롬프트 시 다음 예와 같이 소스 및 대상 데이터 소스를 제공하세요.

  Extract data from the sales.customers table in the us_west_1 region, and load
  it into the reporting.dim_customers table in BigQuery. Match the schema of the
  destination table.

직접적이고 범위가 지정된 요청을 제공하세요. 한 번에 하나의 질문을 하고 프롬프트는 간결하게 유지하세요. 질문이 두 개 이상인 프롬프트의 경우 다음 예와 같이 질문의 각 부분을 명확하게 구분하여 나열하세요.

  1. Create a new table named staging.events_cleaned. Use raw.events as the
     source. This new table should filter out any records where the user_agent
     matches the pattern '%bot%'. All original columns should be included.

  2. Next, create a table named analytics.user_sessions. Use
     staging.events_cleaned as the source. This table should calculate the
     duration for each session by grouping by session_id and finding the
     difference between the MAX(event_timestamp) and MIN(event_timestamp).

명시적인 요청 사항을 제공하고 주요 용어를 강조합니다. 다음 예와 같이 프롬프트에서 주요 용어나 개념을 강조하고 특정 요구사항을 중요하다고 표시할 수 있습니다.

  When creating the staging.customers table, it is *VERY IMPORTANT* that you
  transform the email column from the source table bronze.raw_customers.
  Coalesce any NULL values in the email column to an empty string ''.

작업 순서를 지정합니다. 순서가 지정된 작업의 경우 다음 예와 같이 목록에 프롬프트를 구조화합니다. 목록 항목은 집중적으로 수행할 수 있는 작은 단계로 나뉩니다.

  Create a pipeline with the following steps:
  1. Extract data from the ecomm.orders table.
  2. Join the extracted data with the marts.customers table on customer_id.
  3. Load the final result into the reporting.customer_orders table.

수정하고 반복하세요. 다양한 문구와 접근 방식을 시도하여 가장 좋은 결과를 얻는 방법을 알아보세요. 에이전트가 잘못된 SQL을 생성하거나 다른 실수를 하는 경우 예시나 공개 문서를 사용하여 에이전트를 안내하세요.

  The previous query was incorrect because it removed the timestamp. Please
  correct the SQL. Use the TIMESTAMP_TRUNC function to truncate the
  event_timestamp to the nearest hour, instead of casting it as a DATE. For
  example: TIMESTAMP_TRUNC(event_timestamp, HOUR).

데이터 파이프라인 평가

데이터 엔지니어링 에이전트가 생성한 데이터 파이프라인의 효과를 평가하려면 EvalBench 도구를 사용하세요. EvalBench는 멀티턴 에이전트 평가를 지원하는 오픈소스 프레임워크입니다. EvalBench는 자동화된 단위 테스트 모음으로 작동하여 멀티턴 시나리오를 설정하고, LLM 지원 결정론적 스코어러를 추가하고, Dataform 파이프라인의 수명 주기를 관리할 수 있습니다.

EvalBench는 격리된 샌드박스에서 자연어 프롬프트를 시뮬레이션하여 에이전트가 얼마나 효과적으로 요청 사항을 이해하고, 올바른 도구를 호출하고, 올바른 파이프라인 코드를 생성하는지 측정합니다. EvalBench는 다음을 수행하여 데이터 파이프라인을 확인할 수 있습니다.

• 맞춤 규칙 검증: 에이전트가 조직의 특정 코딩 가이드라인, 이름 지정 규칙, 권장사항을 엄격하게 따르는지 확인합니다.
• 코드 회귀 방지: 배포 전에 파이프라인 변경사항을 테스트하여 에이전트 업데이트나 스키마 수정으로 인해 기존 기능이 중단되지 않도록 합니다.
• 품질 기준 생성: SQL 정확성, 도구 실행 정확성, 파이프라인 안정성에 대한 객관적이고 자동화된 점수를 확인합니다.

데이터 파이프라인 평가 실행

다음 두 가지 모드로 EvalBench를 실행할 수 있습니다.

• 동적 샌드박스: EvalBench는 평가 실행이 시작될 때 새로운 임시 Dataform 저장소와 작업공간을 프로비저닝하고, 테스트 시나리오를 실행하며, 완료되면 생성된 모든 리소스를 자동으로 해체합니다. 이 모드는 프로덕션 코드, 프로덕션 저장소 또는 BigQuery 데이터 세트를 수정하지 않으며 Google Cloud 프로젝트에 남아 있는 아티팩트가 없습니다. 동적 샌드박스 모드는 엄격한 환경 격리가 필요한 자동화된 CI/CD 파이프라인, 야간 회귀 테스트, 객관적 벤치마크 점수 매기기에 적합합니다.

• 정적 워크스페이스: EvalBench는 기존의 사용자 관리 Dataform 저장소 및 워크스페이스에 연결되고 자동 생성 및 삭제 스크립트를 건너뜁니다. 이 모드를 사용하면 평가 중인 에이전트가 평가 사례를 처리할 때 기존 작업공간 내에서 SQLX 파일을 수정하고 새로 만들 수 있습니다. 정적 작업공간 모드는 실행 후 Dataform 작업공간에서 생성된 SQLX 파일을 직접 검사해야 하는 활성 프롬프트 엔지니어링, 기준표 반복, 로컬 디버깅에 적합합니다.

시작하기 전에

EvalBench를 실행하는 데 필요한 권한을 얻으려면 관리자에게 EvalBench를 실행하는 서비스 계정 또는 사용자 ID에 다음 IAM 역할을 부여해 달라고 요청하세요.

• Dataform 관리자 (roles/dataform.admin)
• BigQuery 데이터 편집자 (roles/bigquery.dataEditor)
• BigQuery 작업 사용자 (roles/bigquery.jobUser)
• 평가 결과를 ZIP 패키지로 내보내기: 스토리지 객체 관리자 (roles/bigquery.objectAdmin)

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

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

동적 샌드박스에서 평가 실행

동적 샌드박스 모드에서 데이터 파이프라인을 평가하려면 다음 단계를 따르세요.

1. 단계를 따라 저장소를 클론하고 가상 환경을 설정하고 EvalBench 종속 항목을 설치합니다. 자세한 내용은 시작하기를 참고하세요.

2. datasets/dea-tools/ 디렉터리에서 예시 실행 구성 (example_run_config.yaml) 파일에 다음 줄이 포함되어 있는지 확인합니다.

   set_up_script: datasets/dea-tools/scripts/setup_dataform.sh
   tear_down_script: datasets/dea-tools/scripts/teardown_dataform.sh

3. 다음 명령어를 사용하여 EvalBench를 실행합니다.

   EVAL_GCP_PROJECT_ID=PROJECT_ID \
   EVAL_GCP_PROJECT_REGION=REGION \
   .venv/bin/python3 evalbench/evalbench.py --experiment_config=datasets/dea-tools/example_run_config.yaml

   다음을 바꿉니다.

   • PROJECT_ID: Google Cloud프로젝트의 ID입니다.
   • REGION: Google Cloud프로젝트의 리전입니다.

정적 평가 작업공간에서 평가 실행

정적 작업공간 모드에서 데이터 파이프라인을 평가하려면 다음 단계를 따르세요.

1. 단계를 따라 저장소를 클론하고 가상 환경을 설정하고 종속 항목을 설치합니다. 자세한 내용은 시작하기를 참고하세요.

2. datasets/dea-tools/ 디렉터리에서 예시 실행 구성(example_run_config.yaml) 파일을 수정하여 set_up_script 및 tear_down_script 줄을 주석 처리하고 dataform_repository 및 dataform_workspace 구성을 추가합니다.

   ...
   # set_up_script: datasets/dea-tools/scripts/setup_dataform.sh
   # tear_down_script: datasets/dea-tools/scripts/teardown_dataform.sh
   dataform_repository: !ENV ${EVAL_DEA_REPOSITORY_ID}
   dataform_workspace: !ENV ${EVAL_DEA_WORKSPACE_ID}
   ...

3. 다음 명령어를 사용하여 EvalBench를 실행합니다.

   EVAL_GCP_PROJECT_ID=PROJECT_ID \
   EVAL_GCP_PROJECT_REGION=REGION \
     EVAL_DEA_REPOSITORY_ID=REPOSITORY_ID \
     EVAL_DEA_WORKSPACE_ID=WORKSPACE_ID \
     .venv/bin/python3 evalbench/evalbench.py --experiment_config=datasets/dea-tools/example_run_config.yaml

   다음을 바꿉니다.

   • PROJECT_ID: Google Cloud프로젝트의 ID입니다.
   • REGION: Google Cloud프로젝트의 리전입니다.
   • REPOSITORY_ID: 데이터 파이프라인이 포함된 저장소의 ID입니다.
   • WORKSPACE_ID: 데이터 파이프라인이 포함된 워크스페이스의 ID입니다.

4. 선택사항: core_10_cases_suite.yaml로 EvalBench를 실행하여 각 테스트 사례의 새 저장소를 만들어 환경을 격리하여 10개의 핵심 평가 사례에 대해 순차적으로 데이터 파이프라인을 테스트할 수도 있습니다. 이렇게 하려면 다음 명령어를 실행하세요.

   EVAL_GCP_PROJECT_ID=PROJECT_ID \
   EVAL_GCP_PROJECT_REGION=REGION \
   .venv/bin/python3 evalbench/evalbench.py --suite_config=datasets/dea-tools/core_10_cases_suite.yaml

데이터 파이프라인 평가 권장사항

EvalBench를 사용하여 데이터 파이프라인 평가의 성능과 정확도를 개선하려면 다음을 수행하는 것이 좋습니다.

• 평가 로그에서 Dataform 워크플로 호출 및 BigQuery 작업 ID를 찾습니다. 이러한 ID를 사용하여 Google Cloud 콘솔에서 생성된 실행 아티팩트, 컴파일 결과, 쿼리 로그를 교차 참조하고 검사합니다.
• 다양한 데이터 엔지니어링 시나리오에서 완전한 회귀 범위를 보장하려면 모델이나 프롬프트 변경사항을 출시하기 전에 항상 핵심 평가 모음 (--suite_config)을 실행하세요.
• EVAL_DATAFORM_SETUP_ENV_FILES_DIR를 사용하여 workflow_settings.yaml 및 기본 스키마 정의와 같은 환경 설정 파일을 테스트 작업공간에 미리 로드합니다. 이러한 설정 파일을 사용하면 에이전트가 빈 작업공간이 아닌 실제 기존 환경을 기반으로 빌드됩니다.
• 동적 샌드박스 모드에서 실패한 평가 사례를 문제 해결할 때는 사후 분석을 위해 타겟 작업공간을 유지하도록 실행 구성에서 tear_down_script를 주석 처리하세요.
• 항상 클라우드 컴파일 및 실행 검증 도구(dataform_cloud_compile, dataform_cloud_run)를 LLM 기반 바이너리 루브릭과 페어링하여 구문 또는 런타임 오류와 고급 논리 결함을 모두 식별하세요.
• BigQuery 보고 (<PROJECT_ID>.evalbench.results)를 사용 설정하고 생성된 데이터 스튜디오 링크를 사용하여 시간 경과에 따른 통과율, 도구 사용 정확도, 프롬프트 효율성을 추적합니다.