Hub documentation
Gestionar trabajos
Gestionar trabajos
Listar trabajos
Encuentra tu lista de Jobs en la página de Jobs o en la página de Jobs de tu organización (página de usuario/organización > settings > Jobs):
También está disponible en la CLI de Hugging Face. Muestra la lista de Jobs en ejecución con hf jobs ps y usa -a para mostrar todos los 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 COMPLETEDEspecifique el namespace de su organización para listar los Jobs bajo su organización:
>>> hf jobs ps --namespace <my-org-name>Filtrar trabajos
Las etiquetas más utilizadas se muestran sobre la lista de Jobs con el número de Jobs que usan cada una; haz clic en una para filtrar por ella o escribe cualquier etiqueta key=value:
En la CLI, filtre por estado con --status y por etiqueta con --label key=value. Repita --label para exigir varias etiquetas a la vez:
# 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 por nombre con --name, un atajo para --label name=<name>, por ejemplo para listar todas las ejecuciones de un Job con nombre:
>>> 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 defecto,
hf jobs psmuestra los Jobs en ejecución y en programación. Use-apara mostrar todos los estados;-ano se puede combinar con--status.
Monitorear el uso de recursos
Use hf jobs stats para obtener una instantánea del uso de CPU, memoria, red y GPU (si la hay) de los Jobs en ejecución:
>>> 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.2GBEspecifique uno o varios ids de Job para mostrar solo las estadísticas de ciertos Jobs:
>>> hf jobs stats [job-ids]...Use -f para seguir las estadísticas en vivo hasta que los Jobs se completen:
>>> hf jobs stats -f [job-ids]...Inspeccionar un trabajo
Puedes ver los registros de estado de un Job en la página del Job:
Alternativamente, usando la 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"
}
]y para los registros
>>> 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 el namespace de su organización para inspeccionar un Job bajo su organización:
hf jobs inspect --namespace <my-org-name> <job_id>
hf jobs logs --namespace <my-org-name> <job_id>Esperar a que los trabajos terminen
Use hf jobs wait para bloquear hasta que uno o más Jobs alcancen un estado terminal (COMPLETED, CANCELED, ERROR o DELETED). Sale con código 0 solo si todos los Jobs se completaron con éxito, y con un código no cero en caso contrario, lo cual es útil para encadenar pasos en scripts de shell o 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 waitEstablezca un tiempo de espera máximo con --timeout (acepta s, m, h o d):
>>> hf jobs wait --timeout 30m 693994e21a39f67af5a41ad0Dado que hf jobs wait devuelve un código de salida no cero cuando un Job falla, puedes encadenarlo con &&. Un hf jobs run no desacoplado (o hf jobs uv run) ya bloquea y sale con un código no cero ante un fallo, por lo que solo se necesita una espera explícita para Jobs desacoplados (-d) o al esperar por un lote:
>>> hf jobs wait 693994e21a39f67af5a41ad0 && echo "job completed successfully"Persista sus resultados
El sistema de archivos de un Job se elimina cuando el Job termina. Escribe todo lo que quieras conservar en un lugar duradero antes de que el Job finalice:
Artefactos intermedios, puntos de control y registros → un volumen de Storage Bucket. Monta un bucket y escribe las salidas bajo la ruta de montaje; consulta Volumes para ver ejemplos. Los montajes de volumen se autorizan con tu identidad de Hugging Face al crear el Job, por lo que tu script no necesita un token para escribir en ellos.
Modelos y conjuntos de datos finales → subidos a un repositorio del Hub. Los trabajos no tienen un token de Hugging Face a menos que se pase uno, por ejemplo
--secrets HF_TOKEN(la forma simple resuelve automáticamente el token de la sesión iniciada). Si su script llama apush_to_hub()ocreate_repo(), asegúrese de que el token tenga acceso de escritura (los tokens de grano fino necesitan permisos de escritura y creación de repositorios). Un modo de fallo común es un trabajo que completa horas de cómputo y luego produce un error en la carga final porque el token no puede escribir: el cómputo está hecho, pero los resultados no se guardan.Imprime los resultados clave en los registros. Los registros del trabajo se conservan después de que el trabajo termina y se pueden recuperar en cualquier momento con
hf jobs logs <job-id>. Imprimir las métricas finales en stdout las mantiene recuperables incluso si un paso de carga falla.
Después de que un Job se complete, verifica que tus salidas se hayan guardado correctamente (por ejemplo, con hf buckets list): un estado COMPLETED significa que el comando terminó con éxito, no que los archivos se hayan persistido donde esperabas.
Depurar un trabajo
Si un Job tiene un error, puedes verlo en la página del Job
Mira el mensaje de estado y los registros en la página del trabajo para ver qué salió mal.
También puede consultar las últimas líneas de los registros para ver qué ocurrió antes de que un Job fallara. Puede ver eso en la página del Job o usando la 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'?Depura un trabajo localmente usando tu configuración local de UV o Docker:
hf jobs uv run ...->uv run ...hf jobs run ...->docker run ...
El mensaje de estado puede indicar “Job timeout”: significa que el Job no terminó a tiempo antes del tiempo de espera (el valor predeterminado es 30 min) y, por lo tanto, se detuvo.
En este caso, es necesario especificar un tiempo de espera mayor, usando --timeout en la CLI, por ejemplo:
hf jobs uv run --timeout 3h ...Volver a ejecutar un trabajo
Use hf jobs rerun para iniciar un nuevo Job con la configuración guardada de un Job existente, incluidos sus secrets y hardware flavor:
>>> hf jobs rerun <job_id>El nuevo Job tiene su propio ID. En Python, usa rerun_job.
Cancelar trabajos
Use el botón “Cancel” en la página del Job para cancelar un Job:
o en la CLI:
hf jobs cancel 693b06b8c67c9f186cfe239e
Especifique el namespace de su organización para cancelar un Job bajo su organización:
hf jobs cancel --namespace <my-org-name> <job_id>Barra de menús de MacOS
Encuentra tu lista de Jobs en el cliente de MacOS hfjobs-menubar:
Obtén información sobre los trabajos y monitorea los registros y las estadísticas de uso de recursos:
