Menggunakan gambar Docker

Setiap Job berjalan di dalam image Docker, yang menyediakan lingkungan perangkat lunaknya, termasuk alat sistem dan pustaka yang terpasang. Dengan hf jobs run, Anda menyediakan image dan perintah. Dengan hf jobs uv run, uv menyiapkan lingkungan Python untuk skrip Anda, dan Jobs memilih image default kecuali Anda menentukan satu.

Pilih cara menjalankan beban kerja Anda

Mulai dengan hf jobs uv run ketika dependensi skrip Python Anda dapat diinstal dengan uv, seperti yang ditunjukkan di Quickstart. Pilih sebuah image ketika Anda memerlukan alat sistem tambahan atau ingin menggunakan lingkungan perangkat lunak yang sudah disiapkan.

Gambar default mencakup Python dan uv. Lihat konfigurasi UV Jobs untuk gambar default saat ini dan opsi yang tersedia.

Anda dapat menggunakan gambar yang sudah ada dari registry seperti Docker Hub, atau membangun dan menghosting gambar Anda sendiri dengan Docker Space.

Gunakan gambar yang sudah jadi

Gunakan hf jobs run dengan image dan perintah yang akan dijalankan di dalamnya. Image publik apa pun dari Docker Hub atau registry lain dapat digunakan, termasuk tag tertentu. Mulailah dengan yang kecil:

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

Job menarik image, menjalankan perintah, lalu keluar. Untuk menggunakan perangkat lunak yang sudah disediakan oleh image, pilih image yang menyediakannya. Misalnya, gunakan image PyTorch untuk membuat tensor di GPU dan menggandakan nilainya:

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)'

Gambar menyediakan PyTorch dan tumpukan perangkat lunak CUDA-nya. --flavor t4-small memilih GPU, --timeout 5m membatasi waktu eksekusi Job, dan perintah Python menggunakan paket PyTorch yang terinstal di dalam gambar. Outputnya muncul di log Job.

-- memisahkan opsi Jobs dari perintah dan argumennya. Sebagai contoh, --help setelah pemisah ini diteruskan ke perintah Anda. Lihat Menyampaikan argumen.

Jalankan skrip Anda sendiri dengan file input dan output

Skrip yang dijalankan oleh hf jobs run harus tersedia di dalam Job. Anda dapat menggunakan skrip yang disertakan dalam image, atau mount direktori lokal.

Sebagai contoh, misalkan Anda memiliki skrip inferensi yang menggunakan paket Transformers dan PyTorch dalam image huggingface/trl. Direktori work lokal Anda berisi inference.py dan inputs.jsonl, dan skrip tersebut menerima path --input dan --output. Setelah membuat Storage Bucket untuk hasil, jalankan dengan:

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

Ganti YOUR_USERNAME dengan namespace pemilik bucket. CLI mengunggah direktori lokal dan memount-nya di /work. Skrip Anda membaca input di sana dan menulis hasil ke bucket yang dimount di /output, di mana hasil tersebut tetap tersedia setelah Job selesai. Sesuaikan argumen perintah, perangkat keras, dan timeout sesuai skrip Anda; lihat Volumes untuk opsi input dan output lainnya.

Gunakan gambar dengan uv

Gunakan hf jobs uv run --image ketika skrip Anda memerlukan alat sistem di luar gambar default sambil tetap mempertahankan alur kerja dependensi Python dari uv. Gambar yang dipilih harus memiliki uv yang terinstal.

Terdapat tiga bagian dalam lingkungan:

• Alat sistem dan pustaka dalam image, seperti ffmpeg atau CUDA toolkit, tersedia untuk Job sesuai dengan konfigurasi image.
• Paket Python yang diinstal dalam image termasuk dalam lingkungan Python yang sudah ada.
• Dependensi skrip. Dengan header dependensi inline, uv menginstal paket Python Anda di lingkungan yang terisolasi. Paket yang sudah terpasang di image tidak otomatis tersedia.

Sebagai contoh, skrip vLLM mungkin memerlukan image dengan tooling CUDA sambil menggunakan uv untuk menginstal dependensi Python yang dideklarasikannya sendiri. Tooling sistem tetap harus kompatibel dengan paket-paket yang diinstal oleh uv.

Jika Anda ingin menggunakan PyTorch, TRL, atau vLLM yang sudah terpasang di image secara langsung, gunakan hf jobs run. Jika Anda juga memerlukan uv untuk menginstal dependensi tambahan, lihat Reuse the image’s packages and add dependencies with uv.

Bangun gambar Anda sendiri dengan Docker Space

Docker Space dapat membangun dan menampung image dengan alat yang dibutuhkan oleh workload Anda, termasuk skrip Anda sendiri, dan image tersebut dapat bersifat privat tanpa akun registry. Sebagai contoh, tambahkan FFmpeg ke image Python untuk menyiapkan lingkungan pemrosesan audio atau video.

Buat Docker Space dan tambahkan Dockerfile ini di root repositorinya:

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 menyediakan Python. FFmpeg tidak disertakan dalam image dasar ini, sehingga RUN menginstalnya saat build. useradd membuat pengguna dengan direktori home dan UID 1000, sesuai dengan Docker Spaces; USER menjalankan perintah sebagai pengguna tersebut. CMD mengatur perintah default, di sini untuk memeriksa instalasi FFmpeg.

