Run a vLLM Server on HF Jobs in One Command

通过一个命令在 HF Jobs 上运行 vLLM 服务

返回文章列表

[-1

]

[0

发布于 2026 年 6 月 26 日

GitHub 上的更新

点赞

7

[

• +1

Quentin Gallouédec

qgallouedec

关注

只需一个命令，你就可以在 Hugging Face 基础设施上启动一个私有且兼容 OpenAI 的 LLM 端点 —— 不需要配置服务器，不需要 Kubernetes，按秒计费。一旦启动，你可以从你的笔记本电脑、笔记本或任何其他地方查询它。

这是快速搭建模型进行测试、评估或批量生成的最快方式。（如果你需要的是托管的、生产就绪的服务，那应该是推理端点 —— 关于何时选择哪一种，我们将在最后详细说明。）

以下是从头到尾的完整操作。

先决条件

• 一种支付方式或一个正的预付信用余额（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：

✓ 作业已启动
  id: 6a381ca1953ed90bfb947332
  url: https://huggingface.co/jobs/qgallouedec/6a381ca1953ed90bfb947332
提示：暴露的端口可通过以下网址访问（需要 HF 令牌以读取作业）：
  https://6a381ca1953ed90bfb947332--8000.hf.jobs

6a381ca1953ed90bfb947332 是你的作业 ID。请记住它，我们之后需要它。在本文的其余部分，我们将使用 <job_id> 作为它的占位符。

让它下载权重并启动，大约需要几分钟。当日志显示 Application startup complete 时，你就可以开始使用了。

从任何地方查询它

vLLM 使用 OpenAI API，每个请求只需要你的 HF 令牌作为承载令牌。最快的方式是使用 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，并将令牌作为 API 密钥传递：

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 令牌。普通的浏览器访问将被拒绝。实际上，任务代理就是你的 API 网关：访问权限仅限于你（以及你的组织）。这在私有使用中是可行的，但请务必注意 URL 的使用方式：不要期望它对所有人开放，也请勿将你的令牌粘贴到不可信的地方。如果你需要更细粒度或公开访问权限，请使用合适的网关。或者请参见下面的 HF Jobs 或 Inference Endpoints。

清理

任务按秒计费，因此完成任务后请停止服务器：

hf
jobs
cancel <job_id>

你设置的 --timeout 是一个安全网（它会自动停止），但显式取消任务更便宜。a10g-large 的运行费用为每小时 1.50 美元 —— 查看 hf jobs hardware 获取完整价格列表，并选择适合你模型的最小规格。

更进一步：更大的模型

相同的命令可以扩展到更大的模型 —— 选择更强大的 --flavor，并告诉 vLLM 将模型跨 GPU 分片，使用 --tensor-parallel-size。例如，使用 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 规格通常是最具性价比的选择。

--max-model-len 32768 --max-num-seqs 256 这两个参数是针对该模型的：Qwen3.5-122B 是一种混合 Mamba/attention 架构，默认上下文长度为 256K tokens，这不足以容纳 vLLM 默认的批处理设置。限制上下文长度和并发序列数量可以确保模型在 GPU 内存范围内运行。如果模型启动时出现内存不足或缓存块错误，调整这两个参数是首要尝试的方法。其余内容（暴露的 URL、OpenAI 客户端、令牌认证）保持完全不变。

更进一步：通过 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 还是推理端点？

在 Hugging Face 上提供模型的方式不只有 HF Jobs。推理端点是我们管理的同类产品，选择哪一个取决于你的需求。

当你需要最大灵活性和控制时，选择 HF Jobs：它只是在 HF 基础设施上运行的 docker run，因此你可以选择镜像、精确的 vllm serve 标志和硬件，并按秒计费，只要任务运行。这使其非常适合实验、一次性评估、批量生成或在承诺任何事情之前对模型进行测试。

在需要更接近生产环境的解决方案时，请选择推理端点（Inference Endpoints）。它们为长期运行的服务提供了必要的操作特性：更细粒度的访问控制（端点可以是公开的、受保护的或私有的），以及零规模扩展（scale-to-zero），这样在不活动期间就不会产生费用。如果你要设置一个持久的端点，而不是运行一个任务，这就是你要使用的工具。

进一步阅读

本文专注于 vLLM，但同样的“暴露端口”模式同样适用于任何兼容 OpenAI 的服务器。如果你想使用 llama.cpp 服务 GGUF 模型，或者运行 SGLang，可以参阅《在任务中部署模型》指南，该指南会逐步介绍这些后端的使用方法。

更多文章来自我们的博客

guide

hub

jobs

将你的 GitHub CI 迁移到 Hugging Face Jobs

10

2026年6月9日

cloud

inference

使用推理端点实现超快速的 whisper 转录

• +2

82

2025年5月13日

社区

编辑

预览

通过在文本输入框中拖拽、粘贴或

点击此处

上传图片、音频和视频。

轻点或粘贴此处上传图片

评论

· 注册或登录以发表评论