一行命令在 HF Jobs 上启动 vLLM

它是为测试、评估或批量生成快速启动模型的最佳方式。（如果你需要托管的、生产级的服务，那就是 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 代理路由（详见 Serve Models 指南）。命令会打印你的服务器可访问的 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 是你的 job 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。普通浏览器访问会被拒绝。实际上，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 上运行 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 客户端、token 认证）保持完全相同。

进阶：用 UI 聊天

更喜欢聊天窗口而不是 curl？只需几行 Gradio 代码就能指向同一端点。在 vllm serve 命令中添加 --reasoning-parser deepseek_r1 使 Qwen3 的思考过程以单独字段返回（不必需，但有帮助），然后在本地运行这段代码（你只需要 job 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 内存或实时查看日志？你可以直接在运行的 job 中打开 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

然后用 job ID 连接：

hf jobs ssh <job_id>

现在你在容器内部，可以运行 nvidia-smi、检查进程或直接操作模型 — 这比从外部读日志调试和监控要容易得多。SSH 支持需要 huggingface_hub >= 1.20.0。

进阶：用 Pi 作为编码 Agent 后端

同一端点也可以作为终端编码 agent 的后端。Pi 是一个与提供商无关的 agent 框架。将其指向 job，你就可以获得在自托管模型上运行的 Read/Write/Edit/Bash agent。

首先要设置一件事：agent 通过工具调用驱动模型，vLLM 只有在启用工具调用的情况下才接受。所以用 --enable-auto-tool-choice 和与模型族匹配的 --tool-call-parser（Qwen3 用 hermes）重新启动。Agent 也受益于更强大的模型，所以这是引入更大模型的好地方：

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 中添加 job 作为自定义提供商：

{
  "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" }
      ]
    }
  }
}

然后针对它启动 agent：

pi

你几条命令前启动的模型，现在在你的终端驱动一个交互式编码 agent。

HF Jobs 还是 Inference Endpoints？

HF Jobs 不是在 Hugging Face 上提供模型的唯一方式。Inference Endpoints 是我们用于相同工作的托管产品，选择哪一个取决于你的需求。

当你需要最大的灵活性和控制权时，使用 HF Jobs：它就是在 HF 基础设施上运行 docker run，所以你可以选择镜像、确切的 vllm serve 标志和硬件，按运行时间按秒计费。这使其非常适合实验、一次性评估、批量生成或在提交前试用模型。

当你需要更生产级的东西时，使用 Inference Endpoints。它们添加了长期服务所需的操作便利性：更细粒度的访问控制（端点可以是公开的、受保护的或私有的），以及自动缩放到零，因此在不活跃期间你不会被计费。如果你要建立持久端点而不是运行一个 job，那就用这个工具。

本文专注于 vLLM，但同一端口暴露模式适用于任何 OpenAI 兼容的服务器。要使用 llama.cpp 提供 GGUF 或改用 SGLang，见 Serve Models on Jobs 指南，其中涵盖这些后端。

更多博客文章

Native-speed vLLM transformers 建模后端

将你的 GitHub CI 迁移到 Hugging Face Jobs