快速理解vLLM命令行工具serve

vllm serve 是 vLLM 框架的核心命令行工具，它的作用是将一个大型语言模型（LLM）快速启动为一个高性能的 API 服务 。

简单来说，它的功能等同于："加载模型 + 启动服务器 + 提供推理接口" 三合一。

当你运行 vllm serve 时，它在后台完成了以下工作：

加载模型：从本地磁盘或 Hugging Face 下载并加载指定的大模型权重到 GPU 显存中。
初始化引擎：启动 vLLM 的高性能推理引擎，应用其核心技术（如 PagedAttention、连续批处理 Continuous Batching），以最大化吞吐量。
启动 Web 服务器：基于 FastAPI/Uvicorn 启动一个 HTTP 服务器，监听指定端口（默认 8000）。
提供标准 API：暴露标准的 RESTful API 接口，供客户端调用。

为了方便你快速上手，我将参数分为"核心必配参数"（生产环境必须关注和调整）和"常用功能参数"（根据需求开启），其余大量高级或调试参数则归类为"进阶/调试参数"

核心必配参数

这些参数直接决定了模型能否运行、运行速度以及显存利用率，是部署时的重中之重。

model

含义: 模型名称或路径。
详解: 指定要加载的Hugging Face模型ID（如 Qwen/Qwen2.5-7B-Instruct）或本地模型路径。这是最基础的参数。如果不指定 --served-model-name，API返回的模型名也将使用此值。

gpu-memory-utilization

含义: GPU显存利用率。
详解: 极其重要。指定模型执行器占用GPU显存的比例（0.0 到 1.0）。
默认值为 0.9 (90%)。
建议: 如果单卡只跑一个实例，保持0.9即可；如果一张卡跑多个实例，需按比例调低（如两个实例各设0.45）。剩余显存将自动分配给KV Cache（上下文缓存），直接影响你能支持的并发长度。

max-model-len

含义: 最大模型上下文长度。
详解: 限制单个请求的总长度（Prompt + Output）。
默认自动从模型配置读取。
建议: 如果显存充足但想限制单次请求长度以保护服务，可手动设置（如 8192, 32768）。支持人类可读格式，如 32k。设为 -1 或 auto 会根据显存自动计算最大可行长度。

tensor-parallel-size (-tp)

含义: 张量并行大小。
详解: 指定使用多少张GPU来共同推理一个大模型。
默认 1。
建议: 当模型太大单卡放不下时（如70B模型），需设置为显卡数量（如 -tp 4 表示用4张卡）。注意：这要求多卡间有高速互联（NVLink）。

dtype

含义: 数据类型。
详解: 模型权重和激活值的精度。
选项: auto (默认), float16, bfloat16, float32。
建议: 现代显卡（Ampere架构及以后，如A100/H100/4090）强烈建议使用 bfloat16，它在保持精度的同时比float16更稳定，不易溢出。旧卡可用 float16。

quantization (-q)

含义: 量化方法。
详解: 指定权重量化格式以节省显存并加速。
选项: awq, gptq, fp8, bitsandbytes 等。
建议: 如果下载的是量化模型（如AWQ或GPTQ版本），必须显式指定此参数，否则可能加载失败或速度极慢。若未指定，vLLM会尝试从配置文件自动识别。

port & host

含义: 端口号 & 主机名。
详解: 服务监听的地址。
默认: --port 8000, --host (通常为0.0.0.0以便外部访问)。
建议: 生产环境通常不需要改端口，除非端口冲突。若需外网访问，确保 --host 设置为 0.0.0.0。

常用功能参数

根据具体业务场景（如多模态、LoRA、日志监控）选择性开启。

enable-auto-tool-choice

含义：启用自动工具选择。
详解：当用户的问题需要调用外部工具（如搜索、计算器、代码执行）时，模型会自动判断并生成调用工具的指令，而不需要你在代码层做复杂的逻辑判断。这是构建 Agent（智能体）的关键。

tool-call-parser

含义：工具调用解析器。
详解：不同的模型生成工具调用指令的格式不同（有的用 JSON，有的用特殊函数名）。这个参数告诉 vLLM 按照 qwen3_coder 定义的规则去"读懂"模型生成的工具调用代码，并将其转换为标准格式返回给你的程序。
可选值：deepseek_v3, glm45, granite-20b-fc, granite, hermes, hunyuan_a13b, internlm, jamba, kimi_k2, llama4_pythonic, llama4_json, llama3_json, minimax, mistral, phi4_mini_json, pythonic, qwen3_coder, xlam等

注意：--enable-auto-tool-choice --tool-call-parser qwen3_coder 这两个是成对配置的。

reasoning-parser

含义：推理解析器
详解：新一代的 Qwen 模型（如 Qwen3.5/Next）在输出复杂推理过程时，可能会包含特殊的格式标记（例如 ... 标签）。这个参数告诉 vLLM 如何正确解析这些特殊标记，确保返回给用户的最终答案是干净的，或者在流式输出时正确处理思维链部分。如果不加这个，可能会导致输出格式混乱或解析错误。可选值：deepseek_r1, glm45, granite, hunyuan_a13b, mistral, qwen3等

enable-prefix-caching

含义: 启用前缀缓存。
详解: 强烈推荐开启。对于重复的Prompt前缀（如系统提示词、长文档问答），vLLM会缓存计算结果，显著降低首字延迟（TTFT）并提高吞吐量。

max-num-seqs

含义: 最大并发序列数。
详解: 单个迭代中允许处理的最大序列数量。
建议: 默认值通常较小。在高并发场景下，适当调大此值可以提高吞吐量，但会增加显存压力。需结合 --gpu-memory-utilization 平衡。

max-num-batched-tokens

含义：单次迭代中要处理的最大令牌数。
详解：此配置没有静态默认值。如果用户未指定，它将在 EngineArgs.create_engine_config 中根据使用上下文进行设置。决定了在每一次 GPU 迭代（Iteration/Step）中，vLLM 最多允许同时处理多少个 Token（包括正在生成的输出 Token + 正在处理的输入 Prompt Token）。它不是限制单个请求的长度，而是限制同一时刻所有并发请求加在一起的总计算量。

enforce-eager

含义：是否始终使用 eager-mode PyTorch。
详解：如果为 True，我们将禁用 CUDA 图并始终以 eager 模式执行模型。如果为 False，我们将使用 CUDA 图和 eager 执行的混合模式，以实现最大的性能和灵活性。

enable-lora & --lora-modules

含义: 启用LoRA支持 & LoRA模块路径。
详解: 允许在基座模型上动态加载多个LoRA适配器，实现多任务切换而无需重启服务。需配合 --lora-modules 指定JSON映射（如 {"name1": "/path/to/lora1"}）。

chat-template

含义: 聊天模板。
详解: 指定用于处理对话格式的Jinja2模板文件路径。如果模型自带的tokenizer配置有误，或者你需要自定义对话格式，需手动指定。

api-key

含义: API密钥。
详解: 如果设置了此参数，客户端请求必须在Header中携带正确的Key才能访问，用于简单的身份验证。

disable-log-stats

含义: 禁用统计日志。
详解: 默认情况下vLLM会定期打印吞吐量、延迟等统计信息。若在容器化环境或需要纯净日志，可加此参数关闭。

trust-remote-code

含义: 信任远程代码。
详解: 当模型包含自定义的Python代码（非标准HuggingFace结构）时，必须添加此参数才能加载。出于安全考虑，仅在你信任模型来源时开启。

进阶/调试参数

以下参数除非你有非常特定的需求（如多机分布式、深度性能调优、特定硬件适配），否则通常保持默认即可。

前端与服务配置 (Frontend)

headless: 无头模式运行（用于多节点数据并行）。
config: 从YAML文件读取CLI选项。
shutdown-timeout: 关闭超时时间（秒）。
uvicorn-log-level: Uvicorn日志级别 (debug, info, warning等)。
ssl-keyfile / --ssl-certfile: SSL证书和密钥路径，用于启用HTTPS。
allowed-origins: 允许的跨域来源 (CORS)。
disable-fastapi-docs: 禁用Swagger UI和ReDoc文档页面。
enable-log-requests: 启用请求日志（记录请求ID、参数，Debug级别可记录Prompt内容）。

模型配置 (ModelConfig)

runner: 模型运行器类型 (generate, pooling等)，默认auto。
tokenizer: 指定独立的Tokenizer路径。
tokenizer-mode: Tokenizer模式 (auto, slow, mistral等)。
seed: 随机种子，保证复现性。
revision: 指定HuggingFace模型的分支、Tag或Commit ID。
max-logprobs: 返回的最大logprobs数量。
served-model-name: API中显示的模型名称（可与实际加载模型不同）。
hf-token: HuggingFace认证Token，用于下载私有模型。
generation-config: 生成配置文件路径。
enable-sleep-mode: 启用休眠模式（节省空闲时显存，仅支持CUDA/HIP）。

加载配置 (LoadConfig)

load-format: 权重加载格式 (auto, safetensors, pt, gguf, tensorizer等)。
download-dir: 模型下载缓存目录。
ignore-patterns: 加载时忽略的文件模式。
use-tqdm-on-load: 加载时显示进度条。

并行与分布式 (ParallelConfig)

pipeline-parallel-size (-pp): 流水线并行大小。
data-parallel-size (-dp): 数据并行大小。
distributed-executor-backend: 分布式后端 (ray, mp)。
enable-expert-parallel (-ep): 对MoE模型启用专家并行。
master-addr / --master-port: 多节点分布式的主节点地址和端口。
nnodes: 节点数量。

KV缓存配置 (CacheConfig)

block-size: 缓存块大小（token数）。
kv-cache-dtype: KV缓存的数据类型 (fp8, float16等)，用于进一步节省显存。
num-gpu-blocks-override: 强制指定GPU块数量（用于测试）。
prefix-caching-hash-algo: 前缀缓存的哈希算法 (sha256, xxhash)。
kv-offloading-size: KV缓存卸载到CPU的大小 (GiB)。

多模态配置 (MultiModalConfig)

