Model Training + HPO

Kurzzusammenfassung

• Diese Seite beschreibt den Schritt „Model Training + HPO“ (Training inkl. Hyperparameter-Optimierung) als Detail-Implementierung der Call Activity CallActivity_TrainHPO aus der Gesamtarchitektur.
• Input ist ein publiziertes Training Dataset aus Label Construction (Targets) (training_dataset_version), plus Run Context und eine versionierte Training Spec.
• Der Output ist ein Model Candidate (registriert in MLflow Model Registry, aber noch nicht promoted) sowie ein Training Report inkl. Referenzen (MLflow, OpenMetadata, Artefakte).
• BPMN-Leitpfad (Detail): Training Triggered -> Resolve Inputs + Start MLflow Run -> Prepare Time Split / CV Windows -> Run HPO Study -> Train Best Model -> Model-QA -> Training OK? -> Register Model Candidate -> Update Lineage + Metadata -> Finalize Parent Run -> Downstream Ready Signal.

Einordnung: Dieser Schritt liegt im Retrain-Pfad zwischen Label Construction (Targets) und Backtesting & Model Validation. Die Ausführung wird operativ über Scheduling getriggert (zeitbasiert oder on demand). Für Standards zu Tracking und Registry siehe MLflow Tracking und MLflow Model Registry.

Ziel

1. Reproduzierbares Training: Training ist strikt über training_dataset_version + training_spec_version referenziert und vollständig nachlaufbar.
2. Pragmatische HPO: HPO liefert bessere Parameter, bleibt aber budgetiert (Compute/Time) und transparent via MLflow (Parent/Child Runs).
3. Saubere Übergabe: Ein registrierter Model Candidate (inkl. model_uri) wird an Backtesting/Validierung übergeben – ohne implizite Promotion.
4. Traceability: Lineage und Artefakt-Referenzen werden konsistent in OpenMetadata und MLflow gepflegt.

Scope & Abgrenzung

In Scope (diese Seite):

• Training Run Setup (Inputs, Versionen, deterministische Seeds)
• Zeitbasierte CV-Splits (Leakage-Vermeidung)
• Hyperparameter-Optimierung (HPO) als Parent/Child Runs in MLflow
• Minimal-„Training QA“ (Sanity/Leakage-Guards auf Pipeline-Ebene)
• Registrierung eines Model Candidates in MLflow + Lineage Update (OpenMetadata)

Out of Scope (andere Seiten / BPMN-Schritte):

• Datenbeschaffung & Ingestion → Data Pipeline
• Purpose Gate / DQ Gate → Purpose & Data Quality
• Feature Engineering → Feature Pipeline
• Label Construction → Label Construction
• Backtesting/Validierung & Approval → Backtesting & Model Validation
• Promotion nach Staging/Prod → Promotion Strategy

Inputs

Model Training startet erst, wenn ein Training Dataset publiziert wurde. Alle Inputs sind als Contracts gedacht (klein, referenzierend, reproduzierbar).

1) Training Dataset Contract

Kommt aus Label Construction und referenziert die zu verwendende Trainingsdaten-Version.

Felder (gemäss BPMN-Contract):

• training_dataset_version
• feature_set_version
• dataset_version
• label_spec_version
• as_of_date
• universe_id
• qa_status
• artifact_uri
• dataset_source_uri
• dataset_fingerprint
• openmetadata_entity_ref
• mlflow_run_ref

Praktischer Standard: artifact_uri zeigt auf ein versioniertes, write-once Artefakt (z. B. Parquet + Manifest). dataset_fingerprint ist ein Hash/Fingerprint des Datasets/Manifests, nicht „nur“ ein Dateiname.

2) Run Context

Der Run Context ist die technische Klammer für Traceability (Prefect ↔ MLflow ↔ OpenMetadata).

Felder (gemäss BPMN-Contract):

• run_id
• trigger_reason
• pipeline_id
• pipeline_version
• as_of_date
• mlflow_experiment_name

3) Training Spec Version Contract

Die Training Spec ist die versionierte Definition der Trainingslogik (Modellfamilie, Zielmetrik, CV-/HPO-Settings, Seeds, Registry-Name).

