Jalankan dan kelola Jobs

Hugging Face Hub menyediakan komputasi untuk alur kerja AI dan data melalui Jobs.

Untuk gambaran umum tentang Jobs dan harga, lihat dokumentasi Hub Jobs.

Sebuah job berjalan di infrastruktur Hugging Face dan didefinisikan dengan perintah yang akan dijalankan (misalnya perintah python), Docker Image dari Hugging Face Spaces atau Docker Hub, serta jenis hardware (CPU, GPU, TPU). Panduan ini akan menunjukkan cara berinteraksi dengan Jobs di Hub, khususnya:

• Jalankan sebuah job.
• Periksa status pekerjaan.
• Pilih perangkat keras.
• Konfigurasikan variabel lingkungan dan rahasia.
• Jalankan skrip UV.

Jika Anda ingin menjalankan dan mengelola pekerjaan di Hub, mesin Anda harus dalam keadaan masuk. Jika belum, silakan lihat bagian ini. Dalam sisa panduan ini, kami mengasumsikan bahwa mesin Anda sudah masuk.

Hugging Face Jobs tersedia untuk pengguna atau organisasi mana pun yang memiliki saldo kredit positif. Lihat harga dan penagihan Jobs untuk detailnya.

Antarmuka Baris Perintah Jobs

Gunakan hf jobs CLI untuk menjalankan Jobs dari baris perintah, dan berikan --flavor untuk menentukan perangkat keras Anda.

hf jobs run menjalankan Jobs dengan image Docker dan perintah yang memiliki antarmuka mirip Docker. Bayangkan docker run, tetapi untuk menjalankan kode di perangkat keras apa pun:

>>> hf jobs run --name hello-world python:3.12 python -c "print('Hello world')"
>>> hf jobs run --name gpu-check --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel python -c "import torch; print(torch.cuda.get_device_name())"

Gunakan hf jobs uv run untuk menjalankan skrip UV lokal atau jarak jauh:

>>> hf jobs uv run --name my-script my_script.py
>>> hf jobs uv run --name sft-training --flavor a10g-small "https://raw.githubusercontent.com/huggingface/trl/main/trl/scripts/sft.py"

UV scripts adalah skrip Python yang menyertakan dependensinya secara langsung di dalam file menggunakan sintaks komentar khusus yang didefinisikan dalam dokumentasi UV.

Sekarang, sisa panduan ini akan menunjukkan API python. Jika Anda ingin melihat semua perintah dan opsi hf jobs yang tersedia, lihat panduan tentang antarmuka baris perintah hf jobs.

Butuh mesin interaktif alih-alih tugas sekali jalan — misalnya untuk menjalankan kode yang dihasilkan AI, dengan eksekusi perintah dan transfer file? Coba lihat Sandboxes, yang dibangun di atas Jobs.

Jalankan Job

Jalankan compute Jobs yang didefinisikan dengan sebuah command dan Docker Image pada infrastruktur Hugging Face (termasuk GPU dan TPU).

Anda hanya dapat mengelola Jobs yang Anda miliki (di bawah namespace nama pengguna Anda) atau dari organisasi yang memiliki izin tulis. Fitur ini berbasis pembayaran sesuai penggunaan: Anda hanya membayar untuk detik-detik yang Anda gunakan.

run_job() memungkinkan Anda menjalankan perintah apa pun di infrastruktur Hugging Face:

# Directly run Python code
>>> from huggingface_hub import run_job
>>> run_job(
...     image="python:3.12",
...     command=["python", "-c", "print('Hello from the cloud!')"],
... )

# Use GPUs without any setup
>>> run_job(
...     image="pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel",
...     command=["python", "-c", "import torch; print(torch.cuda.get_device_name())"],
...     flavor="a10g-small",
... )

# Run in an organization account
>>> run_job(
...     image="python:3.12",
...     command=["python", "-c", "print('Running in an org account')"],
...     namespace="my-org-name",
... )

# Run from Hugging Face Spaces
>>> run_job(
...     image="hf.co/spaces/lhoestq/duckdb",
...     command=["duckdb", "-c", "select 'hello world'"],
... )

# Run a Python script with `uv` (experimental)
>>> from huggingface_hub import run_uv_job
>>> run_uv_job("my_script.py")

