Executar e gerenciar Jobs

O Hugging Face Hub fornece computação para fluxos de trabalho de IA e dados por meio de Jobs.

Para uma visão geral de Jobs e preços, consulte a documentação de Jobs do Hub.

Um job é executado na infraestrutura do Hugging Face e é definido por um comando a ser executado (por exemplo, um comando python), uma Imagem Docker do Hugging Face Spaces ou do Docker Hub, e um tipo de hardware (CPU, GPU, TPU). Este guia mostrará como interagir com Jobs no Hub, especialmente:

• Execute um job.
• Verifique o status do trabalho.
• Selecione o hardware.
• Configure variáveis de ambiente e segredos.
• Execute scripts do UV.

Se você deseja executar e gerenciar um job no Hub, sua máquina deve estar conectada. Caso contrário, consulte esta seção. No restante deste guia, assumiremos que sua máquina está conectada.

Os Hugging Face Jobs estão disponíveis para qualquer usuário ou organização com um saldo de crédito positivo. Consulte Preços e faturamento dos Jobs para mais detalhes.

Interface de Linha de Comando de Jobs

Use o hf jobs CLI para executar Jobs pela linha de comando e passe --flavor para especificar seu hardware.

hf jobs run executa Jobs com uma imagem Docker e um comando com uma interface semelhante à do Docker. Pense em docker run, mas para executar código em qualquer hardware:

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

Use hf jobs uv run para executar scripts UV locais ou remotos:

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

Os scripts UV são scripts Python que incluem suas dependências diretamente no arquivo, usando uma sintaxe de comentário especial definida na documentação do UV.

Agora, o restante deste guia mostrará a API em Python. Se você preferir ver todos os comandos e opções disponíveis de hf jobs, confira o guia sobre a interface de linha de comando do hf jobs.

Precisa de uma máquina interativa em vez de um job de execução única — por exemplo, para executar código gerado por IA, com execução de comandos e transferência de arquivos? Confira os Sandboxes, construídos sobre os Jobs.

Executar um Job

Execute Jobs de computação definidos com um comando e uma Imagem Docker na infraestrutura do Hugging Face (incluindo GPUs e TPUs).

Você só pode gerenciar Jobs que você possui (no namespace do seu nome de usuário) ou de organizações nas quais você tem permissões de escrita. Este recurso é pago conforme o uso: você só paga pelos segundos que utiliza.

run_job() permite executar qualquer comando na infraestrutura do 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")

Importante: Os jobs possuem um tempo limite padrão (30 minutos), após o qual são interrompidos automaticamente. Para tarefas de longa duração, como o treinamento de modelos, certifique-se de definir um tempo limite personalizado usando o parâmetro timeout. Consulte Configurar o tempo limite do job para mais detalhes.

run_job() retorna o JobInfo, que contém a URL do Job no Hugging Face, onde você pode ver o status do Job e os logs. Salve o ID do Job do JobInfo para gerenciar o 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

Os jobs são executados em segundo plano. A próxima seção orienta você a usar inspect_job() para conhecer o status de um job, fetch_job_logs() para visualizar os logs e fetch_job_metrics() para monitorar o uso de recursos.

Tentar novamente e reexecutar um Job

Use attempts para tentar novamente um Job que falhou. O número inclui a tentativa inicial, portanto attempts=3 permite até duas novas tentativas. Também funciona com run_uv_job, create_scheduled_job e 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 inicia um Job separado com um novo ID. Funciona para Jobs concluídos ou com falha e reutiliza a especificação salva, incluindo segredos e configurações de hardware. Você também pode executar hf jobs rerun <job_id>.

Verificar o status do 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)

Aguarde até que os Jobs terminem

Use wait_for_job() para bloquear até que um Job atinja um estágio terminal (COMPLETED, CANCELED, ERROR ou DELETED). O JobInfo final é sempre retornado — um Job com falha não lança uma exceção —, portanto, verifique job.status.stage para agir com base no resultado. Passe uma lista de IDs de Job para aguardar um lote inteiro de uma vez.

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

