모델 배포 UI 가이드

GenD 는 MLflow Registry 에 등록된 모델을 KServe InferenceService 로 배포하고, 카나리 트래픽 / 승격 / 롤백 / 예측 테스트를 한 곳에서 수행할 수 있는 모델 배포 페이지 를 제공합니다.

본 페이지는 Epic #1082 Gap 2 (KServe automation) M3 의 UI 산출물입니다. 백엔드는 M1+M2 (POST/PUT/DELETE /api/v1/serving/deployments, /deploy /promote /rollback /predict 5 액션) 으로 이미 운영 중입니다.

진입점

사이드바 ML 허브 → 배포 & 서빙 (/ml-hub/serving?tab=deployments, 구 /models/deployments 는 자동 리디렉션)
등록 모델 카드의 Deploy 버튼 (/ml-hub/models?tab=registered → 다이얼로그)

등록 모델에서 배포 시작

사이드바 → ML 허브 → 모델 스테이지 (/ml-hub/models?tab=registered) 진입
배포할 모델 카드 우하단의 Deploy 버튼 클릭
다이얼로그에서 입력
- endpoint_name (필수) — KServe InferenceService 이름. ^[a-z0-9-]+$ 컨벤션 권장 (백엔드가 normalize)
- replicas — 1~10 (M1/M2 는 min=max 고정)
- resource_profile — small / medium / large / gpu-t4
- canary_percent — 슬라이더로 0~100% 초기값 설정
Deploy 클릭 → 행 생성 + /ml-hub/serving?tab=deployments 로 자동 이동

model_name 과 model_version 은 선택한 카드에서 자동 채워지며 다이얼로그에서 잠겨 있습니다. 다른 모델/버전으로 배포하려면 해당 카드의 Deploy 버튼을 다시 클릭하세요.

배포 라이프사이클

승격 (Promote) — 카나리를 100% 트래픽으로 전환. KServe spec.predictor.canaryTrafficPercent 패치 + DB 동기화.
롤백 (Rollback) — 카나리를 0% 로 재설정. 이전 안정 리비전 으로 트래픽 완전 복귀.
삭제 (Delete) — Soft delete. 행은 status='deleted' 로 보존되며 InferenceService 만 회수됩니다. 동일 endpoint_name 재사용은 불가 — 다른 이름으로 재배포 해야 합니다.

상세 패널 — 카나리 슬라이더 + /predict 테스터

행 우측 상세 버튼을 클릭하면 우측 시트가 열립니다.

카나리 슬라이더

0~100% 5% 단위 조정
카나리 저장 버튼 으로 PUT /deployments/{id} 호출 (canary_percent 필드만 전송)
관리자 (Keycloak admin role) 만 변경 가능 — 비관리자는 슬라이더/저장 버튼이 disabled 되고 "관리자만 변경 가능합니다." 안내가 표시됩니다

/predict 테스터

배포된 엔드포인트를 시트에서 바로 호출해 ABAC + 카나리 분기를 검증합니다. 기본은 피처 폼 모드 입니다 — JSON 본문을 직접 작성할 필요 없이 피처 이름/값을 입력하면 KServe v2 요청이 자동 구성됩니다.

피처 폼 모드 (기본)

predict 피처 폼 — 스키마 자동 채움

ready 배포의 시트를 열면 학습 시점 피처 스키마(GET /api/v1/serving/{name}/schema)를 조회해 피처 이름이 자동으로 채워집니다 (값은 비워 둠). 스키마가 없거나 조회에 실패하면 빈 행 1개가 표시되며, 수동으로 행을 추가해 동일하게 동작합니다.
각 행에 값을 입력하고 전송 을 클릭하면 단일 텐서 KServe v2 본문(shape: [1, N])이 자동 생성되어 POST /api/v1/serving/{endpoint_name}/predict 로 전송됩니다.
모든 값이 숫자면 datatype: FP64, 하나라도 숫자가 아니면 BYTES 로 전송됩니다 — 숫자 피처에 문자열을 넣으면 대부분의 모델 런타임이 예측 에러를 반환하며, 에러는 시트 안에 그대로 표시됩니다.

고급 (raw JSON) 모드

