İşleri Çalıştır ve Yönet

Hugging Face Hub, Jobs aracılığıyla yapay zeka ve veri iş akışları için hesaplama gücü sağlar.

Jobs ve fiyatlandırma hakkında genel bir bakış için Hub Jobs belgelerini inceleyin.

Bir iş, Hugging Face altyapısında çalışır ve çalıştırılacak bir komutla (ör. bir python komutu), Hugging Face Spaces veya Docker Hub'dan bir Docker Image ile ve bir donanım türüyle (CPU, GPU, TPU) tanımlanır. Bu kılavuz, Hub'daki işlerle nasıl etkileşime geçeceğinizi, özellikle de şunları gösterecektir:

• Bir iş çalıştırın.
• İş durumunu kontrol edin.
• Donanımı seçin.
• Ortam değişkenlerini ve gizli bilgileri yapılandırın.
• UV betiklerini çalıştırın.

Hub üzerinde bir iş çalıştırmak ve yönetmek istiyorsanız, makinenizin oturum açmış olması gerekir. Değilse, lütfen bu bölüme bakın. Bu kılavuzun geri kalanında, makinenizin oturum açmış olduğunu varsayacağız.

Hugging Face Jobs, pozitif kredi bakiyesi olan herhangi bir kullanıcı veya kuruluş için kullanılabilir. Ayrıntılar için Jobs fiyatlandırması ve faturalandırma bölümüne bakın.

Jobs Komut Satırı Arayüzü

Komut satırından İşler'i çalıştırmak için hf jobs CLI'sını kullanın ve donanımınızı belirtmek için --flavor parametresini iletin.

hf jobs run, tanıdık bir Docker benzeri arayüzle, bir Docker görüntüsü ve komutla Jobs çalıştırır. docker run gibi düşünün, ancak kodu herhangi bir donanımda çalıştırmak için:

>>> 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())"

Yerel veya uzak UV betiklerini çalıştırmak için hf jobs uv run kullanın:

>>> 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 betikleri, UV belgelerinde tanımlanan özel bir yorum sözdizimi kullanarak bağımlılıklarını doğrudan dosyanın içinde barındıran Python betikleridir.

Şimdi bu rehberin geri kalanı size python API'sini gösterecek. Bunun yerine mevcut tüm hf jobs komutlarını ve seçeneklerini görüntülemek isterseniz, hf jobs komut satırı arayüzü rehberine göz atın.

Ateşle ve unut (fire-and-forget) bir iş yerine etkileşimli bir makineye mi ihtiyacınız var — örneğin AI tarafından üretilen kodu çalıştırmak, komut yürütmek ve dosya aktarımı için? Jobs üzerine inşa edilen Sandboxes özelliğine göz atın.

İş Çalıştır

Hugging Face altyapısında (GPU ve TPU dahil) bir komut ve bir Docker Image ile tanımlanan compute Jobs'larını çalıştırın.

Sadece sahip olduğunuz (kullanıcı adınızın ad alanı altındaki) veya yazma izinlerinizin bulunduğu organizasyonlardaki Jobs öğelerini yönetebilirsiniz. Bu özellik kullanım bazlı ücretlendirilir: yalnızca kullandığınız saniyeler için ödeme yaparsınız.

run_job(), Hugging Face altyapısında herhangi bir komut çalıştırmanızı sağlar:

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

Önemli: İşlerin varsayılan bir zaman aşımı (30 dakika) vardır ve bu süre dolduğunda otomatik olarak durdurulurlar. Model eğitimi gibi uzun süreli görevler için timeout parametresini kullanarak özel bir zaman aşımı ayarlamayı unutmayın. Ayrıntılar için İş Zaman Aşımını Yapılandırma bölümüne bakın.

run_job(), Hugging Face üzerinde işin URL'sini, iş durumunu ve günlüklerini görebileceğiniz JobInfo nesnesini döndürür. İşi yönetmek için JobInfo içindeki İş Kimliğini (Job ID) kaydedin:

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

İşler arka planda çalışır. Bir sonraki bölüm, bir işin durumunu öğrenmek için inspect_job(), günlükleri görüntülemek için fetch_job_logs() ve kaynak kullanımını izlemek için fetch_job_metrics() işlevlerini kullanmanızı adım adım anlatır.