O mesmo está disponível na CLI com hf jobs wait, que encerra com código 0 apenas se todos os Jobs tiverem concluído com sucesso — útil para encadear comandos em scripts de shell ou 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

Observe que um hf jobs run não destacado (ou hf jobs uv run) também encerra com um código não nulo se o Job falhar, de modo que hf jobs run ... && next-step encadeia corretamente sem uma espera explícita.

Selecione o hardware

Existem inúmeros casos em que a execução de Jobs em GPUs é útil:

• Treinamento de modelos: ajuste fino ou treine modelos em GPUs (T4, A10G, A100) sem gerenciar a infraestrutura
• Geração de dados sintéticos: Geração de conjuntos de dados em larga escala usando LLMs em hardware de alto desempenho
• Processamento de dados: Processe conjuntos de dados massivos com configurações de CPU de alto desempenho para cargas de trabalho paralelas
• Inferência em lote: Execute inferência offline em milhares de amostras usando configurações de GPU otimizadas
• Experimentos e Benchmarks: Execute experimentos de ML em hardware consistente para resultados reproduzíveis
• Desenvolvimento e depuração: Teste código de GPU sem configuração local de CUDA

Execute jobs em GPUs ou TPUs com o argumento flavor. Por exemplo, para executar um job do PyTorch em uma 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",
... )

Ao executar isso, a seguinte saída será exibida!

This code ran with the following GPU: NVIDIA A10G

Use isso para executar um script de fine-tuning como trl/scripts/sft.py com 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",
... )

Para orientações completas sobre a execução de trabalhos de treinamento de modelos com TRL na infraestrutura do Hugging Face, consulte a documentação de Treinamento de Jobs do TRL. Ela aborda receitas de fine-tuning, seleção de hardware e melhores práticas para treinar modelos de forma eficiente.

Aqui está a lista completa de hardware disponível para executar Jobs:

Você pode obter essa lista programaticamente executando:

>>> hf jobs hardware

Ou usando a API do Python:

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

É isso! Agora você está executando código na infraestrutura da Hugging Face.

Montar um volume

Monte um volume no disco dos Jobs usando uma lista de Volume.

Você pode montar qualquer Repositório do Hugging Face (modelo/conjunto de dados/espaço) ou Storage Bucket. Por exemplo:

• montar um repositório de modelo: Volume(type="model", source="openai/gpt-oss-120b", mount_path="/model")
• montar um repositório de dataset: Volume(type="dataset", source="HuggingFaceFW/fineweb", mount_path="/data")
• montar um bucket de armazenamento: Volume(type="bucket", source="username/my-bucket", mount_path="/mnt")

Em seguida, você pode usar o volume montado como um diretório local:

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

Você também pode gravar em um bucket montado, por exemplo, para salvar checkpoints ao treinar um modelo:

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

Por padrão, os buckets de armazenamento montados possuem permissões de leitura e gravação. Isso é especialmente útil para buckets de armazenamento, que fornecem armazenamento mutável e rápido para dados que mudam com frequência — os arquivos podem ser sobrescritos ou excluídos no local.

Use read_only=True para habilitar somente leitura: Volume(type="bucket", read_only=True, ...).

Montar dados locais

Para executar um Job com dados na sua máquina, use sync_job_volume(): ele sincroniza um diretório local com o seu Storage Bucket jobs-artifacts (criado automaticamente, se necessário) e retorna um Volume pronto para ser montado:

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

Cada diretório recebe sua própria pasta estável no bucket: reexecutar sync_job_volume() no mesmo diretório apenas faz o upload de novos arquivos ou arquivos modificados. O volume é montado somente para leitura por padrão.

Para recuperar os arquivos gravados por um Job, monte um volume de leitura e gravação (um diretório de saída vazio também funciona) e sincronize-o de volta quando o Job terminar:

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

Na CLI, basta passar um diretório local como o lado de origem de -v:

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

Expor as portas do Job

Pass expose para tornar uma porta de container acessível através do proxy de Jobs. O acesso requer um token HF com permissão de leitura no namespace do Job. Use expose_public em vez disso para permitir acesso sem autenticação:

