From 0ee3f68599e966e3b17097f13cb2c9fbba487461 Mon Sep 17 00:00:00 2001 From: sudolulo Date: Fri, 12 Jun 2026 23:39:01 +0000 Subject: [PATCH] docs: update wiki for 0.2.11 (memory guidance, GPU troubleshooting) --- FAQ.md | 4 +++- Setup.md | 4 ++-- Troubleshooting.md | 32 ++++++++++++++++++++++++++++---- 3 files changed, 33 insertions(+), 7 deletions(-) diff --git a/FAQ.md b/FAQ.md index 666db6b..588ea95 100644 --- a/FAQ.md +++ b/FAQ.md @@ -41,7 +41,9 @@ Yes. By default it processes every named person in your Immich library. Use `ONL ## What GPU is needed? -Any NVIDIA GPU with CUDA 12.x support. The models (InsightFace Buffalo_L + SigLIP) fit comfortably in 4 GB VRAM. CPU mode works but is significantly slower. +Any NVIDIA GPU with CUDA 12.x support. The models (InsightFace Buffalo_L + SigLIP) fit comfortably in 4 GB VRAM. CPU mode works but is significantly slower — typically tens of seconds per person instead of under a second on GPU. + +**CPU memory:** If running without a GPU, set a container memory limit of at least **2 GB** (`mem_limit: 2g`). The models use roughly 1–1.5 GB and thumbnails are processed in bounded batches, so usage stays flat even for large libraries. Without a limit a large person library can trigger an OOM kill and restart loop. ARM builds (linux/arm64) use CPU-only — CUDA is not available on ARM. diff --git a/Setup.md b/Setup.md index d0a4157..21330f4 100644 --- a/Setup.md +++ b/Setup.md @@ -28,7 +28,7 @@ This is the base URL of your Frigate instance, e.g. `http://192.168.1.10:5000`. | `:latest` | amd64 + arm64 | CUDA 13.3 (amd64) | Requires NVIDIA Container Toolkit on amd64 | | `:cpu` | amd64 | None | ~2 GB smaller; use if you have no NVIDIA GPU | -Use `:cpu` if your host has no NVIDIA GPU — it skips the entire CUDA stack and runs InsightFace on CPU. +Use `:cpu` if your host has no NVIDIA GPU — it skips the entire CUDA stack and runs InsightFace on CPU. **Set a container memory limit of at least 2 GB** (`mem_limit: 2g`) — the embedding models need roughly 1–1.5 GB and thumbnails are batched, but without a limit an OOM kill will restart the container mid-run. ## 4. Deploy with Docker Compose @@ -80,7 +80,7 @@ On the first run, winnow downloads the embedding models (~1–2 GB) from Hugging --- -## 5. Scheduling +## 6. Scheduling `CRON_SCHEDULE` controls both the run schedule and container lifetime: diff --git a/Troubleshooting.md b/Troubleshooting.md index 1dfa8fe..dd90e2e 100644 --- a/Troubleshooting.md +++ b/Troubleshooting.md @@ -63,10 +63,34 @@ Use the `:cpu` image tag (`ghcr.io/sudolulo/winnow:cpu`) which omits the CUDA ba Everything works on CPU but embedding computation is slower — typically tens of seconds per person instead of under a second on GPU. -If you have a GPU but it's not being used: -- Confirm the NVIDIA container toolkit is installed: `docker run --rm --gpus all nvidia/cuda:13.3.0-base-ubuntu22.04 nvidia-smi` -- Confirm the `deploy.resources.reservations.devices` block is present in `compose.yml` -- Set `VERBOSE=true` and check the logs — winnow logs which ONNX execution providers are active at startup (should show `CUDAExecutionProvider`) +**Memory:** CPU mode requires more host RAM than GPU mode. Set a minimum container memory limit of **2 GB** (`mem_limit: 2g` in compose). If you have a large library — hundreds of images per person — allow more. Thumbnails are processed in bounded batches of 32 so peak RAM stays flat regardless of library size, but the embedding models themselves use roughly 1–1.5 GB. + +--- + +## GPU not being used / "No GPU execution provider found" + +If you have a GPU and the container is running but winnow reports no GPU provider: + +1. **Confirm the GPU device is visible** inside the container: + ```bash + docker exec winnow nvidia-smi + ``` + If this fails, the container doesn't have GPU access — check the `deploy.resources.reservations.devices` block in `compose.yml` and that the NVIDIA container toolkit is installed on the host. + +2. **Check which ONNX providers are available**: + ```bash + docker exec winnow /app/.venv/bin/python3 -c \ + "import onnxruntime as ort; ort.preload_dlls(cuda=True, cudnn=True); print(ort.get_available_providers())" + ``` + Expected (GPU working): `['CUDAExecutionProvider', 'CPUExecutionProvider', ...]` + GPU not working: `['AzureExecutionProvider', 'CPUExecutionProvider']` — only CPU providers listed. + +3. **If only CPU providers appear even though `nvidia-smi` works**, you may be running an image older than 0.2.11. A packaging bug in 0.2.10 caused the CPU `onnxruntime` package to silently overwrite `onnxruntime-gpu`, removing GPU support without any error. Update to `:latest` to fix it: + ```bash + docker compose pull && docker compose up -d + ``` + +4. **Set `VERBOSE=true`** and check startup logs — winnow logs `ONNX providers available: [...]` at DEBUG level on every start. ---