Add captions
For a new GPU or Full install, Quick start starts the required services together. The recipes below cover an existing installation.
Captions are short descriptions used by selection and sharing checks. They are not the date and place labels printed on the film.
Basic works without them. GPU and Full describe the selected pictures and replacement candidates, then reuse those descriptions on later cuts. You do not need to caption the whole library before making a film.
The default captioner is SmolVLM2 500M. It receives small picture previews. Keep the service on your private network.
One NVIDIA worker
If you are adding GPU inference and rendering too, use the one-GPU setup.
It serves captions at /v1 in the same container, starting its bundled caption process on demand.
Set caption_base_url to http://gpu-box:8092/v1. No separate caption container is needed.
The routes are unauthenticated. Keep the worker private. The GPU and Full tiers still need Laya in the app; captions alone do not enable GPU selection.
Separate Docker Compose captioner
For an existing Compose install, select the GPU and CUDA files
from the same release as the app. They start inference, the caption weight downloader and the
caption server. Keep the file selection in .env for later restarts and updates.
Check the caption server from the host running Compose:
curl -s localhost:8094/v1/models
The Compose files set the inference and caption URLs; a URL saved in Settings wins over them, so on an existing install change it there. The captioner is published on host port 8094; inside Compose it listens on 8092. Captions alone don't make the install GPU: preflight also checks the inference service and Laya, and a CPU-only inference service doesn't count.
For NVIDIA, use the CUDA image and device reservation together. The exact CUDA recipe and Kubernetes overlays are in the service reference.
Apple Silicon
Use the native Mac setup to serve the pinned model natively. Point the app at it:
advanced:
editorial:
preparation:
caption_base_url: http://localhost:8092/v1
From Docker Desktop, replace localhost with host.docker.internal. A Docker container cannot use the Mac’s Metal GPU directly; configure GPU inference separately.
Check it
In Docker, prefix immich-memories commands with docker compose exec immich-memories
from the app's installation folder.
immich-memories preflight
Look for Captions OK Serving smolvlm2-500m-base-public. Preflight checks the served model name; preparation checks synthetic control pictures before sending your library’s pictures. GPU and Full need a working caption provider; Basic with default settings skips it.
The service reference explains unreachable, wrong-model and authentication failures.
Explicit LLM captions
A reader configured for prose never receives pictures automatically. To send previews and video frame strips to a vision-capable LLM instead, opt in:
advanced:
editorial:
preparation:
caption_provider: llm
This uses your configured LLM and its credentials. It can cost much more than the small local captioner, especially hosted. The app warns before using it. Existing valid SmolVLM results are reused first.
Model pins, serving flags, caption provenance and motion-description contracts are in the caption service reference.