Hướng dẫn bắt đầu nhanh với Docker cho Ultralytics#

Hướng dẫn này cung cấp phần giới thiệu toàn diện về cách thiết lập môi trường Docker cho các dự án Ultralytics. Docker là nền tảng để phát triển, đóng gói và chạy ứng dụng trong các container. Docker đặc biệt hữu ích trong việc đảm bảo phần mềm luôn chạy nhất quán, bất kể được triển khai ở đâu. Để biết thêm chi tiết, hãy truy cập repository Docker của Ultralytics trên Docker Hub.

Bạn sẽ học được gì#

• Thiết lập Docker với hỗ trợ NVIDIA
• Cài đặt Docker image của Ultralytics
• Chạy Ultralytics trong Docker container với hỗ trợ CPU hoặc GPU
• Sử dụng display server với Docker để hiển thị kết quả detection của Ultralytics
• Mount các thư mục cục bộ vào container

Điều kiện tiên quyết#

• Hãy đảm bảo Docker đã được cài đặt trên hệ thống của bạn. Nếu chưa, bạn có thể tải xuống và cài đặt từ website của Docker.
• Để tăng tốc GPU, hãy đảm bảo hệ thống có GPU NVIDIA và đã cài đặt driver NVIDIA. CPU image không yêu cầu phần cứng NVIDIA.
• Nếu bạn sử dụng thiết bị NVIDIA Jetson, hãy đảm bảo đã cài đặt phiên bản JetPack phù hợp. Tham khảo hướng dẫn NVIDIA Jetson để biết thêm chi tiết.

Thiết lập Docker với hỗ trợ NVIDIA (Tùy chọn)#

Trước tiên, xác minh driver NVIDIA đã được cài đặt đúng cách bằng cách chạy:

nvidia-smi

Cài đặt NVIDIA Container Toolkit#

Bây giờ, hãy cài đặt NVIDIA Container Toolkit để bật hỗ trợ GPU trong các Docker container:

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

Xác minh thiết bị CDI với Docker#

Chạy nvidia-ctk cdi list để đảm bảo các thiết bị GPU CDI khả dụng (dịch vụ nvidia-cdi-refresh của toolkit tự động tạo và duy trì spec trên toolkit >= 1.18):

nvidia-ctk cdi list

Bạn sẽ thấy các mục như nvidia.com/gpu=0 và nvidia.com/gpu=all. Các thiết bị CDI được phát hiện cũng xuất hiện trong docker info.

Cài đặt Docker Image của Ultralytics#

Ultralytics phát hành các image sau lên Docker Hub. Mỗi image được build từ Dockerfile liên kết bởi quy trình phát hành Docker.

Các hình ảnh AMD64 GPU (latest, latest-export và latest-runner) sử dụng PyTorch 2.14 và CUDA 13.2. Kiểm tra hỗ trợ CUDA của trình điều khiển máy chủ bằng nvidia-smi trước khi khởi chạy chúng; việc cài đặt một container mới hơn không nâng cấp trình điều khiển máy chủ. CUDA 13 loại bỏ hỗ trợ cho các GPU Maxwell, Pascal và Volta, bao gồm Tesla P100 và V100. Xem ghi chú phát hành CUDA của NVIDIA và yêu cầu tương thích trình điều khiển.

Hình ảnh NVIDIA ARM64 sử dụng NVIDIA PyTorch 26.08 với CUDA 13.4 và TensorRT 11.2. Hỗ trợ PyTorch của hình ảnh NVIDIA ARM64 cho Thor không mở rộng sang TensorRT: NVIDIA không hỗ trợ TensorRT 11.2 trên JetPack. Đối với các xuất TensorRT trên Jetson, hãy sử dụng thời gian chạy TensorRT 10.x được hỗ trợ cho bản phát hành JetPack của bạn. Tuân theo các yêu cầu nền tảng trong hướng dẫn Jetson hoặc hướng dẫn DGX Spark. Các hình ảnh JetPack 4, 5 và 6 giữ lại các ngăn xếp riêng biệt dành cho từng thiết bị của chúng.

