一行命令在 HF Jobs 上运行 vLLM 服务器 来源：https://huggingface.co/blog/vllm-jobs 返回文章列表 (https://huggingface.co/blog) Quentin Gallouédec 的头像 (https://huggingface.co/qgallouedec) - 前提条件 (https://huggingface.co/blog/vllm-jobs#prerequisites) - 启动服务器 (https://huggingface.co/blog/vllm-jobs#launch-the-server) - 从任何地方查询 (https://huggingface.co/blog/vllm-jobs#query-it-from-anywhere) - 清理资源 (https://huggingface.co/blog/vllm-jobs#clean-up) - 进阶：更大型的模型 (https://huggingface.co/blog/vllm-jobs#going-further-bigger-models) - 进阶：在 UI 中对话 (https://huggingface.co/blog/vllm-jobs#going-further-chat-with-it-in-a-ui) - 进阶：SSH 进入正在运行的服务器 (https://huggingface.co/blog/vllm-jobs#going-further-ssh-into-the-running-server) - 进阶：用 Pi 作为编程智能体后端 (https://huggingface.co/blog/vllm-jobs#going-further-use-it-as-a-coding-agent-backend-with-pi) - HF Jobs 还是 Inference Endpoints？ (https://huggingface.co/blog/vllm-jobs#hf-jobs-or-inference-endpoints) - 延伸阅读 (https://huggingface.co/blog/vllm-jobs#further-reading) 只需一条命令，你就可以在 Hugging Face 基础设施上启动一个私有的、兼容 OpenAI 的 LLM 端点——无需配置服务器，无需 Kubernetes，按秒计费。启动后，你可以从你的笔记本电脑、笔记本或任何其他地方查询它。这是最快捷的方式，为测试、评估或批量生成搭建一个模型。（如果你想要一个托管、生产就绪的服务，那是 Inference Endpoints (https://huggingface.co/docs/inference-endpoints) 的用途——末尾会有更多关于何时选择哪个 (https://huggingface.co/blog/vllm-jobs#hf-jobs-or-inference-endpoints) 的内容。）以下是端到端的全部流程。 ## https://huggingface.co/blog/vllm-jobs#prerequisites 前提条件 - 一种支付方式或正值的预付费余额（Jobs 按硬件使用量以每分钟计费）。 - huggingface_hub >= 1.20.0：pip install -U "huggingface_hub>=1.20.0"。 - 本地已登录：hf auth login。 ## https://huggingface.co/blog/vllm-jobs#launch-the-server 启动服务器 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 的公共作业代理路由出去（请参阅 Serve Models guide (https://huggingface.co/docs/hub/jobs-serving) 以获取完整参考）。该命令会打印出你的服务器可访问的 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。请记住它，我们后面会用到。在本文的其余部分，我们将用 ```` 作为它的占位符。等待几分钟让它下载权重并启动。当日志显示 Application startup complete 时，你的服务器就上线了。 ## https://huggingface.co/blog/vllm-jobs#query-it-from-anywhere 从任何地方查询 vLLM 使用 OpenAI API，每个请求只需要你的 HF 令牌作为 Bearer 令牌。最快捷的方式是使用 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？ (https://huggingface.co/blog/vllm-jobs#hf-jobs-or-inference-endpoints)。 ## https://huggingface.co/blog/vllm-jobs#clean-up 清理资源 Jobs 按秒计费，所以在完成后停止服务器： hf jobs cancel <JOB_ID> 你设置的 --timeout 是一个安全网（它会自动停止），但显式取消更省钱。a10g-large 的运行成本为 $1.50/小时——运行 hf jobs hardware 查看完整价格列表，并选择适合你模型的最小规格。 ## https://huggingface.co/blog/vllm-jobs#going-further-bigger-models 进阶：更大型的模型 同样的命令可以扩展到更大的模型——选择一个更强大的 --flavor，并告诉 vLLM 使用 --tensor-parallel-size 在多个 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/注意力架构，默认上下文长度为 256K，这不足以让 vLLM 的默认批处理设置使用。限制上下文长度和并发序列数量可以使其保持在 GPU 内存范围内。如果模型因内存不足或缓存块错误而启动失败，降低这两个参数是首先要尝试的。其他一切（暴露的 URL、OpenAI 客户端、令牌认证）都保持不变。 ## https://huggingface.co/blog/vllm-jobs#going-further-chat-with-it-in-a-ui 进阶：在 UI 中对话 更喜欢聊天窗口而不是 curl？几行 Gradio (https://www.gradio.app/) 代码就可以指向同一个端点。在 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，然后聊天——推理过程会流式显示到可折叠面板中，答案在下方。 ## https://huggingface.co/blog/vllm-jobs#going-further-ssh-into-the-running-server 进阶：SSH 进入正在运行的服务器 需要调试启动失败、查看 GPU 内存或交互式地查看日志？你可以直接打开一个 shell 进入正在运行的作业。使用 --ssh 启动它，并确保你的公钥已在 huggingface.co/settings/keys (https://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。 ## https://huggingface.co/blog/vllm-jobs#going-further-use-it-as-a-coding-agent-backend-with-pi 进阶：用 Pi 作为编程智能体后端 同一个端点可以作为终端编程智能体的后端。Pi (https://pi.dev/) 是一个与提供商无关的智能体框架。将其指向该作业，你将得到一个在你的自托管模型上运行的 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" } ] } } } 然后启动智能体指向它： pi 你用几条命令启动的模型，现在正在驱动你终端中的一个交互式编程智能体。 ## https://huggingface.co/blog/vllm-jobs#hf-jobs-or-inference-endpoints HF Jobs 还是 Inference Endpoints？ HF Jobs 并不是在 Hugging Face 上部署模型的唯一方式。Inference Endpoints (https://huggingface.co/docs/inference-endpoints) 是我们针对相同任务的托管产品，选择哪个取决于你的需求。 当你想要最大的灵活性和控制力时，选择 HF Jobs：它只是 HF 基础设施上的 docker run，所以你选择镜像、精确的 vllm serve 标志和硬件，然后按秒付费，只要作业运行。这使得它非常适合实验、一次性评估、批量生成，或者在投入正式使用之前试用一个模型。 当你想要更生产就绪的东西时，选择 Inference Endpoints。它们添加了长期运行服务所需的操作便利性：更细粒度的访问控制（端点可以是公开、受保护或私有的），以及缩放到零，这样在无活动期间你不会被收费。如果你要建立一个持久端点而不是运行一个作业，那才是你应该使用的工具。 ## https://huggingface.co/blog/vllm-jobs#further-reading 延伸阅读 本文专注于 vLLM，但同样的暴露端口模式适用于任何兼容 OpenAI 的服务器。要使用 llama.cpp 部署 GGUF 或运行 SGLang，请参阅 Serve Models on Jobs guide (https://huggingface.co/docs/hub/jobs-serving)，其中详细介绍了这些后端。