一条命令在HF Jobs上启动vLLM服务器
阅读原文· huggingface.co这是一条命令在HF上启动vLLM的完整教程,适合快速测试模型的开发者,但方案完全绑定Hugging Face平台,通用性有限。
HuggingFace Jobs 支持一条命令启动 vLLM 服务器,用于测试、评估或批量生成。使用 hf jobs run 命令,指定官方 vllm/vllm-openai 镜像、GPU flavor(如 a10g-large)、暴露端口 8000 并设置超时。服务器启动后可通过 OpenAI 兼容 API 访问,每次请求需携带 HF token 作为 bearer token(仅限有读权限的用户)。示例部署了 Qwen/Qwen3-4B(多 GPU 需 --tensor-parallel-size)。a10g-large 价格为 $1.50/小时,按分钟计费,可通过 hf jobs cancel 停止。
在 HF Jobs 上一条命令运行 vLLM 服务器
这是快速启动模型以进行测试、评估或批量生成的最快方式。(如果你追求的是托管式、可投入生产环境的服务,那么推理端点才是你需要的——文末会详细介绍何时选择哪种方案。)
以下是完整的端到端流程。
前置条件
- 需要已启用一种支付方式或有正数预付信用余额(Jobs 按硬件使用分钟数计费)。
- huggingface_hub >= 1.20.0:执行 `pip install -U "huggingface_hub>=1.20.0"`。
- 本地已登录:执行 `hf auth login`。
启动服务器
`hf jobs run` 是 HF 基础设施上的 `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 的公共作业代理路由出去(完整参考请查阅《服务模型》指南)。该命令会打印你的服务器可访问的 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` 是你的作业 ID。请记住它,后面会用到。在本文后续部分,我们将使用 `<job_id>` 作为它的占位符。
给它几分钟时间来下载权重并启动。当日志显示 `Application startup complete` 时,说明服务器已就绪。
从任何地方查询它
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` 包含 "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)"` 应能列出模型。
🔐 该端点是有权限控制的,并非公开。每个请求必须携带具有作业命名空间读取权限的 HF token。直接通过浏览器访问会被拒绝。实际上,作业代理就是你的 API 网关:访问权限仅限于你(及你的组织)。这对私有使用来说没问题,但请妥善处理 URL:不要将其当作公开链接分享,也不要在不可信的地方粘贴你的 token。如果你需要更精细的权限控制或公开访问,请在前面放置一个合适的网关。或者参考下面的“HF 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` 应与 flavor 中的 GPU 数量匹配(h200x2 → 2, h200x8 → 8)。运行 hf jobs hardware 查看可用配置,并为更大的模型设置更长的 `--timeout`,因为它们的下载和加载耗时更长。对于大模型,H200 flavors 通常性价比最高。
`--max-model-len 32768 --max-num-seqs 256` 这两个标志是此模型特有的:Qwen3.5-122B 是一种混合 Mamba/注意力架构,默认上下文窗口为 256K token,这会导致 vLLM 的默认批次设置内存不足。限制上下文长度和并发序列数量可以使其保持在 GPU 内存范围内。如果模型因内存不足或缓存块错误而启动失败,首先尝试调低这两个参数。其他的一切(暴露的 URL、OpenAI 客户端、token 认证)都保持不变。
更进一步:在 UI 中与之对话
更偏好聊天窗口而不是 curl?几行 Gradio 代码即可指向同一个端点。在 vllm serve 命令中添加 `--reasoning-parser deepseek_r1`,这样 Qwen3 的思考过程会作为单独字段返回(非必需,但很有用),然后在本地运行此代码(你只需要任务 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 进入正在运行的任务。使用 `--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
然后使用任务 ID 连接:
hf jobs ssh <job_id>
你现在位于容器内部,可以在其中运行 nvidia-smi、检查进程或直接操作模型——这使得调试和监控比从外部读取日志容易得多。SSH 支持需要 huggingface_hub >= 1.20.0。
更进一步:将其用作 Pi 的编码智能体后端
同一个端点可以为终端编码智能体提供支持。Pi 是一个与提供商无关的智能体框架。将其指向该任务,你就能得到一个在你自托管模型上运行的具备读写/编辑/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` 中将该任务添加为自定义提供商:
{
"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?
HF Jobs 并不是在 Hugging Face 上部署模型的唯一方式。Inference Endpoints 是我们用于相同任务的托管产品,选择哪一个取决于你的需求。
当你需要最大灵活性和控制力时,选择 HF Jobs:它只是在 HF 基础设施上运行 docker run,所以你可以选择镜像、精确的 vllm serve 参数以及硬件,并按秒为任务运行时长付费。这使得它非常适合实验、一次性评估、批量生成,或在正式投入前先试运行某个模型。
当你需要更具生产就绪性的方案时,选择 Inference Endpoints。它们提供了长生命周期服务所需的运维便利:更细粒度的访问控制(端点可以是公开的、受保护的或私有的),以及缩放到零功能,这样在不活动期间你不会被收费。如果你要建立一个持久端点而不是运行一次性任务,那么这是应该使用的工具。
延伸阅读
本文聚焦于 vLLM,但相同的暴露端口模式适用于任何兼容 OpenAI 的服务器。若要通过 llama.cpp 提供 GGUF 服务或改用 SGLang,请参阅《在 Jobs 上部署模型》指南,该指南详细介绍了这些后端。
社区
· 或发表评论