Penting: Job memiliki batas waktu default (30 menit), setelah itu job akan berhenti secara otomatis. Untuk tugas yang berjalan lama seperti pelatihan model, pastikan untuk mengatur batas waktu kustom menggunakan parameter timeout. Lihat Menyiapkan Batas Waktu Job untuk detailnya.

run_job() mengembalikan JobInfo yang berisi URL Job di Hugging Face, tempat Anda dapat melihat status Job dan log-nya. Simpan Job ID dari JobInfo untuk mengelola job:

>>> from huggingface_hub import run_job
>>> job = run_job(
...     image="python:3.12",
...     command=["python", "-c", "print('Hello from the cloud!')"]
... )
>>> job.url
https://huggingface.co/jobs/lhoestq/687f911eaea852de79c4a50a
>>> job.id
687f911eaea852de79c4a50a

Jobs berjalan di latar belakang. Bagian selanjutnya memandu Anda melalui inspect_job() untuk mengetahui status jobs, fetch_job_logs() untuk melihat log, dan fetch_job_metrics() untuk memantau penggunaan sumber daya.

Ulangi dan jalankan ulang Job

Gunakan attempts untuk mengulang Job yang gagal. Jumlah ini mencakup percobaan awal, sehingga attempts=3 memungkinkan hingga dua pengulangan. Fitur ini juga berfungsi dengan run_uv_job, create_scheduled_job, dan create_scheduled_uv_job.

>>> from huggingface_hub import rerun_job, run_job
>>> job = run_job(image="python:3.12", command=["python", "train.py"], attempts=3)
>>> job.retry
2

# Start a new Job with the same spec, including its retry setting
>>> new_job = rerun_job(job_id=job.id)

rerun_job memulai Job terpisah dengan ID baru. Fungsinya untuk Job yang selesai atau gagal, dan menggunakan ulang spesifikasi yang disimpan, termasuk secrets dan pengaturan hardware. Anda juga dapat menjalankan hf jobs rerun <job_id>.

Periksa status Job

# List your jobs (results are paginated and returned as an iterator)
>>> from huggingface_hub import list_jobs
>>> jobs = list_jobs()
>>> next(iter(jobs))
JobInfo(id='687f911eaea852de79c4a50a', created_at=datetime.datetime(2025, 7, 22, 13, 24, 46, 909000, tzinfo=datetime.timezone.utc), docker_image='python:3.12', space_id=None, command=['python', '-c', "print('Hello from the cloud!')"], arguments=[], environment={}, secrets={}, flavor='cpu-basic', status=JobStatus(stage='COMPLETED', message=None), owner=JobOwner(id='5e9ecfc04957053f60648a3e', name='lhoestq'), endpoint='https://huggingface.co', url='https://huggingface.co/jobs/lhoestq/687f911eaea852de79c4a50a')

# Materialize the iterator into a list
>>> all_jobs = [job for job in list_jobs()]

# List your running jobs
>>> running_jobs = list_jobs(status="RUNNING")

# Filter by one or more statuses and/or labels
>>> list_jobs(status=["RUNNING", "SCHEDULING"], labels={"env": "prod"})

# Inspect the status of a job
>>> from huggingface_hub import inspect_job
>>> inspect_job(job_id=job_id)
JobInfo(id='687f911eaea852de79c4a50a', created_at=datetime.datetime(2025, 7, 22, 13, 24, 46, 909000, tzinfo=datetime.timezone.utc), docker_image='python:3.12', space_id=None, command=['python', '-c', "print('Hello from the cloud!')"], arguments=[], environment={}, secrets={}, flavor='cpu-basic', status=JobStatus(stage='COMPLETED', message=None), owner=JobOwner(id='5e9ecfc04957053f60648a3e', name='lhoestq'), endpoint='https://huggingface.co', url='https://huggingface.co/jobs/lhoestq/687f911eaea852de79c4a50a')

# View logs from a job
>>> from huggingface_hub import fetch_job_logs
>>> for log in fetch_job_logs(job_id=job_id):
...     print(log)
Hello from the cloud!

# View resources usage metrics from a job
>>> from huggingface_hub import fetch_job_metrics
>>> for metrics in fetch_job_metrics(job_id=job_id):
...     print(metrics)
{
    "cpu_usage_pct": 0,
    "cpu_millicores": 2000,
    "memory_used_bytes": 929792,
    "memory_total_bytes": 17179869184,
    "rx_bps": 0,
    "tx_bps": 0,
    "gpus": {},
    "replica": "4dzsh"
}

