DataGuard AI를 이용한 GitHub Actions에서의 데이터 품질 검사 자동화

데이터 품질 문제는 편리한 시기를 기다리지 않고 나타납니다. 누락된 고객 식별자, 예상치 못한 null 값, 또는 음수 거래 금액이 ETL 파이프라인을 통과하여 아무도 알아차리기 전에 다운스트림 보고서에 영향을 미칠 수 있습니다.

이러한 문제를 더 일찍 포착하는 실용적인 방법은 데이터 품질 검사를 개발 워크플로우의 일부로 만드는 것입니다.

본 튜토리얼에서는 오픈 소스 Python 데이터 품질 및 거버넌스 툴킷인 DataGuard AI를 사용하여 GitHub Actions으로 샘플 데이터를 자동으로 스캔하는 방법을 보여드리겠습니다.

목표는 간단합니다. 코드가 변경될 때마다 데이터 품질 검사를 실행하고 개발자가 검사할 수 있는 보고서를 생성하는 것입니다.

CI/CD에 데이터 품질을 도입해야 하는 이유?

소프트웨어 팀은 단위 테스트(unit tests), 린팅(linting), 보안 검사 등을 일상적으로 자동화합니다. 데이터 파이프라인 역시 유사한 관행의 이점을 누릴 수 있으며, 특히 데이터셋과 변환 로직이 진화할 때 더욱 그렇습니다.

자동화된 검사는 팀이 다음을 식별하는 데 도움을 줄 수 있습니다:

• 누락되거나 유효하지 않은 값
• 중복 식별자
• 예상치 못한 데이터 분포
• 잠재적으로 민감한 정보
• 명시적으로 구성된 비즈니스 규칙 위반

이러한 검사들이 프로덕션 모니터링을 대체하는 것은 아니지만, 전달 과정 초기에 문제를 포착할 수 있게 해줍니다.

DataGuard AI 소개

DataGuard AI는 결정론적 데이터 품질 검사, 거버넌스 신호(governance signals), 구성 가능한 유효성 검사 규칙, 그리고 기계가 읽을 수 있는 보고서를 제공하는 오픈 소스 Python 툴킷입니다.

CSV 및 JSON 파일을 지원하며, 선택적으로 Parquet 지원, DuckDB, PostgreSQL도 지원합니다.

AI 기반 설명은 선택 사항입니다. 핵심 스캔 기능은 LLM이나 API 키를 필요로 하지 않습니다.

GitHub: https://github.com/adiranjan25/dataguard-ai

PyPI: https://pypi.org/project/dataguard-ai/

1단계: DataGuard AI 설치

Python 3.10 이상이 필요합니다.

공개 베타 버전을 설치하세요:

python -m pip install dataguard-ai==0.2.1

내장된 합성 리테일(synthetic retail) 데모를 사용해 보세요:

dataguard demo --rows 100

이 명령어는 합성 리테일 데이터셋을 생성하고, 해당 데이터셋에 대해 데이터 품질 및 거버넌스 위험을 검사합니다.

단계 2: 샘플 데이터 준비

customers.csv라는 파일을 만드세요:

customer_id,name,email,age
101,Alice,[email protected],29
102,Bob,,34
...

이 파일에는 의도적으로 누락된 이메일 주소와 유효하지 않은 음수 나이가 포함되어 있습니다.

dataguard.yml을 만드세요:

quality:
  max_null_pct: 5

...

이 규칙들은 간단한 데이터셋 계약(dataset contract)을 표현합니다. 즉, 고객 식별자(customer identifiers)와 이메일 주소는 반드시 존재해야 하며, 나이는 합리적인 범위 내에 있어야 한다는 것입니다.

단계 3: 로컬 스캔 실행

다음 명령어를 실행하세요:

dataguard scan customers.csv \
  --config dataguard.yml \
  --json-out report.json \
...

