Ultralytics için Docker Hızlı Başlangıç Kılavuzu#
Bu kılavuz, Ultralytics projelerin için Docker ortamı kurmaya yönelik kapsamlı bir başlangıç sunar. Docker, uygulamaları kapsayıcılarda geliştirmek, dağıtmak ve çalıştırmak için kullanılan bir platformdur. Yazılımın dağıtıldığı ortamdan bağımsız olarak her zaman aynı şekilde çalışmasını sağlamak açısından özellikle yararlıdır. Daha fazla bilgi için Docker Hub üzerindeki Ultralytics Docker deposunu ziyaret et.
Öğreneceklerin#
- Docker'ı NVIDIA desteğiyle kurma
- Ultralytics Docker görüntülerini yükleme
- Ultralytics'i CPU veya GPU desteğiyle Docker kapsayıcısında çalıştırma
- Ultralytics algılama sonuçlarını göstermek için Docker ile bir görüntü sunucusu kullanma
- Yerel dizinleri kapsayıcıya bağlama
İzle: Docker'ı Kullanmaya Nasıl Başlanır | Docker İçinde Ultralytics Python Paketinin Kullanımı Canlı Demo 🎉
Ön koşullar#
- Docker'ın sisteminde kurulu olduğundan emin ol. Kurulu değilse Docker'ın web sitesinden indirip yükleyebilirsin.
- GPU hızlandırması için sisteminde bir NVIDIA GPU bulunduğundan ve NVIDIA sürücülerinin yüklü olduğundan emin ol. CPU görüntüleri NVIDIA donanımı gerektirmez.
- NVIDIA Jetson cihazları kullanıyorsan uygun JetPack sürümünün yüklü olduğundan emin ol. Daha fazla bilgi için NVIDIA Jetson kılavuzuna bak.
Docker'ı NVIDIA Desteğiyle Kurma (İsteğe Bağlı)#
Önce şu komutu çalıştırarak NVIDIA sürücülerinin doğru şekilde yüklendiğini doğrula:
nvidia-smiNVIDIA Container Toolkit'i yükleme#
Şimdi Docker kapsayıcılarında GPU desteğini etkinleştirmek için NVIDIA Container Toolkit'i yükleyelim:
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.listPaket listelerini güncelle ve NVIDIA Container Toolkit'i yükle:
sudo apt-get updatesudo apt-get install -y nvidia-container-toolkitCDI Aygıtlarını Docker ile Doğrulama#
GPU CDI aygıtlarının kullanılabilir olduğunu doğrulamak için nvidia-ctk cdi list komutunu çalıştır (toolkit'in nvidia-cdi-refresh hizmeti, toolkit >= 1.18 olduğunda belirtimi otomatik olarak oluşturur ve yönetir):
nvidia-ctk cdi listnvidia.com/gpu=0 ve nvidia.com/gpu=all gibi girdiler görmelisin. Bulunan CDI aygıtları docker info içinde de görünür.
Ultralytics Docker Görüntülerini Yükleme#
Ultralytics aşağıdaki görüntüleri Docker Hub'da yayımlar. Her görüntü, bağlantılı Dockerfile'dan Docker yayımlama iş akışı kullanılarak derlenir.
| Etiket | Platform ve kullanım amacı | Kaynak |
|---|---|---|
latest | GPU eğitimi ve çıkarımı için CUDA destekli Linux AMD64 | Dockerfile |
latest-export | Dönüştürme ve kıyaslama için CUDA ve dışa aktarma bağımlılıklarını içeren Linux AMD64 | Dockerfile-export |
latest-amd | AMD GPU eğitimi ve çıkarımı için ROCm ve MIGraphX içeren Linux AMD64 | Dockerfile-amd |
latest-python | CPU çıkarımı için hafif Linux AMD64 Python 3.14 imajı | Dockerfile-python |
latest-python-export | Dışa aktarma bağımlılıklarını içeren Linux AMD64 Python 3.13 CPU imajı | Dockerfile-python-export |
latest-cpu | Varsayılan komutu Bash olan Linux AMD64 CPU görüntüsü | Dockerfile-cpu |
latest-jupyter | JupyterLab ve Ultralytics eğitim not defterlerini içeren Linux AMD64 CPU görüntüsü | Dockerfile-jupyter |
latest-arm64 | Apple silicon, Raspberry Pi ve diğer ARM64 sistemler için Linux ARM64 Python 3.13 CPU imajı | Dockerfile-arm64 |
latest-nvidia-arm64 | DGX Spark (DGX OS) ve Thor üzerinde PyTorch (JetPack 7.1) için Linux ARM64; pakete dahil TensorRT JetPack'i desteklemez | Dockerfile-nvidia-arm64 |
latest-jetson-jetpack6 | JetPack 6 kullanan NVIDIA Jetson cihazları için Linux ARM64 | Dockerfile-jetson-jetpack6 |
latest-jetson-jetpack5 | JetPack 5 kullanan NVIDIA Jetson cihazları için Linux ARM64 | Dockerfile-jetson-jetpack5 |
latest-jetson-jetpack4 | JetPack 4 kullanan NVIDIA Jetson cihazları için Linux ARM64 | Dockerfile-jetson-jetpack4 |
latest-runner | Kendi barındırdığı GitHub Actions GPU çalıştırıcısı için Linux AMD64 CUDA görüntüsü | Dockerfile-runner |
latest-runner-cpu | Kendi barındırdığı GitHub Actions CPU çalıştırıcısı için Linux AMD64 görüntüsü | Dockerfile-runner-cpu |
AMD64 GPU görüntüleri (latest, latest-export ve latest-runner), PyTorch 2.14 ve CUDA 13.2 kullanır. Bunları başlatmadan önce ana makine sürücüsünün CUDA desteğini nvidia-smi ile denetle; daha yeni bir kapsayıcı yüklemek ana makine sürücüsünü yükseltmez. CUDA 13, Tesla P100 ve V100 dahil Maxwell, Pascal ve Volta GPU'larını artık desteklemiyor. NVIDIA'nın CUDA sürüm notlarına ve sürücü uyumluluğu gereksinimlerine bak.
NVIDIA ARM64 görüntüsü, CUDA 13.4 ve TensorRT 11.2 ile NVIDIA PyTorch 26.08 kullanır. PyTorch'un Thor desteği TensorRT'yi kapsamaz: NVIDIA, JetPack'te TensorRT 11.2'yi desteklemiyor. Jetson TensorRT dışa aktarımları için JetPack sürümünün desteklediği TensorRT 10.x çalışma zamanını kullan. Jetson kılavuzundaki veya DGX Spark kılavuzundaki platform gereksinimlerini izle. JetPack 4, 5 ve 6 görüntülerinde cihaza özgü ayrı yığınlar kullanılmaya devam edilir.
Conda Dockerfile'ı yerel derlemeler için kullanılabilir; latest-conda öğesinin otomatik yayımlanması devre dışı olduğundan bu kayıt defteri etiketi bu güncellemeleri içermez.
LiteRT dışa aktarımları için latest-python-export kullan. GPU latest-export görüntüsü PyTorch 2.14'ü kullanmaya devam eder ve mevcut bağımlılığı PyTorch 2.14'ten eski bir sürüm gerektirdiği için LiteRT'yi içermez.
Python, CPU, Jupyter ve CPU runner imajları Python 3.14 kullanır. Python dışa aktarma imajı, TensorFlow, CoreML ve PaddlePaddle henüz Python 3.14'ü desteklemediği için aynı Dockerfile-python tabanından --build-arg PYTHON_VERSION=3.13 ile oluşturulan latest-python-3.13 tabanını kullanır.
latest ile başlayan etiketler, main dalında en son yayımlanan derlemeyi izler. Sürümlü etiketlerde latest öneki, VERSION, VERSION-cpu veya VERSION-jetson-jetpack6 gibi bir Ultralytics sürümüyle değiştirilir. Tekrarlanabilir bir ortam için sürümlü etiket kullan.
En son görüntüyü çekmek için:
# Pull the latest Ultralytics image from Docker Hub
sudo docker pull ultralytics/ultralytics:latestBunun yerine görüntüyü kendin derlemek için depoyu klonla ve derleme bağlamı olarak depo kökünü kullanarak yukarıdaki tablodaki uygun Dockerfile'ı belirt:
# Build the CPU image locally from docker/Dockerfile-cpu
sudo docker build -t ultralytics/ultralytics:latest-cpu -f docker/Dockerfile-cpu .Ultralytics'i Docker Kapsayıcısında Çalıştırma#
Ultralytics Docker kapsayıcısını şu şekilde çalıştırabilirsin:
Yalnızca CPU kullanma#
# Run without GPU
sudo docker run -it --ipc=host ultralytics/ultralytics:latest-cpuGPU kullanma#
# 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 bayrağı sözde bir TTY atar ve standart girdi akışını açık tutarak kapsayıcıyla etkileşim kurmanı sağlar. --ipc=host bayrağı, işlemler arasında bellek paylaşımı için gerekli olan ana makinenin IPC ad alanının paylaşılmasını sağlar. NVIDIA GPU'larda --device nvidia.com/gpu=... bayrağı CDI üzerinden erişim verir. AMD GPU'larda --device bayrakları GPU çekirdek sürücüsüne (/dev/kfd) ve görüntü oluşturma düğümlerine (/dev/dri) erişim verir.
Linux'ta CDI aygıt istekleri için Docker >= 28.2.0 (CDI varsayılan olarak etkindir) ve nvidia-container-toolkit >= 1.18 (CDI belirtiminin otomatik oluşturulması) gerekir. GPU kapsayıcılarını çalıştırmadan önce eski Linux ana makinelerini yükselt. Eski --gpus all bayrağı, rutin paket güncellemeleri sırasında ana makine systemd'yi yeniden yüklediğinde GPU erişimini (Failed to initialize NVML: Unknown Error) kaybettirebilir (nvidia-container-toolkit#48). CDI --device istekleri aygıt düğümlerini kapsayıcı yapılandırmasına eklediğinden eğitim işçileri veya CI çalıştırıcıları gibi uzun süre çalışan kapsayıcılar yeniden yüklemeler sırasında GPU erişimini korur.
Windows'ta Docker Desktop GPU desteği, NVIDIA CDI aygıtları burada kullanılamadığından şu anda WSL 2 arka ucuyla --gpus all kullanıyor. Windows Linux systemd kullanmadığı için yukarıdaki hizmet arka plan programını yeniden yükleme hatası burada geçerli değildir.
Dosya Erişilebilirliği Hakkında Not#
Yerel makinenizdeki dosyalarla kapsayıcı içinden çalışmak için Docker birimlerini kullanabilirsin:
# 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 yerine yerel makinenizdeki dizin yolunu, /path/in/container yerine Docker kapsayıcısının içindeki istediğin yolu yaz.
Eğitim Çıktılarını Kalıcı Hale Getirme#
Eğitim çıktıları varsayılan olarak kapsayıcının içindeki /ultralytics/runs/<task>/<name>/ konumuna kaydedilir. Ana makinedeki bir dizini bağlamazsan kapsayıcı kaldırıldığında çıktılar kaybolur.
Eğitim çıktılarını kalıcı hale getirmek için:
# 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/runsBu işlem, tüm eğitim çıktılarını ana makinenizdeki ./runs konumuna kaydeder.
Docker Kapsayıcısında Grafik Kullanıcı Arayüzü (GUI) Uygulamalarını Çalıştırma#
Docker çoğunlukla arka plan uygulamalarını ve CLI programlarını kapsayıcıya almak için kullanılır, ancak grafik programları da çalıştırabilir. Linux dünyasında grafik görüntülemeyi iki ana grafik sunucusu yönetir: X11 (X Pencere Sistemi olarak da bilinir) ve Wayland. Başlamadan önce hangi grafik sunucusunu kullandığını belirlemen önemlidir. Öğrenmek için şu komutu çalıştır:
env | grep -E -i 'x11|xorg|wayland'X11 veya Wayland görüntü sunucusunun kurulumu ve yapılandırılması bu kılavuzun kapsamı dışındadır. Yukarıdaki komut hiçbir sonuç döndürmezse devam etmeden önce bu sunuculardan birini sisteminde çalışır hâle getirmen gerekir.
GUI ile Docker Kapsayıcısı Çalıştırma#
GPU'ları kullanma
GPU'ları kullanıyorsan komuta --device nvidia.com/gpu=all bayrağını ekleyebilirsin.
X11 kullanıyorsan Docker kapsayıcısının X11 soketine erişmesine izin vermek için şu komutu çalıştırabilirsin:
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-v ~/.Xauthority:/root/.Xauthority \
-it --ipc=host ultralytics/ultralytics:latestBu komut, DISPLAY ortam değişkenini ana makinenin ekranına ayarlar, X11 soketini bağlar ve .Xauthority dosyasını kapsayıcıya eşler. xhost +local:docker komutu, Docker kapsayıcısının X11 sunucusuna erişmesine izin verir.
Docker'ı GUI ile kullanma#
Ultralytics imajları headless OpenCV içerir; bu nedenle önce kapsayıcı içinde OpenCV'nin GUI sürümünü ve sistem kitaplıklarını yükle:
apt-get update && apt-get install -y --no-install-recommends libgl1 libglib2.0-0 libsm6
pip uninstall -y opencv-python-headless && pip install opencv-pythonArtık Docker kapsayıcının içinde grafik uygulamaları görüntüleyebilirsin. Örneğin, bir YOLO26 modelinin tahminlerini görselleştirmek için şu CLI komutunu çalıştırabilirsin:
yolo predict model=yolo26n.pt show=TrueTest
Docker grubunun X11 sunucusuna erişimi olduğunu doğrulamanın kolay bir yolu, xclock veya xeyes gibi GUI programı içeren bir kapsayıcı çalıştırmaktır. Alternatif olarak X11 sunucusuna erişimi test etmek için bu programları Ultralytics Docker kapsayıcısına da yükleyebilirsin. Herhangi bir sorunla karşılaşırsan -e QT_DEBUG_PLUGINS=1 ortam değişkenini ayarlamayı düşünebilirsin. Bu ortam değişkenini ayarlamak hata ayıklama bilgilerinin çıktılanmasını sağlayarak sorun giderme sürecine yardımcı olur.
Docker GUI kullanımını bitirdiğinde#
Her iki durumda da işin bittiğinde Docker grubunun erişimini iptal etmeyi unutma.
xhost -local:dockerGörüntü sonuçlarını doğrudan Terminal'de görmek ister misin?
Terminal kullanarak görüntü sonuçlarını görüntüleme konusundaki şu kılavuza başvur
Artık Ultralytics'i Docker ile kullanmaya hazırsın ve özelliklerinden yararlanabilirsin. Ultralytics web uygulamasını kendi sunucunda barındırmak için Platformu Şirket İçi Barındırma kılavuzuna bak. Alternatif Python paketi kurulum yöntemleri için Ultralytics hızlı başlangıç belgelerine göz at.
Sık Sorulan Sorular#
Ultralytics'i Docker ile kurmak için önce sisteminde Docker'ın yüklü olduğundan emin ol. NVIDIA GPU'n varsa GPU desteğini etkinleştirmek için NVIDIA Container Toolkit paketini yükle. Ardından aşağıdaki komutu kullanarak en yeni Ultralytics Docker imajını Docker Hub'dan çek:
sudo docker pull ultralytics/ultralytics:latestAyrıntılı adımlar için Docker Hızlı Başlangıç Kılavuzumuza başvur.
Ultralytics Docker imajlarını kullanmak, aynı yazılım ve bağımlılıkları çoğaltarak farklı makinelerde tutarlı bir ortam sağlar. Bu özellikle ekipler arası iş birliği, modelleri çeşitli donanımlarda çalıştırma ve tekrarlanabilirliği koruma açısından faydalıdır. Genel NVIDIA GPU eğitimi için
latestkullan veya NVIDIA Jetson cihazı için JetPack sürümüne uygun imajı seç. İmaj tablosunun tamamına bakabilir veya Ultralytics Docker Hub'ı inceleyebilirsin.Öncelikle NVIDIA Container Toolkit paketinin yüklü ve yapılandırılmış olduğundan emin ol. Ardından Ultralytics YOLO'yu GPU desteğiyle çalıştırmak için şu komutu kullan:
sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest # all GPUsBu komut, GPU erişimi olan bir Docker kapsayıcısı oluşturur. Daha fazla ayrıntı için Docker Hızlı Başlangıç Kılavuzu'na bak.
YOLO tahmin sonuçlarını Docker kapsayıcısında GUI ile görselleştirmek için Docker'ın görüntü sunucuna erişmesine izin vermen gerekir. X11 kullanan sistemlerde komut şöyledir:
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \ -v /tmp/.X11-unix:/tmp/.X11-unix \ -v ~/.Xauthority:/root/.Xauthority \ -it --ipc=host ultralytics/ultralytics:latestWayland kullanan sistemlerde şu komutu kullan:
xhost +local:docker && docker run -e DISPLAY=$DISPLAY \ -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/tmp/$WAYLAND_DISPLAY \ --net=host -it --ipc=host ultralytics/ultralytics:latestKapsayıcı içinde
show=Truekullanmadan önce, Docker Kapsayıcısında grafik kullanıcı arayüzü (GUI) uygulamalarını çalıştırma bölümünde açıklandığı gibi OpenCV'nin GUI sürümünü yükle.Evet, yerel dizinleri
-vbayrağını kullanarak Ultralytics Docker kapsayıcısına bağlayabilirsin:sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latest/path/on/hostyerine yerel makinenin dizinini,/path/in/containeryerine de kapsayıcı içindeki istediğin yolu yaz. Bu yapılandırma, kapsayıcı içinde yerel dosyalarınla çalışmanı sağlar. Daha fazla bilgi için Dosyalara Erişilebilirlik Hakkında Not bölümüne başvur.