>>> 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 e expose_public podem ser combinados. update_job_expose substitui a configuração completa de portas em um Job em execução sem reiniciá-lo: portas que não estão em nenhuma das listas são fechadas. Ambas as opções também estão disponíveis ao criar Jobs UV e agendados.

Conectar via SSH a um Job

Pass ssh=True para run_job() (ou run_uv_job()) para tornar o container do Job acessível via SSH. O endpoint SSH está disponível no status do 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'

Conecte-se de um terminal com hf jobs ssh <job_id> (ou diretamente com ssh <job_id>@ssh.hf.jobs):

>>> hf jobs ssh 68498e23210b3a4f4e6e2a23

Apenas usuários com acesso de escrita ao namespace do Job (o criador do Job ou membros da organização proprietária) são permitidos, autenticados por uma chave pública SSH registrada em https://huggingface.co/settings/keys.

Grupos de rede

Pass network_group="<name>" para run_job() (ou run_uv_job()) para permitir que Jobs no mesmo namespace e grupo de recursos se comuniquem entre si em todas as portas. Dentro de cada membro, HF_NETWORK_GROUP_HOSTNAME resolve para todos os Jobs do grupo, e ${HF_NETWORK_GROUP_PREFIX}<alias> para os membros que reivindicaram um alias com 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'])

Os membros são resolúveis antes de ficarem prontos, portanto, conecte-se com novas tentativas. Os nomes e os aliases de grupo são alfanuméricos em minúsculas e hífens, com no máximo 46 e 34 caracteres, respectivamente.

Configurar tempo limite do Job

Os jobs possuem um tempo limite padrão (30 minutos), após o qual eles param automaticamente. É importante saber disso ao executar tarefas de longa duração, como o treinamento de modelos.

Definindo um tempo limite personalizado

Você pode especificar um valor de timeout personalizado usando o parâmetro timeout ao executar um job. O timeout pode ser especificado de duas maneiras:

1. Como um número (interpretado como segundos):

>>> 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. Como uma string com unidades de tempo:

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

Unidades de tempo suportadas:

• s - segundos
• m - minutos
• h - horas
• d - dias

Usando timeout com jobs do UV

Para trabalhos de UV, você também pode especificar o tempo limite:

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

Se você não especificar um tempo limite, um tempo limite padrão será aplicado ao seu job. Para tarefas de longa duração, como o treinamento de modelos que podem levar horas, certifique-se de definir um tempo limite adequado para evitar encerramentos inesperados do job.

Monitorando a duração do trabalho

Ao executar tarefas longas, é uma boa prática:

• Estime a duração esperada do seu trabalho e defina um tempo limite com alguma folga
• Monitore o progresso do seu trabalho por meio dos logs
• Verifique o status do trabalho para garantir que ele não expirou

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

Para mais detalhes sobre o parâmetro de timeout, consulte a referência da API run_job.

Passar variáveis de ambiente e segredos

Você pode passar variáveis de ambiente para seu trabalho usando env e 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"},
... )

Variáveis de Ambiente Integradas

Dentro do contêiner do job, as seguintes variáveis de ambiente estão automaticamente disponíveis:

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

Essas variáveis são úteis quando você precisa criar identificadores únicos para as saídas, adaptar seu código com base no hardware disponível ou registrar informações de recursos.

Rótulos

Labels são pares chave=valor que anexam metadados a um Job:

Use name para facilitar a localização e a identificação de Jobs na interface. Os nomes são opcionais e não precisam ser únicos:

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

A partir da CLI, passe --name ao criar um Job ou nomeie um Job existente por meio do comando labels:

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

hf jobs ls exibe uma coluna NAME e pode filtrar por nome (um atalho para --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"},
... )

Se você não passar um nome, ele é derivado automaticamente da imagem Docker ou do script, mais um hash curto (por exemplo, python:3.12 foo --truc → python-3-12-1a2b3c4d). A partir da CLI, esse hash cobre o comando e as configurações de runtime resolvidas (flavor, timeout, valores de ambiente, …), de modo que a mesma configuração sempre produz o mesmo nome, e alterar uma configuração — incluindo uma que venha do cabeçalho [tool.hf-jobs] de um script — altera o nome. A partir da API Python, o hash cobre apenas o comando.

