ML 배치 작업 UI 가이드

GenD 는 MLflow Registry 에 등록된 모델로 스케줄링된 배치 추론 을 정의·운영할 수 있는 배치 작업 을 제공합니다. 사이드바 ML 허브 → 배포 & 서빙 의 탭으로 위치하며, 작업 정의 → 수동 트리거 → 실행 이력 → 드리프트 감지 결과까지 한 곳에서 확인할 수 있습니다.

본 가이드는 Epic #1083 M3 (UI partial) 의 산출물이며, 백엔드 M2 (PR #1237) 의 mutation API + manual trigger 위에서 동작합니다.

진입점

• 사이드바 → ML 허브 → 배포 & 서빙 → 배치 작업 탭
• 직접 URL: https://gend.genon.ai/ml-hub/serving?tab=batch (구 /ml-batch 는 자동 리디렉션)

기능 요약

기능	엔드포인트	권한	비고
목록 조회	GET /api/v1/ml/batch/jobs	viewer+	워크스페이스 펜스 자동 적용
작업 생성	POST /api/v1/ml/batch/jobs	admin	UNIQUE (workspace_id, name)
작업 수정	PUT /api/v1/ml/batch/jobs/{id}	admin	description / schedule / drift / status 만 가능
수동 실행	POST /api/v1/ml/batch/jobs/{id}/run	admin	M2 는 queued row 만 삽입, Dagster 트리거는 M3 후속
작업 삭제	DELETE /api/v1/ml/batch/jobs/{id}	admin	Soft delete (status='deleted'), 실행 이력은 CASCADE 보존
실행 이력 조회	GET /api/v1/ml/batch/runs?job_id=<id>	viewer+	드리프트 점수 / verdict 포함

참고: 비관리자는 목록 조회까지 가능하지만, 모든 mutating 액션 버튼은 비활성화됩니다. 백엔드 require_admin 이 fail-closed 로 동작하므로 403 round-trip 도 발생하지 않습니다.

신규 작업 등록

1. 페이지 헤더 우측 신규 작업 버튼 클릭.
2. 다이얼로그에서 다음 필드를 입력:
   • 이름 — 워크스페이스 내 유일. demo_credit_risk 같은 stable identifier.
   • MLflow 모델 — 등록 모델 이름. 자동완성 datalist 가 제공되지만 free-form 입력도 가능.
   • MLflow Alias — default Production. 실행 시 alias 가 concrete version 으로 frozen.
   • Dagster 소스 Asset — dot-separated AssetKey (예: iceberg.silver.demo_customers).
   • 출력 테이블 — Iceberg Gold 테이블 (예: iceberg.gold.predictions_demo_credit_risk).
   • 피처 컬럼 / ID 컬럼 — 쉼표 구분. 둘 다 비어 있으면 안 됨.
   • Cron 스케줄 — UTC. 비워두면 수동 트리거만 가능.
   • 드리프트 감지 — 기본 ON, 임계값 default 0.3 (PSI/KS).
3. 생성 버튼 클릭.

불변 필드 (Immutable on PUT)

다음 필드는 작업 생성 후 변경할 수 없습니다. 변경이 필요하면 새 작업으로 정의 해야 합니다.

• name / model_name / model_alias
• source_asset / feature_columns / id_columns
• output_table

이유: model_name 재바인딩은 live schedule 의 scoring logic 을 silent 하게 교체할 수 있고, source_asset / feature_columns 재바인딩은 같은 스케줄이 완전히 다른 row / shape 을 scoring 하게 만듭니다. 감사 추적 보존을 위해 PUT 에서 22 fail-closed 로 거부합니다.

수동 실행 (Run Now)

1. 작업 목록 행에서 지금 실행 클릭, 또는 상세 시트 헤더의 동일 버튼.
2. 새 ml_batch_run row 가 status='queued' 로 삽입됩니다.
3. M2 단계에서는 Dagster launchRun GraphQL 호출 + lineage emit 은 M3 후속으로 미뤄져 있어, 운영자는 Dagster UI 의 sensor 가 queued → running 으로 promote 하기까지 기다리거나, M3 PR 이 머지되기 전까지는 수동으로 promote 해야 합니다.

실행 이력 + 드리프트

상세 시트 하단의 실행 이력 테이블 컬럼:

컬럼	비고
시작 / 종료	started_at / finished_at
상태	queued / running / success / failed / cancelled
입력 rows / 출력 rows	rows_in / rows_written
드리프트 점수	drift_score (PSI/KS, 소수점 3자리)
드리프트 verdict	ok (녹색) / warn (노랑) / breach (빨강)
MLflow	mlflow_run_id 클릭 → MLflow UI 새 탭으로 점프

드리프트 점수가 drift_threshold 를 초과하면 breach, 70% 를 초과하면 warn 입니다. 임계값은 PUT 으로 언제든 조정 가능합니다.

삭제 (Soft delete)

• 삭제 버튼 클릭 → 확인 다이얼로그 → 실행 시 status='deleted' 로 flip.
• 실행 이력 (ml_batch_run) 은 FK CASCADE 로 보존됩니다.
• 삭제된 작업은 수정 / 트리거가 모두 차단되며, UI 도 액션 버튼을 비활성화합니다.

알려진 제약 (M3 partial)

• 백엔드 M2 는 manual trigger 시 queued row 만 삽입합니다. Dagster GraphQL launchRun 실제 호출 + Marquez lineage emit + DataMart auto-registration 은 M3 후속 PR 에서 추가됩니다.
• 드리프트 점수 계산은 M2 의 interface stub — 실제 Iceberg fetch + Evidently HTML upload 는 Dagster webhook 과 함께 M3 에서 실 ETL 으로 활성화됩니다.
• executor 는 pandas 만 허용됩니다. spark 는 M3 / M4 에서 ORM CheckConstraint 와 함께 확장됩니다.

관련 자료

• 백엔드 라우터: apps/api/src/gend_api/routers/ml_batch.py
• Pydantic 모델: apps/api/src/gend_api/models/ml_batch.py
• Dagster asset factory: pipelines/gend_pipelines/ml/batch_predict_asset.py
• 모델 배포 UI 가이드: model-deployment-ui.md