# 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: ```bash >>> 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: ```bash >>> hf jobs ps --namespace ``` ## 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: ```bash # 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=`, por exemplo, para listar todas as execuções de um Job nomeado: ```bash >>> 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 -- ``` > [!TIP] > 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: ```bash >>> 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: ```bash >>> hf jobs stats [job-ids]... ``` Use `-f` para acompanhar as estatísticas em tempo real até que os Jobs sejam concluídos: ```bash >>> 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 ```bash >>> 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 ```bash >>> 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: ```bash hf jobs inspect --namespace hf jobs logs --namespace ``` ## 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: ```bash # 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 # 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`): ```bash >>> 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: ```bash >>> 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](./jobs-configuration#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 `. 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: ```bash >>> 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 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 ```bash 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: ```bash >>> hf jobs rerun ``` 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: ```bash hf jobs cancel 693b06b8c67c9f186cfe239e ``` Especifique o `namespace` da sua organização para cancelar um Job sob sua organização: ```bash hf jobs cancel --namespace ``` ## Barra de menu do MacOS Encontre sua lista de Jobs no cliente [`hfjobs-menubar`](https://github.com/drbh/hfjobs-menubar) do MacOS: Obtenha informações sobre os Jobs e monitore os logs e as estatísticas de uso de recursos: