sillyhome-next-dev/docs/ml_training.md

ML Training- und Evaluations-Workflow

SillyHome Next trainiert ein lokales statistisches Baseline-Modell pro Sensor und Merkmal. Es benötigt keine Cloud und keine externe ML-Laufzeit.

1. Daten sammeln

Alle Trainingsvektoren werden über FeatureStore.add(...) oder add_batch(...) eingepflegt. Jeder Vektor enthält eine Sensor-ID sowie ein Dictionary mit Merkmalen.

2. Statistisches Artefakt erzeugen

store = FeatureStore()
store.add(FeatureVector(sensor_id="sensor.kitchen", values={"temperature": 21.0}))
pipeline = TrainingPipeline(store)
artifact = pipeline.run("my_artifact")
pipeline.export("my_artifact")

TrainingPipeline.run(...) berechnet für jedes numerische Merkmal:

• Stichprobenzahl
• Mittelwert und Standardabweichung
• Minimum und Maximum
• linearen Trend mit Steigung und Achsenabschnitt

Die nächste Vorhersage kombiniert den letzten beobachteten Wert mit der trainierten Trendsteigung. Die Confidence berücksichtigt Datenmenge und Stabilität.

3. Modell evaluieren

evaluator = Evaluator(pipeline)
report = evaluator.evaluate(artifact.artifact_id, validation_samples)

Der Report enthält echte numerische Vergleichsmetriken:

• artifact_id
• sample_size
• mae (Mean Absolute Error)
• rmse (Root Mean Squared Error)
• coverage für den Anteil auswertbarer Merkmale

4. Modell registrieren

Das trainierte Artefakt kann anschließend über ModelRegistry.register(artifact) bereitgestellt werden. Die ML-Serving-API stellt es unter /ml/predict und /ml/batch zur Verfügung.

5. Retraining ausführen

RetrainingService.retrain(...) führt genau einen Trainingslauf aus und ersetzt ein vorhandenes Artefakt mit derselben ID atomisch in der Registry:

service = RetrainingService(registry)
result = service.retrain("home-model", vectors)

Scheduler, Cronjobs oder Home-Assistant-Automationen können alternativ die zustandslose Funktion retrain_model(registry, artifact_id, vectors) aufrufen. Der Service startet bewusst keinen eigenen Hintergrundprozess. Über POST /ml/retrain kann derselbe Ablauf per API angestoßen werden.

Hinweise

• Für reproduzierbare Sensor-Reihenfolgen wird in TrainingPipeline.run(...) eine sortierte Sensor-Liste verwendet.
• Fehlende Trainingsdaten lösen ValueError aus; nicht registrierte Artefakte lösen KeyError aus.
• Nur endliche numerische Werte werden trainiert.
• coverage bleibt im Bereich 0 bis 1.