고급 (raw JSON) 토글을 켜면 기존처럼 KServe v2 Open Inference Protocol JSON 본문을 직접 작성할 수 있습니다. 폼 → 고급 전환 시 현재 폼 입력이 v2 본문으로 직렬화되어 보존되고, 고급 → 폼 복귀 시 단일 텐서 본문이면 값이 폼으로 복원됩니다 (다중 텐서 등 복원 불가 형태는 안내 문구와 함께 폼이 초기화됩니다).

고급 모드 본문 예시 (3 피처 입력 텐서):

{
  "inputs": [
    {
      "name": "input",
      "datatype": "FP64",
      "shape": [1, 3],
      "data": [[35, 52000, 8]]
    }
  ]
}

예측값 요약

predict 예측값 요약

응답이 v2 형태(outputs[0].data)면 "예측값: …" 요약이 먼저 표시되고, 원본 JSON 은 원본 JSON 응답 접기로 확인합니다
v2 가 아닌 응답은 기존처럼 raw JSON 으로 표시됩니다
에러 케이스:
- 403 — ABAC ModelGrant.check_access 거부 (subject_type=user 가 invoke action 권한 미보유)
- 409 — 행이 soft-delete 됐거나 /deploy 미실행
- 502 — KServe 업스트림 장애 (Prometheus 메트릭 + 백엔드 audit log 확인)

/predict 본문은 PII 마스킹 통과 가 M3 후속 작업으로 분리되어 있습니다. 현재 단계에서는 운영 환경에서 실제 PII 입력은 피하고, 합성 텐서 또는 비식별 샘플로만 검증하세요.

권한 (admin 가드)

액션	백엔드 보호	UI 가드
GET 목록 / 상세	`require_viewer`	모두 가능
POST 신규 배포	`require_analyst`	admin role 만 활성화
PUT 카나리/리소스	`require_analyst`	admin role 만 활성화
Promote / Rollback	`require_analyst`	admin role 만 활성화
Soft delete	`require_analyst`	admin role 만 활성화
POST /predict	`require_viewer` + ABAC	UI 전체 허용 (백엔드 ABAC fail-closed)

UI 는 비관리자가 burning 403 round-trip 을 피하도록 액션 버튼을 비활성화합니다. 실제 권한 enforcement 는 백엔드 require_analyst + workspace fence 가 단일 진실의 원천입니다.

트러블슈팅

증상	원인 후보	조치
배포 행은 생성됐지만 status=pending 고정	`/deploy` 미실행 — UI 의 신규 배포 다이얼로그는 행만 생성합니다. M3 후속에서 자동 deploy 옵션 추가 예정	`gend serving deploy <id>` (CLI) 또는 API 직접 호출
Promote / Rollback 클릭 시 409	`k8s_resource_name IS NULL` (한번도 deploy 안 됨)	먼저 `/deploy` 호출
/predict 가 403	ABAC ModelGrant 부재	`/admin/data-grants` 또는 `gend gov grant` 로 grant 추가
/predict 응답이 PII 포함	마스킹 미적용 (M3 후속)	운영 데이터는 사용 금지, 합성 샘플만 권장
동일 endpoint_name 재배포 시 409	soft-delete 행이 같은 이름을 점유	다른 endpoint_name 선택, 또는 admin 이 force purge (M3 후속)

변경 이력

2026-06-12 — /predict 테스터 폼 UX 반영 (#2103/#2111/#2112/#2130). 피처 폼 모드 기본 + 스키마 자동 채움 + 고급 (raw JSON) 토글 (왕복 입력 보존) + "예측값" 요약/원본 JSON 접기. 비관리자 카나리 안내 카피 명시.
2026-05-28 — M3 UI 초판 (Epic #1082 Gap 2). 사이드바 메뉴 + /models/deployments 페이지 + 등록 모델 카드 Deploy 액션 + 우측 상세 시트 (카나리 슬라이더 + /predict 테스터) + i18n ko/en.

진입점​

등록 모델에서 배포 시작​

배포 라이프사이클​

상세 패널 — 카나리 슬라이더 + /predict 테스터​

카나리 슬라이더​

/predict 테스터​

피처 폼 모드 (기본)​

고급 (raw JSON) 모드​

예측값 요약​

권한 (admin 가드)​

트러블슈팅​

관련 문서​

변경 이력​

진입점