github rtp4jc/immich-animals sidecar-v0.3.1
animal-ml sidecar v0.3.1 (beta)

pre-release30 minutes ago

Community contributions

This release contains our first community contributions! Huge thanks to @thevanburenboy (the first PR), @gorynychzmey (the most improvements), and @qudiqudi (the most important fix) for taking the time to make these improvements and submit them to help benefit everyone using this project.

The animal-ml sidecar can now run on Intel GPUs, and it's steadier and lighter alongside Immich. The models haven't changed, so upgrading keeps every dog, cat and name you already have.

What's new

  • Intel GPU image. ghcr.io/rtp4jc/animal-ml:0.3.1-openvino runs both models on an Intel iGPU or Arc card through OpenVINO, the same way Immich's -openvino image does. On an Intel N100, a photo with one cat takes about a quarter of the time it takes on the CPU. It's amd64 only, and it needs the GPU passed into the container (see Intel GPU below).
  • Uses less memory when idle. After 5 minutes without a face request the sidecar unloads its models, like Immich's own ML container does. The next photo loads them again. Set MODEL_TTL: "0" to keep them loaded.
  • No more stalls. While the sidecar works on a photo, it still answers Immich's health checks and passes search and OCR straight through. It also fetches human faces from Immich's ML container at the same time as it looks for animals.
  • Safer for your human faces. If Immich's ML container fails to answer, the sidecar now reports an error for that photo instead of returning only the animals. Before, a Face Detection Refresh could treat those human faces as gone. For the same reason, the sidecar won't start without UPSTREAM_ML_URL unless KEEP_HUMAN_FACES is false.
  • A health check you can trust. Immich now shows machine learning as unhealthy when the sidecar can't reach Immich's ML container, since search, OCR and human faces depend on it. Docker's own health check only asks whether the sidecar is running, so a stopped ML container doesn't restart it.
  • New settings:
    • UPSTREAM_TIMEOUT (default 120 s) for slow OCR or CLIP models.
    • UPSTREAM_PING_TIMEOUT (default 1.5 s).
    • MODEL_TTL (default 300 s).
    • OPENVINO_DEVICE and OPENVINO_EMBEDDER_PRECISION for the Intel image.
  • Runs as a non-root user.

Upgrading from 0.3.0

  1. Change the image tag to ghcr.io/rtp4jc/animal-ml:0.3.1, or 0.3.1-openvino (see below).
  2. Run docker compose up -d animal-ml.

That's all. You don't need a Refresh, and you don't need to change any Immich settings.

If you list more than one Machine Learning URL in Immich, list only sidecars. Otherwise, when a sidecar fails, Immich falls back to its own ML container, and that container returns no animals for the photo. The sidecar README explains how to keep a fallback.

New install

Next to your Immich docker-compose.yml, create docker-compose.override.yml:

services:
  animal-ml:
    container_name: animal_ml
    image: ghcr.io/rtp4jc/animal-ml:0.3.1
    environment:
      UPSTREAM_ML_URL: http://immich-machine-learning:3003
    restart: always
  1. Run docker compose up -d animal-ml.
  2. Administration → Settings → Machine Learning: set the URL to http://animal-ml:3003. Leave the other settings alone; the sidecar uses its own values for pets.
  3. Job Queues → Face Detection → Refresh. Use Refresh, never Reset: Reset deletes every named face.

Intel GPU

Use the 0.3.1-openvino tag. Get the number of the group that owns your GPU with stat -c %g /dev/dri/renderD128, then add it to the service:

    image: ghcr.io/rtp4jc/animal-ml:0.3.1-openvino
    devices:
      - /dev/dri:/dev/dri
    group_add:
      - "992" # the number from stat

Check that the animal-ml: line at the top of docker logs animal_ml names OpenVINOExecutionProvider. If it doesn't, the models are running on the CPU. While it loads the models, this image needs about 2 GB of memory, against about 0.8 GB for the CPU image.

Full instructions and troubleshooting: sidecar/README.md

Contributing

There's a new CONTRIBUTING.md and a pull request checklist. If you change detection, scripts/evaluate_sidecar.py --baseline compares your build against main on a public validation set and lists every photo whose result changed.


Model files are attached; they're the same files as in 0.3.0. Verify them with sha256sum -c SHA256SUMS. Licensed AGPL-3.0; some training data is for non-commercial use only, see NOTICE.

Don't miss a new immich-animals release

NewReleases is sending notifications on new releases.