硬體加速機器學習

此功能允許您使用 GPU 加速機器學習任務，例如智能搜索和人臉識別，同時減少 CPU 的負載。由於這是一項新功能，目前仍處於試驗階段，可能並不適用於所有系統。

信息

啟用硬體加速後，您無需重新進行任何機器學習工作。加速設備將用於啟用後執行的所有工作。

支援的後端

ARM NN (Mali)
CUDA (具有計算能力 5.2 或更高的 NVIDIA GPUs)
ROCm (AMD GPUs)
OpenVINO (Intel GPUs，例如 Iris Xe 和 Arc)
RKNN (Rockchip)

限制

這裡的指導和配置僅適用於 Docker Compose。其他容器引擎可能需要不同的配置。
僅支援 Linux 和 Windows（通過 WSL2）服務器。
ARM NN 僅支援配備 Mali GPUs 的設備。不支援其他 Arm 設備。
某些模型可能與特定後端不兼容。CUDA 是最穩定的選擇。
由於模型兼容性問題，ARM NN 無法用於加速搜索延遲。然而，智能搜索工作確實會使用 ARM NN。

前置需求

ARM NN

確保您已安裝適當的 Linux 核心驅動程式
- 通常在設備供應商的 Linux 映像中已預安裝
/dev/mali0 必須在主機服務器中可用
- 您可以運行 ls /dev 來確認該設備是否存在
必須擁有專有的 libmali.so 韌體（可能需要額外的韌體文件）
- 如何獲取此文件取決於設備和供應商，但通常由設備供應商提供
- hwaccel.ml.yml 文件假設該文件位於 /usr/lib/libmali.so，如果文件位於其他位置，請相應更新配置
- hwaccel.ml.yml 文件假設需要額外的文件 /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 容器工具包。

ROCm

GPU 必須支援 ROCm。如果未得到官方支援，您可以嘗試使用 HSA_OVERRIDE_GFX_VERSION 環境變數：HSA_OVERRIDE_GFX_VERSION=<支援的版本，例如 10.3.0>。如果無效，您可能還需要設定 HSA_USE_SVM=0。
ROCm 映像相當大，至少需要 35GiB 的可用磁碟空間。然而，通過 Docker 擷取後續服務更新通常僅需幾百 MB，其餘部分將被緩存。
此後端較新，可能會遇到一些問題。例如，即使機器學習服務處於閒置狀態，推理後 GPU 的功耗也可能高於正常水平。在這種情況下，只有在閒置 5 分鐘後（可通過 MACHINE_LEARNING_MODEL_TTL 設置進行配置）恢復正常。

OpenVINO

與離散 GPU 相比，整合式 GPU 更可能遇到問題，特別是對於較舊的處理器或 RAM 低的服務器。
確保服務器核心版本足夠新以使用該設備進行硬體加速。
使用 OpenVINO 時，預期 RAM 使用量比 CPU 處理更高。

RKNN

您必須擁有受支援的 Rockchip SoC：目前僅支援 RK3566、RK3568、RK3576 和 RK3588。
確保您已安裝適當的 Linux 核心驅動程式
- 通常在設備供應商的 Linux 映像中已預安裝
主機服務器中必須可用 RKNPU 驅動版本 V0.9.8 或更高
- 您可以運行 cat /sys/kernel/debug/rknpu/version 檢查版本
可選：配置您的 .env 文件，有關 RKNN 特定設置，請參見環境變數
- 特別是將 MACHINE_LEARNING_RKNN_THREADS 設定為 2 或 3 相比默認的 1 將顯著改善 RK3576 和 RK3588 性能，但需支付每個模型 RAM 使用量倍增的代價。

設置

如果尚未擁有，下載最新的 hwaccel.ml.yml 文件，並確保它與 docker-compose.yml 文件位於同一資料夾中。
在 docker-compose.yml 中的 immich-machine-learning 部分，取消註解 extends 區段，並將 cpu 更改為適當的後端。
同樣在 immich-machine-learning 中，在 image 區段的末尾添加以下之一 -[armnn, cuda, rocm, openvino, rknn]。
使用更新的設置重新部署 immich-machine-learning 容器。

