# 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](https://huggingface.co/docs/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](../quick-start#authentication). Dalam sisa panduan ini, kami mengasumsikan bahwa mesin Anda sudah masuk.

> [!TIP]
> **Hugging Face Jobs** tersedia untuk pengguna atau organisasi mana pun yang memiliki [saldo kredit](https://huggingface.co/settings/billing) positif. Lihat [harga dan penagihan Jobs](https://huggingface.co/docs/hub/jobs-pricing) untuk detailnya.

## Antarmuka Baris Perintah Jobs

Gunakan [`hf jobs` CLI](./cli#hf-jobs) 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:

```bash
>>> 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:

```bash
>>> 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](https://docs.astral.sh/uv/guides/scripts/).

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`](./cli#hf-jobs).

> [!TIP]
> Butuh mesin *interaktif* alih-alih tugas sekali jalan — misalnya untuk menjalankan kode yang dihasilkan AI, dengan eksekusi perintah dan transfer file? Coba lihat [Sandboxes](./sandbox), 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 tempat Anda memiliki izin tulis. Fitur ini bersifat pay-as-you-go: Anda hanya membayar untuk detik-detik yang Anda gunakan.

[run_job()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.run_job) memungkinkan Anda menjalankan perintah apa pun di infrastruktur Hugging Face:

```python
# 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")
```

> [!WARNING]
> **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](#configure-job-timeout) untuk detailnya.

[run_job()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.run_job) mengembalikan [JobInfo](/docs/huggingface_hub/main/id/package_reference/jobs#huggingface_hub.JobInfo) yang berisi URL Job di Hugging Face, tempat Anda dapat melihat status Job dan log. Simpan Job ID dari [JobInfo](/docs/huggingface_hub/main/id/package_reference/jobs#huggingface_hub.JobInfo) untuk mengelola job:

```python
>>> 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()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.inspect_job) untuk mengetahui status jobs, [fetch_job_logs()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.fetch_job_logs) untuk melihat log, dan [fetch_job_metrics()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.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`.

```python
>>> 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

```python
# 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()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.wait_for_job) untuk memblokir hingga sebuah Job mencapai tahap terminal (`COMPLETED`, `CANCELED`, `ERROR` atau `DELETED`). [JobInfo](/docs/huggingface_hub/main/id/package_reference/jobs#huggingface_hub.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.

```python
>>> 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:

```bash
# 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:

```python
# 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!

```bash
This code ran with the following GPU: NVIDIA A10G
```

Gunakan ini untuk menjalankan skrip fine-tuning seperti [trl/scripts/sft.py](https://github.com/huggingface/trl/blob/main/trl/scripts/sft.py) dengan UV:

```python
>>> 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",
... )
```

> [!TIP]
> Untuk panduan komprehensif tentang menjalankan tugas pelatihan model dengan TRL pada infrastruktur Hugging Face, lihat [dokumentasi Pelatihan TRL Jobs](https://huggingface.co/docs/trl/main/en/jobs_training). 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:

| name | nama yang bagus | cpu | ram | penyimpanan | accelerator | biaya/menit | biaya/jam |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `cpu-basic` | Dasar CPU | 2 vCPU | 16 GB | 50 GB | - | $0.0002 | $0.01 |
| `cpu-upgrade` | Upgrade CPU | 8 vCPU | 32 GB | 50 GB | - | $0.0005 | $0.03 |
| `cpu-performance` | Kinerja CPU | 32 vCPU | 256 GB | 1024 GB | - | $0.0317 | $1.90 |
| `cpu-xl` | CPU XL | 16 vCPU | 124 GB | 1000 GB | - | $0.0167 | $1.00 |
| `t4-small` | Nvidia T4 - kecil | 4 vCPU | 15 GB | 50 GB | 1x T4 (16 GB) | $0.0067 | $0.40 |
| `t4-medium` | Nvidia T4 - sedang | 8 vCPU | 30 GB | 100 GB | 1x T4 (16 GB) | $0.0100 | $0.60 |
| `a10g-small` | Nvidia A10G - kecil | 4 vCPU | 15 GB | 110 GB | 1x A10G (24 GB) | $0.0167 | $1.00 |
| `a10g-large` | Nvidia A10G - besar | 12 vCPU | 46 GB | 200 GB | 1x A10G (24 GB) | $0.0250 | $1.50 |
| `a10g-largex2` | 2x Nvidia A10G - besar | 24 vCPU | 92 GB | 1000 GB | 2x A10G (48 GB) | $0.0500 | $3.00 |
| `a10g-largex4` | 4x Nvidia A10G - besar | 48 vCPU | 184 GB | 2000 GB | 4x A10G (96 GB) | $0.0833 | $5.00 |
| `a100-large` | Nvidia A100 - besar | 12 vCPU | 142 GB | 1000 GB | 1x A100 (80 GB) | $0.0417 | $2.50 |
| `a100x4` | 4x Nvidia A100 | 48 vCPU | 568 GB | 4000 GB | 4x A100 (320 GB) | $0.1667 | $10.00 |
| `a100x8` | 8x Nvidia A100 | 96 vCPU | 1136 GB | 8000 GB | 8x A100 (640 GB) | $0.3333 | $20.00 |
| `h200` | Nvidia H200 | 23 vCPU | 256 GB | 3000 GB | 1x H200 (141 GB) | $0.0833 | $5.00 |
| `h200x2` | Nvidia H200 | 46 vCPU | 512 GB | 6000 GB | 2x H200 (282 GB) | $0.1667 | $10.00 |
| `h200x4` | Nvidia H200 | 92 vCPU | 1024 GB | 12000 GB | 4x H200 (564 GB) | $0.3333 | $20.00 |
| `h200x8` | Nvidia H200 | 184 vCPU | 2048 GB | 24000 GB | 8x H200 (1128 GB) | $0.6667 | $40.00 |
| `rtx-pro-6000` | Nvidia RTX PRO 6000 | 23 vCPU | 256 GB | 475 GB | 1x RTX PRO 6000 (96 GB) | $0.0458 | $2.75 |
| `rtx-pro-6000x2` | Nvidia RTX PRO 6000 | 46 vCPU | 512 GB | 950 GB | 2x RTX PRO 6000 (192 GB) | $0.0917 | $5.50 |
| `rtx-pro-6000x4` | Nvidia RTX PRO 6000 | 92 vCPU | 1024 GB | 1900 GB | 4x RTX PRO 6000 (384 GB) | $0.1833 | $11.00 |
| `rtx-pro-6000x8` | Nvidia RTX PRO 6000 | 184 vCPU | 2048 GB | 3800 GB | 8x RTX PRO 6000 (768 GB) | $0.3667 | $22.00 |
| `l4x1` | 1x Nvidia L4 | 8 vCPU | 30 GB | 400 GB | 1x L4 (24 GB) | $0.0133 | $0.80 |
| `l4x4` | 4x Nvidia L4 | 48 vCPU | 186 GB | 3200 GB | 4x L4 (96 GB) | $0.0633 | $3.80 |
| `l40sx1` | 1x Nvidia L40S | 8 vCPU | 62 GB | 380 GB | 1x L40S (48 GB) | $0.0300 | $1.80 |
| `l40sx4` | 4x Nvidia L40S | 48 vCPU | 382 GB | 3200 GB | 4x L40S (192 GB) | $0.1383 | $8.30 |
| `l40sx8` | 8x Nvidia L40S | 192 vCPU | 1534 GB | 6500 GB | 8x L40S (384 GB) | $0.3917 | $23.50 |

Anda dapat memperoleh daftar ini secara programatik dengan menjalankan:

```bash
>>> hf jobs hardware
```

Atau menggunakan API Python:

```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](/docs/huggingface_hub/main/id/package_reference/jobs#huggingface_hub.Volume).

Anda dapat memuat (mount) Repositori Hugging Face (model/dataset/space) mana pun atau [Storage Bucket](/docs/hub/storage-buckets). 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:

```python
>>> 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:

```python
>>> 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()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.sync_job_volume): fungsi ini menyinkronkan direktori lokal ke [Storage Bucket](https://huggingface.co/docs/hub/storage-buckets) `jobs-artifacts` (dibuat secara otomatis jika diperlukan) dan mengembalikan [Volume](/docs/huggingface_hub/main/id/package_reference/jobs#huggingface_hub.Volume) yang siap dipasang:

```python
>>> 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()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.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:

```python
>>> 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`:

```bash
>>> 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:

```python
>>> 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()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.run_job) (atau [run_uv_job()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.run_uv_job)) agar kontainer Job dapat dijangkau melalui SSH. Endpoint SSH tersedia di status Job:

```python
>>> 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`):

```bash
>>> 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()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.run_job) (atau [run_uv_job()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.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=[...]`:

```python
>>> 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):
```python
>>> 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**:
```python
>>> # 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:

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

> [!WARNING]
> 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

```python
>>> 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`](https://huggingface.co/docs/huggingface_hub/package_reference/hf_api#huggingface_hub.HfApi.run_job.timeout).

## Lewati variabel lingkungan dan Secrets

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

```python
# 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"},
... )
```

```python
# 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:

| Variabel | Deskripsi |
|----------|-------------|
| `JOB_ID` | Pengidentifikasi unik dari tugas saat ini. Gunakan ini untuk merujuk tugas secara programatik, misalnya untuk menyimpan output dalam dataset dengan nama unik. |
| `ACCELERATOR` | Jenis akselerator yang tersedia (misalnya, `t4-medium`, `a10g-small`, `a100x4`). Kosong jika tidak ada akselerator. |
| `CPU_CORES` | Jumlah inti CPU yang tersedia untuk pekerjaan (misalnya, `2`, `4`, `8`). |
| `MEMORY` | Jumlah memori yang tersedia untuk pekerjaan (misalnya, `16Gi`, `32Gi`). |

```python
# 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:

```python
>>> 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:

```bash
>>> 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`):

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

```python
# 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()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.update_job_labels) untuk mengganti label pada pekerjaan yang sudah ada. Ini akan mengganti semua label yang diberikan pengguna sebelumnya:

```python
>>> 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()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.update_scheduled_job_labels):

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

Dari CLI:

```bash
>>> 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`:

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

## UV Scripts (Eksperimental)

> [!TIP]
> Mencari skrip UV yang siap digunakan? Lihat [organisasi uv-scripts](https://huggingface.co/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:

```python
# 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](https://docs.astral.sh/uv/guides/scripts/).

#### 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:

```python
# /// 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](./cli#ship-the-launch-config-with-the-script) untuk daftar lengkap kunci dan aturan merge.

> [!WARNING]
> Tabel ini hanya dibaca oleh CLI `hf`: [run_uv_job()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.run_uv_job) dan [create_scheduled_uv_job()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.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`:

```bash
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.

> [!TIP]
> 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()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.create_scheduled_job) atau [create_scheduled_uv_job()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.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):

```python
# 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()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.run_job) dan [run_uv_job()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.run_uv_job) untuk meneruskan variabel lingkungan, rahasia, timeout, dll.

Kelola pekerjaan terjadwal menggunakan [list_scheduled_jobs()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.list_scheduled_jobs), [inspect_scheduled_job()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.inspect_scheduled_job), [suspend_scheduled_job()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.suspend_scheduled_job), [resume_scheduled_job()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.resume_scheduled_job), [update_scheduled_job_schedule()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.update_scheduled_job_schedule), [trigger_scheduled_job()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.trigger_scheduled_job), dan [delete_scheduled_job()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.delete_scheduled_job):

```python
# 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()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.create_webhook) untuk membuat webhook yang memicu Job ketika terjadi perubahan di repositori Hugging Face:

```python
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](./webhooks).