Setting Up Plant Identification (Inference Service)¶

This page describes how to set up the inference-service for self-hosted plant identification (REQ-029-A). The inference service is an optional component — Kamerplanter works fully without it; plant identification will be unavailable.

Overview: What Gets Installed?¶

The inference service (src/inference-service/) is a standalone FastAPI microservice that:

• loads the DINOv2 model (ViT-S/14, Apache-2.0, ~21 M parameters) as an ONNX artefact,
• preprocesses images and converts them into embedding vectors (384 dimensions),
• matches these vectors against a reference index in pgvector and returns the most similar plant species.

The service is an optional, standalone module. There are two deployment topologies:

• Development (Skaffold): The service runs in its own Helm release kamerplanter-recognition (Skaffold profile recognition) and shares the pgvector store with the knowledge service (kamerplanter-ki release, database kamerplanter_vectors, its own table species_embeddings). The kamerplanter-ki vectordb must be running when the recognition profile starts.
• Production (ArgoCD, single-release): The inference service and a dedicated pgvector instance run in the same Helm release as the backend and frontend (kamerplanter). No separate release, no shared pgvector store with the knowledge service. Available from image tag v0.0.17 onwards (CI publishes the kamerplanter-inference-service image to GHCR starting from this release).

In both topologies the service is only reachable within the cluster (Kubernetes ClusterIP).

Activation Order¶

Step 1: Start the Inference Service — Development (Skaffold)¶

# In the project directory (development):
# The recognition profile shares the pgvector DB with the ki stack,
# so start both modules together:
skaffold dev -m ki -m recognition

The recognition profile starts only the inference-service (its own release kamerplanter-recognition); the ki profile provides the shared pgvector DB. On first start, the ONNX model is exported during the build step — this takes 5–15 minutes depending on your hardware (see Resource Requirements below).

Check that the service is running:

# Port-forward (local development):
kubectl port-forward svc/kamerplanter-recognition 8090:8000 -n default

# Check readiness (is the model loaded?):
curl http://localhost:8090/ready
# Expected response: {"status": "ok"}

# Retrieve model information:
curl http://localhost:8090/modelinfo
# Response includes: model, dim, input_size, license, checksum

Step 2: Populate the Reference Index¶

The reference index contains embedding vectors for all global plant species from the master data. Species a garden created itself are not indexed: the index is the same for every garden, and a match only names species the asking garden may see. It is populated by a Celery task that fetches reference images from GBIF and Wikimedia Commons (CC0/CC-BY licences only), embeds them, and stores the vectors in pgvector. Original images are not stored.

# Start the Celery task for all global species (one-time run; takes several hours):
kubectl exec -it deploy/kamerplanter-backend -n default -- \
  celery -A app.tasks call \
  app.tasks.reference_image_tasks.acquire_all_reference_images_task

# Alternatively: via the backend API (admin endpoint):
curl -X POST http://localhost:8000/api/v1/admin/reference-images/acquire \
  -H "Authorization: Bearer <admin-token>"

Monitor progress:

# Query the coverage report (how many species are identifiable?):
curl http://localhost:8000/api/v1/admin/reference-images/coverage \
  -H "Authorization: Bearer <admin-token>"

The response shows per species how many reference images were accepted and whether the species is considered "identifiable" (usable_for_recognition, at least 5 accepted references):

{
  "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 endpoints for reference image acquisition (overview):

All three endpoints require a valid admin token (Authorization: Bearer <admin-token>). They are accessible via the regular backend ingress — no separate port-forward is needed.

Step 3: Enable the Local Path¶

Set the environment variable on both the backend AND the celery-worker:

# Backend env AND celery-worker env (values-dev.yaml) or environment variable:
INFERENCE_SERVICE_ENABLED=true
INFERENCE_SERVICE_URL=http://kamerplanter-recognition:8000

Helm Configuration¶

Development (Skaffold)¶

In the development workflow the inference service is started via the Skaffold profile recognition as a separate Helm release kamerplanter-recognition. Configuration lives in helm/kamerplanter/values-dev-recognition.yaml — the pgvector store is shared with the kamerplanter-ki release (see Overview above).

Production (ArgoCD — Single-Release)¶

In production the inference service and a dedicated pgvector instance (vectordb) run inside the same Helm release as the backend and frontend (release name kamerplanter). The chart helm/kamerplanter/values.yaml ships two additional controllers that are disabled by default: vectordb and inference-service. The operator enables them via valuesObject in the 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"
  celery-worker:
    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

Resources and security context (chart defaults — do not override unless necessary):

In-cluster service hostnames (release name kamerplanter):

• Backend → inference service: http://kamerplanter-inference-service:8000
• Inference service → pgvector: kamerplanter-vectordb:5432 (chart default for VECTORDB_HOST)

Activation Order in Production¶

1. Deploy the ArgoCD Application with the valuesObject fields shown above (without INFERENCE_SERVICE_ENABLED: "true"). Wait until kamerplanter-vectordb and kamerplanter-inference-service are Ready.
2. Populate the reference index (identical to Step 2 in the development path above — the kubectl exec target is deploy/kamerplanter-backend).
3. Add INFERENCE_SERVICE_ENABLED: "true" (and INFERENCE_SERVICE_URL) under both controllers.backend and controllers.celery-worker in the valuesObject and synchronise the Application.

Resource Requirements¶

Environment Variables¶

Inference Service Endpoints (Internal)¶

These endpoints are only reachable within the cluster and are not exposed via the ingress.

Like every non-probe endpoint, all four erasure endpoints require the shared INTERNAL_SERVICE_TOKEN (Authorization: Bearer <token>) — without a valid token they answer 401. A blank key in the request body is rejected with 422 (the response names only the affected field, never the value).

Licences and Legal Notes¶

Troubleshooting¶

See Also¶

• Plant Identification (User Guide)
• Image Recognition Architecture
• Deployment Profiles — Which AI components are included in which profile?
• ArgoCD Deployment — Production deployment with ArgoCD (Application configuration, sync strategies)
• Helm Charts — General Helm configuration
• Environment Variables