Commit file tersebut dan tunggu hingga log build Space menunjukkan bahwa image telah di-push. Kemudian, berikan URL Space di tempat Anda biasanya menuliskan nama image, dengan mengganti YOUR_USERNAME/video-tools dengan ID Space Anda:

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

Versi tersebut muncul di log Job. Sediakan perintah yang berbeda setelah URL Space untuk menggunakan FFmpeg atau Python untuk beban kerja Anda. Untuk menyertakan skrip Anda sendiri dalam image, tambahkan baris seperti COPY --chown=user:user process.py /app/process.py ke Dockerfile dan jalankan python /app/process.py. Lihat file input dan output untuk memount data dan menyimpan hasil.

Contoh ini mencetak versi lalu keluar, sehingga Space menampilkan error runtime setelah build. Hal ini tidak masalah: Jobs hanya membutuhkan image yang sudah di-build, bukan Space yang sedang berjalan.

Gambar yang dibangun oleh sebuah Space tidak dijamin tetap dapat ditarik. Gambar tersebut dapat hilang akibat pemeliharaan registry atau perpindahan region. Jika sebuah Job melaporkan bahwa gambar tidak ditemukan, lakukan factory reboot pada Space untuk membangunnya kembali. Job selalu menggunakan build terbaru, sehingga commit baru juga akan menggantikan gambar tersebut.

Contoh gambar

Gambar registry dipelihara oleh penerbitnya dan dapat dikunci ke tag tertentu.

Gunakan hf jobs run untuk menjalankan perintah dengan paket yang terinstal pada image. Untuk hf jobs uv run, pastikan image memiliki uv yang terinstal dan ikuti panduan lingkungan di atas. Jelajahi Contoh & Tutorial untuk workload yang dapat dijalankan dan disesuaikan.

Gunakan ulang paket dari gambar dan tambahkan dependensi dengan uv

Framework images menyediakan paket yang sudah terpasang sebelumnya, yang mungkin lambat atau sulit untuk dibangun, seperti PyTorch, vLLM, dan ekstensi CUDA-nya. Anda mungkin masih memerlukan paket Python tambahan untuk skrip Anda — misalnya, untuk memuat format data tertentu atau melacak eksperimen.

Anda dapat menumpuk ulang tumpukan yang sudah terpasang di image sambil menggunakan uv untuk menginstal tambahan tersebut. Deklarasikan paket tambahan di header dependensi # /// script skrip Anda, lalu arahkan uv ke interpreter image dan tambahkan site-packages-nya ke jalur impor:

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 membuat lingkungan uv dengan interpreter dari image, yang sesuai dengan versi Python yang digunakan oleh ekstensi terkompilasi-nya. Opsi ini sendiri tidak mengekspos paket-paket dari image tersebut.
• -e PYTHONPATH=... membuat import vllm merujuk ke build prabangun dari image untuk eksekusi tersebut.
• Persempit dependensi # /// script Anda menjadi apa yang tidak ada di image. PYTHONPATH dicari sebelum lingkungan uv, sehingga image akan menenggelamkan apa pun yang dideklarasikan header Anda untuk paket yang sama — termasuk versi yang lebih baru yang Anda pin. Dependensi yang Anda pertahankan masih dapat menarik paket-paket tersebut secara transitif; uv tidak menggunakan PYTHONPATH untuk memenuhi resolusi dependensi.

Path berbeda untuk setiap gambar, jadi periksa di cpu-basic alih-alih hardcoding:

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

Ganti vllm dengan pustaka mana pun yang Anda gunakan kembali. Tata letaknya bervariasi — vllm/vllm-openai dan lmsysorg/sglang menggunakan dist-packages sistem di atas, unsloth/unsloth menggunakan virtualenv (/opt/venv/...), dan huggingface/trl menggunakan conda (/opt/conda/lib/python3.11/site-packages, diwarisi dari pytorch/pytorch).

Ini memilih build gambar untuk impor, bukan untuk resolver dependensi uv. Memangkas header dapat mengurangi instalasi yang redundan, tetapi tidak menjamin bahwa instalasi tersebut dihilangkan. uv run --system-site-packages yang akan melewati langkah PYTHONPATH telah diamankan di hulu.

Untuk gambar huggingface/trl, interpreter dan path paket yang sesuai adalah:

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

Perintah ini menggunakan generate-responses.py dan train.py sebagai nama untuk skrip Anda sendiri.

Pemecahan Masalah

Menggunakan gambar framework untuk pustaka GPU

Beberapa pustaka GPU memerlukan alat sistem tambahan, seperti compiler CUDA (nvcc), NCCL, atau cuDNN. Instalasi paket Python mereka tidak menjamin bahwa image tersebut berisi semua alat yang dibutuhkan. Misalnya, sampler FlashInfer dapat gagal saat mencoba mengompilasi kernel di image yang tidak memiliki CUDA toolkit:

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

Menyampaikan gambar framework dengan tooling CUDA yang diperlukan mengatasi error toolkit yang hilang ini:

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

uv tetap menyelesaikan dan menginstal dependensi skrip Anda secara terpisah. Image menyediakan tooling sistem, tetapi tidak menjamin bahwa paket Python yang di-resolve kompatibel dengannya.