Docker görüntülerini kullanma

Her Job, sistem araçları ve kurulu kütüphaneler dahil olmak üzere yazılım ortamını sağlayan bir Docker görüntüsü içinde çalışır. hf jobs run ile bir görüntü ve bir komut sağlarsınız. hf jobs uv run ile uv, betiğiniz için Python ortamını hazırlar ve Jobs, siz bir görüntü belirtmedikçe varsayılan bir görüntü seçer.

İş yükünüzü nasıl çalıştıracağınızı seçin

Python betiğinizin bağımlılıkları hf jobs uv run ile kurulabiliyorsa, Hızlı Başlangıç’te gösterildiği gibi hf jobs uv run ile başlayın. Ek sistem araçlarına ihtiyacınız varsa veya hazır bir yazılım ortamı kullanmak istiyorsanız bir görüntü seçin.

Varsayılan görüntü Python ve uv içerir. Güncel varsayılan görüntü ve kullanılabilir seçenekler için UV Jobs yapılandırması bölümüne bakın.

Docker Hub gibi bir kayıt defterindeki mevcut bir görüntüyü kullanabilir veya Docker Space ile kendi görüntünüzü oluşturup barındırabilirsiniz.

Hazır bir görüntü kullanın

hf jobs run komutunu, bir görüntü ve bu görüntünün içinde çalıştırılacak komutla birlikte kullanın. Docker Hub veya başka bir kayıt merkezindeki herhangi bir herkese açık görüntü, belirli bir etiket dahil olmak üzere çalışır. Küçük bir görüntüyle başlayın:

hf jobs run ubuntu echo 'Hello from the cloud!'

Job, görüntüyü çeker, komutu çalıştırır ve çıkar. Bir görüntünün zaten sağladığı yazılımı kullanmak için, bu yazılımı içeren bir görüntü seçin. Örneğin, bir GPU üzerinde bir tensör oluşturmak ve değerlerini ikiye katlamak için bir PyTorch görüntüsü kullanın:

hf jobs run --flavor t4-small --timeout 5m \
    pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
    -- python -c 'import torch; x = torch.ones(3, device="cuda"); print(x * 2)'

Görsel, PyTorch ve CUDA yazılım yığını sağlar. --flavor t4-small GPU’yu seçer, --timeout 5m Job çalışma süresini sınırlar ve Python komutu, görselde yüklü PyTorch paketini kullanır. Çıktısı, Job günlüklerinde görünür.

--, İşler seçeneklerini komuttan ve komutun argümanlarından ayırır. Örneğin, bu ayraçtan sonraki --help komutunuza iletilir. Argümanları iletme bölümüne bakın.

Girdi ve çıktı dosyalarıyla kendi betiğinizi çalıştırın

hf jobs run tarafından çalıştırılan bir betik, Job içinde kullanılabilir durumda olmalıdır. Görüntüde yer alan bir betiği kullanabilir veya yerel bir dizini bağlayabilirsiniz.

Örneğin, huggingface/trl görüntüsünde Transformers ve PyTorch paketlerini kullanan bir çıkarım (inference) scriptiniz olduğunu varsayalım. Yerel work dizininizde inference.py ve inputs.jsonl dosyaları bulunuyor ve script --input ile --output yollarını kabul ediyor. Sonuçlar için bir Storage Bucket oluşturduktan sonra, scripti şu komutla çalıştırın:

hf jobs run --flavor t4-small --timeout 10m \
    -v ./work:/work \
    -v hf://buckets/YOUR_USERNAME/results:/output \
    huggingface/trl \
    -- python /work/inference.py --input /work/inputs.jsonl --output /output/results.jsonl

YOUR_USERNAME ifadesini, bucket sahibinin ad alanıyla değiştirin. CLI, yerel dizini yükler ve /work konumuna bağlar. Betiğiniz, girdiyi oradan okur ve sonuçları, Job tamamlandıktan sonra da erişilebilir kalan, /output konumuna bağlanan bucket'a yazar. Komutun argümanlarını, donanımını ve zaman aşımını betiğinize göre uyarlayın; diğer girdi ve çıktı seçenekleri için Volume'lar bölümüne bakın.

uv ile bir görüntü kullanın

Betikleriniz, varsayılan görüntünün ötesinde sistem araçlarına ihtiyaç duyduğunda ve uv’ın Python bağımlılık iş akışını korumak istediğinizde hf jobs uv run --image kullanın. Seçilen görüntüde uv yüklü olmalıdır.

Ortamın üç parçası vardır:

• Görseldeki sistem araçları ve kütüphaneleri, örneğin ffmpeg veya CUDA araç seti, Job tarafından görselin yapılandırmasına göre kullanılabilir.
• Görseldeki kurulu Python paketleri, mevcut Python ortamına aittir.
• Script bağımlılıkları. inline dependency header ile uv, Python paketlerinizi izole bir ortamda yükler. Görüntüde önceden yüklenmiş paketler otomatik olarak kullanılabilir değildir.

Örneğin, bir vLLM betiği, kendi bildirdiği Python bağımlılıklarını uv ile yüklerken CUDA araçları içeren bir imaj gerektirebilir. Sistem araçları, uv'nin yüklediği paketlerle yine de uyumlu olmalıdır.

Bir görüntünün önceden yüklenmiş PyTorch, TRL veya vLLM bileşenlerini doğrudan kullanmak istiyorsanız hf jobs run komutunu kullanın. Ek bağımlılıkları yüklemek için uv’ye de ihtiyacınız varsa, Görüntünün paketlerini yeniden kullanın ve uv ile bağımlılıklar ekleyin bölümüne bakın.

Docker Space ile kendi görüntünüzü oluşturun

Bir Docker Space, iş yükünüzün ihtiyaç duyduğu araçları (kendi betikleriniz dahil) içeren bir görüntüyü derleyebilir ve barındırabilir; bu görüntü, bir kayıt defteri hesabı olmadan da özel kalabilir. Örneğin, ses veya video işleme için bir ortam hazırlamak üzere bir Python görüntüsüne FFmpeg ekleyebilirsiniz.

Bir Docker Space oluşturun ve deposunun kök dizinine bu Dockerfile dosyasını ekleyin:

FROM python:3.12-slim-bookworm

