一行命令在HF Jobs上运行vLLM服务器

点赞 9

这是为测试、评估或批量生成快速部署模型的最优方案。（如果你需要的是托管式、可直接用于生产的服务，那应该选择 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 会通过 Hugging Face 公共 Jobs 代理转发容器端口（完整说明请查看模型部署指南）。执行命令后会输出服务器的访问地址：

✓ 任务已启动
id: 6a381ca1953ed90bfb947332
url: https://huggingface.co/jobs/qgallouedec/6a381ca1953ed90bfb947332
提示：暴露端口的访问地址如下（需拥有任务读取权限的 HF token）：
https://6a381ca1953ed90bfb947332--8000.hf.jobs

6a381ca1953ed90bfb947332 是你的任务 ID，请妥善保存，后续操作会用到。本文后续将用 <job_id> 作为该 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，并将 HF 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，直接用浏览器访问会被拒绝。实际上，Jobs 代理就相当于 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 GPU 上部署 1220 亿参数的 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/注意力混合架构，默认上下文长度为 256K token，若使用 vLLM 默认的批处理设置会导致内存不足。限制上下文长度和并发序列数可确保模型运行在 GPU 内存范围内。如果模型启动时出现内存不足或缓存块错误，首先尝试调低这两个参数。其他设置（暴露的 URL、OpenAI 客户端、token 鉴权）完全保持不变。

不想用 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": "💭 思考中", "status": status}))
if answer.strip():
out.append(ChatMessage(role="assistant", content=answer))
yield out
gr.ChatInterface(chat).launch()

运行代码后打开 http://127.0.0.1:7860 即可开始聊天——思考过程会显示在可折叠面板中，回答内容则在下方。 需要调试启动故障、监控 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 是一款兼容多服务商的代理框架，将其指向你的任务，就能基于自托管模型获得支持读写、编辑、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

你之前部署的模型，现在已成为终端中交互式代码代理的驱动核心。

在 Hugging Face 平台部署模型并非只有 HF Jobs 一种方式。Inference Endpoints 是我们的托管式产品，两者适用场景不同：

当你需要最大灵活性与控制权时，选择 HF Jobs：它就像在 Hugging Face 基础设施上执行 docker run，你可以自主选择镜像、精确配置 vllm serve 参数和硬件规格，按实际运行时长按秒计费。非常适合实验、一次性评估、批量生成，或是在正式投入前快速测试模型。

当你需要更适合生产环境的方案时，选择 Inference Endpoints：它具备长期服务所需的运维特性，包括更精细的访问控制（端点可设为公开、受保护或私有），以及闲置时自动缩容至零的功能，无需为空闲时段付费。如果你需要搭建持久化端点而非临时运行任务，这是更合适的工具。

本文以 vLLM 为例，但这种端口暴露模式适用于所有兼容 OpenAI API 的服务器。如需用 llama.cpp 部署 GGUF 模型或改用 SGLang，请查看Jobs 模型部署指南，其中详细介绍了这些后端的部署方法。