Technical Documentation

Modellarchitektur, Feature Engineering, Evaluation und API — für Data Scientists, ML Engineers und alle, die es genau wissen wollen. 📘 Interactive API Docs (Swagger)

1. System Overview

Multi-Horizon Occupancy Forecasting für 110 Parkhäuser in 5 Schweizer Städten. Vier unabhängige Modelle (h ∈ {1, 2, 4, 8}) prognostizieren alle 15 Minuten die Belegungsquote occ = (total − free) / total ∈ [0, 1]. Zusätzlich ein Quantil-Modell (α = 0.2) und ein Binärklassifikator (P(free < 5)) pro Horizont.

2. Model Architecture

2.1 Regression (Punktprognose)

2.2 Quantile Regression (pessimistisch)

2.3 Binary Classifier (Voll-Wahrscheinlichkeit)

2.4 Baseline (Referenzmodell)

Saisonaler Mittelwert je (parkhaus, wochentag, stunde, viertelstunde) über 8 Wochen, mit Rückfallkette auf Stundenmittel → Stadtmittel → Hausmittel. Additive Zuschläge für aktive Events (+Bonus) und Regen > 0.5 mm (+2 pp). Dient ausschliesslich als Benchmark — kein Ensemble-Bestandteil.

2.5 Residual-Korrektur (Post-Processing)

Pro (city, pls_id, horizon_h) wird ein leichtes LightGBM-Modell trainiert, das den Fehler des globalen Modells konditioniert korrigiert. Anders als der frühere statische Bias-Offset lernt das Residual-Modell, wann und wie stark das globale Modell bei einem spezifischen Parkhaus daneben liegt.

residual = global_pred_occ − actual_occ       Target des Residual-Modells
Features: hour, weekday, is_weekend, occ_now, delta_occ_1h,
          is_raining, event_active, prior_occ, anomaly, month
free_korrigiert = (1 − (occ_pred − residual_pred)) × total

Hyperparameter bewusst klein gehalten (100 Trees, 15 Leaves, min. 30 Samples), um Overfitting zu vermeiden. Mindestens 200 Trainingszeilen pro Parkhaus nötig, sonst Fallback auf den gewichteten Bias der letzten 14 Tage. Wird nur auf ML-Prognosen angewandt, nicht auf Baseline.

3. Feature Engineering

42 Features pro Observation, gruppiert nach Kategorie:

Temporal (zyklisch kodiert)

hour quarter weekday is_weekend month sin_hour cos_hour sin_weekday cos_weekday sin_month cos_month

Kalender

is_holiday is_bridge_day is_school_holiday

Kantonale Feiertage (BS, BE, LU, SG, ZH) inkl. Osterdatum-basierte bewegliche Feiertage. Brückentage zwischen Feiertag und Wochenende. Schulferien pro Kanton und Jahr. Gespeichert in ai_feiertage und ai_schulferien.

Lag Features & Statistiken

occ_now occ_1h_ago occ_2h_ago occ_3d_ago occ_24h_ago occ_7d_ago delta_occ_1h trend_2h occ_mean_3h occ_mean_24h occ_std_24h prior_occ

prior_occ = saisonaler Erwartungswert aus dem Trainingsteil (kein Leakage ins Holdout). delta_occ_1h = Momentum der letzten Stunde. Fehlende Lags bleiben NaN — LightGBM handhabt das nativ.

Wetter

temperature precipitation is_raining temp_bin temp_sq

Quelle: Open-Meteo API, stündlich pro Stadt. is_raining = binäres Flag bei > 0.1 mm. Zum Zielzeitpunkt interpoliert.

Events

event_active event_soon event_bonus event_category

Echte Veranstaltungsdaten von 18 Venue-Websites (Hallenstadion, KKL, Tonhalle, Opernhaus, Theater Basel, OLMA u.a.). event_bonus = venue-spezifischer Zuschlag aus venues.json (z.B. KKL 0.25, Hallenstadion 0.45, Theater 0.10–0.15); Fallback auf Kategorie-Bonus wenn kein venue_bonus konfiguriert. event_soon = Event beginnt innerhalb der venue-spezifischen Ankunftszeit (soon_hours in venues.json, z.B. KKL 1 h, Messen 2 h, Theater 0.5 h; Default 1 h). event_category = kategorische Variable (Konzert, Sport, Messe, …).

