125 lines
2.4 KiB
Markdown
125 lines
2.4 KiB
Markdown
# ML-Serving-API
|
|
|
|
Diese Dokumentation beschreibt die REST-Endpunkte der aktuellen
|
|
Modell-Artefakt- und Vorhersage-Schnittstelle.
|
|
|
|
> Hinweis: Version 0.1.0 enthält noch kein statistisch trainiertes ML-Modell.
|
|
> Die Vorhersage ist eine deterministische Referenzimplementierung für den
|
|
> späteren Modellvertrag.
|
|
|
|
## Basis-URL
|
|
|
|
- Standard: `http://127.0.0.1:8000/ml`
|
|
- Health: `/health`
|
|
- Modelle: `/models`
|
|
- 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**
|
|
```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
|
|
|
|
- `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 derzeit intern über `ModelRegistry.register(...)` registriert. Die
|
|
Registry speichert validiertes JSON atomisch und lädt es beim Neustart.
|
|
|
|
## Verweise
|
|
|
|
- `app/ml/predictor.py`
|
|
- `app/ml/registry/model_registry.py`
|
|
- `backend/routes/ml.py`
|