# Cancel a job
>>> from huggingface_hub import cancel_job
>>> cancel_job(job_id=job_id)

Tunggu hingga Jobs selesai

Gunakan wait_for_job() untuk memblokir hingga sebuah Job mencapai tahap terminal (COMPLETED, CANCELED, ERROR atau DELETED). JobInfo akhir selalu dikembalikan — Job yang gagal tidak memicu pengecualian — jadi periksa job.status.stage untuk bertindak berdasarkan hasilnya. Lewatkan daftar ID Job untuk menunggu seluruh batch sekaligus.

>>> from huggingface_hub import run_job, wait_for_job
>>> job = run_job(image="python:3.12", command=["python", "-c", "print('hello')"])
>>> wait_for_job(job_id=job.id).status.stage
'COMPLETED'

# Run multiple jobs in parallel and wait for all of them to finish
>>> jobs = [run_job(image=image, command=command) for command in commands]
>>> finished_jobs = wait_for_job(job_id=[job.id for job in jobs], timeout=3600)

Hal yang sama tersedia di CLI dengan hf jobs wait, yang keluar dengan kode 0 hanya jika semua Job selesai dengan sukses — berguna untuk merangkai perintah dalam skrip shell atau CI:

# Chain on success
hf jobs wait <job_id> && hf jobs run --detach python:3.12 python eval.py

# Wait for all currently running jobs
hf jobs ls -q | xargs hf jobs wait

Perhatikan bahwa hf jobs run (atau hf jobs uv run) yang tidak dilepas juga keluar dengan kode non-nol jika Job gagal, sehingga hf jobs run ... && next-step berantai dengan benar tanpa perlu wait eksplisit.

Pilih perangkat keras

Terdapat banyak kasus di mana menjalankan Jobs pada GPU sangat berguna:

• Pelatihan Model: Menyesuaikan atau melatih model pada GPU (T4, A10G, A100) tanpa perlu mengelola infrastruktur
• Generasi Data Sintetis: Menghasilkan dataset berskala besar menggunakan LLM pada perangkat keras yang bertenaga
• Pemrosesan Data: Memproses dataset besar dengan konfigurasi CPU tinggi untuk beban kerja paralel
• Inferensi Batch: Jalankan inferensi offline pada ribuan sampel menggunakan setup GPU yang dioptimalkan
• Eksperimen & Benchmark: Jalankan eksperimen ML pada perangkat keras yang konsisten untuk hasil yang dapat direproduksi
• Pengembangan & Debugging: Uji kode GPU tanpa setup CUDA lokal

Jalankan tugas pada GPU atau TPU dengan argumen flavor. Misalnya, untuk menjalankan tugas PyTorch pada GPU A10G:

# Use an A10G GPU to check PyTorch CUDA
>>> from huggingface_hub import run_job
>>> run_job(
...     image="pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel",
...     command=["python", "-c", "import torch; print(f'This code ran with the following GPU: {torch.cuda.get_device_name()}')"],
...     flavor="a10g-small",
... )

Menjalankan ini akan menampilkan output berikut!

This code ran with the following GPU: NVIDIA A10G

Gunakan ini untuk menjalankan skrip fine-tuning seperti trl/scripts/sft.py dengan UV:

>>> from huggingface_hub import run_uv_job
>>> run_uv_job(
...     "sft.py",
...     script_args=["--model_name_or_path", "Qwen/Qwen2-0.5B", ...],
...     dependencies=["trl"],
...     env={"HF_TOKEN": ...},
...     flavor="a10g-small",
... )

Untuk panduan komprehensif tentang menjalankan tugas pelatihan model dengan TRL pada infrastruktur Hugging Face, lihat dokumentasi Pelatihan TRL Jobs. Dokumentasi ini mencakup resep fine-tuning, pemilihan perangkat keras, dan praktik terbaik untuk melatih model secara efisien.

Berikut adalah daftar lengkap perangkat keras yang tersedia untuk menjalankan Jobs:

Anda dapat memperoleh daftar ini secara programatik dengan menjalankan:

>>> hf jobs hardware

Atau menggunakan API Python:

>>> from huggingface_hub import list_jobs_hardware
>>> list_jobs_hardware()

Selesai! Anda sekarang menjalankan kode di infrastruktur Hugging Face.

Mount volume

Pasang volume pada disk Jobs menggunakan daftar Volume.

Anda dapat memuat (mount) Repositori Hugging Face (model/dataset/space) mana pun atau Storage Bucket. Sebagai contoh:

• mount repositori model: Volume(type="model", source="openai/gpt-oss-120b", mount_path="/model")
• mount repositori dataset: Volume(type="dataset", source="HuggingFaceFW/fineweb", mount_path="/data")
• mount bucket penyimpanan: Volume(type="bucket", source="username/my-bucket", mount_path="/mnt")

Lalu, Anda dapat menggunakan volume yang dipasang sebagai direktori lokal:

>>> from huggingface_hub import run_job, Volume
>>> job = run_job(
...     image="duckdb/duckdb",
...     command=["duckdb", "-c", "SELECT * FROM '/data/**/*.parquet' LIMIT 5"],
...     volumes=[Volume(type="dataset", source="HuggingFaceFW/fineweb", mount_path="/data")],
... )

Anda juga dapat menulis ke bucket yang dimount, misalnya, untuk menyimpan checkpoint saat melatih model:

>>> from huggingface_hub import run_uv_job, Volume
>>> script = "my_sft.py"
>>> script_args = ["--output_dir", "/training-outputs/training-v3-final", ...]
>>> checkpoints_bucket = Volume(type="bucket", source="username/my-bucket", mount_path="/training-outputs")
>>> run_uv_job(script, script_args=script_args, volumes=[checkpoints_bucket])

Secara default, bucket penyimpanan yang dipasang memiliki kemampuan baca+tulis. Hal ini sangat berguna untuk bucket penyimpanan, yang menyediakan penyimpanan yang cepat dan dapat diubah untuk data yang sering berubah — file dapat ditimpa atau dihapus di tempatnya.

Gunakan read_only=True untuk mengaktifkan read-only: Volume(type="bucket", read_only=True, ...).

Mount data lokal

Untuk menjalankan Job terhadap data di mesin Anda, gunakan sync_job_volume(): fungsi ini menyinkronkan direktori lokal ke Storage Bucket jobs-artifacts (dibuat secara otomatis jika diperlukan) dan mengembalikan Volume yang siap dipasang:

>>> from huggingface_hub import run_uv_job, sync_job_volume

# Upload ./training-data once...
>>> volume = sync_job_volume("./training-data", "/data")

# ...then run as many Jobs as you want against it
>>> run_uv_job("train.py", script_args=["--learning-rate", "0.01"], volumes=[volume])
>>> run_uv_job("train.py", script_args=["--learning-rate", "0.05"], volumes=[volume])

Setiap direktori memiliki folder stabilnya sendiri di bucket: menjalankan ulang sync_job_volume() pada direktori yang sama hanya mengunggah file baru atau yang telah dimodifikasi. Volume ini secara default dipasang (mounted) hanya-baca (read-only).

Untuk mengambil file yang ditulis oleh sebuah Job, mount volume baca-tulis (direktori output kosong juga bisa) dan sinkronkan kembali setelah Job selesai:

>>> from huggingface_hub import run_uv_job, sync_bucket, sync_job_volume

>>> outputs = sync_job_volume("./outputs", "/outputs", read_only=False)
>>> job = run_uv_job("process.py", volumes=[outputs])

# ...once the Job completes, pull back the data:
>>> sync_bucket(f"hf://buckets/{outputs.source}/{outputs.path}", "./outputs")

Di CLI, cukup berikan direktori lokal sebagai sisi sumber dari -v:

>>> hf jobs uv run -v ./pdfs:/input -v ./md-out:/output:rw ocr.py

Ekspos port Job

Lewati expose untuk membuat port container dapat dijangkau melalui proxy Jobs. Akses memerlukan token HF dengan akses baca ke namespace Job. Gunakan expose_public sebagai gantinya untuk mengizinkan akses tanpa autentikasi:

>>> from huggingface_hub import run_job, update_job_expose
>>> job = run_job(
...     image="python:3.12",
...     command=["python", "-m", "http.server", "8000"],
...     expose_public=[8000],
... )
>>> job.expose_public
[8000]

