initial commit

2026-07-12 10:17:17 -04:00
commit dab5a4ebc6
1424 changed files with 330463 additions and 0 deletions
@@ -0,0 +1,103 @@
+# Immich ML GPU Cache Paths and Model Names
+
+Known working for Immich v2.7.5.
+
+## Model Sources
+
+All models hosted on HuggingFace under `immich-app/` org.
+
+| Model Name | HuggingFace Repo | Files | Size |
+|---|---|---|---|
+| `ViT-B-32__openai` | `immich-app/ViT-B-32__openai` | visual/model.onnx (335 MB), textual/model.onnx (254 MB) | ~590 MB total |
+| `buffalo_l` | `immich-app/buffalo_l` | detection/model.onnx (16 MB), recognition/model.onnx (166 MB) | ~182 MB total |
+
+## Cache Directory Structure
+
+Cache root: `/cache` (from `MACHINE_LEARNING_CACHE_FOLDER` env var).
+
+### CLIP (smart search)
+
+| Field | Value |
+|---|---|
+| Model task | `SEARCH` → `"clip"` |
+| Model type | `VISUAL` → `"visual"`, `TEXTUAL` → `"textual"` |
+| Cache dir | `/cache/clip/ViT-B-32__openai` |
+| Model dir (visual) | `/cache/clip/ViT-B-32__openai/visual` |
+| Model path (visual) | `/cache/clip/ViT-B-32__openai/visual/model.onnx` |
+| Model dir (textual) | `/cache/clip/ViT-B-32__openai/textual` |
+| Model path (textual) | `/cache/clip/ViT-B-32__openai/textual/model.onnx` |
+
+### Face detection & recognition
+
+| Field | Value |
+|---|---|
+| Model task | `FACIAL_RECOGNITION` → `"facial-recognition"` |
+| Cache dir | `/cache/facial-recognition/buffalo_l` |
+| Model dir (detection) | `/cache/facial-recognition/buffalo_l/detection` |
+| Model path (detection) | `/cache/facial-recognition/buffalo_l/detection/model.onnx` |
+| Model dir (recognition) | `/cache/facial-recognition/buffalo_l/recognition` |
+| Model path (recognition) | `/cache/facial-recognition/buffalo_l/recognition/model.onnx` |
+
+## Code Derivation
+
+Cache paths follow this pattern:
+
+```python
+from immich_ml.config import settings
+# settings.cache_folder = "/cache"
+# model_task.value = one of: "clip", "facial-recognition", "ocr"
+# model_name = e.g. "ViT-B-32__openai" or "buffalo_l"
+# model_type.value = one of: "visual", "textual", "detection", "recognition"
+
+cache_dir = settings.cache_folder / model_task.value / model_name
+model_dir = cache_dir / model_type.value
+model_path = model_dir / "model.onnx"
+```
+
+## Pre-download command
+
+```python
+from huggingface_hub import snapshot_download
+import os
+
+# For CLIP
+os.makedirs("/cache/clip/ViT-B-32__openai", exist_ok=True)
+snapshot_download(
+    "immich-app/ViT-B-32__openai",
+    cache_dir="/cache/clip/ViT-B-32__openai",
+    local_dir="/cache/clip/ViT-B-32__openai",
+    ignore_patterns=["*.armnn", "*.rknn"],
+)
+
+# For face detection/recognition
+os.makedirs("/cache/facial-recognition/buffalo_l", exist_ok=True)
+snapshot_download(
+    "immich-app/buffalo_l",
+    cache_dir="/cache/facial-recognition/buffalo_l",
+    local_dir="/cache/facial-recognition/buffalo_l",
+    ignore_patterns=["*.armnn", "*.rknn"],
+)
+```
+
+## docker-compose GPU config
+
+Required addition to `immich-machine-learning` service:
+
+```yaml
+deploy:
+  resources:
+    reservations:
+      devices:
+        - driver: nvidia
+          count: all
+          capabilities: [gpu]
+```
+
+## Environment variables
+
+| Variable | Value | Effect |
+|---|---|---|
+| `DEVICE` | `cuda` | Use CUDA (set by -cuda image) |
+| `MACHINE_LEARNING_MODEL_ARENA` | `false` | Load all models at once. Set `true` to load one at a time (saves VRAM but slower switching) |
+| `MACHINE_LEARNING_DEVICE_ID` | `0` | GPU device index |
+| `MACHINE_LEARNING_CACHE_FOLDER` | `/cache` | Where models are stored |