하드웨어 가속 머신 러닝

이 기능은 GPU를 사용하여 스마트 검색 및 얼굴 인식과 같은 머신 러닝 작업을 가속화하고 CPU 부하를 줄일 수 있도록 합니다. 이것은 새로운 기능이므로 아직 실험적이며 모든 시스템에서 작동하지 않을 수 있습니다.

정보

하드웨어 가속을 활성화한 후 머신 러닝 작업을 다시 수행할 필요는 없습니다. 활성화 후 실행되는 작업에서 가속 장치가 사용됩니다.

지원되는 백엔드

ARM NN (Mali)
CUDA (컴퓨팅 가능 버전이 5.2 이상인 NVIDIA GPU)
ROCm (AMD GPU)
OpenVINO (Iris Xe 및 Arc와 같은 Intel GPU)
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=<지원되는 버전, 예: 10.3.0>을 시도할 수 있습니다. 실패 시, HSA_USE_SVM=0도 설정해야 할 수 있습니다.
ROCm 이미지는 크기가 매우 커서 최소 35GiB의 여유 디스크 공간이 필요합니다. 그러나 Docker를 통해 서비스를 업데이트하는 경우 일반적으로 몇백 메가바이트만 소요됩니다(나머지는 캐시됩니다).
이 백엔드는 새로워서 일부 문제가 발생할 수 있습니다. 예를 들어, 머신 러닝 서비스가 유휴 상태인 경우에도 추론 후 GPU 전력 소모가 평소보다 높을 수 있습니다. 이 경우 유휴 상태가 5분 후에(설정 가능) 정상으로 돌아옵니다.

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에 비해 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에서 텍스트로 검색할 때, 관련 제공자(e.g., CUDA의 경우 CUDAExecutionProvider)를 포함하는 Available ORT providers 로그 또는 ARM NN의 경우 오류 없는 Loaded ANN model 로그 항목을 확인할 수 있습니다.

단일 Compose 파일

Unraid 및 Portainer를 포함한 일부 플랫폼은 작성 시 다중 Compose 파일을 지원하지 않습니다. 대신, hwaccel.ml.yml 파일의 관련 내용을 immich-machine-learning 서비스에 직접 추가할 수 있습니다.

예를 들어, 이 파일의 cuda 섹션은 다음과 같습니다:

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

이를 hwaccel.ml.yml에서 확장하는 대신 immich-machine-learning 서비스에 추가할 수 있습니다:

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

이 예에서 머신 러닝 서비스는 두 개의 작업자를 실행하며, 각 작업자가 0번 또는 1번 장치에 모델을 할당합니다. 서로 다른 요청은 작업자 중 하나가 처리합니다.

이 방법은 특정 장치를 지정하는 데도 사용할 수 있습니다. 예를 들어, MACHINE_LEARNING_DEVICE_IDS=1로 설정하면 0번 대신 항상 1번 장치를 사용하도록 보장합니다.

작업 동시성을 증가시켜 전체 사용률을 높이고 더 효과적으로 작업을 여러 GPU에 분산할 수 있습니다. 또한, 각 GPU는 모든 모델을 로드할 수 있어야 합니다. VRAM이 부족한 단일 모델을 여러 GPU에 분산하거나 특정 모델을 한 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를 활성화한 ARM NN보다 약간 느립니다.
  - 다른 작업도 GPU를 사용하는 경우(예: 트랜스코딩), RKNPU는 GPU 사용 대신 유휴 상태의 NPU를 사용하므로 ARM NN보다 상당한 장점을 가집니다.
- MACHINE_LEARNING_RKNN_THREADS가 기본값 1로 설정된 경우 더 낮은 RAM 사용량을 가지지만, 1 이상으로 설정되는 경우(ARM NN과 유사한 속도를 가지기 위해 NPU를 완전히 활용하려면 필요함) RAM 소비가 크게 증가합니다.

지원되는 백엔드​

제한사항​

사전 준비사항​

ARM NN​

CUDA​

ROCm​

OpenVINO​

RKNN​

설정​

장치 사용 확인​

단일 Compose 파일​

다중 GPU​

팁​