Immich 机器学习硬件加速-未完纪

此功能使用 GPU 加速智能搜索、人脸识别等机器学习任务，同时降低 CPU 负载。它仍属实验功能，可能无法适用于全部系统。

启用后不需要重新执行旧的机器学习作业；之后运行的任务会使用加速设备。

支持的后端

ARM NN：Mali GPU。
CUDA：计算能力至少 5.2 的 NVIDIA GPU。
ROCm：AMD GPU。
OpenVINO：Intel Iris Xe、Arc 等 GPU。
RKNN：Rockchip。

限制

本文针对 Docker Compose，其他容器引擎可能需要不同配置。仅支持 Linux，以及通过 WSL2 运行的 Windows 服务器。

ARM NN 仅支持带 Mali GPU 的设备，不支持其他 Arm 设备。某些模型与特定后端不兼容，CUDA 通常最可靠。

由于模型兼容性问题，ARM NN 不能降低实际搜索延迟，但智能搜索的后台任务会使用它。

前提条件

ARM NN

安装适当的 Linux 内核驱动，设备厂商镜像通常已预装。
主机必须存在 /dev/mali0，可通过 ls /dev 确认。
需要闭源 libmali.so 固件，可能还需要额外固件文件。获取方式依设备与厂商而异，通常由厂商提供。
hwaccel.ml.yml 默认库路径为 /usr/lib/libmali.so，若不同应调整；它还假定存在 /lib/firmware/mali_csffw.bin，设备不需要该文件时也应调整。
可按需在 .env 配置 ARM NN 专用变量。特别是 MACHINE_LEARNING_ANN_FP16_TURBO，可以用极小的精度损失换取明显性能提升。

CUDA

GPU 计算能力至少 5.2；服务器需安装官方 NVIDIA 驱动，版本至少 545，以支持 CUDA 12.3。Linux 上除 WSL2 外，还需 NVIDIA Container Toolkit。

ROCm

Linux 服务器需安装 AMDGPU 驱动模块；使用安全启动时，还需在 UEFI BIOS 注册 DKMS 签名密钥。

GPU 应获得 ROCm 支持。未正式支持时，可尝试 HSA_OVERRIDE_GFX_VERSION=<受支持版本，如 10.3.0>；仍失败时，可能还需 HSA_USE_SVM=0。

ROCm 镜像很大，至少需要 35 GiB 空闲空间。后续 Docker 更新通常只下载数百 MB，其余层可复用缓存。

此后端较新，可能有问题。例如推理结束后，即使服务空闲，GPU 功耗仍可能偏高，直到空闲五分钟才恢复；这个时间由 MACHINE_LEARNING_MODEL_TTL 控制。

MIGraphX 是 AMD 的新后端，会在运行时编译模型，因此前几次推理较慢。

OpenVINO

集成 GPU 比独立 GPU 更容易遇到问题，尤其是旧处理器或内存较少的服务器。确保内核足够新，以支持设备加速。相比 CPU 处理，OpenVINO 通常占用更多内存。

OpenVINO-WSL

确保容器可以访问 /dev/dri，可运行 docker exec -t immich_machine_learning ls -la /dev/dri。

如果不能，在 WSL 主机运行 getent group render 与 getent group video，把对应组加入 hwaccel.ml.yaml：

openvino-wsl:
  devices:
    - /dev/dri:/dev/dri
    - /dev/dxg:/dev/dxg
  volumes:
    - /dev/bus/usb:/dev/bus/usb
    - /usr/lib/wsl:/usr/lib/wsl
  group_add:
    - 44 # Replace this number with the number you found with getent group video
    - 992 # Replace this number with the number you found with getent group render

RKNN

目前支持的 Rockchip SoC 为 RK3566、RK3568、RK3576 和 RK3588。

安装正确 Linux 驱动，厂商镜像通常已预装。主机需 RKNPU 0.9.8 或更新驱动，可运行 cat /sys/kernel/debug/rknpu/version 查看。

