이 글에서 다루는 것
Drift Gate의 KS statistic 기반 검증, Promotion/Shadow 분기 정책, FastAPI 트래픽 분기(Mirror/Split) 전략
선수지식
Drift Gate / Promotion / Shadow
- 검증된 변경만 운영 경로에 올림
들어가며
모델 학습 파이프라인을 만들다 보면
다음 질문이 자연스럽게 등장합니다.
어떤 모델을 운영 환경에 반영할 것인가?
많은 프로젝트에서는 다음 기준을 사용합니다.
accuracy >= threshold
하지만 운영 환경에서는 이 기준만으로는 충분하지 않습니다.
예를 들어 다음 상황을 생각해볼 수 있습니다.
- 학습 데이터와 실제 서비스 데이터 분포가 다름
- 모델 성능이 특정 테스트셋에서는 높지만 실제 환경에서는 낮음
- 데이터 드리프트가 발생했지만 파이프라인이 이를 감지하지 못함
이런 상황에서 단순히 accuracy 기준만 사용하면
다음과 같은 위험이 생깁니다.
Train success
↓
Auto deploy
↓
Service degradation
그래서 이 플랫폼에서는 모델 학습 결과를
바로 운영 환경에 반영하지 않습니다.
대신 다음 세 가지 단계를 거칩니다.
Drift Gate
↓
Promotion Check
↓
Shadow Path
이 글에서는 이 구조를 설명합니다.
Drift Gate: 데이터 분포 검증
Drift Gate는 모델 성능 이전에 데이터 분포를 검증하는 단계입니다.
관련 코드:
dags/mlops_lib/quality/drift_gate.py
Drift Gate의 목적은 다음과 같습니다.
새로운 데이터
vs
기존 데이터
사이의 분포 차이를 확인하는 것입니다.
Drift Detection 방식
이 프로젝트에서는
KS statistic 기반 drift detection을 사용합니다.
KS statistic은 두 데이터 분포 사이의 최대 차이를 계산합니다.
코드 일부:
d_stat=_ks_stat(x,y)
여기서
x= 새 feature 데이터y= 기존 reference 데이터
입니다.
이 값이 일정 기준을 넘으면
데이터 드리프트로 판단합니다.
Drift 기준
드리프트 판단 기준은 policy 파일에서 관리됩니다.
관련 코드:
dags/mlops_lib/core/policy.py
예시 설정:
VAR_DRIFT_KS_STAT_THRESHOLD="drift_ks_stat_threshold"
기본값은 다음과 같습니다.
ks_stat_threshold = 0.20
즉,
KS statistic > 0.20
이면 드리프트로 판단합니다.
P-value 보조 검증
KS statistic D 값 외에
p-value를 함께 계산하여 통계적 유의성을 보강합니다.
코드 일부:
p_value = _ks_pvalue(d_stat, n, m)
여기서 Kolmogorov 분포의 점근 근사를 사용합니다.
p ≈ 2 * exp(-2 * D² * n*m/(n+m))
이 방식의 장점은 다음입니다.
- scipy 의존 없이 numpy만으로 계산 가능
- D 값만으로는 알 수 없는 샘플 크기 대비 통계적 신뢰도를 제공
- 2000 샘플에서 D=0.20은 극도로 유의미하지만, 50 샘플에서는 노이즈일 수 있음
즉 D 값과 p-value를 함께 보면
**“이 분포 차이가 우연일 확률”**까지 판단할 수 있습니다.
Drift Gate 처리 결과
Drift Gate는 단순히 로그만 남기지 않습니다.
결과는 Airflow XCom으로 전달됩니다.
코드 일부:
ti.xcom_push(key=XCOM_DRIFT_BLOCK_PROMOTION,value=block)
즉, 파이프라인에서 다음 정보를 전달합니다.
block_promotion = True / False
reason = drift explanation
이 값은 다음 단계에서 사용됩니다.
Drift 발생 시 처리
Drift가 발생하면
모델 학습 자체를 중단하지는 않습니다.
대신 다음 정책을 적용합니다.
Drift detected
↓
Promotion 차단
↓
Shadow 경로로 이동
즉,
모델은 학습되지만
운영 환경으로 바로 배포되지 않습니다.
Promotion Check
Drift Gate를 통과한 모델은
다음 단계에서 성능 검증을 받습니다.
예를 들어 다음 기준을 사용합니다.
accuracy >= threshold
이 기준은 다음 설정으로 관리됩니다.
VAR_ACCURACY_THRESHOLD
기본값 예시:
accuracy_threshold = 0.60
Promotion / Shadow 분기
모델 성능과 drift 결과에 따라
다음 경로가 결정됩니다.
1️⃣ 정상 promotion
drift 없음
AND
accuracy >= accuracy_threshold
→ 운영 경로 (모델 전환 + FastAPI reload)
2️⃣ shadow
accuracy < threshold
또는
drift detected
→ shadow 경로
4️⃣ promotion 차단
심각한 문제가 있는 경우
→ deploy 중단
예를 들어 다음 상황입니다.
- 데이터 품질 검증 실패 (validation error)
- Feature pipeline 실패
- 모델 학습 자체 실패
- 모델 artifact 생성 실패
- Triton READY 상태 확인 실패
이 경우 파이프라인은 shadow 경로로도 이동하지 않고 즉시 중단됩니다.
즉, 다음과 같은 구조입니다.
Train 실패
or
Artifact 문제
or
Serving 준비 실패
↓
Deploy 중단
Shadow 전략
Shadow 전략은 다음 목적을 가집니다.
운영 트래픽으로 모델을 테스트
하지만 사용자 응답에는 영향 없음
이 구조 덕분에 모델을 실제 환경에서 검증할 수 있습니다.
예를 들어 다음 방식입니다.
prod 요청
↓
primary → production model
shadow → candidate model
candidate 모델의 결과는 사용자에게 반환되지 않습니다.
대신 다음 용도로 사용됩니다.
- 성능 비교
- 오류 탐지
- latency 측정
FastAPI 트래픽 분기
Shadow 트래픽 분기는 FastAPI에서 처리됩니다.
관련 코드:
charts/fastapi/app/services/alias_selector.py
예시:
pct=_stable_pct_0_99(client_id)
이 방식은 다음 특징을 가집니다.
- client_id 기반 deterministic routing
- 동일 사용자 트래픽은 같은 모델로 이동
즉,
sticky traffic routing
이 가능합니다.
Mirror vs Split 전략
이 플랫폼에서는 두 가지 shadow 전략을 지원합니다.
Mirror
응답 → production model
shadow → background inference
사용자 응답에는 영향을 주지 않습니다.
Split
일부 트래픽 → shadow model
나머지 → production model
A/B 테스트에 가까운 방식입니다.
Drift Gate가 중요한 이유
Drift Gate는 단순한 품질 검증이 아닙니다.
오히려 다음 문제를 해결하기 위한 구조입니다.
문제 1
모델 성능이 좋지만
데이터 분포가 완전히 바뀐 경우
문제 2
학습 데이터와 실제 서비스 데이터가 다른 경우
문제 3
데이터 pipeline 오류
이런 상황에서 모델을 바로 배포하면
서비스 품질이 급격히 떨어질 수 있습니다.
그래서 Drift Gate는
운영 반영 이전에 데이터 상태를 확인하는 역할을 합니다.
핵심 메시지
이 플랫폼의 모델 배포 정책은 다음과 같습니다.
학습 성공 ≠ 운영 반영
대신 다음 구조를 사용합니다.
Drift Gate
↓
Performance Check
↓
Promotion / Shadow
이 구조 덕분에
- 데이터 문제
- 모델 성능 문제
- 운영 환경 문제
를 단계적으로 확인할 수 있습니다.
다음 글
지금까지는 모델 품질 검증 구조를 살펴보았습니다.
하지만 실제 ML 플랫폼에서 중요한 것은
모델 등록과 서빙 반영을 분리하는 것입니다.
다음 글에서는 다음 내용을 설명합니다.
- MLflow Model Registry 역할
- Triton Serving Runtime 구조
- FastAPI Reload 전략
- 서빙 전환 계층 설계
관련 코드:
charts/fastapi/app/routes/models.py
charts/fastapi/app/routes/reload.py
charts/triton/templates/deployment.yaml
docs/proof/latest/e2e_success/*
이를 통해
모델 등록과 실제 서비스 반영을 왜 분리해야 하는지
살펴보겠습니다.
설계 판단 (Why This Way?)
데이터 분포 변화가 모델 성능에 직접 영향을 주므로 Drift Gate를 모델 성능 검증보다 먼저 배치하고, 기준 미달 시 Shadow 경로로 운영 리스크를 분산합니다. client_id 기반 SHA256 deterministic routing으로 동일 사용자가 항상 같은 모델로 라우팅되어 A/B 테스트 결과의 일관성을 보장합니다.
다음에 읽을 글
→ GitOps 기반 E2E ML Platform - 모델 등록/서빙 반영 분리 — MLflow + Triton + FastAPI 서빙 구조