# Install FFmpeg for audio and video processing.
RUN apt-get update \
    && apt-get install -y --no-install-recommends ffmpeg \
    && rm -rf /var/lib/apt/lists/*

# Match the non-root user ID used by Docker Spaces.
RUN useradd --create-home --uid 1000 user
USER user

# Check that FFmpeg is available.
CMD ["ffmpeg", "-version"]

FROM Python sağlar. FFmpeg bu temel görüntüde yer almadığından, RUN derleme sırasında onu yükler. useradd, Docker Spaces ile eşleşen, ana dizini ve 1000 UID’si olan bir kullanıcı oluşturur; USER komutları bu kullanıcı olarak çalıştırır. CMD varsayılan bir komut belirler; burada FFmpeg kurulumu kontrol edilir.

Dosyayı commit edin ve Space’in derleme günlüklerinde imajın itildiğini göstermesini bekleyin. Ardından, normalde bir imaj adı girdiğiniz yere Space URL’sini geçirin; YOUR_USERNAME/video-tools ifadesini Space kimliğinizle değiştirin:

hf jobs run --flavor cpu-basic --timeout 5m \
    hf.co/spaces/YOUR_USERNAME/video-tools -- ffmpeg -version

Sürüm, Job’un günlüklerinde görünür. İş yükünüz için FFmpeg veya Python kullanmak üzere Space URL’sinden sonra farklı bir komut sağlayın. Kendi betiğinizi görüntüye dahil etmek için Dockerfile’a COPY --chown=user:user process.py /app/process.py gibi bir satır ekleyin ve python /app/process.py komutunu çalıştırın. Veri bağlama ve sonuçları kaydetme için girdi ve çıktı dosyaları bölümüne bakın.

Bu örnek bir sürüm yazar ve çıkar, bu yüzden Space, derlemeden sonra bir çalışma zamanı hatası gösterir. Bu sorun değil: İşler yalnızca derlenmiş imgeyi, çalışan bir Space'i değil gerektirir.

Bir Space'in oluşturulan görüntüsünün indirilebilir kalması garanti edilmez. Kayıt defteri bakımı veya bölge değişikliği nedeniyle kaybolabilir. Bir Job, görüntünün bulunamadığını bildirirse, Space'i yeniden oluşturmak için fabrika ayarlarına sıfırlayın. Job'lar her zaman en son derlemeyi kullandığı için yeni bir commit de görüntüyü değiştirir.

Örnek görseller

Registry görüntüleri, yayıncıları tarafından sürdürülür ve belirli bir etikete sabitlenebilir.

hf jobs run komutunu, bir görüntünün yüklü paketleriyle komut çalıştırmak için kullanın. hf jobs uv run için, görüntünün uv yüklü olduğundan emin olun ve yukarıdaki ortam yönergelerini izleyin. Çalıştırıp uyarlayabileceğiniz iş yükleri için Örnekler ve Eğitimler bölümüne göz atın.

Görselin paketlerini yeniden kullanın ve bağımlılıkları uv ile ekleyin

Framework görüntüleri, PyTorch, vLLM ve CUDA uzantıları gibi yavaş veya zor derlenebilen önceden yüklü paketler sağlar. Betiğiniz için ek Python paketlerine hâlâ ihtiyaç duyabilirsiniz — örneğin, belirli bir veri biçimini yüklemek veya deneyleri izlemek için.

Görseldeki önceden yüklenmiş yığını yeniden kullanabilir ve bu ekleri yüklemek için uv kullanabilirsiniz. Ek paketleri betiğinizin # /// script bağımlılık başlığına ekleyin, ardından uv’yi görselin yorumlayıcısına yönlendirin ve site-packages’ını içe aktarma yoluna ekleyin:

hf jobs uv run \
    --image vllm/vllm-openai \
    --flavor l4x4 \
    --python /usr/bin/python3 \
    -e PYTHONPATH=/usr/local/lib/python3.12/dist-packages \
    -s HF_TOKEN \
    generate-responses.py

• --python, derlenmiş eklentilerin kullandığı Python sürümüyle uyumlu olacak şekilde, imajın yorumlayıcısını kullanarak uv ortamını oluşturur. Kendi başına imajdaki paketleri dışa açmaz.
• -e PYTHONPATH=..., o çalıştırma için import vllm ifadesinin görüntünün önceden derlenmiş derlemesine yönlendirilmesini sağlar.
• # /// script bağımlılıklarını, imajın eksik bıraktığı şeylerle sınırlayın. PYTHONPATH, uv ortamından önce aranır; bu nedenle imaj, başlığınızda aynı paket için beyan ettiğiniz her şeyi gölgeleyebilir — sabitlediğiniz daha yeni bir sürüm dahil. Sakladığınız bağımlılıklar yine de bu paketleri dolaylı olarak çekebilir; uv, bağımlılık çözümlemesini karşılamak için PYTHONPATH kullanmaz.

Yollar görüntüye göre farklılık gösterdiğinden, bunları sabitlemek yerine cpu-basic üzerinde sorgulayın:

hf jobs run --flavor cpu-basic vllm/vllm-openai bash -c 'which python3; which uv; python3 -m pip show vllm | grep Location'

/usr/bin/python3                              # pass to --python
/usr/local/bin/uv                             # uv is present, so `uv run` works
Location: /usr/local/lib/python3.12/dist-packages   # pass to PYTHONPATH

Hangi kütüphaneyi yeniden kullanıyorsanız vllm yerine onu yazın. Yerleşimler farklıdır — vllm/vllm-openai ve lmsysorg/sglang yukarıdaki sistem dist-packages dizinini kullanırken, unsloth/unsloth bir virtualenv (/opt/venv/...) ve huggingface/trl conda (/opt/conda/lib/python3.11/site-packages, pytorch/pytorch’ten devralınmıştır) kullanır.

This selects the image’s builds for imports, not for uv’s dependency resolver. Trimming the header can reduce redundant installs, but does not guarantee they are eliminated. A uv run --system-site-packages that would skip the PYTHONPATH step is requested upstream.

huggingface/trl görüntüsü için ilgili yorumlayıcı ve paket yolları şunlardır:

hf jobs uv run \
    --image huggingface/trl \
    --flavor a100-large \
    --python /opt/conda/bin/python3 \
    -e PYTHONPATH=/opt/conda/lib/python3.11/site-packages \
    -s HF_TOKEN \
    train.py

Bu komutlar, kendi betikleriniz için generate-responses.py ve train.py adlarını kullanır.

Sorun Giderme

GPU kütüphaneleri için çerçeve görüntüleri kullanma

Bazı GPU kütüphaneleri, CUDA derleyicisi (nvcc), NCCL veya cuDNN gibi ek sistem araçlarına ihtiyaç duyar. Bunların Python paketlerini yüklemek, imajın ihtiyaç duyduğu her aracı içerdiğini garanti etmez. Örneğin, CUDA araç seti olmayan bir imajda çekirdek derlemeye çalışırken FlashInfer'ın örnekleyicisi başarısız olabilir:

RuntimeError: Could not find nvcc and default cuda_home='/usr/local/cuda' doesn't exist

Gerekli CUDA araçlarını içeren bir framework görüntüsü geçirerek bu eksik araç seti hatası giderilir:

hf jobs uv run --image vllm/vllm-openai --flavor l4x4 -s HF_TOKEN generate-responses.py

uv, betik bağımlılıklarınızı yine ayrı olarak çözer ve yükler. Görüntü sistem araçlarını sağlar, ancak çözülen Python paketlerinin bu araçlarla uyumlu olduğunu garanti etmez.