Hub documentation

Gerenciar Jobs

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Gerenciar Jobs

Listar Jobs

Encontre sua lista de Jobs na página Jobs ou na página Jobs da sua organização (página do usuário/organização > configurações > Jobs):

Também está disponível no Hugging Face CLI. Exiba a lista de Jobs em execução com hf jobs ps e use -a para exibir todos os Jobs:

>>> hf jobs ps
JOB ID       IMAGE/SPACE      COMMAND     CREATED             STATUS  
------------ ---------------- ----------- ------------------- ------- 
69402ea6c... ghcr.io/astra... uv run p... 2025-12-15 15:52:06 RUNNING
>>> hf jobs ps -a
JOB ID       IMAGE/SPACE COMMAND         CREATED             STATUS    
------------ ---------- --------------- ------------------- --------- 
69402ea6c... ghcr.io... uv run pytho... 2025-12-15 15:52:06 RUNNING   
693b06b8c... ghcr.io... uv run pytho... 2025-12-11 18:00:24 CANCELED  
693b069fc... ghcr.io... uv run pytho... 2025-12-11 17:59:59 ERROR     
693aef401... ghcr.io... uv run pytho... 2025-12-11 16:20:16 COMPLETED 
693aee76c... ubuntu     echo Hello f... 2025-12-11 16:16:54 COMPLETED 
693ae8e3c... python:... python -c pr... 2025-12-11 15:53:07 COMPLETED

Especifique o namespace da sua organização para listar Jobs sob sua organização:

>>> hf jobs ps --namespace <my-org-name>

Filtrar Vagas

Os rótulos mais usados são exibidos acima da lista de Jobs, com o número de Jobs que utilizam cada um; clique em um para filtrar por ele ou digite qualquer rótulo key=value:

Na CLI, filtre por status com --status e por rótulo com --label key=value. Repita --label para exigir vários rótulos ao mesmo tempo:

# Jobs that ended in error
>>> hf jobs ps --status error

# Running or scheduling Jobs with a given label
>>> hf jobs ps --status running,scheduling --label env=prod

# All Jobs (any status) that have both labels
>>> hf jobs ps -a --label model=Qwen3-06B --label dataset=Capybara

# A label added without a value (`--label fine-tuning`) is matched with a trailing "="
>>> hf jobs ps -a --label fine-tuning=

Filtre pelo nome com --name, um atalho para --label name=<name>, por exemplo, para listar todas as execuções de um Job nomeado:

>>> hf jobs ps -a --name daily-report
JOB_ID      NAME         IMAGE/SPACE COMMAND      CREATED      STATUS    RUNTIME
----------- ------------ ----------- ------------ ------------ --------- -------
6a9042c2... daily-report python:3.12 python -c... 2026-08-2... COMPLETED 0s     
6a904162... daily-report python:3.12 python -c... 2026-08-2... CANCELED  --

Por padrão, hf jobs ps exibe Jobs em execução e em agendamento. Use -a para exibir todos os status; -a não pode ser combinado com --status.

Monitorar o uso de recursos

Use hf jobs stats para obter um instantâneo do uso de CPU, memória, rede e GPU (se houver) dos Jobs em execução:

>>> hf jobs stats
JOB ID                   CPU % NUM CPU MEM % MEM USAGE        NET I/O         GPU UTIL % GPU MEM % GPU MEM USAGE   
------------------------ ----- ------- ----- ---------------- --------------- ---------- --------- --------------- 
695e83c5d2f3efac77e8cf18 8%    12.0    7.18% 10.9GB / 152.5GB 0.0bps / 0.0bps 100%       31.92%    25.9GB / 81.2GB

Especifique um ou vários ids de Job para exibir apenas as estatísticas de determinados Jobs:

>>> hf jobs stats [job-ids]...

Use -f para acompanhar as estatísticas em tempo real até que os Jobs sejam concluídos:

>>> hf jobs stats -f [job-ids]...

Inspecionar um Job

Você pode ver os logs de status de um Job na página do Job:

Alternativamente, usando a CLI

>>> hf jobs inspect 693994e21a39f67af5a41ad0 
[
    {
        "id": "693994e21a39f67af5a41ad0",
        "created_at": "2025-12-10 15:42:26.835000+00:00",
        "docker_image": "ghcr.io/astral-sh/uv:python3.12-bookworm",
        "space_id": null,
        "command": ["bash", "-c", "python -c \"import urllib.request; import os; from pathlib import Path; o = urllib.request.build_opener(); o.addheaders = [(\\\"Authorization\\\", \\\"Bearer \\\" + os.environ[\\\"UV_SCRIPT_HF_TOKEN\\\"])]; Path(\\\"/tmp/script.py\\\").write_bytes(o.open(os.environ[\\\"UV_SCRIPT_URL\\\"]).read())\" && uv run --with trl /tmp/script.py"],
        "arguments": [],
        "environment": {"UV_SCRIPT_URL": "https://huggingface.co/datasets/lhoestq/hf-cli-jobs-uv-run-scripts/resolve/728cc5682eb402d7ffe66a2f6f97645b34cb08dd/train.py"},
        "secrets": ["HF_TOKEN", "UV_SCRIPT_HF_TOKEN"],
        "flavor": "a100-large",
        "status": {"stage": "COMPLETED", "message": null},
        "owner": {"id": "5e9ecfc04957053f60648a3e", "name": "lhoestq", "type": "user"},
        "endpoint": "https://huggingface.co",
        "url": "https://huggingface.co/jobs/lhoestq/693994e21a39f67af5a41ad0"
    }
]

e para os logs

