hf jobs run / hf jobs uv run în Hugging Face Hub & Transformers

hf jobs run [opțiuni] IMAGINE COMANDĂ...
hf jobs uv run [opțiuni] SCRIPT [ARGUMENTE]...

Ce face hf jobs run / hf jobs uv run

hf jobs run pornește un Job: o comandă într-o imagine Docker (sau dintr-un Space, de exemplu hf.co/spaces/lhoestq/duckdb), pe hardware Hugging Face ales cu --flavor. Documentația îl compară cu docker run. Implicit afișează logurile până la final și iese cu cod diferit de 0 dacă Job-ul eșuează; --detach îl lasă în fundal și afișează doar ID-ul. Jobs sunt disponibile utilizatorilor și organizațiilor cu credite preplătite.

hf jobs uv run (experimental) rulează un script UV, adică Python cu dependențele declarate în fișier, local sau de la un URL; --with adaugă pachete. Scriptul își poate declara configurația de lansare într-un tabel [tool.hf-jobs] din antetul PEP 723 (imagine, flavor, timeout, env, secrete, volume etc.); opțiunile date în comandă au prioritate. --dry-run afișează configurația rezolvată fără să trimită Job-ul.

Limita implicită este de 30 de minute; --timeout acceptă secunde sau unități (90m, 2h, 1.5h). -v montează repository-uri sau buckets (hf://...) sau un director local, sincronizat întâi în bucket-ul jobs-artifacts. În container sunt disponibile JOB_ID, ACCELERATOR, CPU_CORES și MEMORY. Folosește -- ca să separi opțiunile Jobs de cele ale comenzii tale.

Sintaxă și opțiuni

Opțiune / Parametru	Descriere
IMAGE COMMAND...	Imaginea Docker și comanda (run).
SCRIPT [SCRIPT_ARGS]...	Scriptul UV (fișier sau URL) și argumentele lui (uv run).
--flavor [...]	Hardware-ul, implicit cpu-basic. Lista completă: hf jobs hardware (de exemplu t4-small, a10g-small, a100-large, h200, l40sx4).
-e, --env / --env-file	Variabile de mediu; fișierul poate fi - (stdin).
-s, --secrets / --secrets-file	Secrete criptate pe server. -s NUME citește valoarea din mediul tău; --secrets HF_TOKEN transmite tokenul tău.
--timeout TEXT	Durata maximă: s (implicit), m, h sau d. Implicit 30 de minute.
--attempts INTEGER	Numărul maxim de încercări, inclusiv prima. Implicit 1.
-d, --detach	Rulează în fundal și afișează ID-ul Job-ului.
--dry-run	Afișează configurația fără să trimită Job-ul.
--name TEXT	Numele Job-ului (salvat ca eticheta name; nu trebuie să fie unic).
-l, --label TEXT	Etichete CHEIE=VALOARE sau ETICHETĂ.
-v, --volume TEXT	hf://[TIP/]SURSĂ:/CALE[:ro|:rw] sau DIR_LOCAL:/CALE. Buckets sunt citire-scriere implicit; restul doar citire.
--expose / --expose-public INTEGER	Expune un port prin proxy-ul Jobs, cu token / fără autentificare.
--ssh	Containerul devine accesibil prin SSH (hf jobs ssh).
--network-group / --network-alias TEXT	Job-urile din același grup se văd pe toate porturile.
--resource-group-id / --namespace	Grupul de resurse; contul sau organizația în care rulează Job-ul.
uv run --image TEXT	Imagine Docker proprie, cu uv instalat.
uv run --with TEXT	Pachete instalate în plus.
uv run -p, --python TEXT	Interpretorul Python folosit.
-q, --quiet / --json / --format	Formatul ieșirii; -q afișează doar ID-ul Job-ului.
--token TEXT	Token de acces (User Access Token) creat în huggingface.co/settings/tokens. Implicit se folosește tokenul salvat de hf auth login.

Exemple practice

Exemplul 1: Primul Job

hf jobs run python:3.12 python -c 'print("Hello from HF compute!")'

Exemplul 2: Pe GPU A10G

hf jobs run --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
  python -c 'import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")'

Rezultat

This code ran with the following GPU: NVIDIA A10G

Exemplul 3: În fundal, cu ID-ul capturat

JOB_ID=$(hf jobs run -dq python:3.12 python train.py)
hf jobs wait "$JOB_ID"

Exemplul 4: Secret din mediul local și limită de 2 ore

hf jobs run -s MY_SECRET --timeout 2h python:3.12 python train.py

Exemplul 5: Script UV pe GPU, cu dependențe în plus

hf jobs uv run --flavor t4-small --with transformers --with torch train.py

Exemplul 6: Dataset montat ca intrare

hf jobs run -v hf://datasets/HuggingFaceFW/fineweb:/dataset \
  duckdb/duckdb duckdb -c "SELECT * FROM '/dataset/**/*.parquet' LIMIT 5"

Greșeli frecvente și bune practici

• Nu setezi --timeout pentru antrenări. După 30 de minute Job-ul este oprit automat.
• Dai secretele ca -s CHEIE=valoare. Valoarea ajunge în istoricul shell-ului și în lista de procese; CLI-ul afișează un avertisment. Folosește -s CHEIE sau --secrets-file.
• Pui opțiunile scriptului înaintea lui --. Fără separator, opțiuni ca --help sau --json sunt consumate de hf jobs.

Comenzi înrudite

• hf-jobs-gestionare
• hf-jobs-scheduled
• hf-sandbox
• hf-buckets