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

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

학습 내용#

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

사전 요구 사항#

• 시스템에 Docker가 설치되어 있는지 확인하십시오. 설치되어 있지 않다면 Docker 웹사이트에서 다운로드하여 설치할 수 있습니다.
• GPU 가속을 위해 시스템에 NVIDIA GPU와 NVIDIA 드라이버가 설치되어 있는지 확인하십시오. CPU 이미지에는 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

Docker에서 CDI 장치 확인하기#

GPU CDI 장치를 사용할 수 있는지 확인하려면 nvidia-ctk cdi list을 실행하십시오(툴킷의 nvidia-cdi-refresh 서비스는 툴킷 버전 1.18 이상에서 사양을 자동으로 생성하고 유지 관리합니다).

nvidia-ctk cdi list

nvidia.com/gpu=0 및 nvidia.com/gpu=all과 같은 항목이 표시되어야 합니다. 검색된 CDI 장치는 docker info에도 나타납니다.

Ultralytics Docker 이미지 설치#

Ultralytics는 Docker Hub에 다음 이미지를 게시합니다. 각 이미지는 Docker 게시 워크플로에 의해 링크된 Dockerfile에서 빌드됩니다.

latest으로 시작하는 태그는 가장 최근에 게시된 메인 브랜치 빌드를 추적합니다. 버전이 지정된 태그는 latest 접두사를 VERSION, VERSION-cpu 또는 VERSION-jetson-jetpack6와 같은 Ultralytics 릴리스로 대체합니다. 재현 가능한 환경을 위해 버전이 지정된 태그를 사용하십시오.

최신 이미지를 가져오려면 다음을 수행하십시오:

# Pull the latest Ultralytics image from Docker Hub
sudo docker pull ultralytics/ultralytics:latest

Docker 컨테이너에서 Ultralytics 실행#

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

CPU만 사용#

# Run without GPU
sudo docker run -it --ipc=host ultralytics/ultralytics:latest-cpu

GPU 사용#

# Run with all GPUs
sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest

# Run specifying which GPUs to use
sudo docker run -it --ipc=host --device nvidia.com/gpu=2 --device nvidia.com/gpu=3 ultralytics/ultralytics:latest

-it 플래그는 유사 TTY를 할당하고 표준 입력을 열어 두어 컨테이너와 상호 작용할 수 있게 합니다. --ipc=host 플래그는 호스트의 IPC 네임스페이스 공유를 활성화하며, 이는 프로세스 간 메모리 공유에 필수적입니다. --device nvidia.com/gpu=... 플래그는 CDI를 통해 컨테이너가 호스트의 GPU에 접근할 수 있도록 권한을 부여합니다.

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

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

# Mount a local directory into the container
sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latest

/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 ultralytics/ultralytics:latest

GUI와 함께 Docker 사용#

이제 Docker 컨테이너 내에서 그래픽 애플리케이션을 표시할 수 있습니다. 예를 들어, 다음 CLI command을(를) 실행하여 YOLO26 model의 predictions을(를) 시각화할 수 있습니다:

yolo predict model=yolo26n.pt show=True

Docker GUI 사용 종료 시#

xhost -local:docker

이제 Ultralytics를 Docker와 함께 사용할 준비가 완료되었으며 기능을 활용할 수 있습니다. Ultralytics 웹 애플리케이션을 자체 호스팅하려면 Platform On-Premise 가이드를 참조하십시오. 대체 Python 패키지 설치 방법은 Ultralytics quickstart 문서를 참조하십시오.

FAQ#

Docker로 Ultralytics를 어떻게 설정합니까?#

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

sudo docker pull ultralytics/ultralytics:latest

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

머신러닝 프로젝트에 Ultralytics Docker 이미지를 사용할 때의 이점은 무엇입니까?#

Ultralytics Docker 이미지를 사용하면 서로 다른 기기 간에 일관된 환경이 보장되어 동일한 소프트웨어와 종속성이 복제됩니다. 이는 팀 간 협업, 다양한 하드웨어에서의 모델 실행, 재현성 유지에 특히 유용합니다. 일반적인 NVIDIA GPU 학습에는 latest을 사용하거나 NVIDIA Jetson 기기의 JetPack 버전에 맞는 이미지를 선택하십시오. 전체 이미지 표를 참조하거나 Ultralytics Docker Hub를 살펴보십시오.

Docker 컨테이너에서 GPU 지원과 함께 Ultralytics YOLO를 어떻게 실행할 수 있습니까?#

먼저 NVIDIA Container Toolkit이 설치 및 구성되어 있는지 확인하십시오. 그런 다음 다음 명령어를 사용하여 GPU 지원과 함께 Ultralytics YOLO를 실행하십시오.

sudo docker run -it --ipc=host --device nvidia.com/gpu=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

자세한 내용은 Run graphical user interface (GUI) applications in a Docker Container 섹션에서 확인할 수 있습니다.

로컬 디렉토리를 Ultralytics Docker 컨테이너에 마운트할 수 있습니까?#

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

sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latest

/path/on/host을 로컬 기기의 디렉터리로 교체하고, /path/in/container을 컨테이너 내부의 원하는 경로로 교체하십시오. 이 설정을 사용하면 컨테이너 내에서 로컬 파일로 작업할 수 있습니다. 자세한 내용은 Note on File Accessibility 섹션을 참조하십시오.