ハードウェア加速機械学習

この機能により、GPUを使用してスマート検索や顔認識などの機械学習タスクを加速し、CPU負荷を軽減することができます。これは新しい機能であるため、まだ実験的な段階にあり、すべてのシステムで動作するわけではありません。

情報

ハードウェア加速を有効にした後、機械学習ジョブを再実行する必要はありません。有効化後に実行されるジョブには、加速デバイスが使用されます。

対応バックエンド

ARM NN (Mali)
CUDA (NVIDIA GPU、計算能力 5.2以上)
ROCm (AMD GPU)
OpenVINO (Intel GPU、例: Iris Xe, Arc)
RKNN (Rockchip)

制限事項

ここで説明される手順および設定はDocker Compose専用です。他のコンテナエンジンには異なる設定が必要な場合があります。
LinuxおよびWindows (WSL2を使用)サーバーのみ対応しています。
ARM NNはMali GPUを搭載したデバイスでのみサポートされます。他の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 Container Toolkitもインストールする必要があります。

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は特に古いプロセッサーやRAM容量が少ないサーバーで問題が発生する可能性が高いです。
デバイスがハードウェアアクセラレーションに使用できるよう、サーバーのカーネルバージョンが十分に新しいものであることを確認してください。
OpenVINOを使用すると、CPU処理に比べてRAM使用量が増加することが予想されます。

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）が含まれるか、もしくはエラーなしの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 GPUを利用する場合は、環境変数MACHINE_LEARNING_DEVICE_IDSにデバイスIDをカンマ区切りで指定し、MACHINE_LEARNING_WORKERSにリスト内のデバイス数を設定します。現在使用可能なデバイスとその対応するIDを確認するには、nvidia-smi -Lまたはglxinfo -Bなどのコマンドを実行できます。

例えば、デバイス0と1がある場合、次のように設定します:

MACHINE_LEARNING_DEVICE_IDS=0,1
MACHINE_LEARNING_WORKERS=2

この例では、機械学習サービスは2つのワーカーを生成し、それぞれデバイス0とデバイス1にモデルを割り当てます。異なるリクエストは、それぞれのワーカーによって処理されます。

また、この方法を使用して特定のデバイスを指定することも可能です。例えば、MACHINE_LEARNING_DEVICE_IDS=1を設定すると、デバイス1が常に使用され、デバイス0は使用されません。

ジョブの同時実行数を増やして、全体的な使用率を高め、複数GPUの作業を効率的に分散させることが推奨されます。ただし、各GPUはすべてのモデルを正常にロードできる必要があります。個々のVRAMが不足している場合、単一のモデルを複数のGPUに分割して処理することはできません。また、特定のGPUに特定のモデルを割り当てることもできません。

ヒント

モデルが実行中にエラーが発生した場合、別のモデルを試してその問題がモデル固有のものかどうかを確認してください。
使用率を高めるために同時実行数をデフォルト値以上に増やすことを検討してください。ただし、これによりVRAMの消費量も増加します。
大きなモデルは、VRAMが十分であればハードウェアアクセラレーションの恩恵をより受けます。
ARM NNに比べてRKNPUには次の特徴があります:
- より広いモデルサポート（検索にも対応、ARM NNはこれを高速化しません）
- 低い熱生成
- わずかに低い精度（RKNPUは常にFP16を使用、ARM NNはデフォルトでより高い精度のFP32を使用。ただし、MACHINE_LEARNING_ANN_FP16_TURBOを有効にするとFP16を使用）
- パフォーマンスの違い (RK3588でのテスト結果):
  - MACHINE_LEARNING_RKNN_THREADSがデフォルトの1では、RKNPUはほとんどの場合MLジョブのスループットがARM NNより大幅に低いが、レイテンシーはほぼ同等
  - MACHINE_LEARNING_RKNN_THREADSが3に設定されている場合、FP32でのARM NNよりやや速くなるが、MACHINE_LEARNING_ANN_FP16_TURBOが有効な場合はARM NNよりやや遅い
  - トランスコーディングなどの他のタスクもGPUを使用する場合、RKNPUはGPU使用を競合する代わりに通常アイドル状態のNPUを活用するためARM NNより有利
- MACHINE_LEARNING_RKNN_THREADSがデフォルトの1ではRAMの使用量は少ないが、それ以上に設定するとRAM使用量が大幅に増加（ただし、NPUを完全に活用するために必要で、その結果ARM NNと同等のスピードが得られる）

対応バックエンド​

制限事項​

前提条件​

ARM NN​

CUDA​

ROCm​

OpenVINO​

RKNN​

設定​

デバイスの使用確認​

単一コンポーズファイル​

複数GPU​

ヒント​