Bir İşlem'i Yeniden Deneyin ve Çalıştırın

Başarısız bir Job'u yeniden denemek için attempts parametresini kullanın. Sayı, ilk denemeyi de içerdiğinden attempts=3 en fazla iki yeniden denemeye izin verir. Ayrıca run_uv_job, create_scheduled_job ve create_scheduled_uv_job ile de çalışır.

>>> 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, yeni bir kimlikle ayrı bir Job başlatır. Tamamlanmış veya başarısız olmuş Job'lar için çalışır ve gizli bilgileri (secrets) ile donanım ayarlarını içeren kaydedilmiş spec'i yeniden kullanır. Ayrıca hf jobs rerun <job_id> komutunu da çalıştırabilirsiniz.

İş durumunu kontrol et

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

İşler tamamlanana kadar bekleyin

Bir Job'un son bir aşamaya (COMPLETED, CANCELED, ERROR veya DELETED) ulaşmasını beklemek için wait_for_job() kullanın. Son JobInfo her zaman döndürülür — başarısız bir Job istisna fırlatmaz — bu nedenle sonucu işlemek için job.status.stage değerini kontrol edin. Bir partiyi aynı anda beklemek için Job kimliklerinin bir listesini iletin.

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

Aynı özellik, hf jobs wait ile CLI'de de kullanılabilir; bu komut yalnızca tüm İşler başarıyla tamamlandığında 0 koduyla sonlanır — kabuk betiklerinde veya CI'da komutları zincirlemek için kullanışlıdır:

# 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

Ayrıştırılmamış bir hf jobs run (veya hf jobs uv run) komutunun, İş başarısız olursa sıfır olmayan bir kodla çıktığını ve bu nedenle hf jobs run ... && next-step zincirinin açık bir bekleme komutu olmadan doğru şekilde çalıştığını unutmayın.

Donanımı seçin

GPU'lerde İşler çalıştırmak için faydalı olan birçok durum vardır:

• Model Eğitimi: Altyapıyı yönetmeden GPU'larda (T4, A10G, A100) modelleri ince ayarlayın veya eğitin
• Sentetik Veri Üretimi: Güçlü donanımlarda LLM'ler kullanarak büyük ölçekli veri kümeleri oluşturun
• Veri İşleme: Yüksek CPU yapılandırmalarıyla paralel iş yükleri için devasa veri kümelerini işleyin
• Toplu Çıkarım: Optimize edilmiş GPU kurulumları kullanarak binlerce örnek üzerinde çevrimdışı çıkarım çalıştırın
• Deneysel Çalışmalar ve Karşılaştırmalar: Yeniden üretilebilir sonuçlar için tutarlı donanımda ML deneyleri çalıştırın
• Geliştirme ve Hata Ayıklama: Yerel CUDA kurulumu olmadan GPU kodunu test edin

İşleri flavor argümanını kullanarak GPU veya TPU üzerinde çalıştırın. Örneğin, bir PyTorch işini A10G GPU üzerinde çalıştırmak için:

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

Bunu çalıştırdığınızda aşağıdaki çıktı görüntülenir!

This code ran with the following GPU: NVIDIA A10G

UV ile trl/scripts/sft.py gibi bir ince ayar betiği çalıştırmak için bunu kullanın:

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

Hugging Face altyapısında TRL ile model eğitim işlerini çalıştırmaya dair kapsamlı yönergeler için TRL Jobs Eğitim belgelerini inceleyin. Bu belgeler, ince ayar tarifleri, donanım seçimi ve modelleri verimli bir şekilde eğitmek için en iyi uygulamaları kapsamaktadır.

İşleri çalıştırmak için kullanılabilen donanımların tam listesi aşağıdadır:

Bu listeyi programatik olarak almak için şunu çalıştırabilirsiniz:

>>> hf jobs hardware

veya Python API'sini kullanarak:

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

Bitti! Artık Hugging Face altyapısında kod çalıştırıyorsunuz.

Bir hacim bağlayın

Jobs diskinde bir Volume listesi kullanarak bir hacim bağlayın.

Herhangi bir Hugging Face Deposu (model/veri seti/uzay) veya Depolama Kovası bağlayabilirsiniz. Örneğin:

• model deposu bağlama: Volume(type="model", source="openai/gpt-oss-120b", mount_path="/model")
• veri seti deposu bağlayın: Volume(type="dataset", source="HuggingFaceFW/fineweb", mount_path="/data")
• bir depolama kovası bağlayın: Volume(type="bucket", source="username/my-bucket", mount_path="/mnt")

Daha sonra bağlı birimi yerel bir dizin olarak kullanabilirsiniz:

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

Ayrıca, örneğin bir model eğitirken kontrol noktalarını (checkpoint) kaydetmek için, bağlı bir kovaya (bucket) da yazabilirsiniz:

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

Varsayılan olarak, bağlanmış depolama varilleri okuma+yazma yeteneklerine sahiptir. Bu, sık sık değişen veriler için hızlı, değiştirilebilir depolama sağlayan depolama varilleri için özellikle faydalıdır — dosyalar yerinde üzerine yazılabilir veya silinebilir.

Salt okunur modu etkinleştirmek için read_only=True kullanın: Volume(type="bucket", read_only=True, ...).

Yerel verileri bağlama

Makinenizdeki verilere karşı bir Job çalıştırmak için sync_job_volume() kullanın: bu fonksiyon, yerel bir dizini jobs-artifacts Storage Bucket’ına (gerekirse otomatik olarak oluşturulur) senkronize eder ve bağlanmaya hazır bir Volume döndürür:

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

Her dizin, kovada kendi kendine özgü, kararlı klasörüne sahip olur: Aynı dizin üzerinde sync_job_volume() işlevini yeniden çalıştırmak yalnızca yeni veya değiştirilmiş dosyaları yükler. Hacim varsayılan olarak salt okunur olarak bağlanır.

Bir Job tarafından yazılan dosyaları almak için, okuma-yazma bir hacim (boş bir çıktı dizini de işe yarar) bağlayın ve Job bittiğinde içeriğini geri senkronize edin:

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

CLI'de, -v'nin kaynak tarafı olarak yerel bir dizin geçmeniz yeterlidir:

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

İş portlarını aç

Jobs proxy üzerinden bir konteyner portuna erişilebilir olması için expose parametresini iletin. Erişim, Job’un namespace’ine okuma erişimine sahip bir HF token gerektirir. Kimlik doğrulama olmadan erişime izin vermek için bunun yerine expose_public kullanın:

>>> 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 ve expose_public birleştirilebilir. update_job_expose, çalışan bir Job’da yeniden başlatma yapmadan tam port yapılandırmasını değiştirir: her iki listede de olmayan portlar kapatılır. Her iki seçenek de UV ve zamanlanmış Job’lar oluşturulurken kullanılabilir.

Bir İşe SSH ile Bağlan

Job konteynerinin SSH üzerinden erişilebilir olması için run_job() (veya run_uv_job()) fonksiyonuna ssh=True parametresini iletin. SSH uç noktası Job durumunda kullanılabilir:

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

Bir terminalden hf jobs ssh <job_id> (veya doğrudan ssh <job_id>@ssh.hf.jobs) ile bağlanın:

>>> hf jobs ssh 68498e23210b3a4f4e6e2a23

Yalnızca İş'in ad alanına yazma erişimine sahip kullanıcılar (İş oluşturucusu veya sahip kuruluşun üyeleri), https://huggingface.co/settings/keys adresinde kayıtlı bir SSH genel anahtarıyla kimlik doğrulaması yapılarak izin verilir.

Ağ grupları

Aynı namespace ve kaynak grubundaki Jobs'ların her portta birbirine erişebilmesi için network_group="<name>" parametresini run_job() (veya run_uv_job()) fonksiyonuna iletin. Her üyenin içinde HF_NETWORK_GROUP_HOSTNAME, gruptaki tüm Jobs'lara, ${HF_NETWORK_GROUP_PREFIX}<alias> ise network_aliases=[...] ile bir alias talep eden üyelere çözümlenir:

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

Üyeler hazır olmadan önce çözümlenebilir, bu nedenle yeniden denemelerle bağlantı kurun. Grup adları ve takma adları küçük harfli alfanümerik karakterler ve tirelerden oluşur, en fazla 46 ve 34 karakter olabilir.

İş Zaman Aşımını Yapılandır

