runpod-vllm

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

vLLM on Runpod

Runpod 上的 vLLM

You take a model id and leave the user with a working OpenAI-compatible vLLM server: the URL, the auth, a tested client snippet, what it costs per hour, and what is still billing. A create call that returned an id is not a working server. The deployment is done only when

scripts/test_endpoint.py

passes against the real URL.

Creating a Pod or an endpoint bills. State the hourly price from the catalog read before each create. The generic endpoint procedure (smoke job, hold limits, hand-back fields) is runpod-serverless-deploy's and the generic Pod procedure is runpod-pod-deploy's. This skill adds what is specific to vLLM. A worked run of the Pod and load-balancing paths is golden path 27; the full index is in golden-paths/README.md.

你输入一个模型 id，最终为用户提供一个正常工作的 OpenAI 兼容 vLLM 服务器：包括 URL、鉴权方式、经过测试的客户端代码片段、每小时费用，以及当前仍在计费的内容。仅返回了 id 的 create 调用并不表示服务器已经可用。只有当

scripts/test_endpoint.py

针对真实 URL 运行通过后，部署才算完成。

创建 Pod 或端点会产生费用。每次 create 之前，都要先读取 catalog 并说明每小时价格。通用端点流程（冒烟任务、保留上限、交回字段）见 runpod-serverless-deploy，通用 Pod 流程见 runpod-pod-deploy。本 skill 补充 vLLM 特有的内容。Pod 和负载均衡路径的一次完整实操见 golden path 27；完整索引见 golden-paths/README.md。

Tool binding

工具绑定

If a tool named here is missing from the session's tool list, say so and use the nearest read. Never invent a result. Parameter names follow the live tool schema (

describe-tool

); the examples in the references show the settings to send, not a schema.

Capability	Tool
Hub worker-vllm release: listed tag, image, CUDA pin, GPU pools, env schema	`list-hub-repos` ( `repoOwner:"runpod-workers"` , `searchTerm:"worker-vllm"` , `includeConfig:true` )
GPU price and stock per product; stock at an exact GPU count and host CUDA version	`list-gpu-types` ( `include:["AVAILABILITY"]` , `product:["POD"]` or `["SERVERLESS"]` ); `get-capacity` ( `gpuCount` , `cudaVersions` )
Queue endpoint from the Hub release	`deploy-hub-repo`
Load-balancing endpoint on a vLLM image	`create-endpoint` ( `type:"LOAD_BALANCER"` )
Pod running `vllm serve`	`create-pod` ( `args` carries the `vllm serve` arguments, `gpu.minCudaVersion` the floor)
CUDA floor or GPU change on an endpoint	`set-endpoint-gpus` or `update-endpoint` ( `gpu` )
Boot progress and failures	`stream-pod-logs` ; `list-endpoint-workers` + `stream-worker-logs`
Read back what you set	`get-pod` , `get-endpoint`
Teardown	`delete-pod` , `delete-endpoint` (and the template a Hub deploy created, `delete-template` )

如果此处指定的工具不在当前会话的工具列表中，应明确说明，并使用最接近的读取方式。绝不能虚构结果。参数名称以实时工具 schema（

describe-tool

）为准；参考文档中的示例展示的是应传入的设置，而不是 schema。

能力	工具
Hub worker-vllm 发布版本：列出的 tag、镜像、CUDA 版本约束、GPU 池、环境变量 schema	`list-hub-repos` （ `repoOwner:"runpod-workers"` 、 `searchTerm:"worker-vllm"` 、 `includeConfig:true` ）
各产品的 GPU 价格和库存；指定 GPU 数量及主机 CUDA 版本时的库存	`list-gpu-types` （ `include:["AVAILABILITY"]` 、 `product:["POD"]` 或 `["SERVERLESS"]` ）； `get-capacity` （ `gpuCount` 、 `cudaVersions` ）
基于 Hub 发布版本创建队列端点	`deploy-hub-repo`
基于 vLLM 镜像创建负载均衡端点	`create-endpoint` （ `type:"LOAD_BALANCER"` ）
运行 `vllm serve` 的 Pod	`create-pod` （ `args` 携带 `vllm serve` 参数， `gpu.minCudaVersion` 为最低版本）
修改端点的 CUDA 下限或 GPU	`set-endpoint-gpus` 或 `update-endpoint` （ `gpu` ）
启动进度和故障	`stream-pod-logs` ； `list-endpoint-workers` + `stream-worker-logs`
回读已设置的配置	`get-pod` 、 `get-endpoint`
清理资源	`delete-pod` 、 `delete-endpoint` （以及 Hub 部署创建的模板 `delete-template` ）

