vLLM 通过命令行工具 python -m vllm.entrypoints.api_server 启动 OpenAI 兼容的 API 服务器，其参数涵盖了模型加载、推理、调度和服务的各个方面。
启动命令基本结构
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模型，单卡）
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张量并行 + 高并发配置
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 量化模型以节省显存
python -m vllm.entrypoints.api_server \--model lmsys/vicuna-7b-v1.5-awq \--quantization awq \--gpu-memory-utilization 0.8
示例 4：设置API密钥和自定义上下文长度
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
