From e7d3862c34da5eb7a7b673b273b2b1dcf909b044 Mon Sep 17 00:00:00 2001 From: SnapOtter Date: Mon, 20 Jul 2026 18:02:39 +0800 Subject: [PATCH] docs: GPU-runs-on-CPU troubleshooting note (#587) Surface how to verify NVIDIA CUDA acceleration and recover when AI tools fall back to CPU despite --gpus all. Adds a Verify GPU acceleration section to the deployment guide (check logs, reinstall the affected bundle to restore the GPU ONNX Runtime build) and a pointer from the getting-started NVIDIA tip. Addresses #490. --- apps/docs/guide/deployment.md | 4 ++++ apps/docs/guide/getting-started.md | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/apps/docs/guide/deployment.md b/apps/docs/guide/deployment.md index 2c5f9f65..a8481e22 100644 --- a/apps/docs/guide/deployment.md +++ b/apps/docs/guide/deployment.md @@ -198,6 +198,8 @@ volumes: docker compose -f docker-compose-gpu.yml up -d ``` +### Verify GPU acceleration {#verify-gpu-acceleration} + Check CUDA detection in the logs: ```bash @@ -205,6 +207,8 @@ docker logs SnapOtter 2>&1 | head -20 # Look for: [gpu] CUDA available via torch ``` +If AI tools run on CPU even though `--gpus all` and the NVIDIA Container Toolkit are set up correctly, reinstall the affected bundle (for example Background Removal) from **Settings → AI Features**. The installer restores the GPU build of ONNX Runtime, which a CPU-only build pulled in by another bundle (such as transcription) can otherwise shadow in the shared AI environment. If reinstalling from the UI doesn't restore GPU on an older image, see the manual repair in [issue #490](https://github.com/snapotter-hq/SnapOtter/issues/490). + ## Hardware Requirements {#hardware-requirements} These numbers come from benchmarks across a range of systems, from a modern amd64 workstation with an NVIDIA RTX 4070 down to a Raspberry Pi, running the whole tool catalog on each and sweeping Docker resource limits to find the real floor. diff --git a/apps/docs/guide/getting-started.md b/apps/docs/guide/getting-started.md index f202024c..a3f3eb46 100644 --- a/apps/docs/guide/getting-started.md +++ b/apps/docs/guide/getting-started.md @@ -37,7 +37,7 @@ Add `--gpus all` for NVIDIA CUDA-accelerated background removal, upscaling, face docker run -d --name SnapOtter -p 1349:1349 --gpus all -v SnapOtter-data:/data snapotter/snapotter:latest ``` -Requires the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html). Falls back to CPU automatically when CUDA is unavailable. Intel/AMD iGPU acceleration through VA-API, Quick Sync, or OpenCL is not supported for AI inference today. See [Docker Tags](/guide/docker-tags) for benchmarks. +Requires the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html). Falls back to CPU automatically when CUDA is unavailable. Intel/AMD iGPU acceleration through VA-API, Quick Sync, or OpenCL is not supported for AI inference today. See [Docker Tags](/guide/docker-tags) for benchmarks. If AI tools run on CPU despite `--gpus all`, see [Verify GPU acceleration](/guide/deployment#verify-gpu-acceleration). ::: ::: details Also on GHCR