Zum Hauptinhalt springen

Zentrale Konzepte

Kurzzusammenfassung​

  • Die Optimorum ML Platform ist contract‑basiert: Jeder Pipeline‑Schritt publiziert ein versioniertes Artefakt plus einen Output‑Contract (als „Übergabeobjekt“ an Downstream‑Schritte).
  • Versionen sind write‑once und reproduzierbar. Downstream arbeitet niemals auf „latest file“/„latest table“, sondern auf *_version + as_of_date.
  • Gates (Purpose, Data Quality, Pilot/Production Readiness) und QA‑Checks (Feature‑QA, Label‑QA, Model‑QA) erzeugen evidence (Reports) und steuern, ob neue Versionen publiziert werden.
  • OpenMetadata ist der Katalog für Owner/Purpose/Lineage/DQ‑Status; MLflow ist das System für Training/HPO/Artefakte/Model Registry.

Einordnung: Die zentrale Ablaufkette ist in der Gesamtarchitektur dokumentiert: /docs/platform/architecture.

Ziel​

Diese Seite definiert eine gemeinsame Sprache für:

  1. Artefakte & IDs (Dataset, Feature Set, Training Dataset, Model Candidate, Signal/Score)
  2. Contracts als stabile Schnittstelle zwischen BPMN‑Schritten
  3. Lineage & Evidence (OpenMetadata/MLflow/Reports)
  4. Gates & Promotion (pragmatische Governance für ein kleines Team)

Scope & Abgrenzung​

In Scope

  • Begriffsklärungen & Minimal‑Contracts
  • ID‑/Versionierungsprinzipien
  • Status‑Semantik (PASS/WARN/FAIL) und „publishable vs. stop“

Out of Scope

  • Implementierungsdetails einzelner Tasks (SQL, Python, Infra)
  • Runbooks / Incident Playbooks (eigene Seiten)

Grundprinzip: Contracts statt „implizite Übergaben“​

Was ist ein Contract?​

Ein Contract ist ein (meist JSON‑ähnliches) Objekt, das ein Artefakt eindeutig referenziert und alle minimalen Metadaten trägt, die Downstream braucht:

  • Welche Version (z.B. dataset_version, feature_set_version, …)
  • Welche Zeit (as_of_date, Window‑Grenzen)
  • Welche Ausführung (run_id, pipeline_version)
  • Welcher Status (quality_status bzw. qa_status)
  • Wo liegt das Artefakt / Evidence (artifact_uri, dq_report_uri, report_uri, …)
  • Wie ist die Lineage (openmetadata_entity_ref, mlflow_run_ref)

Merksatz: Artefakte sind Daten – Contracts sind die API.

Run Context​

Jeder Run wird über einen Run Context identifizierbar:

  • run_id (Orchestrator Run, z.B. Prefect Flow Run ID)
  • pipeline_id / pipeline_version (z.B. Git Commit)
  • trigger_reason (schedule, new_data, backfill, manual)
  • as_of_date (die „Stichtagslogik“ der Pipeline)

Das ist entscheidend für Reproduzierbarkeit und Audit‑Traceability.

Status-Semantik​

Wir unterscheiden zwei nahe verwandte, aber bewusst getrennte Status‑Typen:

  • quality_status: Ergebnis der DQ‑Suite auf einem validierten curated dataset (PASS/WARN/FAIL).
  • qa_status: Schritt‑spezifische QA (Feature‑QA, Label‑QA, Model‑QA).

Leitlinie (pragmatisch):

  • PASS: publishable
  • WARN: publishable, aber mit Flag + Evidence (Review empfohlen)
  • FAIL: keine neue Version publizieren, Downstream nutzt last known good Version

Kern-Artefakte der Plattform​

Die folgenden Artefakte sind die „Währung“ der Architektur. Jedes Artefakt hat eine Version und wird über Contracts übergeben.

1) Validated Curated Dataset​