Step 1: read the facts

第 1 步：读取事实

Read these before you choose anything. Do the reads in parallel.

The model. From the Hugging Face model card and
```
config.json
```
: parameter count, native dtype, context length, whether it is a reasoning model, whether it supports tool calls, whether an official quantized variant exists (FP8, AWQ, GPTQ). vLLM's GGUF support is limited and version-dependent: for a
```
*.gguf
```
repo, prefer the same model's safetensors repo on vLLM, or a GGUF engine from runpod-serverless-deploy's engine table.
The vLLM version the model needs. The model card or the vLLM recipe for the model (
```
https://github.com/vllm-project/recipes
```
) names a minimum vLLM version and the serving flags. If neither says, treat the first boot as the test.
The Hub worker.
```
list-hub-repos
```
for
```
runpod-workers/worker-vllm
```
gives the listed release, its image and its
```
allowedCudaVersions
```
. The release notes on GitHub name the vLLM version it bundles. Read it live every time: the listed release changes, and it can lag the newest GitHub release.

选择任何方案之前，先读取以下信息。并行执行这些读取。

模型。 从 Hugging Face 模型卡和
```
config.json
```
中了解：参数量、原生 dtype、上下文长度、是否为推理模型、是否支持工具调用，以及是否存在官方量化变体（FP8、AWQ、GPTQ）。vLLM 对 GGUF 的支持有限且取决于版本：对于
```
*.gguf
```
仓库，应优先在 vLLM 上使用同一模型的 safetensors 仓库，或使用 runpod-serverless-deploy 引擎表中的 GGUF 引擎。
模型所需的 vLLM 版本。 模型卡或模型的 vLLM recipe（
```
https://github.com/vllm-project/recipes
```
）会注明最低 vLLM 版本和服务启动参数。如果两者都未说明，则将首次启动视为测试。
Hub worker。 对
```
runpod-workers/worker-vllm
```
执行
```
list-hub-repos
```
，获取列出的发布版本、镜像及其
```
allowedCudaVersions
```
。GitHub 上的发布说明会注明其中捆绑的 vLLM 版本。每次都要实时读取：列出的发布版本会变化，并且可能落后于最新的 GitHub release。

Step 2: choose the product

第 2 步：选择产品

Does the Hub worker's vLLM support the model?
├── yes → Is it request/response traffic that can scale to zero?
│         ├── yes → queue endpoint (reference/queue-endpoint.md)
│         └── no, the user wants a server they keep → Pod (reference/pod.md)
└── no (new architecture, needs a newer vLLM or a nightly image)
          ├── model boots in minutes on ≤ 2 GPUs → load-balancing endpoint (reference/lb-endpoint.md)
          └── very large or slow to boot → Pod first; move to an endpoint after it passes

Product	URL	Auth	Choose it when
Queue endpoint (Hub worker-vllm)	`https://api.runpod.ai/v2/<endpoint-id>/openai/v1`	Runpod API key	the Hub vLLM supports the model; scale-to-zero; no image to manage
Load-balancing endpoint ( `vllm/vllm-openai:<tag>` )	`https://<endpoint-id>.api.runpod.ai/v1`	Runpod API key at the gateway	the model needs a vLLM version the Hub worker does not have; direct HTTP, no queue
Pod ( `vllm/vllm-openai:<tag>` )	`https://<pod-id>-8000.proxy.runpod.net/v1`	vLLM's own API key ( `VLLM_API_KEY` )	a long-running server, debugging a boot, or a model too large or slow for the endpoint health window

For a new or very large model, prove the config on a Pod first: a Pod has no health watchdog, so a long first boot (download plus compile) is fine and the logs stay readable. Then move the same image and arguments to an endpoint.

Hub worker 的 vLLM 是否支持该模型？
├── 是 → 流量是否为可弹性伸缩至零的请求/响应流量？
│         ├── 是 → 队列端点（reference/queue-endpoint.md）
│         └── 否，用户需要一个持续保留的服务器 → Pod（reference/pod.md）
└── 否（新架构，需要更新的 vLLM 或 nightly 镜像）
          ├── 模型可在 ≤ 2 张 GPU 上于几分钟内启动 → 负载均衡端点（reference/lb-endpoint.md）
          └── 模型非常大或启动耗时较长 → 先使用 Pod；通过测试后再迁移到端点

