01 / Overview
Executive Overview
Dieses Projekt zeigt einen vollständigen Cloud-Data-Engineering- und MLOps-Workflow für großskaliges Retail Demand Forecasting. Rohe Walmart-M5-Dateien werden in Amazon S3 gespeichert, in Databricks und Delta Lake über eine Bronze-Silver-Gold-Architektur verarbeitet, in modellfähige Features überführt, unter strengen zeitlichen und Leakage-Kontrollen evaluiert und als Production-Forecast-Outputs materialisiert.
Das Projekt geht deutlich über Modelltraining hinaus. Es umfasst Data-Quality-Validierung, Experiment Tracking, Model Governance, Production Forecasting, Monitoring-Tabellen, inventory-orientierte Analysen, einen vierseitigen Power-BI-Report, einen dokumentierten FastAPI-Service, Docker-Containerisierung und automatisierte API-Tests.
02 / Business
Business Problem
Retailer müssen Bestände für tausende Produkte und Filialen planen, bevor die zukünftige Nachfrage bekannt ist. Zu niedrige Forecasts führen zu Stockouts und Umsatzverlusten; zu hohe Forecasts erzeugen Überbestand und binden Working Capital.
- Nachfrage konsistent über Produkt-Filial-Kombinationen prognostizieren.
- Stockout- und Overstock-Risiko reduzieren.
- Safety-Stock- und Reorder-Point-Entscheidungen unterstützen.
- Nachvollziehbare und kontrollierte Modellergebnisse bereitstellen.
- Qualitätsfehler erkennen, bevor Forecasts nachgelagerte Systeme erreichen.
03 / Architecture
End-to-End-Architektur
Die Plattform trennt Storage, Processing, Modelling, Serving, Monitoring und Business Intelligence in klar definierte Layer. Dadurch wird der Workflow reproduzierbar und auditierbar.
1
Amazon S3 Raw Zone
Originale M5-Dateien werden außerhalb von GitHub im Cloud Data Lake gespeichert.
2
Bronze Delta Layer
Rohstruktur und Ingestion-Metadaten werden erhalten.
3
Silver Delta Layer
Datumswerte, IDs, Schemas, Missing Values und Joins werden standardisiert.
4
Gold Analytics Layer
Model-ready Features, Evaluation, Inventory Outputs und Monitoring-Tabellen werden aufgebaut.
5
Leakage-Safe Modelling
Modelle werden mit zeitlicher Trennung und horizon-sicheren Features evaluiert.
6
Production Forecast Run
Das ausgewählte Modell erzeugt einen kontrollierten 28-Tage-Forecast für jede aktive Item-Store-Serie.
7
Serving & BI
FastAPI, Docker, Power BI und Monitoring machen Ergebnisse zugänglich und überprüfbar.
04 / Data
Datensatz und Processing Scale
Das Projekt verwendet den Walmart-M5-Forecasting-Datensatz mit täglichen Stückverkäufen, Kalenderereignissen, SNAP-Indikatoren und historischen Verkaufspreisen über mehrere Stores und Produktkategorien.
| Measure | Value | Meaning |
|---|
| Datenabdeckung | 29.01.2011 bis 22.05.2016 | Historisches tägliches Demand-Fenster |
| Verknüpfte Analysezeilen | ca. 46,9 Millionen | Großskaliges Spark-Processing |
| Forecastbare Serien | 30.490 | Aktive Item-Store-Kombinationen |
| Forecast-Horizont | 28 Tage | Direktes Production-Fenster |
| Production-Forecast-Zeilen | 853.720 | 30.490 Serien × 28 Tage |
05 / Engineering
Data-Engineering-Pipeline
- M5-Kalender-, Sales- und Preisdateien aus Amazon S3 ingestieren.
- Schemas, Abdeckung, Row Counts und Pflichtspalten validieren.
- Saubere Silver-Tabellen mit standardisierten IDs und Datumswerten erstellen.
- Demand-, Kalender-, Event-, SNAP- und Preisinformationen großskalig verbinden.
- Gold-Datasets für Modelling, Evaluation, Inventory Planning und Monitoring erzeugen.
- Kritische Outputs als Delta-Tabellen für Reproduzierbarkeit und Downstream-Nutzung persistieren.
06 / Quality
Data Quality und Production Controls
Production Eligibility basiert auf expliziten Kontrollen und nicht nur auf Modellgenauigkeit.
| Control | Result | Interpretation |
|---|
| Null-Forecast-Zeilen | 0 | Keine fehlenden Production Forecasts |
| Negative Forecasts | 0 | Alle Werte erfüllen Non-Negativity |
| Duplicate Forecasts | 0 | Eindeutiger Series-Date-Grain |
| Critical Alerts | 0 | Kein blockierender Monitoring Alert |
| Monitoring Ready | True | Alle erforderlichen Operational Outputs vorhanden |
07 / Forecasting Integrity
Leakage Audit und Horizon-Safe Design
Eine zentrale Engineering-Erkenntnis war, dass das Modell mit dem niedrigsten scheinbaren Fehler nicht automatisch das beste Production Model ist. Ein früheres Hybrid-System erzielte eine niedrigere WAPE, aber der abschließende Audit identifizierte Leakage-Risiken in Feature-Konstruktion und Selection Path.
Das kontrollierte Modell nutzt deshalb eine direkte 28-Tage-horizon-sichere Baseline. Für jedes Target werden nur Informationen verwendet, die am Forecast Origin tatsächlich verfügbar gewesen wären – ungefähr t-55 bis t-28. Der finale Testzeitraum wurde nicht für Tuning oder Champion Selection verwendet.
Governance-Entscheidung: etwas schwächere Headline Accuracy akzeptieren, um zeitliche Validität, Reproduzierbarkeit, Interpretierbarkeit und Production Safety sicherzustellen.
08 / Governance
Model Comparison und Governance Decision
Eine Promotion erforderte sowohl Predictive Quality als auch Governance Eligibility. Ein Challenger musste mindestens 0,50 % relative Verbesserung liefern, ohne schlechteres operationales Verhalten.
| Kandidat | Test WAPE | Entscheidung | Begründung |
|---|
| Legacy Hybrid Reference | 69,53 % | Nur Referenz | Niedrigerer numerischer Fehler, aber wegen Leakage-Risiken nur als historische Evidenz behalten. |
| Residual Challenger | ≈75,55 % | Abgelehnt | Relativer Gewinn nur etwa 0,152 %, unterhalb des 0,50-%-Promotion-Gates; Bias verschlechterte sich. |
| Horizon-Safe Moving Average 28 | 75,66 % | Promoted | Leakage-sicher, stabil, interpretierbar, reproduzierbar und production-eligible. |
Governed Production Model
| Modellname | horizon_safe_moving_average_28 |
| Version | v1.0.0 |
| Status | ACTIVE_PRODUCTION_MODEL |
| Strategie | direct_28_day_horizon_safe_baseline |
| Test für Tuning verwendet | False |
| Production Eligible | True |
09 / Evaluation
Finale Test Performance
WAPE entspricht dem gesamten absoluten Forecast-Fehler geteilt durch die gesamte tatsächliche Nachfrage. Der Wert reflektiert die Schwierigkeit sparsamer und intermittierender Retail-Demand-Serien in einer großen Hierarchie.
10 / Production
Production Forecast Run
Der finale kontrollierte Run erzeugte einen vollständigen 28-Tage-Forecast-Snapshot mit operationalen Qualitätsprüfungen und Monitoring Readiness.
| Forecast Run ID | forecast_20260729_122428_95fe2427 |
| Forecast Origin | 22.05.2016 |
| Forecast-Fenster | 23.05.2016 bis 19.06.2016 |
| Forecast-Zeilen | 853.720 |
| Aktive Serien | 30.490 |
| Gesamte Forecast Units | 1.199.197,57 |
| Durchschnitt pro Zeile | 1,4047 |
| Zero-Forecast-Rate | 3,75 % |
11 / Operations
Inventory und Operational Analytics
Forecast Outputs werden in Entscheidungsunterstützung für Inventory Planning überführt. Die Plattform unterstützt Expected Demand, Safety Stock, Reorder Points, Stockout-Risk-Priorisierung, Excess-Inventory-Erkennung und Category-/Store-Drilldowns.
12 / MLOps
MLOps und Governance
- MLflow Experiment Tracking und Run-Vergleich.
- Champion-Model-Metadaten und Versionierung.
- Validation-/Test-Trennung und Test-Use-Audit.
- Forecast Run IDs und reproduzierbare Output Snapshots.
- Monitoring-Tabellen für WAPE, MAE, RMSE, Bias, Coverage, Nulls, Negatives, Duplicates und Alerts.
- Explizite Production-Eligibility- und Promotion-Gates.
13 / Business Intelligence
Power BI Forecast Intelligence
Ein vierseitiger Power-BI-Report kommuniziert Executive KPIs, Forecast Performance, Category-Verhalten, Production Volumes und Model-Governance-Status. Der exportierte Report liegt im GitHub-Repository.
Power-BI-Report öffnen
14 / Serving
FastAPI Serving Layer
Ein modularer FastAPI-Service stellt kontrollierte Model-Metadaten, Production-Forecast-Summaries, Service Health und repräsentative 28-Tage-Item-Store-Forecasts bereit. Swagger und ReDoc werden automatisch generiert.
| Methode | Endpoint | Zweck |
|---|
| GET | / | Service-Information |
| GET | /health | Liveness und Runtime Status |
| GET | /model-info | Governed Model Metadata und Test Metrics |
| GET | /forecast-summary | Production Snapshot und Quality Statistics |
| GET | /forecasts/{item_id}/{store_id} | Repräsentative lokale 28-Tage-Demo-Serie |
Transparente Data-Source-Grenze: Model-Metadaten und Aggregate repräsentieren kontrollierte Production Snapshots. Der Item-Store-Endpoint ist explizit als local_demo_fixture gekennzeichnet und wird nicht als Live-Databricks-SQL-Query dargestellt.
15 / Deployment
Docker und reproduzierbare Ausführung
Die API ist in einem schlanken Python-3.10-Linux-Image verpackt. Dadurch werden maschinenspezifische Dependency-Unterschiede vermieden und eine konsistente Runtime für lokale Demonstration oder spätere Deployments geschaffen.
docker build -t retail-demand-forecasting-api:v1.0.0 .
docker run --rm -p 8000:8000 --name retail-forecast-api retail-demand-forecasting-api:v1.0.0
16 / Quality Assurance
Automatisierte Tests
Pytest und der FastAPI Test Client prüfen Service Availability, Model Metadata, Forecast-Summary-Werte, 28-Tage-Struktur, Non-Negativity, Data-Source-Transparenz und korrektes 404-Verhalten.
6 automatisierte Tests bestanden
17 / Evidence
Ausgewählte Projektnachweise
Screenshots werden automatisch angezeigt, sobald passende Dateien im Image-Ordner der Website liegen.
End-to-End-Architektur des Retail-Forecasting- und MLOps-Lakehouse.
Power-BI-Executive-Overview mit Production-Forecast-KPIs.
Dashboard für Model Governance und Leakage Audit.
Forecast Monitoring, Qualitätskontrollen und Alert-Readiness.
FastAPI-OpenAPI-Dokumentation und Forecast-Endpunkte.
Containerisierte API in Docker Desktop.
18 / Stack
Technology Stack
Cloud & Lakehouse
AWS S3DatabricksDelta LakeDatabricks SQL
Data Engineering
PySparkSpark SQLMedallion ArchitectureParquet
ML & MLOps
PythonMLflowTime-Series ForecastingModel Governance
Serving & Quality
FastAPIPydanticUvicornPytestHTTPX
Deployment & BI
DockerPower BIDAXGitHub
19 / Transparency
Aktuelle Limitationen
- Der Item-Store-API-Endpoint verwendet ein explizites lokales Demo Fixture statt eines Live-Databricks-Adapters.
- Die API ist containerisiert, aber noch nicht öffentlich in der Cloud gehostet.
- Der Power-BI-Report wird als PDF exportiert statt als öffentliches interaktives Workspace-Artefakt.
- Intermittierende Retail-Nachfrage begrenzt die erreichbare Point-Forecast-Genauigkeit.
- Automatisiertes CI/CD und Scheduled Retraining sind zukünftige Erweiterungen.
20 / Learnings
Zentrale Engineering Learnings
- Zeitliche Validität ist wichtiger als ein künstlich starker Benchmark.
- Model Governance muss Accuracy, Leakage Safety, Bias, Reproduzierbarkeit und Operational Checks kombinieren.
- Production Forecasting benötigt verlässliche Data Contracts und Monitoring – nicht nur Notebooks.
- Klare Dokumentation von Limitationen erhöht technische Glaubwürdigkeit.
- Serving, Containerisierung, Tests und BI machen aus einem Modelling-Projekt ein End-to-End-Engineering-System.
21 / Outcome
Projektergebnis
Dies ist eines meiner stärksten Portfolio-Projekte für Data Engineering, Cloud Data Engineering, Analytics Engineering und MLOps. Es zeigt großskaliges Spark Processing, Lakehouse Architecture, temporale Modelling-Disziplin, Model Governance, API Design, Containerisierung, automatisierte Tests und Executive Reporting in einem kohärenten System.
Das Endergebnis ist nicht nur ein Forecast-Modell, sondern ein nachvollziehbares, produktionsorientiertes Data Product mit dokumentierten Engineering-Trade-offs und klaren Grenzen zwischen implementierter Funktionalität und zukünftigen Erweiterungen.