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.

Seit v0.4.0 ist der bevorzugte Weg aktor-zentriert: ein bestätigter Aktuator wird mit einem numerischen Primärsensor verknüpft, die Historie dieses Sensors wird automatisch geladen und in ein deterministisches Artefakt überführt.

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.

Im Normalbetrieb erzeugt die Reconciliation diese Vektoren selbst aus realer Home-Assistant-History. Das Trainingsmerkmal heißt dabei immer value. Binäre Kontextsensoren bleiben Kontext und werden nicht als numerische Samples missverstanden.

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.

6. Autonomer Lebenszyklus

Der ActuatorReconciliationService verwaltet pro konfiguriertem Aktuator:

• die automatische Sensor- und Kontextzuordnung mit Score, Confidence und Evidenz
• persistente manuelle Overrides
• den Modellstatus (trained, pending_history, review_required, archived, ...)
• ein Audit-Protokoll mit Gründen für Training, Retraining oder Archivierung

Retraining erfolgt nur, wenn:

• genügend nutzbare numerische Historie vorliegt
• die aktuelle Zuordnung eindeutig oder manuell bestätigt ist
• die Historie sich materiell verändert hat oder das Modell als stale gilt

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.