产品	URL	鉴权	选择条件
队列端点（Hub worker-vllm）	`https://api.runpod.ai/v2/<endpoint-id>/openai/v1`	Runpod API key	Hub vLLM 支持该模型；可弹性伸缩至零；无需管理镜像
负载均衡端点（ `vllm/vllm-openai:<tag>` ）	`https://<endpoint-id>.api.runpod.ai/v1`	网关处使用 Runpod API key	模型需要 Hub worker 中没有的 vLLM 版本；使用直接 HTTP，无队列
Pod（ `vllm/vllm-openai:<tag>` ）	`https://<pod-id>-8000.proxy.runpod.net/v1`	vLLM 自身的 API key（ `VLLM_API_KEY` ）	需要长时间运行的服务器、排查启动故障，或模型过大、启动过慢而无法通过端点健康检查时间窗口

对于新模型或超大模型，应先在 Pod 上验证配置：Pod 没有健康监控 watchdog，因此很长的首次启动过程（下载和编译）没有问题，日志也会保持易读。然后将相同的镜像和参数迁移到端点。

Step 3: size the GPUs

第 3 步：确定 GPU 规格

Show the arithmetic in the answer.

Weights in GB ≈ parameters (billions) × bytes per parameter: bf16/fp16 2, FP8 1, 4-bit 0.5.
```
Qwen/Qwen3-8B
```
in bf16 is about 16 GB.
Add room for the KV cache and activations: at least 20–30 % of the weights for a short context, more for a long one. Lower
```
--max-model-len
```
when the model's native context does not fit (the boot fails with a KV-cache error that names the largest length that fits).
One card is best. When one card cannot hold the model, set the GPU count to the next of 1, 2, 4 or 8 and set tensor parallelism to that count (
```
--tensor-parallel-size
```
, or
```
TENSOR_PARALLEL_SIZE
```
on the Hub worker). Say that the cost scales with the count.
Read stock for the product you create (
```
product:["POD"]
```
for a Pod,
```
["SERVERLESS"]
```
for an endpoint), at the GPU count you will use, and at the host CUDA versions that meet the image floor (
```
get-capacity
```
with
```
gpuCount
```
and
```
cudaVersions
```
). Stock for one product, count or CUDA version says nothing about another.

在回答中展示计算过程。

权重占用（GB）≈ 参数量（十亿）× 每参数字节数：bf16/fp16 为 2，FP8 为 1，4-bit 为 0.5。
```
Qwen/Qwen3-8B
```
在 bf16 下约占 16 GB。
为 KV cache 和 activation 预留空间：短上下文至少预留权重的 20–30%，长上下文则需要更多。如果模型的原生上下文长度无法容纳，应降低
```
--max-model-len
```
（启动时会因 KV cache 报错而失败，错误信息中会注明可容纳的最大长度）。
单卡通常是最佳选择。当单卡无法容纳模型时，将 GPU 数量设为 1、2、4 或 8 中的下一个可用数量，并将 tensor parallelism 设置为相同数量（
```
--tensor-parallel-size
```
，或 Hub worker 中的
```
TENSOR_PARALLEX_SIZE
```
）。说明费用会随 GPU 数量成比例增加。
必须读取将要创建的产品对应的库存（Pod 使用
```
product:["POD"]
```
，端点使用
```
product:["SERVERLESS"]
```
）、将要使用的 GPU 数量，以及满足镜像 CUDA 下限的主机 CUDA 版本（通过
```
get-capacity
```
传入
```
gpuCount
```
和
```
cudaVersions
```
）。某个产品、GPU 数量或 CUDA 版本下的库存情况不能说明其他配置的情况。

Step 4: pin the host CUDA floor

第 4 步：锁定主机 CUDA 下限

vllm/vllm-openai:v0.32.0

and the Hub worker-vllm image built on it are CUDA 13 builds (

NVIDIA_REQUIRE_CUDA=cuda>=13.0

); read that variable in the image config for any other tag. Set

gpu.minCudaVersion

to the image floor on every create. The general rule and why: gpu-selection.md step 3.

Prefer the open floor (

minCudaVersion

) to an exact list (

allowedCudaVersions

): the CUDA version is a property of each machine's driver and differs between machines of one GPU type, so an exact list matches only the hosts that report exactly those versions. A Hub release can carry an exact list, and

deploy-hub-repo

copies it to the endpoint. Read the endpoint back after the deploy. If the workers stay at zero or throttled while the stock read shows capacity at a newer CUDA version, widen it with

set-endpoint-gpus