Felder (gemäss BPMN-Contract):

• training_spec_version
• model_family
• objective_metric
• cv_settings
• hpo_budget
• search_space_ref
• random_seed
• registered_model_name

Praktischer Standard: Training Specs liegen als YAML/JSON im Repo (Review via PR). training_spec_version ist SemVer oder Git-Commit.

Beispiel (YAML):

training_spec_version: v1
registered_model_name: banana-rocket-score-model
model_family: "xgboost_ranker"

objective_metric: "ic_mean" # z.B. mean information coefficient (rank-correlation)
random_seed: 42

cv_settings:
  type: "rolling"
  train_years: 5
  val_months: 6
  step_months: 1
  embargo_days: 5
  purge_overlap: true

hpo_budget:
  max_trials: 40
  timeout_minutes: 60

search_space_ref: "repo://training/search_spaces/xgb_ranker_v1.yaml"

Output

1) Model Candidate Contract

Ein Model Candidate ist eine registrierte Model-Version in MLflow (Model Registry), die als Kandidat für den nächsten Schritt (Backtesting/Validierung) bereitsteht.

Felder (gemäss BPMN-Contract):

• model_candidate_version
• registered_model_name
• model_version
• model_uri
• training_dataset_version
• training_spec_version
• run_id
• pipeline_version
• best_trial_run_id
• best_params_ref
• metrics_summary_ref
• artifact_uri
• openmetadata_entity_ref
• mlflow_run_ref

Beispiel (JSON):

{
  "model_candidate_version": "mc__tds_fs_2026-02-14__ts_v1__2026-02-20T09:00Z",
  "registered_model_name": "banana-rocket",
  "model_version": "17",
  "model_uri": "models:/banana-rocket/17",
  "training_dataset_version": "tds__fs_2026-02-14__ls_v1__win_2018-01-02_2026-02-14",
  "training_spec_version": "v1",
  "run_id": "prefect-flow-run-9c8b12",
  "pipeline_version": "git:9f3c2ab",
  "best_trial_run_id": "mlflow-run-3f2c8d-trial-17",
  "best_params_ref": "s3://ml-artifacts/hpo/studies/2026-02-20/best_params.json",
  "metrics_summary_ref": "s3://ml-artifacts/hpo/studies/2026-02-20/metrics_summary.json",
  "artifact_uri": "s3://ml-artifacts/models/candidates/banana-rocket/17/",
  "openmetadata_entity_ref": {
    "service": "lakehouse",
    "database": "ml",
    "schema": "models",
    "table": "model_candidate__banana-rocket__v17"
  },
  "mlflow_run_ref": "mlflow://experiments/score-model/runs/3f2c8d"
}

2) Training Report Contract

Der Training Report beschreibt die Ergebnisse des Trainings inkl. HPO-Resultat und minimaler Training-QA (Sanity + Leakage-Guards). Er ist bewusst nicht „Backtesting“.

Felder (gemäss BPMN-Contract):

• run_id
• mlflow_parent_run_id
• best_trial_run_id
• training_dataset_version
• training_spec_version
• qa_status
• report_uri
• metrics_summary
• best_params
• cv_plan_ref

Beispiel (JSON):

{
  "run_id": "prefect-flow-run-9c8b12",
  "mlflow_parent_run_id": "mlflow-run-3f2c8d",
  "best_trial_run_id": "mlflow-run-3f2c8d-trial-17",
  "training_dataset_version": "tds__fs_2026-02-14__ls_v1__win_2018-01-02_2026-02-14",
  "training_spec_version": "v1",
  "qa_status": "PASS",
  "report_uri": "s3://ml-artifacts/reports/training/2026-02-20/report.json",
  "metrics_summary": {
    "ic_mean": 0.034,
    "ic_std": 0.011,
    "cv_folds": 12
  },
  "best_params": {
    "max_depth": 6,
    "learning_rate": 0.05,
    "subsample": 0.8
  },
  "cv_plan_ref": "s3://ml-artifacts/cv_plans/2026-02-20/cv_plan.json"
}

