Ultralytics를 위한 Docker 퀵스타트 가이드

이 가이드는 Ultralytics 프로젝트를 위한 Docker 환경 설정에 대한 포괄적인 소개를 제공합니다. Docker는 컨테이너 내부에서 애플리케이션을 개발, 배포 및 실행하기 위한 플랫폼입니다. 이 플랫폼은 소프트웨어가 어디에 배포되든 항상 동일하게 실행되도록 보장하는 데 특히 유용합니다. 자세한 내용은 Docker Hub의 Ultralytics Docker 저장소를 방문하십시오.

학습 내용

• NVIDIA 지원을 포함한 Docker 설정
• Ultralytics Docker 이미지 설치
• CPU 또는 GPU 지원을 사용하여 Docker 컨테이너에서 Ultralytics 실행하기
• Docker와 함께 디스플레이 서버를 사용하여 Ultralytics 탐지 결과 표시하기
• 로컬 디렉토리를 컨테이너에 마운트하기

사전 요구 사항

• 시스템에 Docker가 설치되어 있는지 확인하십시오. 설치되어 있지 않다면 Docker 웹사이트에서 다운로드하여 설치할 수 있습니다.
• 시스템에 NVIDIA GPU가 있고 NVIDIA 드라이버가 설치되어 있는지 확인하십시오.
• NVIDIA Jetson 장치를 사용하는 경우, 적절한 JetPack 버전이 설치되어 있는지 확인하십시오. 자세한 내용은 NVIDIA Jetson 가이드를 참조하십시오.

NVIDIA 지원을 포함한 Docker 설정

먼저 다음을 실행하여 NVIDIA 드라이버가 올바르게 설치되었는지 확인하십시오:

nvidia-smi

NVIDIA Container Toolkit 설치

이제 Docker 컨테이너에서 GPU 지원을 활성화하기 위해 NVIDIA Container Toolkit을 설치하겠습니다:

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
    | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update

sudo apt-get install -y nvidia-container-toolkit \
  nvidia-container-toolkit-base libnvidia-container-tools \
  libnvidia-container1

export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.17.8-1
sudo apt-get install -y \
  nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION}

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Docker로 NVIDIA 런타임 검증

docker info | grep -i runtime을 실행하여 런타임 목록에 nvidia가 나타나는지 확인하십시오:

docker info | grep -i runtime

Ultralytics Docker 이미지 설치

Ultralytics는 다양한 플랫폼 및 사용 사례에 최적화된 여러 Docker 이미지를 제공합니다:

• Dockerfile: 학습에 최적화된 GPU 이미지.
• Dockerfile-arm64: Raspberry Pi와 같은 장치에 적합한 ARM64 아키텍처용 이미지.
• Dockerfile-cpu: 추론 및 비 GPU 환경을 위한 CPU 전용 버전.
• Dockerfile-jetson-jetpack4: Optimized for NVIDIA Jetson devices running NVIDIA JetPack 4.
• Dockerfile-jetson-jetpack5: Optimized for NVIDIA Jetson devices running NVIDIA JetPack 5.
• Dockerfile-jetson-jetpack6: Optimized for NVIDIA Jetson devices running NVIDIA JetPack 6.
• Dockerfile-jupyter: 브라우저에서 JupyterLab을 사용하는 대화형 개발용.
• Dockerfile-nvidia-arm64: JetPack 7.0 및 DGX OS를 지원하는 Jetson AGX Thor 및 DGX Spark와 같은 NVIDIA ARM64 장치용.
• Dockerfile-python: 경량 애플리케이션을 위한 최소 Python 환경.
• Dockerfile-python-export: YOLO 모델 변환을 위한 전체 내보내기 기능이 포함된 최소 Python 이미지.
• Dockerfile-conda: Miniconda3 및 Conda를 통해 설치된 Ultralytics 패키지 포함.
• Dockerfile-export: 모델 변환 및 벤치마킹을 위해 모든 내보내기 형식 종속성이 사전 설치된 GPU 이미지.

최신 이미지를 가져오려면:

# Set image name as a variable
t=ultralytics/ultralytics:latest

# Pull the latest Ultralytics image from Docker Hub
sudo docker pull $t

Docker 컨테이너에서 Ultralytics 실행하기

Ultralytics Docker 컨테이너를 실행하는 방법은 다음과 같습니다:

CPU만 사용

# Run without GPU
sudo docker run -it --ipc=host $t

GPU 사용

# Run with all GPUs
sudo docker run -it --ipc=host --runtime=nvidia --gpus all $t

# Run specifying which GPUs to use
sudo docker run -it --ipc=host --runtime=nvidia --gpus '"device=2,3"' $t

-it 플래그는 의사 터미널(pseudo-TTY)을 할당하고 표준 입력을 열어 두어 컨테이너와 상호 작용할 수 있게 합니다. --ipc=host 플래그는 호스트의 IPC 네임스페이스 공유를 활성화하며, 이는 프로세스 간 메모리를 공유하는 데 필수적입니다. --gpus 플래그는 컨테이너가 호스트의 GPU에 액세스할 수 있도록 합니다.

파일 접근성에 대한 참고 사항

컨테이너 내에서 로컬 컴퓨터의 파일로 작업하려면 Docker 볼륨을 사용할 수 있습니다:

# Mount a local directory into the container
sudo docker run -it --ipc=host --runtime=nvidia --gpus all -v /path/on/host:/path/in/container $t

/path/on/host를 로컬 컴퓨터의 디렉토리 경로로, /path/in/container를 Docker 컨테이너 내부의 원하는 경로로 바꾸십시오.

학습 출력 유지

