ML-005: Doku zu ML-Serving-API ergänzen

2026-06-11 13:27:01 +02:00
parent fad517e56a
commit 57275d5172
2 changed files with 117 additions and 0 deletions
--- a/docs/ml_api.md
+++ b/docs/ml_api.md
@@ -0,0 +1,116 @@
+# ML-Serving-API
+
+Diese Dokumentation beschreibt die REST-Endpoints für ML-Vorhersagen in SillyHome Next.
+
+## Basis-URL
+
+- Standard: `http://127.0.0.1:8000/ml`
+- Health: `/health`
+- Modelle: `/models`
+- Einzelvorhersage: `/predict`
+- Batchvorhersage: `/batch`
+
+Der Standard-Start erfolgt über `uvicorn backend.app:app --reload`, danach steht die API unter `/ml` bereit.
+
+## Endpoints
+
+### `GET /ml/health`
+
+Health-Check der ML-Services.
+
+**Beispielantwort**
+```json
+{
+  "status": "ok",
+  "updated_at": "2026-06-11T12:00:00Z"
+}
+```
+
+### `GET /ml/models`
+
+Listet alle registrierten Modell-Artefakte auf.
+
+**Beispielantwort**
+```json
+{
+  "models": ["default"]
+}
+```
+
+### `POST /ml/predict`
+
+Einzelne Vorhersage für einen Sensor.
+
+**Request**
+```json
+{
+  "modelId": "default",
+  "sensor_id": "sensor.kitchen",
+  "values": {"temperature": 21.0}
+}
+```
+
+**Antwort**
+```json
+{
+  "model_id": "default",
+  "sensor_id": "sensor.kitchen",
+  "prediction": "default:sensor.kitchen:{'temperature': 21.0}"
+}
+```
+
+### `POST /ml/batch`
+
+Batch-Vorhersage für mehrere Sensorwerte.
+
+**Request**
+```json
+{
+  "requests": [
+    {
+      "modelId": "default",
+      "sensor_id": "sensor.kitchen",
+      "values": {"temperature": 21.0}
+    },
+    {
+      "modelId": "default",
+      "sensor_id": "sensor.bedroom",
+      "values": {"temperature": 18.5}
+    }
+  ]
+}
+```
+
+**Antwort**
+```json
+{
+  "predictions": [
+    {
+      "model_id": "default",
+      "sensor_id": "sensor.kitchen",
+      "prediction": "default:sensor.kitchen:{'temperature': 21.0}"
+    },
+    {
+      "model_id": "default",
+      "sensor_id": "sensor.bedroom",
+      "prediction": "default:sensor.bedroom:{'temperature': 18.5}"
+    }
+  ]
+}
+```
+
+## Fehlerfälle
+
+- `400 Bad Request`: Fehlende oder ungültige Felder.
+- `404 Not Found`: Modell oder Sensor nicht registriert.
+- `500 Internal Server Error`: Registry nicht initialisiert oder unerwarteter Fehler.
+
+## Betrieb
+
+Beim Start wird automatisch ein Default-Artefakt erstellt, falls noch kein Modell registriert ist. Neue Modelle müssen zusätzlich über `ModelRegistry.register(...)` eingetragen werden.
+
+## Verweise
+
+- `app/ml/predictor.py`
+- `app/ml/registry/model_registry.py`
+- `backend/routes/ml.py`