返回
原文
Hugging Face：Blog（RSS）
精选
62AI 编辑部评分，满分 100

一条命令在HF Jobs上启动vLLM服务器

2026-06-26 08:00· 51天前
AI 导读

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上启动vLLM的完整教程，适合快速测试模型的开发者，但方案完全绑定Hugging Face平台，通用性有限。

正文 · AI 翻译

只需一条命令，就能在 Hugging Face 基础设施上启动一个私有的、兼容 OpenAI 的大语言模型端点——无需配置服务器，无需 Kubernetes，按秒计费。启动后，你可以从笔记本电脑、笔记本或其他任何地方查询该模型。

这是为测试、评估或批量生成快速搭建模型的最快捷方式。（如果你需要的是托管式、生产就绪的服务，那应该使用推理端点——文末会详细介绍何时选择哪种方案。）

以下是完整的端到端流程。

前置条件

  • 需要一种支付方式或正值的预付费余额（作业按硬件使用量以每分钟计费）。
  • 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 的公共作业代理进行路由（完整参考请参阅《服务模型指南》）。该命令会打印出你的服务器可访问的 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，每个请求只需将你的 Hugging Face 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 系列通常性价比最高。

`--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 上提供模型服务》指南，该指南详细介绍了这些后端方案。

Hugging Face教程/实践部署/工程

来源：Hugging Face：Blog（RSS） · huggingface.co

导出 Markdown
返回
精选AI 评分 62/100打开原文
导出 Markdown

一条命令在HF Jobs上启动vLLM服务器

Hugging Face：Blog（RSS）·2026-06-26 08:00·51天前
AI 导读

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 停止。

正文 · AI 翻译

只需一条命令，就能在 Hugging Face 基础设施上启动一个私有的、兼容 OpenAI 的大语言模型端点——无需配置服务器，无需 Kubernetes，按秒计费。启动后，你可以从笔记本电脑、笔记本或其他任何地方查询该模型。

这是为测试、评估或批量生成快速搭建模型的最快捷方式。（如果你需要的是托管式、生产就绪的服务，那应该使用推理端点——文末会详细介绍何时选择哪种方案。）

以下是完整的端到端流程。

前置条件

  • 需要一种支付方式或正值的预付费余额（作业按硬件使用量以每分钟计费）。
  • 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 的公共作业代理进行路由（完整参考请参阅《服务模型指南》）。该命令会打印出你的服务器可访问的 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，每个请求只需将你的 Hugging Face 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 系列通常性价比最高。

`--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 上提供模型服务》指南，该指南详细介绍了这些后端方案。

来源：Hugging Face：Blog（RSS）· huggingface.co