# Keep the port exposed, but require an HF token from now on
>>> job = update_job_expose(job_id=job.id, expose=[8000])

# Close all exposed ports
>>> job = update_job_expose(job_id=job.id)

expose dan expose_public dapat digabungkan. update_job_expose mengganti konfigurasi port penuh pada Job yang sedang berjalan tanpa me-restart-nya: port yang tidak ada di kedua daftar akan ditutup. Kedua opsi ini juga tersedia saat membuat Job UV dan terjadwal.

SSH ke Job

Lewati ssh=True ke run_job() (atau run_uv_job()) agar kontainer Job dapat dijangkau melalui SSH. Endpoint SSH tersedia di status Job:

>>> from huggingface_hub import run_job
>>> job = run_job(
...     image="python:3.12",
...     command=["sleep", "infinity"],
...     ssh=True,
... )
>>> job.status.ssh_url
'ssh://68498e23210b3a4f4e6e2a23@ssh.hf.jobs'

Hubungkan dari terminal dengan hf jobs ssh <job_id> (atau langsung dengan ssh <job_id>@ssh.hf.jobs):

>>> hf jobs ssh 68498e23210b3a4f4e6e2a23

Hanya pengguna dengan akses tulis ke namespace Job yang diizinkan masuk (pembuat Job, atau anggota organisasi pemilik), yang terautentikasi melalui kunci publik SSH yang terdaftar di https://huggingface.co/settings/keys.

Grup jaringan

Lewati network_group="<name>" ke run_job() (atau run_uv_job()) agar Jobs dalam namespace dan resource group yang sama dapat saling menjangkau di setiap port. Di dalam setiap anggota, HF_NETWORK_GROUP_HOSTNAME dipecahkan ke setiap Job dalam grup, dan ${HF_NETWORK_GROUP_PREFIX}<alias> ke anggota yang mengklaim alias dengan network_aliases=[...]:

>>> from huggingface_hub import run_job
>>> server = run_job(
...     image="python:3.12",
...     command=["python", "-m", "http.server", "8000"],
...     network_group="train",
...     network_aliases=["master"],
... )
>>> client = run_job(
...     image="python:3.12",
...     command=["sh", "-c", 'curl --retry 10 --retry-connrefused "http://${HF_NETWORK_GROUP_PREFIX}master:8000/"'],
...     network_group="train",
... )
>>> server.network
JobNetwork(group='train', aliases=['master'])

Anggota dapat di-resolve sebelum mereka siap, sehingga hubungkan dengan retry. Nama grup dan alias adalah alfanumerik kecil dan tanda hubung, maksimal 46 dan 34 karakter.

Konfigurasi Batas Waktu Tugas

Jobs memiliki timeout default (30 menit), setelah itu mereka akan berhenti secara otomatis. Hal ini penting untuk diketahui saat menjalankan tugas jangka panjang seperti pelatihan model.

Mengatur batas waktu kustom

Anda dapat menentukan nilai timeout khusus menggunakan parameter timeout saat menjalankan job. Timeout dapat ditentukan dengan dua cara:

1. Sebagai angka (diartikan sebagai detik):

>>> from huggingface_hub import run_job
>>> job = run_job(
...     image="pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel",
...     command=["python", "train_model.py"],
...     flavor="a10g-large",
...     timeout=7200,  # 2 hours in seconds
... )

2. Sebagai string dengan satuan waktu:

>>> # Using different time units
>>> job = run_job(
...     image="pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel",
...     command=["python", "train_model.py"],
...     flavor="a10g-large",
...     timeout="2h",  # 2 hours
... )

>>> # Other examples:
>>> # timeout="30m"    # 30 minutes
>>> # timeout="1.5h"   # 1.5 hours
>>> # timeout="1d"     # 1 day
>>> # timeout="3600s"  # 3600 seconds

Satuan waktu yang didukung:

• s - detik
• m - menit
• h - jam
• d - hari

Menggunakan timeout dengan pekerjaan UV

Untuk pekerjaan UV, Anda juga dapat menentukan batas waktu:

>>> from huggingface_hub import run_uv_job
>>> job = run_uv_job(
...     "training_script.py",
...     flavor="a10g-large",
...     timeout="90m",  # 90 minutes
... )

