sillyhome-next/docs/ml_api.md

ML-Serving-API

Diese Dokumentation beschreibt die REST-Endpunkte der aktuellen Modell-Artefakt- und Vorhersage-Schnittstelle.

Das Serving verwendet ein lokal trainiertes statistisches Baseline-Modell.

Basis-URL

• Standard: http://127.0.0.1:8000/ml
• Health: /health
• Modelle: /models
• Retraining: /retrain
• Evaluation: /evaluate
• Einzelvorhersage: /predict
• Batchvorhersage: /batch

Der Standard-Start erfolgt über uvicorn app.main:app, danach stehen HA- und ML-Routen in derselben Anwendung bereit.

Endpoints

GET /ml/health

Health-Check der ML-Services.

Beispielantwort

{
  "status": "ok",
  "updated_at": "2026-06-11T12:00:00Z"
}

GET /ml/models

Listet alle registrierten Modell-Artefakte auf.

Beispielantwort

{
  "models": ["default"]
}

POST /ml/predict

Einzelne Vorhersage für einen Sensor.

Request

{
  "modelId": "default",
  "sensor_id": "sensor.kitchen",
  "values": {"temperature": 21.0}
}

Antwort

{
  "model_id": "default",
  "sensor_id": "sensor.kitchen",
  "predictions": {"temperature": 21.4},
  "confidence": 0.78,
  "model_type": "statistical_baseline",
  "explanations": {
    "temperature": {
      "direction": "steigend",
      "change": 0.4,
      "sample_count": 24,
      "historical_mean": 20.7,
      "trend_per_step": 0.4,
      "summary": "temperature: steigend; Prognose ..."
    }
  }
}

Die Erklärung nennt pro Merkmal den aktuellen und prognostizierten Wert, Richtung, Veränderung, Datenbasis, historischen Bereich, Streuung, Trend und Confidence. Sie wird deterministisch aus den gespeicherten Modellparametern erzeugt.

POST /ml/retrain

Trainiert die Artefakt-Metadaten aus neuen Sensordaten. Existiert modelId bereits, wird das Artefakt atomisch ersetzt und beim nächsten Prozessstart aus dem Modellverzeichnis geladen.

Request

{
  "modelId": "home-model",
  "samples": [
    {
      "sensor_id": "sensor.kitchen",
      "values": {"temperature": 21.0},
      "label": "occupied"
    }
  ]
}

Antwort

{
  "model_id": "home-model",
  "supported_sensors": ["sensor.kitchen"],
  "trained_features": 1,
  "model_type": "statistical_baseline",
  "replaced": false
}

POST /ml/evaluate

Vergleicht Modellvorhersagen mit Validierungsdaten und liefert MAE, RMSE und Coverage. Der Request verwendet dasselbe Sample-Format wie /ml/retrain.

POST /ml/batch

Batch-Vorhersage für mehrere Sensorwerte.

Request

{
  "requests": [
    {
      "modelId": "default",
      "sensor_id": "sensor.kitchen",
      "values": {"temperature": 21.0}
    },
    {
      "modelId": "default",
      "sensor_id": "sensor.bedroom",
      "values": {"temperature": 18.5}
    }
  ]
}

Antwort

{
  "predictions": [
    {
      "model_id": "default",
      "sensor_id": "sensor.kitchen",
      "predictions": {"temperature": 21.4},
      "confidence": 0.78,
      "model_type": "statistical_baseline"
    },
    {
      "model_id": "default",
      "sensor_id": "sensor.bedroom",
      "predictions": {"temperature": 18.3},
      "confidence": 0.74,
      "model_type": "statistical_baseline"
    }
  ]
}

Fehlerfälle

• 404 Not Found: Modell nicht registriert.
• 422 Unprocessable Content: Sensor wird vom Modell nicht unterstützt oder Eingabe ist ungültig.
• 503 Service Unavailable: Registry ist nicht initialisiert.

Betrieb

Die produktive App lädt Artefakte aus SILLYHOME_MODEL_STORE. Neue Artefakte werden über /ml/retrain, RetrainingService oder direkt über ModelRegistry.register(...) registriert. Die Registry speichert validiertes JSON atomisch und lädt es beim Neustart. Die API sollte nur in einem vertrauenswürdigen Netz oder hinter einem authentifizierenden Reverse Proxy erreichbar sein.

Verweise

• app/ml/predictor.py
• app/ml/retraining.py
• app/ml/registry/model_registry.py
• backend/routes/ml.py