Bilderkennung in Betrieb nehmen (Inferenz-Service)¶

Diese Seite beschreibt die Inbetriebnahme des inference-service für die selbst gehostete Pflanzen-Bilderkennung (interne Anforderungsreferenz REQ-029-A). Der Inferenz-Service ist eine optionale Komponente — Kamerplanter funktioniert vollständig ohne sie; die Bilderkennung ist dann nicht verfügbar.

Überblick: Was wird installiert?¶

Der Inferenz-Service (src/inference-service/) ist ein eigenständiger FastAPI-Microservice, der:

• das DINOv2-Modell (ViT-S/14, Apache-2.0, ~21 M Parameter) als ONNX-Artefakt (Open Neural Network Exchange) lädt,
• Bilder vorverarbeitet und in Embedding-Vektoren (384 Dimensionen) umrechnet,
• diese Vektoren gegen einen Referenz-Index in pgvector abgleicht und die ähnlichsten Pflanzenarten zurückgibt.

Der Service ist ein optionales, eigenständiges Modul. Es gibt zwei Deployment-Topologien:

• Entwicklung (Skaffold): Der Service läuft im eigenen Helm-Release kamerplanter-recognition (Skaffold-Profil recognition) und teilt sich den pgvector-Speicher mit dem Knowledge-Service (kamerplanter-ki-Release, Datenbank kamerplanter_vectors, eigene Tabelle species_embeddings). Die kamerplanter-ki-vectordb muss laufen, wenn das recognition-Profil startet.
• Produktion (ArgoCD, Single-Release): Der Inference-Service und eine dedizierte pgvector-Instanz laufen im selben Helm-Release wie Backend und Frontend (kamerplanter). Kein separates Release, kein geteilter pgvector-Speicher mit dem Knowledge-Service. Verfügbar ab Image-Tag v0.0.17 (ab diesem Release publiziert CI das kamerplanter-inference-service-Image auf GHCR).

Der Service ist in beiden Topologien nur clusterintern erreichbar (Kubernetes ClusterIP).

Aktivierungsreihenfolge¶

Schritt 1: Inferenz-Service starten — Entwicklung (Skaffold)¶

# Im Projektverzeichnis (Entwicklung):
# Das recognition-Profil teilt sich die pgvector-DB mit dem ki-Stack,
# daher beide Module zusammen starten:
skaffold dev -m ki -m recognition

Das recognition-Profil startet ausschließlich den inference-service (eigenes Release kamerplanter-recognition); das ki-Profil stellt die gemeinsam genutzte pgvector-DB bereit. Beim ersten Start wird das ONNX-Modell im Build-Schritt exportiert — das dauert je nach Hardware 5–15 Minuten.

Prüfen, ob der Service läuft:

# Port-Forward (lokale Entwicklung):
kubectl port-forward svc/kamerplanter-recognition 8090:8000 -n default

# Readiness prüfen (ist das Modell geladen?):
curl http://localhost:8090/ready
# Erwartete Antwort: {"status": "ok"}

# Modellinformationen abrufen:
curl http://localhost:8090/modelinfo
# Antwort enthält: model, dim, input_size, license, checksum

Schritt 2: Referenz-Index befüllen¶

Der Referenz-Index enthält Embedding-Vektoren für alle Pflanzenarten aus den Stammdaten. Er wird durch einen Celery-Task befüllt, der Referenzbilder von GBIF (Global Biodiversity Information Facility) und Wikimedia Commons abruft (nur CC0/CC-BY-Lizenzen), einbettet und die Vektoren in pgvector speichert. Originalbilder werden dabei nicht persistiert.

# Celery-Task für alle Arten starten (einmalig, dauert je nach Artenzahl mehrere Stunden):
kubectl exec -it deploy/kamerplanter-backend -n default -- \
  celery -A app.tasks call \
  app.tasks.reference_image_tasks.acquire_all_reference_images_task

# Alternativ: über die Backend-API (Admin-Endpoint):
curl -X POST http://localhost:8000/api/v1/admin/reference-images/acquire \
  -H "Authorization: Bearer <admin-token>"

Fortschritt verfolgen:

# Abdeckungs-Report abfragen (wie viele Arten sind erkennbar?):
curl http://localhost:8000/api/v1/admin/reference-images/coverage \
  -H "Authorization: Bearer <admin-token>"

Die Antwort zeigt pro Art, wie viele Referenzbilder akzeptiert wurden und ob die Art als "erkennbar" gilt (usable_for_recognition, mindestens 5 akzeptierte Referenzen):