Definition
Ein validated curated dataset ist ein domänenneutral harmonisiertes, validiertes Dataset in der Internal Data Zone. Es ist der Upstream‑Input für Feature Pipeline, Label Construction und Backtests.

Contract-Name (konzeptuell)

  • OutputContract_ValidatedCuratedDataset

Minimale Pflichtfelder (aus der Data Pipeline Logik)

  • dataset_id
  • dataset_version
  • as_of_date
  • run_id
  • pipeline_version
  • provider
  • schema_version
  • schema_hash
  • quality_status
  • row_count
  • content_hash
  • dq_report_uri
  • openmetadata_entity_ref
  • allowed_use
  • classification
  • retention_policy

Hinweis: Der Contract ist gleichzeitig die Schnittstelle zu Gate A (Purpose/Entitlement) und zum DQ‑Gate.

Warum ist das wichtig?

  • Downstream kann strikt auf dataset_version referenzieren (keine „moving target“).
  • DQ‑Reports sind als Evidence referenziert (dq_report_uri).

2) Feature Set Version​

Definition
Ein Feature Set ist eine versionierte Sammlung von Features (inkl. Manifest), die für Training/Scoring reproduzierbar geladen werden kann.

Contract-Name (konzeptuell)

  • OutputContract_FeatureSetVersion

Minimale Pflichtfelder

  • feature_set_id
  • feature_set_version
  • dataset_version
  • run_id
  • pipeline_version
  • as_of_date
  • universe_id
  • feature_manifest_uri
  • qa_status
  • openmetadata_entity_ref
  • mlflow_run_ref

Interpretation

  • feature_set_id ist der stabile „Name“ (z.B. fs_equity_daily_v1)
  • feature_set_version ist die konkrete Publikation (immutable)
  • feature_manifest_uri referenziert die Feature‑Definitionen/Spalten/Checksums

3) Label Spec und Training Dataset Version​

Definition
Label Spec beschreibt wie Targets/Labels berechnet werden (z.B. Horizon, Benchmark‑Optionen).
Training Dataset ist das jointe Artefakt aus Features + Labels (Leakage‑frei aligned).

Contracts (konzeptuell)

  • Input: InputContract_FeatureSetVersion + InputContract_LabelSpec
  • Output: OutputContract_TrainingDataset
  • Evidence: OutputContract_LabelQAReport

Minimale Pflichtfelder – Training Dataset

  • training_dataset_version
  • feature_set_version
  • dataset_version
  • label_spec_version
  • run_id
  • pipeline_version
  • window_start
  • window_end
  • row_count
  • artifact_uri
  • openmetadata_entity_ref
  • mlflow_run_ref

Minimale Pflichtfelder – Label-QA Report

  • run_id
  • feature_set_version
  • dataset_version
  • as_of_date
  • label_spec_version
  • qa_status
  • report_uri

Wichtigster fachlicher Punkt

  • Strict forward alignment: Labels müssen strikt „t → t+H“ sein (Leakage‑Guard).

4) Model Candidate (Training + HPO)​

Definition
Ein Model Candidate ist ein trainiertes Modell‑Artefakt, das technisch/qualitativ „OK“ ist, aber noch nicht als Pilot/Production „promoted“ wurde.
Die technische Referenzierung erfolgt über MLflow (Run + Model Registry).

Contracts (konzeptuell)

  • Output: OutputContract_ModelCandidate
  • Evidence: OutputContract_ModelTrainingReport

Minimale Pflichtfelder – Model Candidate

  • model_candidate_version
  • registered_model_name
  • model_version
  • model_uri (z.B. models:/name/version)
  • 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

Minimale Pflichtfelder – Training Report

  • 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

Warum trennen wir „Candidate“ von „Promotion“?

  • Training/HPO ist ein iterativer Engineering‑Schritt.
  • Promotion ist eine bewusste Entscheidung (mit Evidence) – nicht automatisches „deploy“.

5) Signal / Score​

Definition
Ein Signal/Score ist der Output eines Scoring‑Runs: pro Instrument und Datum ein Modell‑basierter Score (oder Signal‑Label), der Downstream (Backtesting, Portfolio Construction) genutzt wird.

