使用 Docker 镜像

每个 Job 都在 Docker 镜像中运行，该镜像提供了其软件环境，包括系统工具和已安装的库。使用 hf jobs run 时，您需要提供一个镜像和一条命令。使用 hf jobs uv run 时，uv 会为脚本准备 Python 环境，除非您指定了镜像，否则 Jobs 会选择默认镜像。

选择运行工作负载的方式

当您的 Python 脚本的依赖项可以通过 uv 安装时，请从 hf jobs uv run 开始，如 快速入门 中所示。当您需要额外的系统工具或希望使用预配置的软件环境时，请选择一个镜像。

默认镜像包含 Python 和 uv。有关当前默认镜像和可用选项，请参阅 UV Jobs 配置。

您可以使用来自 Docker Hub 等注册表的现有镜像，或者使用 Docker Space 构建并托管您自己的镜像。

使用现成的图像

使用 hf jobs run 并指定镜像以及在镜像内运行的命令。可以使用来自 Docker Hub 或其他注册表的任何公共镜像，包括特定标签。从一个较小的镜像开始：

hf jobs run ubuntu echo 'Hello from the cloud!'

Job 会拉取镜像、运行命令并退出。若要使用镜像中已提供的软件，请选择包含该软件的镜像。例如，使用 PyTorch 镜像在 GPU 上创建张量并将其值翻倍：

hf jobs run --flavor t4-small --timeout 5m \
    pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
    -- python -c 'import torch; x = torch.ones(3, device="cuda"); print(x * 2)'

该镜像提供了 PyTorch 及其 CUDA 软件栈。--flavor t4-small 用于选择 GPU，--timeout 5m 限制 Job 的运行时间，而 Python 命令则使用镜像中已安装的 PyTorch 包。其输出内容会显示在 Job 的日志中。

-- 用于将 Jobs 选项与命令及其参数分隔开。例如，位于该分隔符之后的 --help 会被传递给你的命令。请参阅 传递参数。

使用输入和输出文件运行你自己的脚本

通过 hf jobs run 运行的脚本必须在 Job 内部可用。您可以使用镜像中包含的脚本，或者 挂载本地目录。

例如，假设您有一个推理脚本，它使用 huggingface/trl 镜像中的 Transformers 和 PyTorch 包。您的本地 work 目录包含 inference.py 和 inputs.jsonl，并且该脚本接受 --input 和 --output 路径。在创建用于存放结果的 Storage Bucket 后，使用以下命令运行它：

hf jobs run --flavor t4-small --timeout 10m \
    -v ./work:/work \
    -v hf://buckets/YOUR_USERNAME/results:/output \
    huggingface/trl \
    -- python /work/inference.py --input /work/inputs.jsonl --output /output/results.jsonl

将 YOUR_USERNAME 替换为存储桶所有者的命名空间。CLI 会上传本地目录并将其挂载到 /work。您的脚本将从该位置读取输入，并将结果写入挂载在 /output 的存储桶中，这些结果在 Job 结束后仍可供访问。请根据您的脚本调整命令的参数、硬件和超时设置；有关其他输入和输出选项，请参阅 Volumes。

使用 uv 中的镜像

当您的脚本需要默认镜像之外的系统工具，同时希望保留 uv 的 Python 依赖工作流时，请使用 hf jobs uv run --image。所选镜像必须已安装 uv。

环境由三个部分组成：

• 镜像中的系统工具和库（例如 ffmpeg 或 CUDA 工具包）会根据镜像的配置供 Job 使用。
• 安装在镜像中的 Python 包 属于其现有的 Python 环境。
• 脚本依赖项。 使用 内联依赖项头 时，uv 会在隔离的环境中安装您的 Python 包。镜像中预装的包不会自动可用。

例如，vLLM 脚本可能需要一个包含 CUDA 工具链的镜像，同时使用 uv 来安装其自身声明的 Python 依赖项。系统工具链仍必须与 uv 安装的包保持兼容。

如果你想直接使用镜像中预装的 PyTorch、TRL 或 vLLM，请使用 hf jobs run。如果你还需要使用 uv 来安装额外的依赖项，请参阅 复用镜像中的包并使用 uv 添加依赖项。

使用 Docker Space 构建你自己的镜像

Docker Space 可以构建并托管包含工作负载所需工具（包括您自己的脚本）的镜像，并且无需注册表账户即可将镜像设为私有。例如，您可以在 Python 镜像中添加 FFmpeg，以准备用于处理音频或视频的环境。

创建一个 Docker Space，并在其仓库的根目录下添加此 Dockerfile：

FROM python:3.12-slim-bookworm

