Catalog registration

The choices in wizard steps 2, 3 and 7 (framework cards, model variants, hyperparameters) come from the training catalog. There is one catalog per framework key (the framework value of a training runtime variant). Importing an image and creating an external variant makes the image runnable, but without a catalog for the key that framework cannot be chosen in the wizard.

There are three ways to register a catalog. Whichever you use, the result is stored in the platform DB, and the on-screen defaults and ranges use the same values as the server's submission checks.

New tasks and new data kinds cannot be added through the catalog; choose from the fixed lists in the format below.

Catalog format#

geo-mlops/catalog/v1, written in YAML or JSON.

schema: geo-mlops/catalog/v1
framework:
  key: defect-clf               # framework key; must match the training runtime variant's framework
  label: Defect classifier      # wizard step 2 card name
  description: Predicts defects from tabular measurements
  badges: [tabular]             # card badges
  license: Proprietary
  data_kind: tabular            # image | tabular | pointcloud
  split_methods: [random, stratified]
  requires_gpu: false           # true rejects submissions without a GPU
models:
  - key: okng                   # passed as GEO_PARAM_MODEL
    task: classification
    label: OK/NG prediction
    classes_mode: none          # required | optional | none
    hyperparameters:
      iterations: {type: int, default: 300, min: 50, max: 2000, description: iterations}
      lr: {type: float, default: 0.08, min: 0.005, max: 0.5, description: learning rate}
  - key: type
    task: classification
    label: Defect type
    classes_mode: optional
    label_column: defectType    # required for tabular data that uses classes
    hyperparameters:
      iterations: {type: int, default: 300, min: 50, max: 2000}
      backbone: {type: str, default: catboost}

Unknown fields only produce a warning and are ignored. Validation errors are shown with line numbers.

Putting it in an image label#

Turn the catalog into one line of JSON and put it in the OCI label io.geo-mlops.catalog.v1. The size limit is 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

For a multi-architecture image the label of the first platform image is read; keep the label the same on every architecture.

The platform reads labels only from images in the platform registry: when an import finishes, when the same tag is pushed to the registry, and when an admin creates or edits a training runtime variant. It applies the label to the DB when:

• the variant's training framework equals the label's framework.key. Set the same key with Enter own key (자체 키 입력) when creating the variant.
• there is no tenant catalog for the key yet, or the existing one came from a label. A catalog an admin edited by hand is not overwritten; it only shows Differs from label (라벨과 다름).

See Training catalog for the full rules.

Values passed by the wizard#

The wizard passes the model key chosen in step 3 as GEO_PARAM_MODEL and the step 7 values as GEO_HP_*. One image may handle several model variants. Out-of-range values are rejected at submission.

If you run an external image as a built-in framework (for example YOLO), the step 7 keys are checked against that framework's allowed keys (for YOLO epochs, batch, imgsz, lr0 and so on) and only those are passed as GEO_HP_*. For the built-in runtimes' catalog combinations see Built-in training runtimes.

A model that trains in units other than epochs (for example boosting iterations) logs that value to MLflow as the param epochs; progress is computed from it.

Deliverables checklist#

• Image tar (docker save, gzip recommended) + tag name + sha256
• Catalog: the image label io.geo-mlops.catalog.v1, or a catalog.yaml (format above), or an hp_preset.yaml (format below) with the list and descriptions of model variants
• Proof that mlflow models serve passes: the model name and version used, request/response examples (Local verification)
• Input data: file kinds, label format (annotation files, CSV column, properties inside files); for tabular or time-series data, the column list, dtypes, missing-value handling, sampling period, window length
• Who performs the train/val split (the image by default)
• Inference response JSON structure and how the decision basis is expressed
• Resources: CPU/GPU count, memory and expected time for one training run; whether serving needs a CPU or GPU and the target response time. If it cannot run without a GPU, set requires_gpu: true in the catalog.
• A sample dataset to try training with

hp_preset.yaml format#

Write the hyperparameters each model variant exposes in the wizard as {default, min, max, description}. An admin merges it into the current catalog text with Import hp_preset.yaml (hp_preset.yaml 가져오기) in the editor. A model already present gets its whole hyperparameter table replaced; a missing model is added (it borrows the task of the first existing model, so check it before saving).

# hp_preset.yaml: hyperparameters per model variant
small-cnn:
  epochs:
    default: 20
    min: 1
    max: 500
    description: training epochs (progress basis)
  batch:
    default: 64
    min: 1
    max: 1024
    description: batch size
  lr:
    default: 0.001
    min: 0.000001
    max: 1.0
    description: learning rate
large-cnn:
  epochs:
    default: 50
    min: 1
    max: 500
    description: training epochs

• The type is inferred from default (integer, float, boolean, string). A fractional range makes it a float.
• Key rules and environment variable names are the same as in the catalog format above.

Pre-set experiments (presets)#

Frequently used setting combinations are defined as "go straight" presets. A preset fills every wizard step 1–10 and jumps to the review step. The format is the same as the submission config.

id: person-detect-yolo26n
name: Person detection (YOLO26n)
description: Train YOLO26n object detection on the Person dataset with default settings
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: ""        # empty means the framework defaults
  serving: { runtime: cpu }