{
  "total_species": 66,
  "usable_species": 48,
  "entries": [
    {
      "species_key": "species_alocasia_zebrina",
      "scientific_name": "Alocasia zebrina",
      "accepted": 2,
      "candidates_found": 7,
      "usable_for_recognition": false,
      "license_breakdown": {"CC0": 1, "CC_BY": 1}
    }
  ]
}

Admin-API-Endpunkte für die Referenzbild-Beschaffung (Übersicht):

Alle drei Endpunkte erfordern einen gültigen Admin-Token (Authorization: Bearer <admin-token>). Die Endpunkte sind über den regulären Backend-Ingress erreichbar — es ist kein separater Port-Forward nötig.

Schritt 3: Lokalen Pfad aktivieren¶

Setze die Umgebungsvariable im Backend:

# Backend-Env (values-dev.yaml) oder Umgebungsvariable:
INFERENCE_SERVICE_ENABLED=true

Helm-Konfiguration¶

Entwicklung (Skaffold)¶

Im Entwicklungs-Workflow wird der Inferenz-Service über das Skaffold-Profil recognition als separates Helm-Release kamerplanter-recognition gestartet. Konfiguration in helm/kamerplanter/values-dev-recognition.yaml — der pgvector-Speicher wird mit dem kamerplanter-ki-Release geteilt (siehe Überblick oben).

Produktion (ArgoCD — Single-Release)¶

In Produktion laufen der Inferenz-Service und eine dedizierte pgvector-Instanz (vectordb) im selben Helm-Release wie Backend und Frontend (Release-Name kamerplanter). Das Chart helm/kamerplanter/values.yaml enthält dafür zwei zusätzliche Controller, die standardmäßig deaktiviert sind: vectordb und inference-service. Der Operator aktiviert sie über valuesObject in der ArgoCD-Application.

PW=$(openssl rand -base64 24)
kubectl patch secret kamerplanter-secrets -n kamerplanter --type merge \
  -p "{\"stringData\":{\"POSTGRES_PASSWORD\":\"$PW\"}}"

kubectl create secret generic kamerplanter-secrets -n kamerplanter \
  --from-literal=POSTGRES_PASSWORD="$(openssl rand -base64 24)"

ArgoCD Application — spec.sources[].helm.valuesObject:

controllers:
  vectordb:
    enabled: true
  inference-service:
    enabled: true
  backend:
    containers:
      main:
        env:
          INFERENCE_SERVICE_ENABLED: "true"
          INFERENCE_SERVICE_URL: "http://kamerplanter-inference-service:8000"
service:
  vectordb:
    enabled: true
  inference-service:
    enabled: true
persistence:
  inference-service-tmp:
    enabled: true
networkpolicies:
  vectordb:
    enabled: true
  inference-service:
    enabled: true

Ressourcen und Sicherheitskontext (Chart-Defaults, nicht überschreiben sofern nicht nötig):

Service-Hostnamen im Cluster (Release-Name kamerplanter):

• Backend → Inferenz-Service: http://kamerplanter-inference-service:8000
• Inferenz-Service → pgvector: kamerplanter-vectordb:5432 (Chart-Default für VECTORDB_HOST)

Aktivierungsreihenfolge in Produktion¶

1. ArgoCD-Application mit den oben gezeigten valuesObject-Feldern (ohne INFERENCE_SERVICE_ENABLED: "true") deployen. Warten, bis kamerplanter-vectordb und kamerplanter-inference-service Ready sind.
2. Referenz-Index befüllen (identisch mit Schritt 2 im Entwicklungs-Pfad oben — das kubectl exec-Ziel ist deploy/kamerplanter-backend).
3. INFERENCE_SERVICE_ENABLED: "true" in das valuesObject eintragen und die Application synchronisieren.

Ressourcenbedarf¶

Umgebungsvariablen¶

Endpunkte des Inferenz-Service (intern)¶

Die Endpunkte sind nur clusterintern erreichbar und nicht über den Ingress exponiert.

Lizenzen und Rechtliches¶

Fehlerbehebung¶

Siehe auch¶

• Pflanzen-Bilderkennung verwenden
• Architektur der Bilderkennung
• Betriebsprofile — Welche KI-Komponenten sind in welchem Profil enthalten?
• ArgoCD-Deployment — Produktiv-Deployment mit ArgoCD (Application-Konfiguration, Sync-Strategien)
• Helm Charts — Allgemeine Helm-Konfiguration
• Umgebungsvariablen