From 9381564269e248103a68cfb8758ca02a87969365 Mon Sep 17 00:00:00 2001
From: Siddharth Kumar Sah <siddharth123sk@gmail.com>
Date: Sun, 5 Apr 2026 20:04:04 +0800
Subject: [PATCH] docs: add CUDA/GPU documentation and benchmarks

- Add :cuda tag to Docker Tags docs with setup, benchmarks, compose example
- Add GPU acceleration tip to AI engine docs
- Include benchmark table from RTX 4070 testing
---
 apps/docs/api/ai.md            |  4 +++
 apps/docs/guide/docker-tags.md | 61 +++++++++++++++++++++++++++++++++-
 2 files changed, 64 insertions(+), 1 deletion(-)

diff --git a/apps/docs/api/ai.md b/apps/docs/api/ai.md
index e6332da4..6974ad55 100644
--- a/apps/docs/api/ai.md
+++ b/apps/docs/api/ai.md
@@ -8,6 +8,10 @@ All model weights are bundled in the Docker image during the build. No downloads
 AI tools are not available in the `:lite` Docker image. The API returns `501 Not Available` for these endpoints when running the lite variant. Use `:latest` for AI features. See [Docker Tags](/guide/docker-tags) for details.
 :::
 
+::: tip GPU acceleration
+The `:cuda` Docker image includes GPU-accelerated versions of the ML libraries. Background removal, upscaling, and OCR all benefit from NVIDIA GPU acceleration. The image auto-detects your GPU and falls back to CPU if none is available. See [Docker Tags](/guide/docker-tags) for setup.
+:::
+
 ## Background removal
 
 Removes the background from an image and returns a transparent PNG.
diff --git a/apps/docs/guide/docker-tags.md b/apps/docs/guide/docker-tags.md
index f7835cc3..c30f9263 100644
--- a/apps/docs/guide/docker-tags.md
+++ b/apps/docs/guide/docker-tags.md
@@ -1,6 +1,6 @@
 # Docker Image Tags
 
-Stirling Image ships two Docker image variants to fit different use cases.
+Stirling Image ships three Docker image variants to fit different use cases.
 
 ## Full (default)
 
@@ -35,6 +35,38 @@ Use this if you:
 
 All other tools (27+) work identically in both variants.
 
+## CUDA (GPU acceleration)
+
+```bash
+docker pull stirlingimage/stirling-image:cuda
+```
+
+Same tools as the full image, but built with GPU-accelerated Python packages (onnxruntime-gpu, PyTorch CUDA, PaddlePaddle GPU). The image auto-detects your NVIDIA GPU at runtime and falls back to CPU if none is found.
+
+Requires [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) on the host. Linux amd64 only.
+
+### What gets faster with GPU
+
+| Tool | CPU | GPU (RTX 4070) | Speedup |
+|------|-----|----------------|---------|
+| Background removal | 2.4s | 0.9s | 2.7x |
+| Upscale 2x | 350ms | 310ms | ~1.1x |
+| Upscale 4x | 910ms | 310ms | ~3x |
+| OCR (PaddleOCR) | 137ms | 94ms | ~1.5x |
+
+Benchmarked with a 572x1024 JPEG portrait. Larger images show bigger speedups, especially for upscaling.
+
+Non-AI tools (resize, crop, convert, etc.) are unaffected since they use Sharp (CPU-based).
+
+### GPU health check
+
+After the first AI request, the admin health endpoint reports GPU status:
+
+```
+GET /api/v1/admin/health
+{"ai": {"gpu": true}}
+```
+
 ## Docker Compose
 
 ### Full
@@ -71,6 +103,30 @@ volumes:
   stirling-workspace:
 ```
 
+### CUDA
+
+```yaml
+services:
+  stirling-image:
+    image: stirlingimage/stirling-image:cuda
+    ports:
+      - "1349:1349"
+    volumes:
+      - stirling-data:/data
+      - stirling-workspace:/tmp/workspace
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
+
+volumes:
+  stirling-data:
+  stirling-workspace:
+```
+
 ## Switching from lite to full
 
 To upgrade from lite to full and unlock AI tools:
@@ -90,7 +146,10 @@ Both variants support semver tags for pinning:
 |-----|------------|
 | `latest` | Latest full release |
 | `lite` | Latest lite release |
+| `cuda` | Latest full release with GPU support |
 | `1.6.0` | Exact full version |
 | `1.6.0-lite` | Exact lite version |
+| `1.6.0-cuda` | Exact CUDA version |
 | `1.6` | Latest patch in 1.6.x (full) |
 | `1.6-lite` | Latest patch in 1.6.x (lite) |
+| `1.6-cuda` | Latest patch in 1.6.x (CUDA) |