vllm 大模型推理框架

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

启动命令基本结构

bash

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

A. 核心模型参数

这些参数决定了加载哪个模型以及如何服务。

参数名	类型	默认值	说明
model	str	(必填)	要服务的模型标识符。可以是 Hugging Face 模型 ID（如 meta-llama/Llama-3.1-8B-Instruct）、本地模型路径、或 vLLM 支持的其他仓库的模型。
tokenizer	str	None	指定要使用的分词器。如果未设置，则使用与 model 相同的值。这在模型和分词器位于不同路径时有用。
tokenizer-mode	str	auto	指定如何加载分词器。选项：auto（自动检测）, slow（使用 Hugging Face 慢速但准确的分词器）。通常不需要更改。
trust-remote-code	action="store_true"	False	安全注意：是否信任远程代码（例如，从 Hugging Face 加载模型时，如果模型有自定义的 modeling_xxx.py 文件）。必须显式传递此参数才允许执行。
download-dir	str	None	下载模型和分词器的目录。默认为 Hugging Face 的缓存目录。
load-format	str	auto	模型的加载格式。选项：auto（自动）, pt（PyTorch weights）, safetensors（安全张量）, npcache（拆分后的张量缓存）, dummy（随机权重，用于基准测试）。
dtype	str	auto	模型权重的数据类型。选项：auto（自动）, half（float16）, bfloat16, float（float32）。为了性能和内存，通常使用 bfloat16 或 float16。
seed	int	0	随机数生成器的种子，用于可重复的采样。

---

B. 推理与性能参数

这些参数控制着生成文本的方式和质量。

参数名	类型	默认值	说明
max-model-len	int	None	重要：模型上下文窗口的最大长度（token 数）。如果不指定，vLLM 会尝试从模型配置自动检测，但有时会出错，导致 OOM。如果遇到 OOM，应手动设置一个更小的值。
gpu-memory-utilization	float	0.9	重要：GPU 内存利用率。介于 0 和 1 之间。如果遇到 CUDA OOM 错误，可以降低此值（如 0.8），为系统预留更多内存。
swap-space	float	4	CPU 和 GPU 之间交换的存储空间大小（GiB）。当 GPU 内存不足时，使用 CPU 内存作为交换空间。
pipeline-parallel-size	int	1	分布式：流水线并行（PP）大小。用于跨多个 GPU 对模型层进行拆分。
tensor-parallel-size	int	1	分布式：张量并行（TP）大小。用于将单个层的权重拆分到多个 GPU 上。对于大模型（如 70B+）至关重要。
block-size	int	16	PagedAttention 关键参数：KV Cache 中每个块（block）的 token 数量。通常不需要修改，除非进行深度优化。
max-num-batched-tokens	int	None	一次预填充操作中 token 数量的上限。可用于防止单个巨大请求影响整个系统的吞吐量。
max-num-seqs	int	256	最大并发请求数（序列数）。如果收到的请求超过此值，将被排队。
max-paddings	int	256	最大填充数量。当启用动态批处理时，为了对齐序列而添加的填充 token 数上限。
max-lora-rank	int	16	最大 LoRA 适配器的秩（rank）。
max-cpu-loras	int	4	保留在 CPU 内存中的 LoRA 适配器的最大数量。

---

C. 调度与优化参数

这些参数控制着 vLLM 的核心调度器。

参数名	类型	默认值	说明
scheduler	str	vllm	重要：调度策略。选项：vllm（默认，最优吞吐量）, fcfs（先到先服务，最优延迟）。
disable-log-stats	action="store_true"	False	禁用日志统计。
log-requests	action="store_true"	False	记录所有收到的请求。用于调试。
quantization	str	None	量化方法。选项：awq（激活感知权重量化）, squeezellm, gptq, fp8（实验性）等。用于减少显存占用，提高推理速度。
enforce-eager	action="store_true"	False	强制使用 eager 模式而不是 CUDA graph。用于调试或某些不兼容 CUDA graph 的模型。
max-log-len	int	None	请求日志的最大长度。

---

D. API 服务器参数

这些参数控制着 API 服务器本身的行为。

参数名	类型	默认值	说明
host	str	0.0.0.0	API 服务器绑定的网络地址。0.0.0.0 表示监听所有网络接口。
port	int	8000	API 服务器监听的端口。
uvicorn-log-level	str	info	Uvicorn 服务器的日志级别。选项：debug, info, warning, error, critical。
allowed-origins	list	["*"]	安全：允许的 CORS 源。可以传入一个 URL 列表来限制哪些前端可以访问 API。默认 ["*"] 允许所有，生产环境应限制。
allowed-methods	list	["*"]	安全：允许的 HTTP 方法。
allowed-headers	list	["*"]	安全：允许的 HTTP 头。
served-model-name	str	None	在 OpenAI API 响应中返回的模型名称。如果未设置，则使用 model 参数的值。
chat-template	str	None	与模型一起使用的聊天模板的路径。如果不指定，vLLM 将尝试从分词器自动加载。
response-role	str	assistant	聊天响应中使用的默认角色。通常不需要修改。
ssl-keyfile	str	None	SSL 密钥文件路径（.key），用于启用 HTTPS。
ssl-certfile	str	None	SSL 证书文件路径（.crt），用于启用 HTTPS。
root-path	str	None	设置 ASGI 根路径，当服务器位于代理之后时有用。

---

E. 工具调用相关参数

参数名	类型	默认值	说明
enable-auto-tool-choice	action="store_true"	False	启用后，模型可以自主决定是否需要调用工具。
tool-call-parser	str	auto	指定如何解析模型输出的工具调用。选项：auto, json, grammar。

---

完整示例命令

结合以上参数，一个典型的生产环境启动命令可能如下所示：

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --host 0.0.0.0 \
    --port 8000 \
    --tensor-parallel-size 2 \          # 在两个 GPU 上张量并行
    --gpu-memory-utilization 0.85 \     # 预留一些 GPU 内存给系统
    --max-model-len 8192 \              # 限制上下文长度以防止 OOM
    --max-num-seqs 128 \                # 限制最大并发请求数
    --scheduler vllm \                  # 使用 vLLM 调度器以获得高吞吐
    --dtype bfloat16 \                  # 使用 bfloat16 节省显存
    --trust-remote-code \               # 允许加载自定义模型代码
    --enforce-eager \                   # 如果遇到 CUDA graph 问题则启用
    --allowed-origins "https://myapp.com" "https://staging.myapp.com" # 限制 CORS
    --enable-auto-tool-choice           # 启用自动工具调用