(

allowedCudaVersions:""

minCudaVersion:"13.0"

vllm/vllm-openai:v0.32.0

以及基于它构建的 Hub worker-vllm 镜像都是基于 CUDA 13 构建的（

NVIDIA_REQUIRE_CUDA=cuda>=13.0

）；对于其他 tag，应从镜像配置中读取该变量。每次创建时，都应将

gpu.minCudaVersion

设置为镜像下限。通用规则及其原因见 gpu-selection.md 第 3 步。

优先设置最低版本下限（

minCudaVersion

），而不是精确版本列表（

allowedCudaVersions

）：CUDA 版本是每台机器驱动程序的属性，同一种 GPU 类型的不同机器可能存在差异，因此精确列表只会匹配报告这些确切版本的主机。Hub 发布版本可能包含精确列表，而

deploy-hub-repo

会将其复制到端点。部署后应回读端点配置。如果库存读取结果显示较新 CUDA 版本仍有可用容量，但 worker 始终为零或受到限制，则可使用

set-endpoint-gpus

放宽限制（

allowedCudaVersions:""

、

minCudaVersion:"13.0"

）。

Step 5: set the vLLM flags

第 5 步：设置 vLLM 参数

The flags and what each one costs are in reference/serving-flags.md. The short list:

```
--max-model-len
```
: cap it to what the job needs and the KV cache holds.
```
--gpu-memory-utilization 0.90
```
: leave the default unless the boot log says otherwise.
```
--tensor-parallel-size N
```
= GPU count.
Tool calls:
```
--enable-auto-tool-choice --tool-call-parser <parser>
```
. Reasoning models:
```
--reasoning-parser <parser>
```
. Take the parser names from the model card or the vLLM recipe.
A quantized checkpoint (FP8, AWQ, GPTQ) needs no flag: vLLM reads the method from the checkpoint config.
Gated weights:
```
HF_TOKEN
```
in the env. Never print it.

各项参数及其作用和成本见 reference/serving-flags.md。简要列表如下：

```
--max-model-len
```
：根据任务需求和 KV cache 容量设置上限。
```
--gpu-memory-utilization 0.90
```
：除非启动日志另有说明，否则保持默认值。
```
--tensor-parallel-size N
```
：等于 GPU 数量。
工具调用：
```
--enable-auto-tool-choice --tool-call-parser <parser>
```
。推理模型：
```
--reasoning-parser <parser>
```
。parser 名称应取自模型卡或 vLLM recipe。
量化 checkpoint（FP8、AWQ、GPTQ）不需要额外参数：vLLM 会从 checkpoint 配置中读取量化方式。
受限权重：将
```
HF_TOKEN
```
放入环境变量中。绝不能打印它。

Step 6: deploy and watch the boot

第 6 步：部署并观察启动过程

Follow exactly one reference: queue-endpoint.md, lb-endpoint.md or pod.md.

Watch the boot in short reads, never one long blind wait. Each read checks three things: the resource still exists, its status, and the log tail. Judge progress by forward movement (download, shard load, compile, CUDA graph capture,

Application startup complete

), not by the word ERROR: a healthy vLLM boot prints warnings. The failure signatures and their fixes are in reference/boot-log-triage.md. On a known crash loop, stop the spend first (delete the Pod, or set the endpoint's

workers.max

to 0), then diagnose.

The first log lines prove which settings took effect: vLLM prints

non-default args: {...}

at startup. Check it against what you set before you wait for the rest of the boot.

严格只遵循以下三个参考流程之一：queue-endpoint.md、lb-endpoint.md 或 pod.md。

以短间隔读取的方式观察启动过程，绝不进行一次长时间的无反馈等待。每次读取都应检查三件事：资源是否仍然存在、其当前状态，以及日志尾部。应根据是否持续向前推进来判断进度（下载、分片加载、编译、CUDA graph 捕获、

Application startup complete

），而不是根据是否出现

ERROR

字样：健康的 vLLM 启动过程也会打印警告。故障特征及其修复方法见 reference/boot-log-triage.md。遇到已知的崩溃循环时，应先停止费用产生（删除 Pod，或将端点的

workers.max

设为 0），然后再进行诊断。

启动最初的日志行可以证明哪些设置已生效：vLLM 会在启动时打印

non-default args: {...}

。在继续等待启动完成之前，先将其与设置的内容进行核对。

Step 7: verify with a real client

第 7 步：使用真实客户端进行验证

bash

pip install openai
python3 scripts/test_endpoint.py --base-url <url>/v1 --api-key-env RUNPOD_API_KEY --model <served-model-id> \
  --wait-for-ready 1800 [--thinking-switch] [--skip-tools] [--vision]

The key comes from the named environment variable, so it stays out of the process list:

RUNPOD_API_KEY

for an endpoint,

VLLM_API_KEY

for a Pod.

The script waits for

GET /v1/models

, then tests chat, streaming (time to first token), tool calls and, with flags, the Qwen-style thinking switch and an image input. It exits non-zero if any enabled test fails. A model that answers with garbage or repeats itself has the wrong parser or chat template: fix the server before you report anything.

The first request after a boot can be several times slower than the next one (kernels compile on first use). Quote both numbers if you quote latency.

bash

pip install openai
python3 scripts/test_endpoint.py --base-url <url>/v1 --api-key-env RUNPOD_API_KEY --model <served-model-id> \
  --wait-for-ready 1800 [--thinking-switch] [--skip-tools] [--vision]

API key 来自指定的命名环境变量，因此不会出现在进程列表中：端点使用

RUNPOD_API_KEY

，Pod 使用

VLLM_API_KEY

。

脚本会等待

GET /v1/models

，随后测试 chat、streaming（首个 token 的耗时）、tool calls，并根据参数测试 Qwen 风格的思考开关和图像输入。如果任何已启用的测试失败，脚本会以非零状态退出。如果模型输出无意义内容或反复重复，说明 parser 或 chat template 不正确：应先修复服务器，然后再报告结果。

启动后的首次请求可能比下一次请求慢数倍（首次使用时需要编译 kernel）。如果引用延迟数据，应同时给出首次请求延迟和预热后延迟。

Step 8: hand back and clean up

第 8 步：交回结果并清理资源

The final message is standalone:

product, model id, image or Hub release, GPU type × count, data center, hourly price;
the sizing arithmetic and the flags you set, with the reason for each non-default flag;
the base URL, which key authenticates it, and a working OpenAI SDK snippet that reads the key from an environment variable;
the test result: each check, pass or fail, with the measured first-request and warm latency;
what is billing now, and how to stop it.

Default to keeping what the user asked for. Tear down when the user framed the deployment as a test or asks for cleanup: delete the Pod or endpoint (and the template a Hub deploy created), then confirm with

list-pods

list-endpoints

that nothing you created is left.

最终消息应独立完整，包含：

产品、模型 id、镜像或 Hub 发布版本、GPU 类型 × 数量、数据中心、每小时价格；
规格计算过程和已设置的参数，并说明每个非默认参数的原因；
base URL、用于鉴权的 key，以及从环境变量读取 key 的可用 OpenAI SDK 代码片段；
测试结果：每项检查的通过或失败情况，以及实测的首次请求延迟和预热后延迟；
当前哪些内容仍在计费，以及如何停止计费。

默认保留用户要求的服务。如果用户将部署定义为测试或明确要求清理，则删除 Pod 或端点（以及 Hub 部署创建的模板），然后使用

list-pods

list-endpoints

确认没有遗留任何由本次对话创建的资源。

Hard rules

硬性规则

Never claim the server works without a passing
```
test_endpoint.py
```
run, or the quoted failure.
Never put a vLLM
```
--api-key
```
on a load-balancing endpoint: the gateway checks the Runpod API key, and a second key makes every request fail. A Pod is the opposite: its proxy URL is public, so it always gets a random
```
VLLM_API_KEY
```
.
Never change the config of a warm endpoint during a test without saying it: an image or env change cuts a new release and replaces the workers with cold ones.
Deploy only what the user asked for, and change or delete only what this conversation created.

如果没有通过
```
test_endpoint.py
```
的运行结果，或没有引用实际失败信息，绝不能声称服务器可以正常工作。
绝不能在负载均衡端点上设置 vLLM
```
--api-key
```
：网关会检查 Runpod API key，第二个 key 会导致所有请求失败。Pod 的情况正相反：其代理 URL 是公开的，因此必须始终配置一个随机生成的
```
VLLM_API_KEY
```
。
测试期间绝不能在未说明的情况下修改已处于热状态的端点配置：镜像或环境变量变更会触发新的 release，并将 worker 替换为冷启动的 worker。
只部署用户明确要求的内容，只修改或删除本次对话创建的内容。

Contract

契约

The cross-journey answer contract is in the

runpod-mcp

skill. If it is not loaded in this conversation, load it before the next tool call.

跨流程回答契约位于

runpod-mcp

skill 中。如果当前对话尚未加载该 skill，必须在下一次工具调用前加载。