跳到正文
Hugging Face Blog·· 2026-06-26精選AI 評分68

用一條命令在 HF Jobs 上執行 vLLM 伺服器

Run a vLLM Server on HF Jobs in One Command

AI 導讀

Hugging Face Blog 示範用一條命令在 HF Jobs 上以 vLLM 啟動私有、OpenAI-compatible 的 LLM 端點。內容提供 curl 和 Python OpenAI client 呼叫範例,並示範以 SSH、Gradio 及 Pi 延伸使用;每次請求須附上具該 Job 讀取權限的 HF token。

推薦理由

文章把 HF Jobs、vLLM 與 OpenAI-compatible API 的部署、驗證和停止流程串成可複用命令,並説明私有端點的 token 權限與成本控制。

正文 · 繁體中文

只需一個指令,你就能在 Hugging Face 基礎設施上啟動私人、兼容 OpenAI 的 LLM 端點;毋須佈建伺服器,也毋須 Kubernetes,按秒計費。端點啟動後,可從手提電腦、筆記簿或其他地方查詢。

這是為測試、評估或批次生成快速啟動模型的方式。(如果你需要的是託管式、可用於生產環境的服務,請使用 Inference Endpoints;文章末段會比較何時選用哪種服務。)

以下是完整流程。

必要條件

  • 需要付款方式或正數預付餘額(Jobs 按硬件使用量以分鐘計費)。
  • huggingface_hub >= 1.20.0:pip install -U "huggingface_hub>=1.20.0"。
  • 已在本機登入:hf auth login。

啟動伺服器

hf jobs run 就是 Hugging Face 基礎設施上的 docker run。我們會使用官方 vllm/vllm-openai 映像檔,透過 --flavor 指定 GPU,並以 --expose 公開 vLLM 連接埠:

hf jobs run --flavor a10g-large --expose 8000 --timeout 2h \
  vllm/vllm-openai:latest \
  vllm serve Qwen/Qwen3-4B --host 0.0.0.0 --port 8000

--expose 8000 會透過 HF 的公開 Jobs Proxy 轉送容器連接埠(完整參考資料請參閲模型服務指南)。指令會輸出伺服器可存取的 URL:

✓ Job started
  id: 6a381ca1953ed90bfb947332
  url: https://huggingface.co/jobs/qgallouedec/6a381ca1953ed90bfb947332
Hint: Exposed ports are reachable at (requires an HF token with read access to the job):
  https://6a381ca1953ed90bfb947332--8000.hf.jobs

6a381ca1953ed90bfb947332 是你的 job ID,請保留;下文會以 <job_id> 作為佔位符。

等候幾分鐘,讓模型下載權重並啟動。日誌顯示 Application startup complete 時,伺服器便已就緒。

從任何地方查詢

vLLM 支援 OpenAI API,每個請求只須在 bearer token 中附上你的 HF token。最快的方法是使用 curl:

curl https://<job_id>--8000.hf.jobs/v1/chat/completions \
  -H "Authorization: Bearer $(hf auth token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-4B",
    "messages": [{"role": "user", "content": "Hello!"}],
    "chat_template_kwargs": {"enable_thinking": false}
  }'

它會傳回一般的 OpenAI 格式 JSON,當中 choices[0].message.content 欄位包含 "Hello! How can I assist you today? 😊"。

你亦可使用 Python,把 OpenAI 用戶端指向公開 URL,並將 token 作為 API key 傳入:

from huggingface_hub import get_token
from openai import OpenAI

client = OpenAI(
    base_url="https://<job_id>--8000.hf.jobs/v1",
    api_key=get_token(),
)
resp = client.chat.completions.create(
    model="Qwen/Qwen3-4B",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_body={"chat_template_kwargs": {"enable_thinking": False}},
)
print(resp.choices[0].message.content)
Hello! How can I assist you today? 😊

開始前可快速檢查健康狀態:curl https://<job_id>--8000.hf.jobs/v1/models -H "Authorization: Bearer $(hf auth token)" 應會列出模型。

🔐 此端點設有存取限制,並非公開。每個請求都必須附上對該 job 所屬 namespace 具備讀取權限的 HF token。直接在瀏覽器開啟會遭拒絕。換言之,Jobs Proxy 本身就是你的 API 存取閘道:存取權限僅限你本人及所屬機構。私人使用沒有問題,但請妥善處理 URL:不要把它分享給預期會公開存取的人,也不要把 token 貼到不可信的位置。如需更細緻或公開的存取控制,請在前方設置正式閘道。亦可參閲下文HF Jobs 還是 Inference Endpoints?。

停止服務

Jobs 按秒計費,因此用完後請停止伺服器:

hf jobs cancel <job_id>

你設定的 --timeout 是安全網(到期後會自動停止),但明確取消更省錢。a10g-large 的收費為每小時 $1.50;請使用 hf jobs hardware 查看完整價格清單,並選擇足以運行模型的最小規格。

進階用法:更大型模型

同一指令亦可擴展至大型模型:選擇更高規格的 --flavor,並使用 --tensor-parallel-size 指示 vLLM 將模型分片至多張 GPU。例如,在 2 張 H200 上執行 122B Qwen3.5 混合專家模型:

hf jobs run --flavor h200x2 --expose 8000 --timeout 2h \
  vllm/vllm-openai:latest \
  vllm serve Qwen/Qwen3.5-122B-A10B \
  --host 0.0.0.0 --port 8000 --tensor-parallel-size 2 \
  --max-model-len 32768 --max-num-seqs 256

--tensor-parallel-size 應與所選規格的 GPU 數量一致(h200x2 → 2,h200x8 → 8)。使用 hf jobs hardware 查看可選規格;大型模型下載和載入所需時間較長,請為它們設定更長的 --timeout。大型模型通常以 H200 規格最具性價比。