Jika Anda tidak menentukan timeout, timeout default akan diterapkan pada job Anda. Untuk tugas berdurasi panjang seperti pelatihan model yang mungkin memakan waktu berjam-jam, pastikan untuk mengatur timeout yang sesuai guna menghindari pengakhiran job yang tidak terduga.

Memantau durasi job

Saat menjalankan tugas yang panjang, praktik yang baik adalah:

• Perkirakan durasi yang diharapkan untuk pekerjaan Anda dan atur batas waktu dengan sedikit cadangan
• Pantau kemajuan pekerjaan Anda melalui log
• Periksa status pekerjaan untuk memastikan tidak terjadi timeout

>>> from huggingface_hub import inspect_job, fetch_job_logs
>>> # Check job status
>>> job_info = inspect_job(job_id=job.id)
>>> if job_info.status.stage == "ERROR":
...     print(f"Job failed: {job_info.status.message}")
...     # Check logs for more details
...     for log in fetch_job_logs(job_id=job.id):
...         print(log)

Untuk detail lebih lanjut tentang parameter timeout, lihat referensi API run_job.

Lewati variabel lingkungan dan Secrets

Anda dapat meneruskan variabel lingkungan ke pekerjaan Anda menggunakan env dan secrets:

# Pass environment variables
>>> from huggingface_hub import run_job
>>> run_job(
...     image="python:3.12",
...     command=["python", "-c", "import os; print(os.environ['FOO'], os.environ['BAR'])"],
...     env={"FOO": "foo", "BAR": "bar"},
... )

# Pass secrets - they will be encrypted server side
>>> from huggingface_hub import run_job
>>> run_job(
...     image="python:3.12",
...     command=["python", "-c", "import os; print(os.environ['MY_SECRET'])"],
...     secrets={"MY_SECRET": "psswrd"},
... )

Variabel Lingkungan Bawaan

Di dalam kontainer job, variabel lingkungan berikut tersedia secara otomatis:

# Access job environment information
>>> from huggingface_hub import run_job
>>> run_job(
...     image="python:3.12",
...     command=["python", "-c", """
... import os
... print(f"Job ID: {os.environ.get('JOB_ID')}")
... print(f"Accelerator: {os.environ.get('ACCELERATOR', 'none')}")
... print(f"CPU cores: {os.environ.get('CPU_CORES')}")
... print(f"Memory: {os.environ.get('MEMORY')}")
... """],
... )

Variabel-varabel ini berguna ketika Anda perlu membuat pengenal unik untuk output, menyesuaikan kode Anda berdasarkan perangkat keras yang tersedia, atau mencatat informasi sumber daya.

Label

Label adalah pasangan key=value yang menempelkan metadata ke sebuah Job:

Gunakan name untuk memudahkan pencarian dan identifikasi Jobs di UI. Nama bersifat opsional dan tidak harus unik:

>>> from huggingface_hub import run_job
>>> run_job(name="daily-report", image="python:3.12", command=["python", "report.py"])

Dari CLI, berikan --name saat membuat Job, atau beri nama Job yang sudah ada melalui perintah labels:

>>> hf jobs run --name daily-report python:3.12 python report.py
>>> hf jobs labels <job_id> --name daily-report

hf jobs ls menampilkan kolom NAME dan dapat memfilter berdasarkan nama (jalan pintas untuk --label name=NAME):

>>> hf jobs ls -a --name daily-report

# Pass extra metadata with Labels
>>> from huggingface_hub import run_job
>>> run_job(
...     image="python:3.12",
...     command=["python", "-c", "import os; print(os.environ['MY_SECRET'])"],
...     labels={"my-label": "my-value", "foo": "bar"},
... )

Jika Anda tidak meneruskan nama, nama akan diturunkan secara otomatis dari image Docker atau skrip, ditambah hash pendek (mis. python:3.12 foo --truc → python-3-12-1a2b3c4d). Dari CLI, hash tersebut mencakup perintah dan pengaturan runtime yang telah di-resolve (flavor, timeout, nilai environment, …), sehingga konfigurasi yang sama selalu menghasilkan nama yang sama, dan mengubah pengaturan — termasuk yang berasal dari header [tool.hf-jobs] skrip — akan mengubahnya. Dari API Python, hash hanya mencakup perintah.

Perbarui label

Gunakan update_job_labels() untuk mengganti label pada pekerjaan yang sudah ada. Ini akan mengganti semua label yang diberikan pengguna sebelumnya:

>>> from huggingface_hub import update_job_labels
>>> update_job_labels(job_id=job_id, labels={"env": "prod", "team": "ml"})

Hal ini juga berlaku untuk pekerjaan terjadwal dengan update_scheduled_job_labels():

>>> from huggingface_hub import update_scheduled_job_labels
>>> update_scheduled_job_labels(scheduled_job_id=scheduled_job_id, labels={"env": "staging"})

Dari CLI:

>>> hf jobs labels <job_id> --label env=prod --label team=ml
>>> hf jobs scheduled labels <scheduled_job_id> --label env=staging

Untuk menghapus semua label, berikan --clear:

>>> hf jobs labels <job_id> --clear

UV Scripts (Eksperimental)

Mencari skrip UV yang siap digunakan? Lihat organisasi uv-scripts di Hugging Face Hub, yang menawarkan kumpulan komunitas skrip UV untuk tugas seperti pelatihan model, generasi data sintetis, pemrosesan data, dan lainnya.

Jalankan skrip UV (skrip Python dengan dependensi inline) pada infrastruktur HF:

# Run a UV script (creates temporary repo)
>>> from huggingface_hub import run_uv_job
>>> run_uv_job("my_script.py")

# Run with GPU
>>> run_uv_job("ml_training.py", flavor="gpu-t4-small")

# Run with dependencies
>>> run_uv_job("inference.py", dependencies=["transformers", "torch"])

# Run a script directly from a URL
>>> run_uv_job("https://huggingface.co/datasets/username/scripts/resolve/main/example.py")

# Run a command
>>> run_uv_job("python", script_args=["-c", "import lighteval"], dependencies=["lighteval"])

UV scripts adalah skrip Python yang menyertakan dependensi mereka secara langsung di dalam file menggunakan sintaks komentar khusus. Hal ini menjadikannya sempurna untuk tugas-tugas mandiri yang tidak memerlukan setup proyek yang kompleks. Pelajari lebih lanjut tentang UV scripts di dokumentasi UV.

Sertakan konfigurasi peluncuran dengan skrip

Skrip yang hanya berjalan dengan benar pada runtime tertentu dapat membawa runtime tersebut bersamanya, dalam tabel opsional [tool.hf-jobs] di header PEP 723-nya:

# /// script
# requires-python = ">=3.11"
# dependencies = ["vllm", "datasets"]
#
# [tool.hf-jobs]
# image   = "vllm/vllm-openai:unlimited-ocr"
# flavor  = "l4x1"
# python  = "/usr/bin/python3"
# secrets = ["HF_TOKEN"]
# ///

hf jobs uv run ocr.py kemudian meluncurkan dengan image, hardware, dan interpreter yang tepat, dan --flavor, -e, … masih menimpa apa yang dideklarasikan oleh skrip. Lihat panduan CLI untuk daftar lengkap kunci dan aturan merge.

Tabel ini hanya dibaca oleh CLI hf: run_uv_job() dan create_scheduled_uv_job() mengabaikannya dan menggunakan persis argumen yang diberikan. Dengan kata lain, run_uv_job("ocr.py") dan hf jobs uv run ocr.py tidak menjalankan Job yang sama — API Python memerlukan image=, flavor=, … untuk diteruskan secara eksplisit.

Docker Images untuk Skrip UV

Meskipun skrip UV dapat menentukan dependensi secara inline, beban kerja ML sering kali memiliki dependensi yang kompleks. Menggunakan image Docker yang sudah dibangun sebelumnya dengan pustaka-pustaka ini terpasang dapat mempercepat startup pekerjaan secara signifikan dan menghindari masalah dependensi.

Secara default, saat Anda menjalankan hf jobs uv run, image astral-sh/uv:python3.12-bookworm digunakan. Image ini didasarkan pada distribusi Python 3.12 Bookworm dengan uv yang sudah terpasang.

Anda dapat menentukan gambar yang berbeda menggunakan flag --image:

hf jobs uv run \
 --flavor a10g-large \
 --image vllm/vllm-openai:latest \
...

Perintah di atas akan dijalankan menggunakan image vllm/vllm-openai:latest. Pendekatan ini bisa berguna jika Anda menggunakan vLLM untuk pembuatan data sintetis.

