sillyhome-next/docs/ml_api.md

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

{
  "status": "ok",
  "updated_at": "2026-06-11T12:00:00Z"
}

GET /ml/models

Listet alle registrierten Modell-Artefakte auf.

Beispielantwort

{
  "models": ["default"]
}

POST /ml/predict

Einzelne Vorhersage für einen Sensor.

Request

{
  "modelId": "default",
  "sensor_id": "sensor.kitchen",
  "values": {"temperature": 21.0}
}

Antwort

{
  "model_id": "default",
  "sensor_id": "sensor.kitchen",
  "prediction": "default:sensor.kitchen:{'temperature': 21.0}"
}

POST /ml/batch

Batch-Vorhersage für mehrere Sensorwerte.

Request

{
  "requests": [
    {
      "modelId": "default",
      "sensor_id": "sensor.kitchen",
      "values": {"temperature": 21.0}
    },
    {
      "modelId": "default",
      "sensor_id": "sensor.bedroom",
      "values": {"temperature": 18.5}
    }
  ]
}

Antwort

{
  "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