熱門映像檔

以下列出可直接使用、來自熱門框架的 Docker 映像檔，您可以在 Jobs 中搭配 uv 使用。

這些 Docker 映像檔皆已預裝 uv；但如果您想在未預裝 uv 的映像檔中使用 uv，則需要確保先安裝 uv。這在許多情況下都能順利運作，但對於需求較特殊的 LLM 推論函式庫而言，使用已安裝該函式庫的特定映像檔會更有幫助。

對於 GPU 推論函式庫，請傳入 --image，以便讓執行環境獲得相容的 CUDA 系統堆疊（工具組、nvcc、函式庫等）——請參閱下方的將框架映像檔用於 GPU 函式庫。

vLLM

vLLM 是一個非常知名且廣泛使用的推論引擎，以其擴展 LLM 推論的能力而聞名。他們提供的 vllm/vllm-openai Docker 映像檔已預裝 vLLM 與 UV，非常適合執行批次推論。

使用 --image 引數來指定此 Docker 映像檔：

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

vllm/vllm-openai 映像檔內含 CUDA 工具組以及預先建置的 vLLM/FlashInfer 核心（kernels）。通常只需使用它即可；您也可以重複利用其預先建置的 Python 版本——請參閱下方的將框架映像檔用於 GPU 函式庫。

您可以從 Daniel Van Strien 的部落格文章找到更多關於在 Jobs 上執行 vLLM 批次推論的資訊。

TRL

TRL 是一個專為模型後訓練所設計的函式庫，運用如監督式微調 (SFT)、群體相對策略優化 (GRPO) 與直接偏好優化 (DPO) 等技術。一個包含 UV 與所有 TRL 相依套件的最新版 Docker 映像檔位於 huggingface/trl，可直接與 Hugging Face Jobs 一起使用。

使用 --image 引數來指定此 Docker 映像檔：

>>> hf jobs uv run --image huggingface/trl --flavor a100-large -s HF_TOKEN train.py

將框架映像檔用於 GPU 函式庫

像 vLLM 這樣的 GPU 函式庫所需的遠不止其 Python 套件本身，它們需要相容的系統環境：CUDA 工具組（包含 nvcc）、如 NCCL 與 cuDNN 等系統函式庫。如果您省略了 --image，hf jobs uv run 將會使用預設的 uv 映像檔 (ghcr.io/astral-sh/uv:python3.12-bookworm)，這是一個不含 CUDA 工具組的基礎 Python 環境。您的相依套件仍會從 PyPI 安裝，但在執行階段時，需要該工具組的函式庫可能會失敗——例如 FlashInfer 的採樣器在進行 JIT 編譯核心時會中止並顯示錯誤。

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

傳入框架映像檔即可解決此問題——它提供了 CUDA 工具組、nvcc 以及相容的函式庫——這通常就是您所需要的全部。

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

UV 仍會從 PyPI 重新安裝您的指令碼相依套件，但它們現在將針對該映像檔的系統堆疊執行，因此框架便能順利運作。

選擇性：重複利用映像檔預先建置的 Python 版本

這些映像檔同時也隨附了框架本身預先建置、與 CUDA 相容的版本。若要匯入這些版本而非透過 UV 從 PyPI 重新安裝（當 PyPI 建置版本與映像檔的 CUDA 堆疊不一致，例如 ABI 不相容或核心無法編譯時非常有用），請將 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 使用映像檔內建的直譯器，以保持與其編譯擴充功能的 ABI 相容性。
• -e PYTHONPATH=... 使得在該次執行中，import vllm 會解析為映像檔中預先建置的版本。

路徑會隨映像檔而異，因此建議在 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/...)。

這會將匯入鎖定為映像檔的建置版本；由於 UV 仍會安裝您宣告的相依套件，因此這並不會加速安裝過程。目前已有上游需求，希望新增 uv run --system-site-packages 來重複利用映像檔中的套件並跳過重新安裝。