diff --git a/README.md b/README.md index 7165428..13da62c 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,7 @@ uvicorn app.main:app --reload - `http://127.0.0.1:8000/health` - Health-Check - `http://127.0.0.1:8000/docs/` - OpenAPI-Dokumentation - `http://127.0.0.1:8000/v1/entities` - Home-Assistant-Entities +- `http://127.0.0.1:8000/ml/health` - ML-Serving Health (ab ML-005) ### ENV-Konfiguration (`.env.example`) - `SILLYHOME_HA_URL` – Basis-URL deiner Home-Assistant-Instanz (z. B. `http://homeassistant.local:8123`) diff --git a/docs/ml_api.md b/docs/ml_api.md new file mode 100644 index 0000000..afced19 --- /dev/null +++ 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` \ No newline at end of file