Evidently AI 실무 스터디 가이드

1. Evidently AI란?

Evidently AI는 머신러닝 모델의 데이터 드리프트, 모델 성능 저하, 대상 드리프트를 실시간으로 탐지하고 시각화하는 오픈소스 모니터링 라이브러리입니다. ML 파이프라인에 쉽게 통합되어 프로덕션 모델의 건강 상태를 지속적으로 추적할 수 있습니다.

3대 핵심 능력

📊 데이터 드리프트

입력 데이터 분포 변화를 통계적 검정(PSI, KS, Jensen-Shannon 등)으로 감지합니다.

📈 모델 성능 모니터링

정확도, 정밀도, 재현율, AUC 등 메트릭을 시간에 따라 추적하고 이상 징후를 알립니다.

🎯 대상 드리프트

예측값과 실제 레이블의 분포 변화를 관찰하여 모델 출력의 신뢰도를 평가합니다.

💡 Tip: Evidently는 단일 노트북부터 대규모 Kubernetes 기반 파이프라인까지 확장 가능합니다.

2. 왜 써야 하는가?

기존 모니터링 대안(Alibi Detect, WhyLabs, NannyML)과 비교한 Evidently의 주요 차별점은 직관적인 리포트 UI, 다양한 드리프트 검정 방법, 오픈소스 기반의 유연한 커스터마이징입니다.

비교 항목	Evidently AI	Alibi Detect	WhyLabs	NannyML
라이선스	Apache 2.0	Apache 2.0	SaaS/부분 유료	Apache 2.0
드리프트 검정 다양성	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐
리포트/대시보드	✅ HTML, JSON, Colab	❌ (API 위주)	✅ SaaS 대시보드	✅ PDF/HTML
배포 난이도	낮음 (pip install)	중간	낮음 (SDK)	낮음
실시간 알림	✅ (커스텀 가능)	❌	✅	✅ (유료)

⚠️ 주의: WhyLabs는 클라우드 종속성이 있고, Alibi Detect는 시각화 기능이 부족합니다. Evidently는 로컬/프라이빗 환경에서 완전한 모니터링을 원하는 팀에 적합합니다.

3. 핵심 개념

Evidently는 Reports와 Test Suites라는 두 가지 주요 구성 요소로 동작합니다. 보고서는 탐색적 분석에, 테스트 스위트는 CI/CD 파이프라인에 적합합니다.

주요 객체

Report — 드리프트, 성능, 데이터 품질 등 복합 메트릭을 HTML/JSON으로 생성
TestSuite — 사전 정의된 조건을 기반으로 Pass/Fail 판정 (CI/CD 통합)
ColumnMapping — 타겟, 예측, 특성 컬럼을 매핑하는 설정
Profile — 보고서 생성을 위한 중간 데이터 구조 (v0.4.x 이후 Report로 통합)

4. 퀵스타트

4-1. 설치

# 최신 버전 설치 (pip)
pip install evidently

# 특정 버전 (권장: 0.4.x 이상)
pip install evidently==0.4.28

4-2. 기본 설정

import pandas as pd
from evidently.report import Report
from evidently.metric_preset import DataDriftPreset

# 1. 데이터 준비 (reference: 학습 시, production: 현재)
reference = pd.read_csv("reference_data.csv")
production = pd.read_csv("production_data.csv")

# 2. 리포트 생성
report = Report(metrics=[
    DataDriftPreset(stattest="ks", stattest_threshold=0.05)
])

# 3. 실행
report.run(reference_data=reference, current_data=production)

# 4. 저장 / 보기
report.save_html("drift_report.html")
report.json()  # JSON 형태로도 출력 가능

4-3. 첫 번째 예제 — CLI로 빠르게 확인

# CLI로 리포트 생성 (데이터 파일 필요)
evidently --reference reference.csv --current production.csv \
         --report drift --output report.html

# 도움말
evidently --help

💡 Tip: 노트북 환경에서는 report.show()를 사용하면 인라인으로 바로 시각화할 수 있습니다.

5. 핵심 설정 레퍼런스

파라미터 / 설정	타입	기본값	설명
`stattest`	str	"ks"	드리프트 검정 통계량: "ks", "chi-square", "wasserstein", "jensenshannon" 등
`stattest_threshold`	float	0.05	p-value 임계값, 이보다 작으면 드리프트로 판정
`ColumnMapping.target`	str / None	None	타겟 컬럼명 (실제 레이블)
`ColumnMapping.prediction`	str / list	None	예측 컬럼명 (분류: 확률 리스트 가능)
`ColumnMapping.numerical_features`	list	모든 숫자형	분석할 숫자 특성 리스트
`ColumnMapping.categorical_features`	list	모든 범주형	분석할 범주 특성 리스트
`DataDriftPreset.agg_method`	str	"avg"	특성 그룹화 시 집계 방식 ("avg", "max", "min")
`Report.include`	dict	—	포함/제외할 특성 지정 (예: `{"include": ["feat1"]}`)

⚠️ 주의: stattest_threshold를 너무 낮게 설정하면 민감도가 높아져 잦은 알람이 발생할 수 있습니다. 도메인에 따라 0.01~0.1 사이를 권장합니다.

6. 실무 팁 & 트러블슈팅

자주 겪는 문제와 해결책

문제	원인	해결책
`KeyError`: 타겟/예측 컬럼 없음	`ColumnMapping` 미설정	명시적으로 `ColumnMapping(target='y', prediction='pred')` 설정
리포트가 너무 느림	특성 수가 많거나 데이터 크기가 큼	`include`/`exclude`로 특성 축소, 또는 샘플링 사용
드리프트가 항상 탐지됨	임계값이 너무 낮거나 데이터에 잡음이 많음	`stattest_threshold`를 0.05→0.01로 낮추거나, 다른 통계량 사용
CLI 명령어 에러	파일 경로 문제 또는 버전 불일치	`pip install --upgrade evidently` 후 절대 경로 사용
HTML 리포트가 열리지 않음	브라우저 보안 정책 (로컬 파일)	`--allow-file-access` 플래그로 열거나, http 서버 사용

실무 팁

Reference 데이터 선정: 모델 학습 시점의 1~2주치 데이터를 사용하세요. 너무 짧으면 계절성 드리프트에 둔감해집니다.
알림 연동: Test Suite의 결과를 Slack Webhook이나 PagerDuty로 전송하여 자동 대응 체계를 구축하세요.
버전 관리: 모델 버전마다 Reference 데이터와 리포트를 함께 저장하여 회귀 분석에 활용하세요.
분할 모니터링: 전체 데이터 대신 세그먼트(지역, 사용자 그룹)별로 드리프트를 분석하면 더 세밀한 인사이트를 얻을 수 있습니다.

7. 참고 자료

💡 Tip: 공식 문서의 “How-to Guides” 섹션에서 실전 통합 예제를 확인하세요.