vllm 大模型推理框架

vLLM 通过命令行工具 python -m vllm.entrypoints.api_server 启动 OpenAI 兼容的 API 服务器，其参数涵盖了模型加载、推理、调度和服务的各个方面。

启动命令基本结构

bash

python -m vllm.entrypoints.api_server \--model <model_name_or_path> \[其他参数]

---

核心参数分类详解

1. 模型加载参数

 

参数	默认值	说明
--model	必填	模型名称或路径（Hugging Face 模型ID或本地路径）。
--tokenizer	None	可选，单独指定 tokenizer 的名称或路径。如果未指定，则使用 --model 的值。
--tokenizer-mode	auto	Tokenizer 加载模式。auto（自动）, slow（使用HF慢速tokenizer）。
--trust-remote-code	False	重要：如果模型需要自定义代码（如某些国产模型），必须添加此参数以信任远程代码。
--download-dir	None	模型下载的缓存目录。
--load-format	auto	模型权重加载格式。auto， dummy（随机权重，用于测试）， safetensors（强制使用 safetensors）， npcache（串行缓存）， tensorizer。
--seed	0	随机数种子，用于可复现性。

2. 推理与调度参数（性能关键）

参数	默认值	说明
--tensor-parallel-size	1	张量并行的GPU数量。用于将模型层拆分到多个GPU上。例如，对于 7B/8B 模型，通常设为 1；对于 70B 模型，可设为 4 或 8。
--block-size	16	PagedAttention 的块大小。通常保持默认即可，调整它可能影响内存碎片和性能。
--swap-space	4	GPU显存不足时，用于交换到CPU内存的空间大小（GB）。
--gpu-memory-utilization	0.9	GPU显存利用率（0到1之间）。例如 0.9 表示使用 90% 的GPU显存。如果遇到 OOM，可以适当调高。
--max-num-batched-tokens	None	一次前向传播中最大批处理的 token 数。vLLM 会自动调整，但可以手动设置以控制延迟。
--max-num-seqs	256	最大并发序列数（批大小）。如果请求排队严重，可以适当增大；如果显存小，可以减小。
--max-model-len	None	手动指定模型上下文长度。vLLM 通常会从模型配置中读取，但如果读取失败或你想覆盖，可以用此参数。
--enforce-eager	False	强制使用 eager 模式而非 CUDA graph。会降低性能，但用于调试。

3. 服务与API参数

 

参数	默认值	说明
--host	0.0.0.0	API 服务器监听的主机地址。0.0.0.0 表示监听所有网络接口。
--port	8000	API 服务器监听的端口。
--uvicorn-log-level	info	Uvicorn 服务器的日志级别。debug, info, warning, error, critical。
--api-key	None	可选，设置 API 密钥以启用认证。如果设置，客户端必须在 Authorization 头中提供 Bearer <api-key>。
--root-path	None	在代理后面运行时，设置应用的根路径。

4. 量化与优化参数

参数	默认值	说明
--quantization	None	量化方法。例如 awq（对于支持的 AWQ 量化模型）, gptq, squeezellm, fp8（H100等支持）。
--dtype	auto	模型计算的数据类型。auto（自动从权重推断）, half（torch.float16）, bfloat16, float（torch.float32）。
--revision	None	指定加载的模型版本（git revision，如分支名或commit id）。

---

完整示例

示例 1：基础启动（7B模型，单卡）

bash

python -m vllm.entrypoints.api_server \--model Qwen/Qwen2.5-7B-Instruct \--tokenizer-mode auto \--trust-remote-code \--host 0.0.0.0 \--port 8000

示例 2：多GPU张量并行 + 高并发配置

bash

python -m vllm.entrypoints.api_server \--model Qwen/Qwen2.5-72B-Instruct \--tokenizer Qwen/Qwen2.5-72B-Instruct \--tensor-parallel-size 4 \--gpu-memory-utilization 0.95 \--max-num-seqs 512 \--trust-remote-code \--host 0.0.0.0 \--port 8000

示例 3：使用 AWQ 量化模型以节省显存

bash

python -m vllm.entrypoints.api_server \--model lmsys/vicuna-7b-v1.5-awq \--quantization awq \--gpu-memory-utilization 0.8

示例 4：设置API密钥和自定义上下文长度

bash

python -m vllm.entrypoints.api_server \--model meta-llama/Llama-3.1-8B-Instruct \--max-model-len 8192 \--api-key "your-secret-token-123" \--host 127.0.0.1