limit-mm-per-prompt: 每个Prompt允许的多模态输入数量（图片、视频等）。
mm-processor-kwargs: 传递给多模态处理器的额外参数。
language-model-only: 仅启用语言模型部分，禁用多模态输入。

编译与内核 (Compilation & Kernel)

compilation-config (-cc): torch.compile和CUDA Graph的详细配置。
cudagraph-capture-sizes: 指定捕获CUDA Graph的batch size列表。
moe-backend: MoE专家计算的后端内核选择 (triton, cutlass, deep_gemm等)。
optimization-level: 优化级别 (-O0 到 -O3)，权衡启动时间和运行性能。
performance-mode: 性能模式 (balanced, interactivity, throughput)。

观测性 (Observability)

otlp-traces-endpoint: OpenTelemetry追踪发送地址。
enable-mfu-metrics: 启用MFU (Model FLOPs Utilization) 指标。
show-hidden-metrics-for-version: 显示已废弃但暂时保留的Prometheus指标。

调度器 (SchedulerConfig)

max-num-batched-tokens: 单次迭代处理的最大token数。
enable-chunked-prefill: 启用分块预填充（减少长Prompt对短请求的阻塞）。
scheduling-policy: 调度策略 (fcfs 先来先服务, priority 优先级)。

专家建议总结

起步命令: 对于大多数单卡用户，只需关注 --model, --gpu-memory-utilization, --dtype, --max-model-len。

python 复制代码

vllm serve Qwen/Qwen2.5-7B-Instruct \
  --dtype bfloat16 \
  --gpu-memory-utilization 0.9 \
  --max-model-len 32768 \
  --enable-prefix-caching

显存不足: 优先检查 --quantization 是否使用了量化模型，或调整 --gpu-memory-utilization 和 --max-model-len。
高并发: 开启 --enable-prefix-caching 和 --enable-chunked-prefill，并适当调大 --max-num-seqs。
多卡/大模型: 务必正确设置 -tp (张量并行) 或 -pp (流水线并行)。

举个栗子

我们就用Qwen3.5-35B-A3B-FP8官方给的启动命令作为示例：

以下命令将在 http://localhost:8000/v1 创建 API 端点：

标准版本：以下命令可用于在 8 个 GPU 上使用张量并行创建最大上下文长度为 262,144 个 token 的 API 端点。

VLLM_USE_MODELSCOPE=true vllm serve Qwen/Qwen3.5-35B-A3B --port 8000 --tensor-parallel-size 8 --max-model-len 262144 --reasoning-parser qwen3
工具调用：若要支持工具调用，可使用以下命令。

VLLM_USE_MODELSCOPE=true vllm serve Qwen/Qwen3.5-35B-A3B --port 8000 --tensor-parallel-size 8 --max-model-len 262144 --reasoning-parser qwen3 --enable-auto-tool-choice --tool-call-parser qwen3_coder
多 Token 预测（MTP）：推荐对 MTP 使用以下命令：

VLLM_USE_MODELSCOPE=true vllm serve Qwen/Qwen3.5-35B-A3B --port 8000 --tensor-parallel-size 8 --max-model-len 262144 --reasoning-parser qwen3 --speculative-config '{"method":"qwen3_next_mtp","num_speculative_tokens":2}'
纯文本模式：以下命令将跳过视觉编码器和多模态分析，以释放内存用于额外的 KV 缓存：

VLLM_USE_MODELSCOPE=true vllm serve Qwen/Qwen3.5-35B-A3B --port 8000 --tensor-parallel-size 8 --max-model-len 262144 --reasoning-parser qwen3 --language-model-only

我们只需要关注几个常用的参数，其他参数等实际用到的时候再去查。

常见的几种通用配置

生成模型

复制代码

vllm serve /mnt/models --served-model-name qwen3-xxx --dtype auto --trust-remote-code --max-model-len 32678 --enable-chunked-prefill --max-num-batched-tokens 8192 --enforce-eager --max-num-seqs 512

推理模型

复制代码

vllm serve /mnt/models --served-model-name deepseek-r1 --dtype auto --enable-reasoning --reasoning-parser deepseek_r1 --trust-remote-code --max-model-len 32678 --enable-chunked-prefill --max-num-batched-tokens 8192 --enforce-eager --max-num-seqs 64

多模态模型

复制代码

vllm serve /mnt/models --served-model-name deepsee-ocr --trust-remote-code --disable-log-stats --gpu-memory-utilization 0.85 --enforce-eager --limit_mm_per_prompt.images 2 --limit_mm_per_prompt.videos 2 --limit_mm_per_prompt.audios 2

reranker模型

复制代码

vllm serve /mnt/models --served-model-name qwen3-reranker-8b --hf-overrides {"architectures":["Qwen3ForSequenceClassification"],"classifier_from_token":["no","yes"],"is_original_qwen3_reranker":true}  --max-num-batched-tokens 4096 --enforce-eager --max-num-seqs 512

要支持function call则需要加上下面参数：

--enable-auto-tool-choice --tool-call-parser hermes

参考文献

https://docs.vllm.ai/en/latest/cli/serve/

https://www.modelscope.cn/models/lovedheart/Qwen3.5-35B-A3B-FP8