折腾 Zhēteng

Immich remote GPU machine learning

Created: 5 min read

Immich remote GPU machine learning

此笔记记录将 Immich 的 Machine Learning (ML) 微服务剥离至单独的 GPU 服务器 (GPU Box) 的配置与调试过程。主要解决本地算力不足及利用远程 RTX 3070 加速 CLIP 索引的问题。

Connectivity & Debugging (Crucial)

由于 Main Server 和 GPU Box 之间存在防火墙 (Firewall) 或网络隔离，连通性测试是排错的第一步。

在 Main Server (Immich App) 上执行以下命令，验证能否连接到 Remote GPU Box：

Command 1: 基础连通性检查 (Ping)

最基础的测试，验证端口 (Default: 3003) 是否开放以及服务是否存活。这是排查 Connection refused 的首要手段。

curl -v http://<REMOTE_GPU_IP>:3003/ping
  • 预期返回: {"status":"ok"}
  • 常见错误: Connection refused (端口未映射/防火墙拦截) 或 Timeout (网络不通)。

Command 2: 模型加载状态 (Stats)

验证特定模型是否已成功加载进显存。这对于确认模型是否因为 OOM (显存溢出) 导致加载失败非常有用。

curl -v http://<REMOTE_GPU_IP>:3003/stats
  • 用途: 检查返回 JSON 中的 loadedModels 列表，确认你的大模型是否 Ready。

Docker Compose Configuration (GPU Box)

在远程 GPU 机器上运行 ML 服务。 注意： 必须使用 -cuda 镜像标签，并正确暴露端口。

version: "3.8"
 
services:
  immich-machine-learning:
    container_name: immich_machine_learning
    # Core 1: 必须使用 -cuda 后缀，否则无法调用 GPU
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}-cuda
    ports:
      # Core 2: 必须显式暴露端口，否则外部 curl 会 Connection Refused
      - "3003:3003"
    volumes:
      # 模型缓存路径，建议映射到大容量磁盘
      - ${MODEL_CACHE_LOCATION}:/cache
    env_file:
      - .env
    restart: always
    # Core 3: NVIDIA GPU Passthrough
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

Model Selection: XLM vs NLLB

Immich 支持多种多语言模型，其搜索行为（Search Pattern）有本质区别。

Current Model

  • Model Name: XLM-Roberta-Large-ViT-H-14__frozen_laion5b_s13b_b90k
  • Type: xlm (Language Agnostic)

Search Patterns Explained

根据官方文档，多语言模型分为两类：

  1. NLLB Models (e.g., nllb-clip-large-siglip)
  • 机制: 强依赖用户的 User Settings → Language。
  • 限制: 搜索词的语言必须与用户界面语言一致。如果界面是英文，搜中文可能无效。
  • 场景: 适合单语言用户（只用中文）。
  1. XLM / SigLIP2 Models (当前使用)
  • 机制: Language Agnostic (语言无关)。模型理解文本本身的语义，不依赖界面设置。
  • 优势: 支持 Mixed Language Search。用户可以使用英文 UI，但直接搜索中文关键词（如“海边”、“红色车”），语义理解完全互通。

Resource Planning (Hardware Requirements)

运行上述 ViT-H (Huge) 模型对宿主机有特定要求：

VRAM (显存)

  • Usage: ~2.8 GB (具体为 2869 MB @ Concurrency=1)。
  • Warning: 如果同时运行 Ollama (8B Model, ~5.5GB)，8GB 显存会 OOM。需配置 TTL 错峰运行。

Disk Space (存储)

宿主机需预留 10GB+ 空间：

  • Model Cache: 该模型文件巨大，下载后约占用 4 GB。
  • Docker Image: cuda 版本的镜像包含驱动库，解压后约 2 GB+。
  • Runtime: 容器运行时临时文件。

Main Server Configuration (Failover)

无需修改 .env，直接在 Web UI 中配置。

  • Path: Administration → Settings → Machine Learning Settings → URL
  • Configuration: 支持配置多个 URL，按顺序 Failover (故障转移)。

Example:

http://<REMOTE_GPU_IP>:3003
 
http://<LOCAL_CPU_IP>:3003
  • 逻辑: 优先尝试 GPU Box。如果远程服务不可达（如 GPU 机器维护中），自动降级回退到本地 CPU 处理，保证服务不中断。

Critical Tuning (Huge Model Specific)

针对 ViT-H-14 这种巨型模型，必须调整并发策略：

Concurrency Lock

  • Location: Administration → Settings → Job Settings → Smart Search
  • Value: 1
    • 就算是1，59000的照片视频也在一下午晚上都搞定了。
  • Reason: 该模型单次推理消耗巨大资源（毕竟不能跟 LLM 比）。不确定在 3070 上并发 > 1 会不会导致 OOM 或请求超时。

TTL (Time To Live)

  • Env Var: MACHINE_LEARNING_MODEL_TTL=60 (Default: 300)
  • Reason: 让模型在空闲 60秒后自动卸载释放显存，以便让出 GPU 给 Ollama 或其他服务使用。

Graph View