Ablauf

BPMN-Schritte → technische Umsetzung

BPMN-Element	Zweck	Output / Artefakte	Hinweise
StartEvent_TrainHPO – Training Triggered	Start nach publizierter training_dataset_version	Input Contracts + Run Context + Training Spec	Keine vorgelagerten Purpose/DQ/Label Gates in diesem Diagramm
ScriptTask_ResolveInputs – Resolve Inputs + Start MLflow Run	Inputs normalisieren, Training Dataset laden, MLflow Parent Run starten	normalisierter Run Context + mlflow_parent_run_id	Setze konsistente Tags/Params (siehe MLflow Abschnitt)
ScriptTask_PrepareCV – Prepare Time Split / CV Windows	Zeitbasierte Splits definieren (rolling/expanding)	cv_plan_ref (Artefakt)	Optional: embargo/purge gegen temporale Leakage-Effekte
ServiceTask_RunHPO – Run HPO Study (child runs)	HPO als Study mit Child Runs	best_trial_run_id, best_params_ref, Study Summary	Budgetiert (Trials/Timeout) – pragmatisch für Setup/Compute
ScriptTask_TrainBestModel – Train Best Model	Finales Training mit best_params	trained model + signature/input_example + training artefacts	Bereite Modell für Registry/Serving vor (Signature, Feature-Liste)
BusinessRuleTask_ModelQA – Model-QA	Minimal-QA (Sanity + Leakage-Guards) + Report erzeugen	Training Report Contract	Nicht mit Backtesting verwechseln (nächster Schritt)
Gateway_ModelOk – Training OK?	Entscheidung PASS/WARN/FAIL	Route OK vs FAIL	FAIL stoppt Candidate; WARN kann Candidate erzeugen (klar markiert)
ServiceTask_ModelFailAlert – Publish Training Report + Alert	Fail-Path: Report publizieren + Team informieren	Report URI + Logs	Kein Candidate
ServiceTask_RegisterModelCandidate – Log + Register Model Candidate	Modell loggen + neue Model Version registrieren	Model Candidate Contract	Keine Promotion (Staging/Prod) hier
ServiceTask_OpenMetadata – Update Lineage + Metadata	Lineage & Metadaten aktualisieren	OpenMetadata Edges/Refs	training_dataset_version -> model_candidate_version
ServiceTask_MLflowLog – Finalize Parent Run	Parent Run finalisieren, Referenzen konsolidieren	MLflow Run (stable refs)	Downstream konsumiert Candidate via model_uri + Contracts
ThrowEvent_ModelCandidateReady – Downstream Ready Signal	Handover an Backtesting/Validierung	Signal / Contract-Übergabe	Entspricht Übergang im Main-BPMN zu CallActivity_BacktestValidation

Training & HPO Design

Zeitbasierte Splits und Leakage-Vermeidung

Für EOD/long-horizon Stock-Picking ist zeitbasierte Cross-Validation der Standard:

• Rolling oder Expanding Windows (train/validation) basierend auf as_of_date / Trainingsfenster.
• Optional Embargo / Purge (wenn Features/Labels nahe am Split-Ende Leakage-Risiken haben).
• cv_plan_ref wird als Artefakt gespeichert (Vergleichbarkeit & Reproduzierbarkeit).

Wichtig: Der CV-Plan ist Teil der Training Spec (oder referenziert sie). So sind HPO-Ergebnisse später interpretierbar.

HPO (pragmatisch, aber sauber)

HPO wird bewusst „professionell, aber klein-team-tauglich“ umgesetzt:

• Budget: max_trials + timeout_minutes verhindert Runaway-Compute.
• Determinismus: random_seed fixieren.
• Transparenz: Jeder Trial als Child Run mit Params/Metrics.

Ergebnis-Standard:

• best_trial_run_id
• best_params_ref (z. B. JSON Artefakt)
• metrics_summary_ref (z. B. JSON Artefakt)

Minimal-Training-QA (vor Backtesting)

Training-QA ist eine technische und pipeline-spezifische Absicherung:

• Sanity Checks: Shapes, NaNs, Feature Columns, Output Range.
• Leakage Guards: Keine Nutzung von Future-Informationen im Join/Training.
• CV-/Holdout-Summary: Objective Metric + Varianz über Splits.

Output:

• qa_status in {PASS, WARN, FAIL}
• Training Report Contract (inkl. report_uri)

Ein PASS bedeutet „training pipeline ist gesund und Candidate ist registrierbar“ – nicht „Model ist validiert“. Validierung kommt im Backtesting-Step.

MLflow Integration

Dieser Step nutzt MLflow gemäss den Projektstandards unter:

• Experiments & Tracking
• Tracking
• Model Registry

Parent/Child Runs (HPO)

Empfohlenes Muster:

• Parent Run: gesamter Training+HPO Run (mlflow_parent_run_id)
• Child Runs: einzelne Trials (nested=true)
• Logge Params + Fold Metrics + Trial Artefakte

Minimum an Tags/Params (pragmatisch):

• Identität: pipeline_id, pipeline_version, run_id
• Daten: training_dataset_version, feature_set_version, dataset_version, label_spec_version
• Training: training_spec_version, model_family, objective_metric, random_seed
• Registry: registered_model_name, model_version, model_uri (nach Registrierung)

Dataset Logging

Praktischer Standard (wenn möglich):

• mlflow.log_input(...) / Dataset-Referenz (Source URI + Fingerprint)

Artefakte:

• cv_plan_ref
• Study Summary (HPO)
• Training Report (report_uri)
• Feature-Liste / Preprocessing Config
• Model Signature + Input Example

Model Registry: Candidate, nicht Promotion

In diesem Schritt wird nur ein Candidate erzeugt:

• Modell wird als neue Version in registered_model_name registriert.
• Output enthält model_uri (z. B. models:/name/version).
• Keine Stage-Promotion (Staging/Prod) in diesem Step.

Promotion/Go-Live ist ein separater Prozess (siehe Promotion Strategy).

OpenMetadata & Lineage

Im OpenMetadata-Update werden mindestens gepflegt:

• Lineage: training_dataset_version -> model_candidate_version
• Links/Refs:
  • training_spec_version
  • mlflow_parent_run_id, best_trial_run_id
  • model_uri
  • training_report_uri
• Tags/Description (kurz & hilfreich): Universe, Objective Metric, As-Of Date

Ziel: Downstream (Backtesting/Approval/Deployment) kann exakt referenzieren, welcher Candidate aus welchen Daten entstanden ist.

Triggering & Orchestrierung

Model Training + HPO läuft typischerweise im Retrain-Pfad:

• Retrain wird zeitbasiert (monatlich) oder on demand getriggert (siehe Scheduling).
• Model Training läuft in einem dedizierten Prefect Work Pool (z. B. train) mit geringer Parallelität (meist 1), damit Training nicht mit Ingestion/Scoring kollidiert.
• Inputs sind Contracts: Training lädt nie „irgendeinen latest snapshot“, sondern referenziert training_dataset_version.

BPMN-Detailansicht

Diagramm wird geladen …

⋮⋮⋮

Glossar-Begriffe

• Model – versionierte Abbildungslogik für Vorhersagen oder Empfehlungen
• MLflow – Plattform für Experiment-Tracking, Artefakte und Model Registry
• MLflow Model Version – eindeutig versioniertes Modellobjekt in der Registry
• Registry Stage – Freigabestatus einer Model Version
• Lineage – nachvollziehbare Herkunft und Transformation von Daten und Modellartefakten
• Feature – reproduzierbar berechnete Eingangsvariablen als Modellinput
• Output Contract – versioniertes Übergabe-Artefakt zwischen Prozessschritten

BPMN-Kontext

• IDs: CallActivity_TrainHPO
• Input-Bezug: Publizierte training_dataset_version plus Run Context und versionierte Training Spec.
• Entscheidungsbezug: Gateway_ModelOk entscheidet über PASS/WARN/FAIL für Candidate-Registrierung.
• Output-Bezug: Model Candidate Contract (model_uri) und Training Report Contract als Übergabe an Backtesting/Validierung.