DataGuard AI는 데이터셋을 검사하고 두 개의 보고서를 작성합니다:

• report.json — 자동화에 적합한 구조화된 결과물(structured findings)
• report.html — 발견된 결과를 사람이 읽기 쉬운 형식의 보고서

샘플 데이터가 의도적으로 유효하지 않은 값을 포함하고 있기 때문에, 누락된 이메일 데이터와 나이 범위 규칙과 관련된 발견 사항들이 나타날 것으로 예상됩니다.

정확한 심각도(severity), 점수(scores) 및 기타 발견 사항은 도구의 구성 및 탐지 동작에 따라 달라집니다.

단계 4: GitHub Actions로 스캐닝 자동화

저장소에 이 파일을 만드세요:

.github/workflows/data-quality.yml

name: Data Quality Checks

on:
...

이제 누군가 main 브랜치에 변경 사항을 푸시하거나 풀 리퀘스트(pull request)를 열 때, GitHub Actions가 스캐너를 실행하고 생성된 보고서를 업로드합니다.

개발자들은 워크플로우 실행(workflow run)을 열어 아티팩트(artifacts)를 찾고 검토를 위해 보고서를 다운로드할 수 있습니다.

중요 제한 사항: DataGuard AI v0.2.1은 발견된 결과(findings)를 생성하지만, 위 워크플로는 단순히 품질 문제가 감지되었다는 이유만으로 자동으로 실패하지 않습니다. 스캔 단계가 실행 및 보고서 생성이 성공하면 성공합니다. 품질 게이트(quality gate)를 강제하려면 합의된 임계값과 JSON 보고서를 평가하는 추가 정책 단계가 필요합니다.

5단계: 발견된 결과 검토하기

HTML 보고서는 품질 및 거버넌스 점수, 영향을 받은 열(columns), 심각도(severity), 제안된 복구 조치 등을 검사할 수 있는 접근성 높은 방법을 제공합니다.

JSON 보고서는 품질 대시보드, 정책 평가 또는 사용자 지정 CI 확인과 같은 다운스트림 자동화에 더 적합합니다.

이러한 분리는 유용합니다. 왜냐하면 각 팀이 서로 다른 수준의 세부 정보가 필요하기 때문입니다. 엔지니어는 구조화된 출력을 원할 수 있고, 검토자는 시각적 요약을 선호할 수 있습니다.

이 접근 방식이 적합한 경우

이 패턴은 다음의 경우에 유용할 수 있습니다:

• 샘플 또는 테스트 데이터셋을 포함하는 데이터 엔지니어링 저장소(repositories)
• ETL 개발 및 변환 검증
• 데이터 계약 실험(Data contract experimentation)
• 개발 중 거버넌스 확인
• CI/CD 시연 및 교육

대규모 프로덕션 데이터셋의 경우, 팀은 동일한 접근 방식을 채택하기 전에 스캔 비용, 데이터 민감도, 실행 환경, 성능을 평가해야 합니다.

최종 생각

데이터 품질은 파이프라인이 프로덕션에 도달한 후에만 시작되어서는 안 됩니다.

GitHub Actions에 가볍고 재현 가능한 확인(checks)을 통합함으로써, 엔지니어링 팀은 품질 위험을 더 일찍 눈에 띄게 하고 강력한 데이터 제공 관행의 기반을 마련할 수 있습니다.

DataGuard AI는 아직 공개 베타 버전이며, 커뮤니티 피드백을 환영합니다.

만약 Python, ETL, 데이터 거버넌스 또는 CI/CD 작업을 하신다면, 설치 경험, 검증 기능 및 개선 기회에 대한 여러분의 피드백을 부탁드립니다.

소스 코드 탐색: https://github.com/adiranjan25/dataguard-ai

PyPI에서 설치: https://pypi.org/project/dataguard-ai/**

기여 또는 이슈 보고: https://github.com/adiranjan25/dataguard-ai/issues