可在 .env 配置 RKNN 变量。对 RK3576、RK3588，将 MACHINE_LEARNING_RKNN_THREADS 从默认 1 改为 2 或 3，可以大幅提升性能，但每个模型使用的内存也会增加到相应倍数。

配置

下载最新 hwaccel.ml.yml，与 docker-compose.yml 放在同目录。
在 immich-machine-learning 的镜像标签末尾加上对应后缀：-armnn、-cuda、-rocm、-openvino 或 -rknn。
在同一服务下取消 extends 部分注释，把 cpu 改为所需后端。
按新配置重新部署机器学习容器。

确认设备使用情况

可查看设备利用率，例如 NVIDIA 或 Intel 使用 nvtop，Intel 使用 intel_gpu_top，AMD 使用 radeontop。

也可检查容器日志。智能搜索、人脸检测任务开始，或在 Immich 输入文字搜索时，Available ORT providers 应包含相应提供程序，例如 CUDA 的 CUDAExecutionProvider；ARM NN 则应出现无错误的 Loaded ANN model。

单个 Compose 文件

原文写作时，Unraid、Portainer 等平台不支持多 Compose 文件。可以将 hwaccel.ml.yml 的相关内容直接内联到服务。

例如 CUDA 配置：

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: 1
          capabilities:
            - gpu

可以直接写入 immich-machine-learning，代替 extends：

immich-machine-learning:
  container_name: immich_machine_learning
  # Note the `-cuda` at the end
  image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}-cuda
  # Note the lack of an `extends` section
  deploy:
    resources:
      reservations:
        devices:
          - driver: nvidia
            count: 1
            capabilities:
              - gpu
  volumes:
    - model-cache:/cache
  env_file:
    - .env
  restart: always

然后重新部署容器。

多 GPU

使用多块 NVIDIA 或 Intel GPU 时，把 MACHINE_LEARNING_DEVICE_IDS 设为逗号分隔设备 ID，并将 MACHINE_LEARNING_WORKERS 设为设备数量。可通过 nvidia-smi -L 或 glxinfo -B 查看设备及 ID。

例如设备 0 和 1：

MACHINE_LEARNING_DEVICE_IDS=0,1
MACHINE_LEARNING_WORKERS=2

服务会启动两个 worker，分别把模型放到设备 0 与设备 1，不同请求由不同 worker 处理。

这也可以用于指定单个设备，例如 MACHINE_LEARNING_DEVICE_IDS=1 会始终使用设备 1。

应提高任务并发量，以提高利用率、分散多 GPU 工作。每块 GPU 都必须能加载全部模型；不能把一个模型拆到多块各自显存不足的 GPU，也不能把特定模型指定给某一块 GPU。

技巧

某个模型运行报错时，尝试其他模型，判断是否是模型专属问题。
提高默认并发可能改善利用率，但也增加显存消耗。
显存允许时，较大模型通常更能受益于硬件加速。

与 ARM NN 相比，RKNPU 支持更多模型，包括 ARM NN 无法加速的搜索；发热更低；精度略低，因为 RKNPU 始终使用 FP16，而 ARM NN 默认 FP32，除非启用 FP16 Turbo。

RK3588 上的速度表现：

线程为默认 1 时，多数机器学习任务吞吐量明显低于 ARM NN，但搜索等延迟相近。
线程为 3 时，比 ARM NN FP32 稍快，但比开启 FP16 Turbo 的 ARM NN 稍慢。
转码等其他任务也使用 GPU 时，RKNPU 优势明显，因为它使用原本空闲的 NPU，不与 GPU 争用。

线程为 1 时 RKNPU 内存更少；大于 1 时显著增加，但要充分利用 NPU、达到与 ARM NN 相近速度，通常需要增加线程。

原文：Hardware-Accelerated Machine Learning。作者／维护方：Immich 文档维护者。本文为中文翻译，代码及命令保留原文。

文章版权归作者所有，未经允许请勿转载。

THE END

技术译文

Immich 机器学习硬件加速