# Install FFmpeg for audio and video processing.
RUN apt-get update \
    && apt-get install -y --no-install-recommends ffmpeg \
    && rm -rf /var/lib/apt/lists/*

# Match the non-root user ID used by Docker Spaces.
RUN useradd --create-home --uid 1000 user
USER user

# Check that FFmpeg is available.
CMD ["ffmpeg", "-version"]

FROM 提供 Python 环境。该基础镜像不包含 FFmpeg，因此 RUN 在构建时安装它。useradd 创建一个具有主目录和 UID 1000 的用户，与 Docker Spaces 保持一致；USER 以该用户身份运行命令。CMD 设置默认命令，此处用于检查 FFmpeg 的安装情况。

提交该文件，并等待 Space 的构建日志显示镜像已推送。然后，在通常填写镜像名称的位置传入 Space URL，将 YOUR_USERNAME/video-tools 替换为您的 Space ID：

hf jobs run --flavor cpu-basic --timeout 5m \
    hf.co/spaces/YOUR_USERNAME/video-tools -- ffmpeg -version

该版本会显示在 Job 的日志中。在 Space URL 后提供不同的命令，即可使用 FFmpeg 或 Python 来处理您的工作负载。若要在镜像中包含您自己的脚本，请在 Dockerfile 中添加一行，例如 COPY --chown=user:user process.py /app/process.py，然后运行 python /app/process.py。有关挂载数据和保存结果，请参阅 输入和输出文件。

此示例会打印版本号并退出，因此 Space 在构建后会显示运行时错误。这没有问题：Jobs 只需要构建好的镜像，而不需要一个正在运行的 Space。

Space 的构建镜像不保证始终可拉取。它可能因注册表维护或区域迁移而丢失。如果 Job 报告未找到镜像，请通过 factory 重启 Space 以重新构建。Job 始终使用最新构建，因此新的 commit 也会替换该镜像。

示例图像

Registry 镜像由其发布者维护，并且可以固定到特定的标签。

使用 hf jobs run 来运行命令，并使用镜像中已安装的包。对于 hf jobs uv run，请检查镜像中是否已安装 uv，并遵循上述 环境指南。浏览 示例与教程 以查找可运行和适配的工作负载。

复用镜像中的软件包并使用 uv 添加依赖项

框架镜像提供了预装的软件包，这些软件包（如 PyTorch、vLLM 及其 CUDA 扩展）的构建过程可能耗时较长或较为复杂。您的脚本可能仍需要额外的 Python 软件包——例如，用于加载特定的数据格式或跟踪实验。

您可以在使用 uv 安装额外依赖项的同时，复用镜像中预装的软件栈。在脚本的 # /// script 依赖项头部中声明额外的包，然后将 uv 指向镜像中的解释器，并将其 site-packages 添加到导入路径中：

hf jobs uv run \
    --image vllm/vllm-openai \
    --flavor l4x4 \
    --python /usr/bin/python3 \
    -e PYTHONPATH=/usr/local/lib/python3.12/dist-packages \
    -s HF_TOKEN \
    generate-responses.py

• --python 使用镜像中的解释器创建 uv 环境，以匹配其编译扩展所使用的 Python 版本。它本身不会暴露镜像中的包。
• -e PYTHONPATH=... 使 import vllm 在该次运行中解析到镜像中预构建的版本。
• 将 # /// script 中的依赖项精简为镜像中缺失的部分。PYTHONPATH 的搜索优先级高于 uv 的环境，因此镜像会遮蔽头部中为同一包声明的任何内容——包括你固定的更新版本。你保留的依赖项仍可能通过传递依赖引入这些包；uv 不会使用 PYTHONPATH 来满足依赖解析。

由于不同图像的路径各不相同，因此请在 cpu-basic 上探测它们，而不是硬编码：

hf jobs run --flavor cpu-basic vllm/vllm-openai bash -c 'which python3; which uv; python3 -m pip show vllm | grep Location'

/usr/bin/python3                              # pass to --python
/usr/local/bin/uv                             # uv is present, so `uv run` works
Location: /usr/local/lib/python3.12/dist-packages   # pass to PYTHONPATH

将 vllm 替换为您正在复用的库。目录结构各不相同——vllm/vllm-openai 和 lmsysorg/sglang 使用上述系统 dist-packages，unsloth/unsloth 使用虚拟环境（/opt/venv/...），而 huggingface/trl 使用 conda（/opt/conda/lib/python3.11/site-packages，继承自 pytorch/pytorch）。

这选择的是用于导入的镜像构建，而非用于 uv 依赖解析器的构建。精简头部可以减少冗余安装，但并不能保证完全消除。跳过 PYTHONPATH 步骤的 uv run --system-site-packages 已在上游提出请求。

对于 huggingface/trl 镜像，对应的解释器和包路径为：

hf jobs uv run \
    --image huggingface/trl \
    --flavor a100-large \
    --python /opt/conda/bin/python3 \
    -e PYTHONPATH=/opt/conda/lib/python3.11/site-packages \
    -s HF_TOKEN \
    train.py

这些命令使用 generate-responses.py 和 train.py 作为您自己脚本的名称。

故障排除

使用框架镜像用于 GPU 库

某些 GPU 库需要额外的系统工具，例如 CUDA 编译器（nvcc）、NCCL 或 cuDNN。安装它们的 Python 包并不能保证镜像中包含所需的所有工具。例如，如果镜像中没有 CUDA 工具包，FlashInfer 的采样器在尝试编译内核时可能会失败：

RuntimeError: Could not find nvcc and default cuda_home='/usr/local/cuda' doesn't exist

通过传入包含所需 CUDA 工具的框架镜像，可以解决此工具包缺失错误：

hf jobs uv run --image vllm/vllm-openai --flavor l4x4 -s HF_TOKEN generate-responses.py

uv 仍然会单独解析并安装您的脚本依赖项。该镜像提供了系统工具，但并不保证解析出的 Python 包与其兼容。