Banyak framework inferensi menyediakan gambar docker yang dioptimalkan. Seiring dengan semakin diadopsinya uv di ekosistem Python, semakin banyak framework ini yang juga memiliki uv terpasang sebelumnya, yang berarti mereka akan berfungsi saat menggunakan hf jobs uv run.

Jadwal Tugas

Jadwalkan dan kelola pekerjaan yang akan dijalankan di infrastruktur HF.

Gunakan create_scheduled_job() atau create_scheduled_uv_job() dengan jadwal @annually, @yearly, @monthly, @weekly, @daily, @hourly, atau ekspresi jadwal CRON (misalnya, "0 9 * * 1" untuk pukul 09.00 setiap Senin):

# Schedule a job that runs every hour
>>> from huggingface_hub import create_scheduled_job
>>> create_scheduled_job(
...     image="python:3.12",
...     command=["python",  "-c", "print('This runs every hour!')"],
...     schedule="@hourly"
... )

# Use the CRON syntax
>>> create_scheduled_job(
...     image="python:3.12",
...     command=["python",  "-c", "print('This runs every 5 minutes!')"],
...     schedule="*/5 * * * *"
... )

# Schedule with GPU
>>> create_scheduled_job(
...     image="pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel",
...     command=["python",  "-c", 'import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")'],
...     schedule="@hourly",
...     flavor="a10g-small",
... )

# Schedule a UV script
>>> from huggingface_hub import create_scheduled_uv_job
>>> create_scheduled_uv_job("my_script.py", schedule="@hourly")

Gunakan parameter yang sama seperti run_job() dan run_uv_job() untuk meneruskan variabel lingkungan, rahasia, timeout, dll.

Kelola pekerjaan terjadwal menggunakan list_scheduled_jobs(), inspect_scheduled_job(), suspend_scheduled_job(), resume_scheduled_job(), update_scheduled_job_schedule(), trigger_scheduled_job(), dan delete_scheduled_job():

# List your active scheduled jobs
>>> from huggingface_hub import list_scheduled_jobs
>>> list_scheduled_jobs()

# Only list scheduled jobs with the given labels
>>> list_scheduled_jobs(labels={"env": "prod"})

# Inspect the status of a job
>>> from huggingface_hub import inspect_scheduled_job
>>> inspect_scheduled_job(scheduled_job_id=scheduled_job_id)

# Suspend (pause) a scheduled job
>>> from huggingface_hub import suspend_scheduled_job
>>> suspend_scheduled_job(scheduled_job_id=scheduled_job_id)

# Resume a scheduled job
>>> from huggingface_hub import resume_scheduled_job
>>> resume_scheduled_job(scheduled_job_id=scheduled_job_id)

# Change future run times without recreating the scheduled job
>>> from huggingface_hub import update_scheduled_job_schedule
>>> updated = update_scheduled_job_schedule(scheduled_job_id=scheduled_job_id, schedule="0 9 * * 1")
>>> updated.schedule
'0 9 * * 1'

# Trigger a scheduled job to run right now (does not change the schedule)
>>> from huggingface_hub import trigger_scheduled_job
>>> job = trigger_scheduled_job(scheduled_job_id=scheduled_job_id)
>>> job.url

# Delete a scheduled job
>>> from huggingface_hub import delete_scheduled_job
>>> delete_scheduled_job(scheduled_job_id=scheduled_job_id)

Memicu Pekerjaan dengan webhook

Webhooks memungkinkan Anda untuk mendengarkan perubahan baru pada repositori tertentu atau pada semua repositori yang dimiliki oleh kumpulan pengguna/organisasi tertentu (bukan hanya repositori Anda, tetapi repositori apa pun).

Gunakan create_webhook() untuk membuat webhook yang memicu Job ketika terjadi perubahan di repositori Hugging Face:

from huggingface_hub import create_webhook

# Example: Creating a webhook that triggers a Job
webhook = create_webhook(
    job_id=job_id,
    watched=[{"type": "user", "name": "your-username"}, {"type": "org", "name": "your-org-name"}],
    domains=["repo", "discussion"],
    secret="your-secret"
)

Webhook memicu Job dengan payload webhook di variabel lingkungan WEBHOOK_PAYLOAD. Anda dapat menemukan informasi lebih lanjut tentang webhook di dokumentasi Webhooks.