一键在 HF Jobs 上运行 vLLM 服务器：快速部署与深度解读

背景

在机器学习模型的开发、测试、评估（evals）或批量生成任务中，快速启动一个可用的模型推理服务是常见需求。虽然 Hugging Face 提供了生产就绪的托管服务 Inference Endpoints，但对于需要灵活控制、临时测试或低成本运行的场景，直接利用 HF Jobs 运行开源推理引擎（如 vLLM）提供了更轻量、更直接的解决方案。

本文介绍如何通过一条命令，在 Hugging Face Jobs 基础设施上快速启动一个基于 vLLM 的 OpenAI 兼容服务器。这种方法不仅适用于快速验证模型，还可以作为代码代理（Coding Agent）的后端，甚至支持交互式调试。

核心内容

1. 前置准备

在开始之前，需确保满足以下条件：

• 账户与支付：拥有有效的支付方式或正向预存余额。HF Jobs 按硬件使用时长（每分钟）计费。
• 软件版本：本地需安装 huggingface_hub >= 1.20.0。

  pip install -U "huggingface_hub>=1.20.0"
  

• 身份认证：本地需登录 Hugging Face 账户。

  hf auth login
  

2. 启动服务器

使用 hf jobs run 命令启动容器。该命令类似于 docker run，但针对 HF 基础设施进行了优化。以下命令以 Qwen3-4B 模型为例，使用 a10g-large 规格，暴露 8000 端口，并设置 2 小时超时：

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：将容器内的 8000 端口通过 HF 的公共 Jobs 代理路由出去。
• 输出结果：命令执行后会返回 Job ID 和访问 URL。
  • Job ID: 6a381ca1953ed90bfb947332
  • 访问 URL: https://<job_id>--8000.hf.jobs
• 等待启动：模型权重下载和启动需要几分钟。当日志显示 Application startup complete 时，服务即就绪。

3. 查询与交互

vLLM 兼容 OpenAI API 格式。所有请求均需携带带有读取权限的 HF Token 作为 Bearer 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 包含模型回复。

使用 Python OpenAI 客户端

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)

健康检查：启动前可先检查模型列表： curl https://<job_id>--8000.hf.jobs/v1/models -H "Authorization: Bearer $(hf auth token)"

安全提示：该端点是**受保护（Gated）**的，并非公开访问。URL 仅对拥有 Job 命名空间读取权限的 Token 有效。请勿随意分享 URL 或将 Token 粘贴到不受信任的地方。如需更细粒度的访问控制，建议在前端添加网关。

4. 清理资源

HF Jobs 按秒计费，任务结束后应及时停止以节省成本：

hf jobs cancel <job_id>

虽然设置了 --timeout 会自动停止，但手动取消更经济。例如 a10g-large 的价格约为 $1.50/小时。

5. 进阶：运行更大规模的模型

对于更大参数量的模型（如 Qwen3.5-122B），需要选择更强的硬件规格（如 h200x2），并使用 --tensor-parallel-size 进行张量并行分片：

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）。
• 内存优化：对于混合架构（如 Mamba/Attention）的大模型，默认批处理设置可能导致显存溢出。通过限制 --max-model-len（上下文长度）和 --max-num-seqs（并发序列数）可以防止 OOM 错误。

6. 进阶：使用 Gradio 构建聊天 UI

可以通过几行 Python 代码将上述端点转换为交互式聊天界面，并支持思维链（Reasoning）的分离显示：

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 即可进行聊天，思维过程会显示在可折叠面板中。

7. 进阶：SSH 调试

若需调试启动失败、监控 GPU 显存或查看实时日志，可使用 --ssh 参数启动 Job，并通过 Job ID 连接：

# 启动时添加 --ssh
hf jobs run --flavor a10g-large --ex