>>> hf jobs logs 693994e21a39f67af5a41ad0
Downloading nvidia-cuda-nvrtc-cu12 (84.0MiB)
Downloading numpy (15.8MiB)
Downloading nvidia-cuda-cupti-cu12 (9.8MiB)
Downloading tokenizers (3.1MiB)
Downloading nvidia-cusolver-cu12 (255.1MiB)
Downloading nvidia-cufft-cu12 (184.2MiB)
Downloading transformers (11.4MiB)
Downloading setuptools (1.1MiB)
...

Especifique o namespace da sua organização para inspecionar um Job sob sua organização:

hf jobs inspect --namespace <my-org-name> <job_id>
hf jobs logs --namespace <my-org-name> <job_id>

Aguarde a conclusão dos Jobs

Use hf jobs wait para bloquear até que um ou mais Jobs atinjam um estado terminal (COMPLETED, CANCELED, ERROR ou DELETED). Ele sai com o código 0 apenas se todos os Jobs tiverem concluído com sucesso, e com um código diferente de zero caso contrário — útil para encadear etapas em scripts de shell ou CI:

# Wait for a single Job
>>> hf jobs wait 693994e21a39f67af5a41ad0

# Wait for several Jobs at once (all must be in the same namespace)
>>> hf jobs wait <job_id_1> <job_id_2>

# Wait for every currently running Job
>>> hf jobs ps -q | xargs hf jobs wait

Defina um tempo máximo de espera com --timeout (aceita s, m, h ou d):

>>> hf jobs wait --timeout 30m 693994e21a39f67af5a41ad0

Como hf jobs wait retorna um código de saída não nulo quando um Job falha, você pode encadeá-lo com &&. Um hf jobs run não destacado (ou hf jobs uv run) já bloqueia e sai com código não nulo em caso de falha, portanto, um wait explícito é necessário apenas para Jobs destacados (-d) ou ao aguardar um lote:

>>> hf jobs wait 693994e21a39f67af5a41ad0 && echo "job completed successfully"

Persista seus resultados

O sistema de arquivos de um Job é excluído quando o Job termina. Escreva tudo o que deseja manter em um local durável antes que o Job saia:

Artefatos intermediários, checkpoints e logs → um volume de Storage Bucket. Monte um bucket e escreva as saídas sob o caminho de montagem — veja Volumes para exemplos. As montagens de volume são autorizadas com sua identidade do Hugging Face quando o Job é criado, então seu script não precisa de um token para gravar neles.
Modelos e conjuntos de dados finais → enviar para um repositório no Hub. Os Jobs não possuem um token do Hugging Face, a menos que você forneça um, por exemplo, --secrets HF_TOKEN (a forma simples resolve automaticamente para o token da sua sessão atual). Se o seu script chamar push_to_hub() ou create_repo(), certifique-se de que o token tenha acesso de escrita (tokens de granularidade fina precisam das permissões de escrita e criação de repositório). Um modo de falha comum é um Job que completa horas de computação e, em seguida, apresenta um erro no upload final porque o token não pode escrever — a computação foi concluída, mas os resultados não foram salvos.
Imprima os resultados principais nos logs. Os logs do Job são retidos após o término do Job e podem ser obtidos a qualquer momento com hf jobs logs <job-id>. Imprimir as métricas finais no stdout as mantém recuperáveis mesmo se uma etapa de upload falhar.

Após a conclusão de um Job, verifique se as suas saídas foram realmente gravadas (por exemplo, com hf buckets list) — um status COMPLETED significa que o comando terminou com sucesso, e não que os arquivos foram persistidos no local esperado.

Depurar um Job

Se um Job tiver um erro, você pode vê-lo na página do Job

Veja a mensagem de status e os logs na página do Job para ver o que deu errado.

Você também pode verificar as últimas linhas dos logs para ver o que aconteceu antes de um Job falhar. Você pode ver isso na página do Job, ou usando o CLI:

>>> hf jobs logs 69405cf51a39f67af5a41f29 | tail -n 10     
 Downloaded nvidia-cudnn-cu12
 Downloaded torch
Installed 66 packages in 226ms
Generating train split: 100%|██████████| 15806/15806 [00:00<00:00, 73330.17 examples/s]
Generating test split: 100%|██████████| 200/200 [00:00<00:00, 45427.32 examples/s]
Traceback (most recent call last):
  File "/tmp/script.py", line 7, in <module>
    train_dataset=train_dataset,
                  ^^^^^^^^^^^^^
NameError: name 'train_dataset' is not defined. Did you mean: 'load_dataset'?

Depure um Job localmente usando sua configuração local de UV ou Docker:

hf jobs uv run ... -> uv run ...
hf jobs run ... -> docker run ...

A mensagem de status pode indicar “Job timeout”: isso significa que o Job não terminou a tempo antes do tempo limite (o padrão é 30min) e, portanto, foi interrompido. Nesse caso, você precisa especificar um tempo limite maior, usando --timeout na CLI, por exemplo

hf jobs uv run --timeout 3h ...

Executar novamente um Job

Use hf jobs rerun para iniciar um novo Job com a configuração salva de um Job existente, incluindo seus secrets e hardware flavor:

>>> hf jobs rerun <job_id>

O novo Job possui seu próprio ID. Em Python, use rerun_job.

Cancelar Jobs

Use o botão “Cancel” na página do Job para cancelar um Job:

ou na CLI:

hf jobs cancel 693b06b8c67c9f186cfe239e

Especifique o namespace da sua organização para cancelar um Job sob sua organização:

hf jobs cancel --namespace <my-org-name> <job_id>

Barra de menu do MacOS

Encontre sua lista de Jobs no cliente hfjobs-menubar do MacOS:

Obtenha informações sobre os Jobs e monitore os logs e as estatísticas de uso de recursos:

Update on GitHub

←Preços e Cobranças Configuração→