93 lines
3.5 KiB
Markdown
93 lines
3.5 KiB
Markdown
# 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
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
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.
|