학습 결과는 기본적으로 컨테이너 내부의 /ultralytics/runs/<task>/<name>/에 저장됩니다. 호스트 디렉토리를 마운트하지 않으면 컨테이너가 제거될 때 결과도 삭제됩니다.

학습 결과를 보존하려면:

# Recommended: mount workspace and specify project path
sudo docker run --rm -it -v "$(pwd)":/w -w /w ultralytics/ultralytics:latest \
  yolo train model=yolo26n.pt data=coco8.yaml project=/w/runs

이렇게 하면 모든 학습 결과가 호스트 머신의 ./runs에 저장됩니다.

Docker 컨테이너에서 그래픽 사용자 인터페이스(GUI) 애플리케이션 실행하기

Docker는 주로 백그라운드 애플리케이션 및 CLI 프로그램을 컨테이너화하는 데 사용되지만, 그래픽 프로그램을 실행할 수도 있습니다. Linux 세계에서는 X11(X Window System이라고도 함)과 Wayland라는 두 가지 주요 그래픽 서버가 그래픽 표시를 처리합니다. 시작하기 전에 현재 사용 중인 그래픽 서버를 확인하는 것이 필수적입니다. 다음 명령을 실행하여 확인하십시오:

env | grep -E -i 'x11|xorg|wayland'

X11 또는 Wayland 디스플레이 서버의 설정 및 구성은 이 가이드의 범위를 벗어납니다. 위 명령이 아무것도 반환하지 않으면 계속하기 전에 시스템에서 이들 중 하나가 작동하도록 설정해야 합니다.

GUI가 포함된 Docker 컨테이너 실행하기

xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v ~/.Xauthority:/root/.Xauthority \
  -it --ipc=host $t

GUI와 함께 Docker 사용하기

Now you can display graphical applications inside your Docker container. For example, you can run the following CLI command to visualize the predictions from a YOLO26 model:

yolo predict model=yolo26n.pt show=True

Docker GUI 작업 완료 시

xhost -local:docker

이제 Docker로 Ultralytics를 사용할 준비가 되었으며 해당 기능을 활용할 준비가 되었습니다. 다른 설치 방법은 Ultralytics 퀵스타트 문서를 참조하십시오.

FAQ

Docker로 Ultralytics를 설정하려면 어떻게 해야 하나요?

Docker로 Ultralytics를 설정하려면 먼저 시스템에 Docker가 설치되어 있는지 확인하십시오. NVIDIA GPU가 있는 경우 GPU 지원을 활성화하기 위해 NVIDIA Container Toolkit을 설치하십시오. 그런 다음 다음 명령을 사용하여 Docker Hub에서 최신 Ultralytics Docker 이미지를 가져오십시오:

sudo docker pull ultralytics/ultralytics:latest

자세한 단계는 Docker 퀵스타트 가이드를 참조하십시오.

머신러닝 프로젝트에 Ultralytics Docker 이미지를 사용하면 어떤 이점이 있나요?

Ultralytics Docker 이미지를 사용하면 서로 다른 머신에서 일관된 환경을 보장하며 동일한 소프트웨어 및 종속성을 복제할 수 있습니다. 이는 팀 간 협업, 다양한 하드웨어에서 모델 실행 및 재현성 유지에 특히 유용합니다. GPU 기반 학습을 위해 Ultralytics는 일반 GPU 사용을 위한 Dockerfile 및 NVIDIA Jetson 장치를 위한 Dockerfile-jetson과 같은 최적화된 Docker 이미지를 제공합니다. 자세한 내용은 Ultralytics Docker Hub를 살펴보십시오.

GPU 지원을 사용하여 Docker 컨테이너에서 Ultralytics YOLO를 실행하려면 어떻게 해야 하나요?

먼저 NVIDIA Container Toolkit이 설치 및 구성되었는지 확인하십시오. 그런 다음 다음 명령을 사용하여 GPU 지원으로 Ultralytics YOLO를 실행하십시오:

sudo docker run -it --ipc=host --runtime=nvidia --gpus all ultralytics/ultralytics:latest # all GPUs

이 명령은 GPU 액세스가 가능한 Docker 컨테이너를 설정합니다. 추가 세부 정보는 Docker 퀵스타트 가이드를 참조하십시오.

디스플레이 서버가 있는 Docker 컨테이너에서 YOLO 예측 결과를 시각화하려면 어떻게 해야 하나요?

Docker 컨테이너의 GUI로 YOLO 예측 결과를 시각화하려면 Docker가 디스플레이 서버에 액세스할 수 있도록 허용해야 합니다. X11을 실행하는 시스템의 경우 명령은 다음과 같습니다:

xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v ~/.Xauthority:/root/.Xauthority \
  -it --ipc=host ultralytics/ultralytics:latest

Wayland를 실행하는 시스템의 경우 다음을 사용하십시오:

xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
  -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/tmp/$WAYLAND_DISPLAY \
  --net=host -it --ipc=host ultralytics/ultralytics:latest

자세한 내용은 Docker 컨테이너에서 그래픽 사용자 인터페이스(GUI) 애플리케이션 실행하기 섹션에서 확인할 수 있습니다.

로컬 디렉토리를 Ultralytics Docker 컨테이너에 마운트할 수 있나요?

네, -v 플래그를 사용하여 로컬 디렉토리를 Ultralytics Docker 컨테이너에 마운트할 수 있습니다:

sudo docker run -it --ipc=host --runtime=nvidia --gpus all -v /path/on/host:/path/in/container ultralytics/ultralytics:latest

/path/on/host를 로컬 머신의 디렉토리로, /path/in/container를 컨테이너 내부의 원하는 경로로 바꾸십시오. 이 설정을 통해 컨테이너 내에서 로컬 파일로 작업할 수 있습니다. 자세한 내용은 파일 접근성에 대한 참고 사항 섹션을 참조하십시오.