Wichtig: Ein Signal ist keine Order, sondern eine quantitative Einschätzung.

Konzeptuelle Minimalfelder

  • signal_set_id (oder score_set_id)
  • signal_version (oder score_version)
  • as_of_date
  • universe_id
  • model_candidate_version (oder model_uri)
  • feature_set_version
  • dataset_version (falls relevant)
  • run_id, pipeline_version
  • artifact_uri (z.B. Parquet/Delta)
  • qa_status (Sanity/Completeness/Distribution)
  • openmetadata_entity_ref
  • optional: horizon_trading_days, calibration_ref

Das Scheduling enthält explizite Deployments für Scoring/Monitoring; das Konzept „Signal/Score“ ist die gemeinsame Sprache dafür.

6) Promotion​

Definition
Promotion ist ein kontrollierter Übergang eines Artefakts (meist Model Candidate) in einen „höheren“ Status, z.B.:

  • Candidate → Pilot (Pilot Ready)
  • Pilot → Production (Production Ready)

Promotion ist Evidence‑getrieben (Reports/Backtests/Review) und wird in Metadaten nachvollziehbar dokumentiert.

Konzeptuelle Minimalfelder

  • from_stage
  • to_stage
  • approval_ref (Ticket/Decision Log, bewusst pragmatisch)
  • constraints (Universe/Region/Max Exposure/…)
  • evidence_bundle_uri (Backtest‑Report, Training‑Report, DQ‑Status, etc.)
  • effective_from
  • owner / approver

Hinweis: MLflow „Stages“/„Aliases“ können Promotion technisch abbilden, sind aber nur dann sinnvoll, wenn die Evidence‑Logik stabil ist.

Lineage: Wie alles zusammenhängt​

Die zentrale Kette (vereinfachtes Mapping):

dataset_version → feature_set_version → training_dataset_version → model_candidate_version → backtest_report / validation_decision → (optional) promotion → scoring (signal_version)

Systeme

  • OpenMetadata: Entities + Lineage Edges + Allowed Use + DQ Status
  • MLflow: Experiments/Runs/Artefakte/Model Registry + Parameter/Metriken

Mapping auf BPMN & die wichtigsten Seiten​

Diese Seite ist eine Begriffs‑Basis. Die Details stehen in den jeweiligen Prozessseiten:

  • Scheduling → /docs/orchestration-prefect/scheduling
  • Data Pipeline / Ingestion (ELT + Validierung) → /docs/orchestration-prefect/data-pipeline
  • Purpose Gate (Gate A) → /docs/data-catalog-openmetadata/purpose
  • Data Quality Gate → /docs/data-catalog-openmetadata/data-quality
  • Feature Pipeline → /docs/orchestration-prefect/feature-pipeline
  • Label Construction → /docs/data/label-construction
  • Training / Experiments (MLflow) → /docs/ml-lifecycle-mlflow/experiments
  • Backtesting → /docs/research-risk/backtesting
  • Gesamtübersicht → /docs/platform/architecture

Anti-Patterns (die wir bewusst vermeiden)​

  1. „Latest“-Nutzung ohne Version
    Downstream liest „latest table“ → Ergebnisse sind nicht reproduzierbar.

  2. Mutable Publikationen
    Publizierte *_version wird überschrieben → Audit/Backtests verlieren Basis.

  3. QA/DQ nur in Logs
    Wenn Evidence nicht als URI referenziert ist (*_report_uri), ist sie in Reviews wertlos.

  4. Vermischung von Universen/Regionen
    universe_id/region nicht sauber im Contract → Backtests und Scores werden unklar.

  5. Promotion ohne Evidence Bundle
    „Wir deployen, weil es gut aussieht“ → fehlende Nachvollziehbarkeit und unnötiges Risiko.

Referenzen​

  • Plattform‑Architektur: /docs/platform/architecture
  • Glossar: /docs/platform/glossary