Interaktions-Features

weekend_event rain_hour

weekend_event = is_weekend × event_active — Events am Wochenende haben stärkeren Effekt. rain_hour = is_raining × hour — Regen wirkt je nach Tageszeit unterschiedlich.

Metadaten

log_total city pls_key

log_total = log(Kapazität) — normalisiert den Grösseneffekt. city und pls_key sind kategorial kodiert.

4. Training Pipeline

5. Evaluation & Metriken

5.1 Aktuelle Performance (letzte 7 Tage, Prod)

Metriken erklärt:

• MAE_free — Mean Absolute Error in freien Plätzen. Anschaulich, aber abhängig von der Hausgrösse.
• MAE_occ — MAE in Belegungsprozentpunkten. Vergleichbar über unterschiedlich grosse Häuser.
• Bias_free — systematische Abweichung. Positiv = Modell überschätzt die freien Plätze.
• Skill Score — 1 − MAE(ML) / MAE(Baseline). 0.72 = 72 % weniger Fehler als der saisonale Durchschnitt. Negativ = Modell schlechter als Baseline.
• R² (Bestimmtheitsmass) — 1 − SSres / SStot. Anteil der erklärten Varianz. 0.85 = das Modell erklärt 85 % der Belegungsschwankungen. Berechnet auf dem Holdout (letzte 14 Tage) und beim Training gespeichert.
• Bewusst kein MAPE: bei free → 0 explodiert der relative Fehler.

5.2 Evaluation Pipeline

1. Alle 15 Min: gereifte Prognosen dem nächsten Messwert zuordnen (±20 Min Toleranz)
2. Fehler berechnen: error = predicted_free − actual_free
3. Tagesweise aggregieren in ai_accuracy_daily: MAE, Bias, Anzahl je (day, city, pls_id, model_type, horizon_h)
4. Stadtweite und globale Aggregate separat (mit pls_id = '')

6. Data Pipeline

Scanner (alle 15 Min)
│  Stadt-APIs → pls_fetch_current (~1.6 Mio Zeilen)
│  Open-Meteo  → weather_forecasts (2× täglich)
│  Venues      → local_events + event_parkhaus (2× täglich, automatisch)
│
FastAPI-ML (Port 80)
├── :10/:25/:40/:55  predict.py   → ai_predictions
│   └── Residual-Korrektur (pro Parkhaus) oder Bias-Fallback
├── :13/:28/:43/:58  evaluate.py  → ai_accuracy_daily
├── 03:15            identity.py  → ai_parkhaus_map
└── 03:30            train.py     → ai_model_runs + models_store/
                     └── Regression + Quantile + Classifier + Residual × 4 Horizonte

Rasterung & Preprocessing

• Messwerte werden auf ein striktes 15-Minuten-Raster gelegt (letzter Wert je Slot)
• Lücken bis 1 Stunde: Forward-Fill. Längere Lücken: NaN (fallen aus dem Training)
• Zielgrösse: occ = (total − free) / total — ermöglicht ein globales Modell über Häuser mit 50 bis 1100 Plätzen
• Rückrechnung auf freie Plätze via letztes bekanntes total

7. Parkhaus Identity Mapping

Die Messwert-IDs (pls_fetch_current.id) und Stammdaten-IDs (parkhaeuser.id) verwenden unterschiedliche Namenskonventionen:

Zentral gelöst in core/identity.py, Ergebnis in ai_parkhaus_map. Häuser ohne Treffer werden trotzdem prognostiziert — nur ohne Event-Features.

8. REST API

Vollständige, interaktive Dokumentation: 📘 Swagger UI öffnen

Alle Endpunkte akzeptieren ?env=prod|test.

9. Datenbank-Schema

MariaDB, zwei parallele Instanzen: ph_fetch_prod und ph_fetch_test. Die KI-App liest bestehende Tabellen nur und schreibt ausschliesslich in ai_-präfixierte Tabellen.

Scanner-Tabellen (read-only)

KI-Tabellen (read-write)

10. Stack & Deployment

11. Change History

Änderungsprotokoll aus der Zusammenarbeit mit Claude Code — Anfrage und Umsetzung.