Hub documentation
管理任务
管理任务
列出任务
在 Jobs 页面或您的组织 Jobs 页面（用户/组织页面 > 设置 > Jobs）中查找您的 Jobs 列表：
它也可以在 Hugging Face CLI 中使用。使用 hf jobs ps 显示正在运行的 Jobs 列表，并使用 -a 显示所有 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指定您的组织 namespace 以列出您组织下的 Jobs：
>>> hf jobs ps --namespace <my-org-name>筛选任务
最常用标签显示在任务列表上方，并附带使用各标签的任务数量；点击某个标签可按其筛选，或输入任意 key=value 标签：
在 CLI 中，使用 --status 按状态筛选，使用 --label key=value 按标签筛选。重复使用 --label 可同时要求多个标签：
# 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=使用 --name 按名称筛选，它是 --label name=<name> 的快捷方式，例如列出某个命名 Job 的所有运行：
>>> 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 -- 默认情况下，
hf jobs ps显示正在运行和正在调度的 Job。使用-a可显示所有状态；-a不能与--status一起使用。
监控资源使用情况
使用 hf jobs stats 获取正在运行的 Jobs 的 CPU、内存、网络和 GPU（如有）使用情况快照：
>>> 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指定一个或多个 Job id，以仅显示特定 Job 的统计信息：
>>> hf jobs stats [job-ids]...使用 -f 实时跟踪统计信息，直到任务完成：
>>> hf jobs stats -f [job-ids]...检查任务
您可以在 Job 页面中查看 Job 的状态日志：
或者使用 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"
}
]以及日志
>>> 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)
... 指定您的组织 namespace 以查看您组织下的 Job：
hf jobs inspect --namespace <my-org-name> <job_id>
hf jobs logs --namespace <my-org-name> <job_id>等待任务完成
使用 hf jobs wait 可阻塞等待，直到一个或多个 Job 达到终止状态（COMPLETED、CANCELED、ERROR 或 DELETED）。仅当所有 Job 均成功完成时，该命令才会以退出码 0 结束，否则返回非零退出码——这便于在 Shell 脚本或 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使用 --timeout 设置最大等待时间（接受 s、m、h 或 d）：
>>> hf jobs wait --timeout 30m 693994e21a39f67af5a41ad0由于 hf jobs wait 在 Job 失败时会返回非零退出码，因此可以使用 && 将其与其他命令串联。非分离模式的 hf jobs run（或 hf jobs uv run）本身就会阻塞并在失败时返回非零退出码，因此只有在处理分离模式（-d）的 Job 或等待一批 Job 时，才需要显式调用 wait：
>>> hf jobs wait 693994e21a39f67af5a41ad0 && echo "job completed successfully"持久化您的结果
Job 结束时，其文件系统会被删除。在 Job 退出之前，请将任何需要保留的内容写入持久化存储：
中间产物、检查点和日志 → 存储桶卷。挂载存储桶并在挂载路径下写入输出——示例请参见 卷。创建作业时，卷挂载会通过你的 Hugging Face 身份进行授权，因此你的脚本无需令牌即可向其写入数据。
最终模型和数据集 → 推送到 Hub 仓库。 除非你传入令牌，否则任务没有 Hugging Face 令牌，例如
--secrets HF_TOKEN（裸形式会自动解析为你已登录的令牌）。如果你的脚本调用了push_to_hub()或create_repo()，请确保令牌具有写入权限（细粒度令牌需要仓库写入和创建权限）。一种常见的失败模式是：任务完成了数小时的计算，却在最终上传时因令牌无法写入而报错——计算已完成，但结果未保存。将关键结果打印到日志中。作业结束后，作业日志会被保留，并可以随时通过
hf jobs logs <job-id>获取。将最终指标打印到标准输出（stdout）可确保即使上传步骤失败，这些指标仍可恢复。
Job 完成后，请确认输出文件确实已写入（例如使用 hf buckets list）—— COMPLETED 状态仅表示命令成功退出，并不意味着文件已持久化到您预期的位置。
调试作业
如果某个 Job 出现错误，您可以在 Job 页面上查看
查看 Job 页面上的状态消息和日志，以了解出了什么问题。
您也可以查看日志的最后几行，以了解作业失败前发生了什么。您可以在作业页面中查看，或使用 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'?使用本地 UV 或 Docker 环境在本地调试作业：
hf jobs uv run ...->uv run ...hf jobs run ...->docker run ...
状态消息可能显示为“Job timeout”：这意味着 Job 未能在超时（默认为 30 分钟）前完成，因此被停止。
在这种情况下，你需要使用 CLI 中的 --timeout 来指定更长的超时时间，例如
hf jobs uv run --timeout 3h ...重新运行任务
使用 hf jobs rerun 可以基于现有 Job 的已保存配置（包括其 secrets 和硬件 flavor）启动一个新的 Job：
>>> hf jobs rerun <job_id>新的 Job 拥有自己的 ID。在 Python 中，请使用 rerun_job。
取消任务
使用 Job 页面上的“Cancel”按钮来取消 Job：
或在 CLI 中：
hf jobs cancel 693b06b8c67c9f186cfe239e
指定您的组织 namespace 以取消您组织下的 Job：
hf jobs cancel --namespace <my-org-name> <job_id>MacOS 菜单栏
在 MacOS 的 hfjobs-menubar 客户端中查看您的 Jobs 列表：
获取任务信息，并监控日志和资源使用统计：