İşlerin varsayılan bir zaman aşımı (30 dakika) vardır; bu süre dolduğunda işler otomatik olarak durdurulur. Model eğitimi gibi uzun süreli görevleri çalıştırırken bunu bilmek önemlidir.

Özel zaman aşımı ayarlama

Bir iş çalıştırırken timeout parametresi kullanarak özel bir zaman aşımı değeri belirleyebilirsiniz. Zaman aşımı iki şekilde belirtilebilir:

1. Sayı olarak (saniye olarak yorumlanır):

>>> 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. Zaman birimleriyle bir dize olarak:

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

Desteklenen zaman birimleri:

• s - saniye
• m - dakika
• h - saat
• d - günler

UV işlerinde timeout kullanımı

UV işleri için zaman aşımını da belirleyebilirsiniz:

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

Zaman aşımı belirtmezseniz, işinize varsayılan bir zaman aşımı uygulanır. Saatler sürebilen model eğitimi gibi uzun süreli görevlerde, beklenmeyen iş sonlandırmalarını önlemek için uygun bir zaman aşımı ayarlamayı unutmayın.

İş süresini izleme

Uzun görevler çalıştırılırken iyi bir uygulama şudur:

• İşinizin beklenen süresini tahmin edin ve biraz pay bırakarak bir zaman aşımı ayarlayın
• İşinizin ilerlemesini günlükler aracılığıyla izleyin
• Zaman aşımına uğramadığından emin olmak için iş durumunu kontrol edin

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

Zaman aşımı parametresi hakkında daha fazla ayrıntı için run_job API referansına bakın.

Ortam değişkenlerini ve Gizli bilgileri iletil

Ortam değişkenlerini işinize env ve secrets kullanarak iletebilirsiniz:

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

Yerleşik Ortam Değişkenleri

İş konteynerinin içinde, aşağıdaki ortam değişkenleri otomatik olarak kullanılabilir:

# 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')}")
... """],
... )

Bu değişkenler, çıktılar için benzersiz tanımlayıcılar oluşturmanız, mevcut donanıma göre kodunuzu uyarlamanız veya kaynak bilgilerini günlüğe kaydetmeniz gerektiğinde kullanışlıdır.

Etiketler

Etiketler, bir İşe (Job) meta veri ekleyen anahtar=değer çiftleridir:

Arayüzde İşleri bulmayı ve tanımlamayı kolaylaştırmak için name kullanın. İsimler isteğe bağlıdır ve benzersiz olmak zorunda değildir:

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

CLI'den, bir Job oluştururken --name parametresini geçirin veya mevcut bir Job'ı labels komutuyla adlandırın:

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

hf jobs ls bir NAME sütunu gösterir ve adına göre filtreleme yapılabilir (--label name=NAME kısayolu):

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

Bir ad geçirmiyorsanız, ad Docker görüntüsünden veya betikten otomatik olarak türetilir ve kısa bir özet eklenir (ör. python:3.12 foo --truc → python-3-12-1a2b3c4d). CLI üzerinden bu özet, komutu ve çözümlenen çalışma zamanı ayarlarını (flavor, zaman aşımı, ortam değerleri, …) kapsar; bu nedenle aynı yapılandırma her zaman aynı adı üretir ve bir ayarın değiştirilmesi — betiğin [tool.hf-jobs] başlığından gelen bir ayar dahil — adı değiştirir. Python API’sinden ise özet yalnızca komutu kapsar.

Etiketleri güncelle

Mevcut bir işteki etiketleri değiştirmek için update_job_labels() kullanın. Bu, mevcut tüm kullanıcı sağlanan etiketlerin yerini alır:

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

Bu, update_scheduled_job_labels() ile planlanmış işler için de geçerlidir:

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

Komut satırından:

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

Tüm etiketleri kaldırmak için --clear parametresini iletin:

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

UV Betikleri (Deneysel)

Hazır kullanıma uygun UV betikleri arıyor musunuz? Model eğitimi, sentetik veri üretimi, veri işleme ve daha fazlası gibi görevler için topluluk tarafından derlenmiş bir UV betikleri koleksiyonu sunan Hugging Face Hub'daki uv-scripts organizasyonunu inceleyin.

HF altyapısında UV betiklerini (satır içi bağımlılıklara sahip Python betikleri) çalıştırın:

# 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 betikleri, bağımlılıklarını özel bir yorum sözdizimi kullanarak doğrudan dosya içinde barındıran Python betikleridir. Bu özellik, karmaşık proje kurulumları gerektirmeyen, kendi kendine yeten görevler için onları ideal kılar. UV betikleri hakkında daha fazla bilgi için UV belgelerini inceleyin.

Başlatma yapılandırmasını betikle birlikte gönderin

Sadece belirli bir çalışma zamanında doğru çalışan bir betik, PEP 723 başlığında isteğe bağlı [tool.hf-jobs] tablosuyla bu çalışma zamanını taşıyabilir:

# /// 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 komutu, doğru görüntü, donanım ve yorumlayıcıyla başlatılır ve --flavor, -e, … gibi parametreler, betiğin bildirdiği değerleri yine de geçersiz kılar. Tüm anahtarların listesi ve birleştirme kuralları için CLI kılavuzuna bakın.

Tablo yalnızca hf CLI tarafından okunur: run_uv_job() ve create_scheduled_uv_job() bunu görmezden gelir ve kendilerine verilen argümanları aynen kullanır. Başka bir deyişle run_uv_job("ocr.py") ve hf jobs uv run ocr.py aynı Job'u çalıştırmaz — Python API'si için image=, flavor=, … gibi parametrelerin açıkça geçirilmesi gerekir.

UV Betikleri İçin Docker Görselleri

UV betikleri bağımlılıklarını satır içi olarak belirleyebilirken, ML iş yükleri genellikle karmaşık bağımlılıklara sahiptir. Bu kütüphanelerin önceden yüklü olduğu hazır Docker görüntülerini kullanmak, iş başlatma hızını önemli ölçüde artırabilir ve bağımlılık sorunlarını önleyebilir.

Varsayılan olarak, hf jobs uv run komutunu çalıştırdığınızda astral-sh/uv:python3.12-bookworm görüntüsü kullanılır. Bu görüntü, uv önceden yüklü olan Python 3.12 Bookworm dağıtımına dayanmaktadır.

--image bayrağını kullanarak farklı bir görsel belirtebilirsiniz:

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

Yukarıdaki komut, vllm/vllm-openai:latest görüntüsü kullanılarak çalıştırılır. Bu yaklaşım, sentetik veri üretimi için vLLM kullanıyorsanız faydalı olabilir.

Birçok çıkarım çerçevesi optimize edilmiş docker görüntüleri sağlar. uv, Python ekosisteminde giderek daha fazla benimsendiği için, bu görüntülerin daha fazlasında da uv önceden yüklü olacak ve bu da hf jobs uv run kullanıldığında çalışacakları anlamına geliyor.

Zamanlanmış İşler

HF altyapısında çalışacak işleri planlayın ve yönetin.

@annually, @yearly, @monthly, @weekly, @daily, @hourly zamanlaması veya bir CRON zamanlama ifadesi (ör. her Pazartesi saat 9:00 için "0 9 * * 1") ile create_scheduled_job() veya create_scheduled_uv_job() kullanın:

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

Ortam değişkenleri, gizli bilgiler, zaman aşımı vb. iletmek için run_job() ve run_uv_job() ile aynı parametreleri kullanın.

list_scheduled_jobs(), inspect_scheduled_job(), suspend_scheduled_job(), resume_scheduled_job(), update_scheduled_job_schedule(), trigger_scheduled_job() ve delete_scheduled_job() işlevlerini kullanarak zamanlanmış işleri yönetin:

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

Webhook'larla İşleri Tetikleyin

Webhooks, belirli depolardaki yeni değişiklikleri dinlemenize veya belirli bir kullanıcı/organizasyon grubuna ait tüm depolardaki değişiklikleri dinlemenize olanak tanır (yalnızca kendi depolarınız değil, herhangi bir depo).

Bir Hugging Face deposunda değişiklik olduğunda bir Job'u tetikleyen bir webhook oluşturmak için create_webhook() kullanın:

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, ortam değişkeni WEBHOOK_PAYLOAD içindeki webhook yüküyle Job'u tetikler. Webhooklar hakkında daha fazla bilgiyi Webhooks belgelerinde bulabilirsiniz.