GPU와 함께 Qdrant 실행하기

GPU와 함께 Qdrant 실행하기 (ops-configuration-running-with-gpu)

v1.13.0부터 Qdrant는 GPU 가속을 지원해요.

다만 GPU 지원은 추가적인 의존성과 라이브러리 때문에 기본 Qdrant 바이너리에 포함되어 있지 않아요. 대신 GPU 지원이 포함된 전용 Docker 이미지(NVIDIA, AMD)를 사용해야 해요.

설정 (Configuration)

Qdrant는 GPU 사용을 제어하는 여러 설정 옵션을 제공해요. 사용 가능한 옵션은 다음과 같아요.

gpu:
    # Enable GPU indexing.
    indexing: false
    # Force half precision for `f32` values while indexing.
    # `f16` conversion will take place 
    # only inside GPU memory and won't affect storage type.
    force_half_precision: false
    # Used vulkan "groups" of GPU. 
    # In other words, how many parallel points can be indexed by GPU.
    # Optimal value might depend on the GPU model.
    # Proportional, but doesn't necessary equal
    # to the physical number of warps.
    # Do not change this value unless you know what you are doing.
    # Default: 512
    groups_count: 512
    # Filter for GPU devices by hardware name. Case insensitive.
    # Comma-separated list of substrings to match 
    # against the gpu device name.
    # Example: "nvidia"
    # Default: "" - all devices are accepted.
    device_filter: ""
    # List of explicit GPU devices to use.
    # If host has multiple GPUs, this option allows to select specific devices
    # by their index in the list of found devices.
    # If `device_filter` is set, indexes are applied after filtering.
    # By default, all devices are accepted.
    devices: null
    # How many parallel indexing processes are allowed to run.
    # Default: 1
    parallel_indexes: 1
    # Allow to use integrated GPUs.
    # Default: false
    allow_integrated: false
    # Allow to use emulated GPUs like LLVMpipe. Useful for CI.
    # Default: false
    allow_emulated: false

이 옵션들은 Qdrant 내부와 Vulkan API에 익숙하지 않다면 바꾸지 않는 걸 권장해요.

독립 실행형(Standalone) GPU 지원

독립 실행형으로 쓰는 경우, 다음 명령으로 GPU 지원을 포함해 Qdrant를 빌드할 수 있어요.

cargo build --release --features gpu

여기서 주의할 점은 장치가 Vulkan API v1.3을 지원해야 한다는 거예요. 여기에는 Apple Silicon, Intel GPU, CPU 에뮬레이터와의 호환성도 포함돼요. 그리고 런타임에 GPU를 쓰려면 설정에 gpu.indexing: true를 반드시 지정해야 해요.

NVIDIA GPU

사전 요구사항 (Prerequisites)

Docker에서 NVIDIA GPU 지원을 사용하려면 호스트에 다음이 설치되어 있어야 해요.

• 최신 NVIDIA 드라이버
• nvidia-container-toolkit

Amazon/GCP의 대부분 AI 또는 CUDA 이미지에는 NVIDIA 컨테이너 툴킷이 미리 구성되어 있어요.

NVIDIA GPU 지원 Docker 이미지

NVIDIA GPU 지원 Docker 이미지는 태그 접미사 gpu-nvidia를 사용해요. 예를 들어 qdrant/qdrant:v1.13.0-gpu-nvidia처럼요. 이 이미지에는 필요한 모든 의존성이 포함되어 있어요.

GPU 지원을 활성화하려면 Docker 설정에 --gpus=all 플래그를 사용해요. 예시는 다음과 같아요.

# `--gpus=all` flag says to Docker that we want to use GPUs.
# `-e QDRANT__GPU__INDEXING=1` flag says to Qdrant that we want to use GPUs for indexing.
docker run \
	--rm \
	--gpus=all \
	-p 6333:6333 \
	-p 6334:6334 \
	-e QDRANT__GPU__INDEXING=1 \
	qdrant/qdrant:gpu-nvidia-latest

GPU가 올바르게 초기화됐는지 로그에서 확인할 수 있어요. Qdrant는 먼저 필터링 없이 발견된 모든 GPU 장치를 출력하고, 그다음 생성된 모든 장치 목록을 출력해요.

2025-01-13T11:58:29.124087Z  INFO gpu::instance: Found GPU device: NVIDIA GeForce RTX 3090    
2025-01-13T11:58:29.124118Z  INFO gpu::instance: Found GPU device: llvmpipe (LLVM 15.0.7, 256 bits)    
2025-01-13T11:58:29.124138Z  INFO gpu::device: Create GPU device NVIDIA GeForce RTX 3090    

여기선 두 장치가 발견된 걸 볼 수 있어요. RTX 3090과 llvmpipe(Docker 이미지에 포함된 CPU 에뮬레이션 GPU)요. 이후 로그를 보면 RTX만 초기화된 걸 확인할 수 있어요.

