用一条命令在 HF Jobs 上运行 vLLM 服务器-未完纪

用一条命令，就能在 Hugging Face 基础设施上启动一个私有、兼容 OpenAI API 的大模型端点：无需自行准备服务器，无需 Kubernetes，按秒付费。启动后，可从笔记本电脑、Notebook 或其他地方查询它。

这是为测试、评测或批量生成快速部署模型的一种方式。如果需要托管且可用于生产的服务，可以选择 Inference Endpoints；文末的选择建议见文末。

下面从头到尾走一遍完整流程。

前提条件

已绑定付款方式，或预付费余额为正（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 的公共 Jobs 代理转发容器端口，完整参考见模型服务指南。命令将输出服务器的访问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 令牌作为 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 令牌作为 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 令牌。直接在浏览器访问会被拒绝。实际上，Jobs 代理就是 API 的访问入口，权限限定在你及你的组织范围内。这样适合私用，但不要分享URL并期待它能公开访问，也不要把令牌粘贴到不可信的地方。如果需要更细粒度的权限或公开访问，应在前面部署合适的网关。也可参见下文 HF Jobs or Inference Endpoints?。

清理

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 应与硬件规格中的 GPU 数量一致，例如 h200x2 对应2，h200x8 对应8。运行 hf jobs hardware 查看可用硬件；较大模型下载和加载更慢，应给它们更长的 --timeout。对于大型模型，H200 规格通常更划算。

--max-model-len 32768 --max-num-seqs 256 参数针对这个模型：Qwen3.5-122B 采用 Mamba/attention 混合架构，默认上下文长度为256K token，留给 vLLM 默认批处理设置的内存不足。限制上下文长度及并发序列数量，可使模型适配 GPU 内存。如果启动时出现内存不足或缓存块错误，首先尝试调低这两个参数。其他部分，包括暴露的URL、OpenAI 客户端和令牌鉴权，都不变。

进一步：通过图形界面聊天

更喜欢聊天窗口而不是 curl？几行 Gradio 代码即可连接同一个端点。在 vLLM 启动时，添加 --reasoning-parser deepseek_r1 到 vllm serve 命令，让 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 内存，或者交互式查看日志？可以直接进入正在运行的任务。启动时添加 --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 是不绑定特定提供商的智能体运行框架。把它指向 Jobs 任务，就能让 Read/Write/Edit/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" }
      ]
    }
  }
}

接着启动智能体来使用它：