確認設備使用

您可以通過檢查設備的利用率來確認它是否被識別和使用。有許多工具可以顯示此資訊，例如 NVIDIA 或 Intel 的 nvtop、Intel 的 intel_gpu_top 和 AMD 的 radeontop。

您還可以檢查 immich-machine-learning 容器的日誌。在智能搜索或人臉檢測工作開始時，或在 Immich 中使用文本搜索時，您應該會看到一條 Available ORT providers 的日誌，其中包含相關提供者（例如，在 CUDA 的情況下是 CUDAExecutionProvider），或者在 ARM NN 的情況下，出現 Loaded ANN model 的日誌條目且無錯誤。

單鍵組合文件

截至撰寫時，包括 Unraid 和 Portainer 在內的一些平台不支援多鍵組合文件。作為替代方案，您可以將 hwaccel.ml.yml 文件中相關內容直接 "內嵌" 到 immich-machine-learning 服務中。

例如，此文件中的 cuda 區段為：

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

您可以將其添加到 immich-machine-learning 服務中，而不是從 hwaccel.ml.yml 擴展：

immich-machine-learning:
  container_name: immich_machine_learning
  # 注意 `-cuda` 在末尾
  image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}-cuda
  # 注意缺少 `extends` 區段
  deploy:
    resources:
      reservations:
        devices:
          - driver: nvidia
            count: 1
            capabilities:
              - gpu
  volumes:
    - model-cache:/cache
  env_file:
    - .env
  restart: always

完成此操作後，您可以重新部署 immich-machine-learning 容器。

多 GPU

如果要使用多個 NVIDIA 或 Intel GPUs，可以將環境變數 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

在此示例中，機器學習服務將生成兩個工作者，其中一個將分配模型給設備 0，另一個則分配給設備 1。不同的請求將由其中一個工作者處理。

此方法也可以用於簡單地指定特定設備。例如，設置 MACHINE_LEARNING_DEVICE_IDS=1 可確保始終使用設備 1 而不是設備 0。

請注意，應增加工作併發數以提高總體利用率，更有效地分配工作負載到多個 GPUs。另外，每個 GPU 必須能夠加載所有模型。不可能將單個模型分佈到多個 VRAM 不足的 GPUs，或將特定模型委派給某個 GPU。

提示

如果在運行模型時遇到錯誤，請嘗試使用其他模型以查看問題是否特定於模型。
您可能希望將併發數量增加到默認值以上以提高利用率。然而，需要考慮的是，這將增加 VRAM 消耗。
如果您的 VRAM 足夠，大型模型從硬體加速中獲益更大。
與 ARM NN 相比，RKNPU 具有以下特點：
- 更廣泛的模型支持（包括搜索，ARM NN 不進行加速）
- 更少的熱量產生
- 非常輕微的準確性降低（RKNPU 始終使用 FP16，而 ARM NN 默認使用更高精度的 FP32，除非啟用了 MACHINE_LEARNING_ANN_FP16_TURBO）
- 速度變化（在 RK3588 上測試）：
  - 如果 MACHINE_LEARNING_RKNN_THREADS 默認為 1，大多數情況下 RKNPU 的 ML 工作吞吐量將顯著低於 ARM NN，但延遲相似（例如在搜索時）
  - 如果將 MACHINE_LEARNING_RKNN_THREADS 設置為 3，FP32 模式下速度稍快於 ARM NN，但如果啟用了 MACHINE_LEARNING_ANN_FP16_TURBO，則稍慢。
  - 當其他任務也使用 GPU（如轉碼）時，RKNPU 相較於 ARM NN 具有顯著優勢，因為它使用的是本來處於閒置狀態的 NPU，而不是與 GPU 使用競爭。
- 如果 MACHINE_LEARNING_RKNN_THREADS 為默認的 1，RAM 使用量較低，但若超過 1，則顯著增加（這對於其完全利用 NPU 並在速度上與 ARM NN 可比是必要的）。

支援的後端​

限制​

前置需求​

ARM NN​

CUDA​

ROCm​

OpenVINO​

RKNN​

設置​

確認設備使用​

單鍵組合文件​

多 GPU​

提示​