카탈로그 등록

마법사 2·3·7단계의 선택지(프레임워크 카드, 모델 변형, 하이퍼파라미터)는 학습 카탈로그가 결정. 카탈로그는 프레임워크 키(학습 런타임 변형의 프레임워크 값)마다 하나. 이미지를 반입해 외부 변형만 만들면 이미지는 실행되지만, 그 키의 카탈로그가 없으면 마법사에서 그 프레임워크를 선택할 수 없음.

카탈로그를 등록하는 방법은 세 가지. 어느 쪽이든 결과는 플랫폼 DB 에 저장되고, 화면의 기본값·범위와 서버의 제출 검증이 같은 값 사용.

새 태스크와 새 데이터 종류는 카탈로그로 추가 불가. 아래 형식의 고정 목록 중에서 선택.

카탈로그 형식#

geo-mlops/catalog/v1. YAML 이나 JSON 으로 작성.

schema: geo-mlops/catalog/v1
framework:
  key: defect-clf               # 프레임워크 키. 학습 런타임 변형의 프레임워크와 같아야 함
  label: 결함 분류기             # 마법사 2단계 카드 이름
  description: 표 형식 측정값으로 불량을 예측
  badges: [tabular]             # 카드 배지
  license: Proprietary
  data_kind: tabular            # image | tabular | pointcloud
  split_methods: [random, stratified]
  requires_gpu: false           # true 면 GPU 없이 제출 거절
models:
  - key: okng                   # GEO_PARAM_MODEL 로 전달
    task: classification
    label: 양불 예측
    classes_mode: none          # required | optional | none
    hyperparameters:
      iterations: {type: int, default: 300, min: 50, max: 2000, description: 반복 수}
      lr: {type: float, default: 0.08, min: 0.005, max: 0.5, description: 학습률}
  - key: type
    task: classification
    label: 불량 유형 분류
    classes_mode: optional
    label_column: defectType    # 표 형식에서 클래스를 쓰면 필수
    hyperparameters:
      iterations: {type: int, default: 300, min: 50, max: 2000}
      backbone: {type: str, default: catboost}

모르는 항목은 경고만 내고 무시. 검증 오류는 행 번호와 함께 표시.

이미지 라벨로 포함하기#

카탈로그를 한 줄 JSON 으로 바꿔 OCI 라벨 io.geo-mlops.catalog.v1 에 넣음. 크기 상한은 64 KiB.

python3 -c 'import json, yaml; print(json.dumps(yaml.safe_load(open("catalog.yaml")), ensure_ascii=False, separators=(",", ":")))' > catalog.json
docker build --label io.geo-mlops.catalog.v1="$(cat catalog.json)" -t defect-clf-trainer:v1 .
docker image inspect --format '{{ index .Config.Labels "io.geo-mlops.catalog.v1" }}' defect-clf-trainer:v1

멀티 아키텍처 이미지는 첫 번째 플랫폼 이미지의 라벨을 읽음. 아키텍처마다 같은 라벨 권장.

플랫폼은 플랫폼 레지스트리에 있는 이미지만 라벨을 읽음. 반입이 끝날 때, 레지스트리에 같은 태그로 push 될 때, 관리자가 학습 런타임 변형을 만들거나 수정할 때 읽고, 아래 조건이면 DB 에 반영.

• 변형의 학습 프레임워크가 라벨의 framework.key 와 같음. 변형을 만들 때 자체 키 입력 으로 같은 키 지정.
• 그 키의 테넌트 카탈로그가 없거나, 있어도 라벨에서 들어온 것. 관리자가 직접 편집한 카탈로그는 자동으로 덮어쓰지 않고 라벨과 다름 으로만 표시.

자세한 반영 규칙은 학습 카탈로그 참고.

마법사로 전달되는 값#

마법사는 3단계에서 선택한 모델 키를 GEO_PARAM_MODEL 로, 7단계 값을 GEO_HP_* 로 전달. 한 이미지가 여러 모델 변형을 처리해도 무방. 범위를 벗어난 값은 제출 시 거절.

외부 이미지를 내장 프레임워크(예: YOLO)로 실행하면 7단계 키는 그 프레임워크의 허용 키(YOLO 는 epochs, batch, imgsz, lr0 등)로 검사되고 그 키만 GEO_HP_* 로 전달. 내장 런타임의 카탈로그 조합은 내장 학습 런타임 참고.

epoch 과 다른 단위로 학습하는 모델(예: 부스팅 반복 수)은 그 값을 param epochs 로 MLflow 에 기록. 진행률이 그 값으로 계산.

전달물 체크리스트#

• 이미지 tar(docker save, gzip 권장) + 태그 이름 + sha256
• 카탈로그: 이미지 라벨 io.geo-mlops.catalog.v1, 또는 catalog.yaml(위 형식), 또는 hp_preset.yaml(아래 형식)과 모델 변형 목록·설명
• mlflow models serve 검증 통과 기록: 사용한 모델 이름·버전, 요청/응답 예시(로컬 검증)
• 입력 데이터: 파일 종류, 라벨 형식(어노테이션 파일, CSV 컬럼, 파일 내부 속성), 표·시계열이면 컬럼 목록, dtype, 결측 처리, 샘플링 주기, 윈도우 길이
• train/val 분할 수행 주체(기본은 이미지)
• 추론 응답 JSON 구조와 판정 근거 표현
• 자원: 학습 1건의 CPU/GPU 수, 메모리, 예상 시간, 서빙 CPU/GPU 여부와 목표 응답 시간. GPU 없이 실행되지 않으면 카탈로그에 requires_gpu: true.
• 학습을 시험할 수 있는 샘플 데이터셋

hp_preset.yaml 형식#

모델 변형마다 마법사에 노출할 하이퍼파라미터를 {default, min, max, description} 으로 작성. 관리자가 편집 화면의 hp_preset.yaml 가져오기 로 지금 카탈로그 본문에 합침. 같은 모델은 하이퍼파라미터 표 전체가 바뀌고, 없는 모델은 새로 추가(태스크는 기존 첫 모델의 것을 사용하므로 저장 전에 확인).

# hp_preset.yaml: 모델 변형별 하이퍼파라미터
small-cnn:
  epochs:
    default: 20
    min: 1
    max: 500
    description: 학습 epoch 수 (진행률 기준)
  batch:
    default: 64
    min: 1
    max: 1024
    description: 배치 크기
  lr:
    default: 0.001
    min: 0.000001
    max: 1.0
    description: 학습률
large-cnn:
  epochs:
    default: 50
    min: 1
    max: 500
    description: 학습 epoch 수

• 타입은 default 에서 추정(정수, 실수, 참거짓, 문자열). 범위가 소수면 실수로 처리.
• 키 규칙과 환경 변수 이름은 위 카탈로그 형식과 같음.

미리 지정된 실험(프리셋)#

자주 사용하는 설정 조합은 "바로 진행" 프리셋으로 정의. 프리셋은 마법사 1~10단계 전체를 채우고 검토 단계로 건너뜀. 형식은 제출 설정과 동일.

id: person-detect-yolo26n
name: Person 탐지 (YOLO26n)
description: Person 데이터셋으로 YOLO26n 객체 탐지를 기본 설정으로 학습
config:
  task: object_detection
  framework: yolo
  model: yolo26n
  dataset_id: person
  classes: [person_poly, person_bmp]
  split: { method: random, train_percent: 80, seed: 0 }
  hyperparameters: ""        # 비우면 프레임워크 기본값
  serving: { runtime: cpu }