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

Hướng dẫn này giới thiệu toàn diện cách thiết lập môi trường Docker cho các dự án Ultralytics của bạn. Docker là nền tảng để phát triển, phân phố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 giống nhau, bất kể được triển khai ở đâu. Để biết thêm chi tiết, hãy truy cập kho lưu trữ Docker của Ultralytics trên Docker Hub.

Bạn sẽ tìm hiểu#

• Thiết lập Docker với hỗ trợ NVIDIA
• Cài đặt Docker image 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ả phát hiện của Ultralytics
• Mount thư mục cục bộ vào container

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

• Đả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 Docker từ trang web Docker.
• Để tăng tốc GPU, hãy đảm bảo hệ thống có GPU NVIDIA và đã cài đặt driver NVIDIA. Image CPU 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 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 bằng 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 Ultralytics#

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

Các GPU image AMD64 (latest, latest-export và latest-runner) sử dụng PyTorch 2.14 và CUDA 13.2. Trước khi khởi chạy, hãy kiểm tra khả năng hỗ trợ CUDA của driver máy chủ bằng nvidia-smi; cài đặt container mới hơn không nâng cấp driver máy chủ. CUDA 13 ngừng hỗ trợ 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 driver.

Image NVIDIA ARM64 sử dụng NVIDIA PyTorch 26.08 với CUDA 13.4 và TensorRT 11.2. Khả năng hỗ trợ Thor của PyTorch không áp dụng cho TensorRT: NVIDIA không hỗ trợ TensorRT 11.2 trên JetPack. Để xuất TensorRT cho Jetson, hãy sử dụng runtime TensorRT 10.x được hỗ trợ cho bản JetPack của bạn. Làm theo yêu cầu nền tảng trong hướng dẫn Jetson hoặc hướng dẫn DGX Spark. Các image JetPack 4, 5 và 6 vẫn giữ nguyên các stack riêng cho từng thiết bị.

Dockerfile Conda có sẵn để build cục bộ; tính năng phát hành tự động của latest-conda đã bị tắt, vì vậy tag registry đó không chứa các bản cập nhật này.

Sử dụng latest-python-export để xuất LiteRT. GPU image latest-export vẫn dùng PyTorch 2.14 và không bao gồm LiteRT vì dependency hiện tại của LiteRT yêu cầu PyTorch thấp hơn 2.14.

Các image Python, CPU, Jupyter và CPU runner sử dụng Python 3.14. Image Python export sử dụng base latest-python-3.13, được build từ cùng Dockerfile-python với --build-arg PYTHON_VERSION=3.13, vì TensorFlow, CoreML và PaddlePaddle hiện chưa hỗ trợ Python 3.14.

Các tag bắt đầu bằng latest theo dõi bản build nhánh main được phát hành gần đây nhất. Trong tag có phiên bản, tiền tố latest được thay bằng phiên bản phát hành Ultralytics, chẳng hạn VERSION, VERSION-cpu hoặc VERSION-jetson-jetpack6. Hãy dùng tag có phiên bản để tạo môi trường có thể tái lập.

Để tải image mới nhất:

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

Nếu muốn tự build image, hãy clone repository và truyền Dockerfile tương ứng trong bảng trên, dùng thư mục gốc 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 chạy 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 cấp pseudo-TTY và giữ stdin luôn mở, cho phép bạn tương tác với container. Cờ --ipc=host bật chia sẻ namespace IPC của máy chủ, cần thiết để chia sẻ bộ nhớ giữa các tiến trình. Với GPU NVIDIA, cờ --device nvidia.com/gpu=... cấp quyền truy cập thông qua CDI. Với GPU AMD, các cờ --device cấp quyền truy cập vào driver kernel GPU (/dev/kfd) và các nút render của display (/dev/dri).

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

Để làm việc với file trên máy cục bộ từ 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 giữ output huấn luyện#

Theo mặc định, output huấn luyện được lưu tại /ultralytics/runs/<task>/<name>/ bên trong container. Nếu không mount thư mục trên máy chủ, output sẽ bị mất khi container bị xóa.

Để lưu giữ output huấn luyện:

# 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

Lệnh này lưu toàn bộ output huấn luyện vào ./runs trên máy chủ 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 dùng để đóng gói các ứng dụng chạy nền và chương trình CLI trong container, nhưng cũng có thể chạy các chương trình đồ họa. Trong môi trường Linux, có hai máy chủ đồ họa chính xử lý việc hiển thị: X11 (còn gọi là Hệ thống Cửa sổ X) và Wayland. Trước khi bắt đầu, bạn cần xác định máy chủ đồ họa hiện đang sử dụng. Chạy lệnh sau để kiểm tra:

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

Việc thiết lập và cấu hình máy chủ hiển thị 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ả, bạn cần bắt đầu bằng cách thiết lập một trong hai máy chủ này hoạt động trên hệ thống trước khi tiếp tục.

Chạy container Docker có giao diện đồ họa#

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 giao diện đồ họa#

Các image Ultralytics đi kèm OpenCV headless, vì vậy trước tiên hãy cài đặt bản GUI của OpenCV cùng các thư viện hệ thống bên trong container:

apt-get update && apt-get install -y --no-install-recommends libgl1 libglib2.0-0 libsm6
pip uninstall -y opencv-python-headless && pip install opencv-python

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

yolo predict model=yolo26n.pt show=True

Sau khi sử dụng giao diện đồ họa Docker#

xhost -local:docker

Giờ đây, bạn đã thiết lập xong để sử dụng Ultralytics với Docker và sẵn sàng khai thác các khả năng của nền tảng. Để tự lưu trữ ứng dụng web Ultralytics, hãy xem hướng dẫn triển khai tại chỗ cho nền tảng. Để biết các phương thức cài đặt gói Python khác, hãy xem tài liệu bắt đầu nhanh của Ultralytics.

Câu hỏi thường gặp#