# 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 |