Atualizar rótulos

Use update_job_labels() para substituir os rótulos de um trabalho existente. Isso substitui todos os rótulos fornecidos pelo usuário:

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

Isso também funciona para agendamentos com 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"})

A partir da CLI:

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

Para remover todos os rótulos, passe --clear:

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

UV Scripts (Experimental)

Procurando scripts UV prontos para uso? Confira a organização uv-scripts no Hugging Face Hub, que oferece uma coleção da comunidade de scripts UV para tarefas como treinamento de modelos, geração de dados sintéticos, processamento de dados e muito mais.

Execute scripts UV (scripts Python com dependências inline) na infraestrutura do 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"])

Os scripts UV são scripts Python que incluem suas dependências diretamente no arquivo usando uma sintaxe de comentário especial. Isso os torna perfeitos para tarefas autossuficientes que não exigem configurações complexas de projeto. Saiba mais sobre scripts UV na documentação do UV.

Envie a configuração de lançamento com o script

Um script que só é executado corretamente em um runtime específico pode carregar esse runtime com ele, em uma tabela opcional [tool.hf-jobs] no cabeçalho PEP 723:

# /// 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 em seguida inicia com a imagem, o hardware e o interpretador corretos, e --flavor, -e, … ainda substituem o que o script declara. Consulte o guia da CLI para a lista completa de chaves e as regras de mesclagem.

A tabela é lida apenas pelo CLI hf: run_uv_job() e create_scheduled_uv_job() a ignoram e usam exatamente os argumentos que recebem. Em outras palavras, run_uv_job("ocr.py") e hf jobs uv run ocr.py não executam o mesmo Job — a API em Python precisa que image=, flavor=, … sejam passados explicitamente.

Imagens Docker para Scripts UV

Embora os scripts do UV possam especificar suas dependências inline, as cargas de trabalho de ML frequentemente possuem dependências complexas. O uso de imagens Docker pré-criadas com essas bibliotecas já instaladas pode acelerar significativamente a inicialização do job e evitar problemas de dependências.

Por padrão, ao executar hf jobs uv run, a imagem astral-sh/uv:python3.12-bookworm é utilizada. Esta imagem é baseada na distribuição Python 3.12 Bookworm com o uv pré-instalado.

Você pode especificar uma imagem diferente usando a flag --image:

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

O comando acima será executado usando a imagem vllm/vllm-openai:latest. Essa abordagem pode ser útil se você estiver usando o vLLM para geração de dados sintéticos.

Muitos frameworks de inferência fornecem imagens docker otimizadas. Como o uv está sendo cada vez mais adotado no ecossistema Python, mais desses frameworks também terão o uv pré-instalado, o que significa que eles funcionarão ao usar hf jobs uv run.

Jobs agendados

Agende e gerencie jobs que serão executados na infraestrutura da HF.

Use create_scheduled_job() ou create_scheduled_uv_job() com um agendamento de @annually, @yearly, @monthly, @weekly, @daily, @hourly ou uma expressão de agendamento CRON (por exemplo, "0 9 * * 1" para 9h de toda segunda-feira):

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

Use os mesmos parâmetros de run_job() e run_uv_job() para passar variáveis de ambiente, segredos, timeout, etc.

Gerencie trabalhos agendados usando list_scheduled_jobs(), inspect_scheduled_job(), suspend_scheduled_job(), resume_scheduled_job(), update_scheduled_job_schedule(), trigger_scheduled_job() e 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)

Disparar Jobs com webhooks

Webhooks permitem que você monitore novas alterações em repositórios específicos ou em todos os repositórios pertencentes a um conjunto particular de usuários/organizações (não apenas seus repositórios, mas qualquer repositório).

Use create_webhook() para criar um webhook que aciona um Job quando uma alteração ocorre em um repositório do 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"
)

O webhook aciona o Job com o payload do webhook na variável de ambiente WEBHOOK_PAYLOAD. Você pode encontrar mais informações sobre webhooks na documentação de webhooks.