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-openvinoruns both models on an Intel iGPU or Arc card through OpenVINO, the same way Immich's-openvinoimage 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_URLunlessKEEP_HUMAN_FACESisfalse. - 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_DEVICEandOPENVINO_EMBEDDER_PRECISIONfor the Intel image.
- Runs as a non-root user.
Upgrading from 0.3.0
- Change the image tag to
ghcr.io/rtp4jc/animal-ml:0.3.1, or0.3.1-openvino(see below). - 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- Run
docker compose up -d animal-ml. - 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. - 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 statCheck 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.