Dockerfile Conda có sẵn cho các bản dựng cục bộ; việc xuất bản tự động latest-conda đã bị vô hiệu hóa, do đó thẻ registry đó không chứa các cập nhật này.

Sử dụng latest-python-export cho các bản xuất LiteRT. Image GPU latest-export giữ nguyên PyTorch 2.14 và bỏ qua LiteRT vì dependency hiện tại của nó yêu cầu PyTorch dưới 2.14.

Các tag bắt đầu bằng latest theo dõi bản build mới nhất được phát hành từ main branch. Các tag có phiên bản thay thế tiền tố latest bằng một bản phát hành Ultralytics, chẳng hạn như VERSION, VERSION-cpu hoặc VERSION-jetson-jetpack6. Hãy sử dụng tag có phiên bản để có môi trường reproducible.

Để pull image mới nhất:

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

Thay vào đó, nếu muốn tự build image, hãy clone repository và truyền Dockerfile tương ứng từ bảng trên, sử dụng thư mục gốc của repository làm build context:

# Build the CPU image locally from docker/Dockerfile-cpu
sudo docker build -t ultralytics/ultralytics:latest-cpu -f docker/Dockerfile-cpu .

Chạy Ultralytics trong Docker Container#

Sau đây là cách thực thi Ultralytics Docker container:

Chỉ sử dụng CPU#

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

Sử dụng 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

Cờ -it gán pseudo-TTY và giữ stdin mở, cho phép bạn tương tác với container. Cờ --ipc=host bật chia sẻ namespace IPC của host, cần thiết để chia sẻ bộ nhớ giữa các process. Cờ --device nvidia.com/gpu=... cấp cho container quyền truy cập GPU của host thông qua CDI.

Lưu ý về khả năng truy cập file#

Để làm việc với các file trên máy cục bộ bên trong container, bạn có thể sử dụng Docker volume:

# 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

Thay /path/on/host bằng đường dẫn thư mục trên máy cục bộ của bạn và /path/in/container bằng đường dẫn mong muốn bên trong Docker container.

Lưu kết quả training#

Theo mặc định, kết quả training được lưu vào /ultralytics/runs/<task>/<name>/ bên trong container. Nếu không mount thư mục trên host, kết quả sẽ bị mất khi container bị xóa.

Để lưu kết quả training:

# 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

Thao tác này lưu toàn bộ kết quả training vào ./runs trên máy host của bạn.

Chạy ứng dụng giao diện người dùng đồ họa (GUI) trong Docker Container#

Docker chủ yếu được sử dụng để containerize các ứng dụng chạy nền và chương trình CLI, nhưng cũng có thể chạy các chương trình đồ họa. Trong môi trường Linux, có hai display server chính xử lý việc hiển thị đồ họa: X11 (còn được gọi là X Window System) và Wayland. Trước khi bắt đầu, điều quan trọng là xác định display server bạn đang sử dụng. Chạy lệnh này để kiểm tra:

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

Việc thiết lập và cấu hình display server X11 hoặc Wayland nằm ngoài phạm vi của hướng dẫn này. Nếu lệnh trên không trả về kết quả, trước tiên bạn cần thiết lập một trong hai display server hoạt động trên hệ thống của mình rồi mới tiếp tục.

Chạy Docker Container với GUI#

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

Sử dụng Docker với GUI#

Bây giờ bạn có thể hiển thị các ứng dụng đồ họa bên trong Docker container. Ví dụ, bạn có thể chạy lệnh CLI sau để trực quan hóa prediction từ YOLO26 model:

yolo predict model=yolo26n.pt show=True

Sau khi hoàn tất việc sử dụng Docker GUI#

xhost -local:docker

Bây giờ bạn đã thiết lập xong để sử dụng Ultralytics với Docker và sẵn sàng khai thác các tính năng của nền tảng. Để tự host ứng dụng web Ultralytics, hãy xem hướng dẫn Platform On-Premise. Để biết các phương pháp cài đặt Python package khác, hãy xem tài liệu bắt đầu nhanh của Ultralytics.

FAQ#