이로써 설정이 끝났어요. 이제 이 Qdrant 인스턴스를 사용하기 시작하면 됩니다.

NVIDIA GPU 문제 해결 (Troubleshooting NVIDIA GPUs)

Docker에서 GPU가 감지되지 않으면 드라이버와 nvidia-container-toolkit이 최신인지 확인해요. 필요하다면 GitHub Releases 페이지에서 최신 버전의 nvidia-container-toolkit을 설치할 수 있어요.

Docker 컨테이너 안에서 Vulkan API 가시성을 다음으로 확인해요.

docker run --rm --gpus=all qdrant/qdrant:gpu-nvidia-latest vulkaninfo --summary

시스템이 NVIDIA 장치가 보이지 않는 이유를 설명하는 오류 메시지를 보여줄 수 있어요. 참고로 NVIDIA GPU가 Docker에서 보이지 않으면 Docker 이미지가 호스트의 libGLX_nvidia.so.0을 사용할 수 없어요. 오류 메시지는 대략 이렇게 생겼어요.

ERROR: [Loader Message] Code 0 : loader_scanned_icd_add: Could not get `vkCreateInstance` via `vk_icdGetInstanceProcAddr` for ICD libGLX_nvidia.so.0
WARNING: [Loader Message] Code 0 : terminator_CreateInstance: Failed to CreateInstance in ICD 0. Skipping ICD.

오류를 해결하려면 NVIDIA 컨테이너 런타임 설정을 업데이트해요.

sudo nano /etc/nvidia-container-runtime/config.toml

no-cgroups=false로 설정하고 저장한 뒤, Docker를 재시작해요.

sudo systemctl restart docker

AMD GPU

사전 요구사항 (Prerequisites)

AMD GPU로 Qdrant를 실행하려면 호스트에 ROCm이 설치되어 있어야 해요.

AMD GPU 지원 Docker 이미지

AMD GPU용 Docker 이미지는 태그 접미사 gpu-amd를 사용해요. 예를 들어 qdrant/qdrant:v1.13.0-gpu-amd처럼요. 이 이미지에는 필요한 모든 의존성이 포함되어 있어요.

Docker에 GPU를 활성화하려면 추가로 --device /dev/kfd --device /dev/dri 플래그가 필요해요. Qdrant에 GPU를 활성화하려면 enable 플래그를 설정해야 해요. 예시는 다음과 같아요.

# `--device /dev/kfd --device /dev/dri` flags say to Docker that we want to use GPUs.
# `-e QDRANT__GPU__INDEXING=1` flag says to Qdrant that we want to use GPUs for indexing.
docker run \
	--rm \
	--device /dev/kfd --device /dev/dri \
	-p 6333:6333 \
	-p 6334:6334 \
	-e QDRANT__LOG_LEVEL=debug \
	-e QDRANT__GPU__INDEXING=1 \
	qdrant/qdrant:gpu-amd-latest

로그를 확인해 GPU 초기화를 확인해요. 예시 로그 출력은 다음과 같아요.

2025-01-10T11:56:55.926466Z  INFO gpu::instance: Found GPU device: AMD Radeon Graphics (RADV GFX1103_R1)
2025-01-10T11:56:55.926485Z  INFO gpu::instance: Found GPU device: llvmpipe (LLVM 17.0.6, 256 bits) 
2025-01-10T11:56:55.926504Z  INFO gpu::device: Create GPU device AMD Radeon Graphics (RADV GFX1103_R1)

이로써 설정이 끝났어요. 기본적인 시나리오에서는 다른 걸 추가로 설정할 필요가 없어요.

알려진 제한 사항 (Known limitations)

• 플랫폼 지원: Docker 이미지는 Linux x86_64에서만 사용할 수 있어요. Windows, macOS, ARM, 그리고 다른 플랫폼은 지원되지 않아요.
• 메모리 제한: 각 GPU는 인덱싱 반복(iteration)마다 최대 16GB의 벡터 데이터를 처리할 수 있어요.

이 제한 때문에, 원본 벡터든 양자화된 벡터든 16GB보다 큰 세그먼트를 만들면 안 돼요.

예를 들어 1536차원 벡터와 스칼라 양자화를 쓰는 컬렉션은 세그먼트당 최대:

16Gb / 1536 ~= 11 million vectors per segment

그리고 양자화 없이:

16Gb / 1536 * 4 ~= 2.7 million vectors per segment

각 세그먼트의 최대 크기는 컬렉션 설정에서 구성할 수 있어요. 기존 컬렉션에서 다음 연산으로 변경할 수 있어요.

PATCH collections/{collection_name}
{
  "optimizers_config": {
    "max_segment_size": 1000000
  }
}

참고로 max_segment_size는 킬로바이트(KiloBytes) 단위로 지정해요.

출처: Qdrant 공식문서

더 알아보기 (Learn more)

• 운영 구성(Operational Configuration) 개요
• 설정(Configuration)
• 용량 계획