--max-model-len 32768 --max-num-seqs 256 這些旗標是針對此模型設定:Qwen3.5-122B 採用混合 Mamba/attention 架構,預設上下文長度為 256K token,不足以讓 vLLM 使用預設批次設定。限制上下文長度及並行序列數,可確保模型符合 GPU 記憶體容量。如模型因記憶體不足或快取區塊錯誤而無法啟動,首先可嘗試調低這兩項設定。其餘設定(公開 URL、OpenAI 用戶端和 token 驗證)完全相同。

進階用法:在介面中與模型對話

如果你偏好聊天視窗而非 curl,只需幾行 Gradio 程式碼即可連接相同端點。把 --reasoning-parser deepseek_r1 加入 vllm serve 指令中,便可把 Qwen3 的思考內容以獨立欄位傳回(非必要,但很有用),然後在本機執行以下程式碼(只需 job ID):

import gradio as gr
from gradio import ChatMessage
from huggingface_hub import get_token
from openai import OpenAI

client = OpenAI(base_url="https://<job_id>--8000.hf.jobs/v1", api_key=get_token())

def chat(message, history):
    messages = [{"role": m["role"], "content": m["content"]} for m in history if not m.get("metadata")]
    messages.append({"role": "user", "content": message})
    stream = client.chat.completions.create(model="Qwen/Qwen3-4B", messages=messages, stream=True)

    thinking, answer = "", ""
    for chunk in stream:
        delta = chunk.choices[0].delta
        thinking += delta.model_extra.get("reasoning", "")
        answer += delta.content or ""
        out = []
        if thinking.strip():
            status = "done" if answer.strip() else "pending"
            out.append(ChatMessage(role="assistant", content=thinking, metadata={"title": "💭 Thinking", "status": status}))
        if answer.strip():
            out.append(ChatMessage(role="assistant", content=answer))
        yield out

gr.ChatInterface(chat).launch()

執行程式、開啟 http://127.0.0.1:7860,即可開始聊天;推理過程會顯示在可摺疊面板中,答案則顯示於下方。

進階用法:透過 SSH 連線至運行中的伺服器

需要診斷啟動失敗、查看 GPU 記憶體,或互動式追蹤日誌嗎?你可直接透過 Shell 連入運行中的 job。啟動時加入 --ssh,並確保已在 huggingface.co/settings/keys 登記公開金鑰:

hf jobs run --flavor a10g-large --expose 8000 --timeout 2h --ssh \
  vllm/vllm-openai:latest \
  vllm serve Qwen/Qwen3-4B --host 0.0.0.0 --port 8000

然後使用 job ID 連線:

hf jobs ssh <job_id>

現在你已進入容器,可執行 nvidia-smi、檢查程序,或直接操作模型;相比在外部讀取日誌,這樣更容易除錯及監察。SSH 支援需要 huggingface_hub >= 1.20.0。

進階用法:使用 Pi 作為編碼代理後端

同一端點亦可供終端機編碼代理使用。Pi 是不依賴特定供應商的代理框架。把它指向該 job,即可在自託管模型上運行具備 Read/Write/Edit/Bash 能力的代理程式。

開始前要先設定一項功能:代理程式透過工具呼叫驅動模型,而 vLLM 只會在伺服器啟用工具呼叫後接受這些請求。因此,重新啟動時要加入 --enable-auto-tool-choice,並設定與模型系列相符的 --tool-call-parser(Qwen3 使用 hermes)。代理程式亦能從較強模型受惠,因此這裡適合改用大型模型:

hf jobs run --flavor h200x2 --expose 8000 --timeout 2h \
  vllm/vllm-openai:latest \
  vllm serve Qwen/Qwen3.5-122B-A10B \
  --host 0.0.0.0 --port 8000 --tensor-parallel-size 2 \
  --max-model-len 32768 --max-num-seqs 256 \
  --reasoning-parser deepseek_r1 \
  --enable-auto-tool-choice --tool-call-parser hermes

然後在 ~/.pi/agent/models.json 中加入此 job 作為自訂供應商:

{
  "providers": {
    "hf-jobs": {
      "baseUrl": "https://<job_id>--8000.hf.jobs/v1",
      "api": "openai-completions",
      "apiKey": "!hf auth token",
      "models": [
        { "id": "Qwen/Qwen3.5-122B-A10B" }
      ]
    }
  }
}

最後,使用該模型啟動代理程式:

pi

幾個指令前啟動的模型,現在已在終端機中驅動互動式編碼代理程式。

HF Jobs 還是 Inference Endpoints?

在 Hugging Face 上提供模型服務,不只有 HF Jobs 一種方式。Inference Endpoints 是我們為相同用途提供的託管產品,應選哪種服務取決於你的需要。

如果你需要最高的彈性和控制能力,請選 HF Jobs:它本質上是在 HF 基礎設施上執行 docker run,你可自行選擇映像檔、精確的 vllm serve 旗標及硬件,並只在 job 運行期間按秒付費。因此,它很適合實驗、單次評估、批次生成,或在正式採用模型前先行試用。

如果你需要更適合生產環境的服務,請選 Inference Endpoints。它加入長期服務所需的營運功能:更細緻的存取控制(端點可設為公開、受保護或私人),以及縮減至零閒置資源,讓你在沒有流量時毋須付費。若要建立長期穩定的端點,而非執行單次 job,便應選用這項服務。

延伸閲讀

本文以 vLLM 為例,但任何兼容 OpenAI 的伺服器都可使用相同的公開連接埠模式。如要使用 llama.cpp 服務 GGUF,或改用 SGLang,請參閲在 Jobs 上提供模型服務指南,瞭解這些後端的操作方式。

來源:Hugging Face Blog · huggingface.co