vLLM Serve 命令参数详解
简介
vllm serve 命令用于启动 vLLM 的 OpenAI 兼容 API 服务器，通过 REST API 与大型语言模型交互。
基本用法
vllm serve [model_tag] [选项]
核心参数
模型配置
| 参数 | 说明 |
|---|
--model MODEL | 使用的 Hugging Face 模型名称或路径，默认为 facebook/opt-125m |
--model-tag MODEL_TAG | 模型标签（如果在配置中未指定则为可选） |
--revision REVISION | 特定的模型版本（分支名、标签名或提交 ID） |
--served-model-name SERVED_MODEL_NAME | API 中使用的模型名称，可提供多个名称 |
服务器配置
| 参数 | 说明 |
|---|
--host HOST | 主机名 |
--port PORT | 端口号，默认为 8000 |
--api-key API_KEY | 如果提供，服务器将要求在请求头中提供此密钥 |
--disable-log-requests | 禁用请求日志记录 |
--disable-log-stats | 禁用统计日志 |
--disable-uvicorn-access-log | 禁用 uvicorn 访问日志 |
模型执行配置
| 参数 | 说明 |
|---|
--dtype {auto,half,float16,bfloat16,float,float32} | 模型权重和激活的数据类型，auto 会为 FP32/FP16 模型使用 FP16，为 BF16 模型使用 BF16 |
--max-model-len MAX_MODEL_LEN | 模型上下文长度，如未指定，会从模型配置自动推导 |
--max-num-batched-tokens MAX_NUM_BATCHED_TOKENS | 每次迭代的最大批处理令牌数 |
--max-num-seqs MAX_NUM_SEQS | 每次迭代的最大序列数 |
--gpu-memory-utilization GPU_MEMORY_UTILIZATION | GPU 内存使用率（0-1），默认为 0.9 |
分布式执行配置
| 参数 | 说明 | 简写 |
|---|
--tensor-parallel-size TENSOR_PARALLEL_SIZE | 张量并行组的数量 | -tp |
--pipeline-parallel-size PIPELINE_PARALLEL_SIZE | 流水线并行组的数量 | -pp |
--data-parallel-size DATA_PARALLEL_SIZE | 数据并行组的数量 | -dp |
量化配置
| 参数 | 说明 | 简写 |
|---|
--quantization {aqlm,awq,gptq,...,None} | 权重量化方法 | -q |
--kv-cache-dtype {auto,fp8,fp8_e5m2,fp8_e4m3} | KV 缓存的数据类型，auto 将使用模型数据类型 | |
模型加载配置
| 参数 | 说明 |
|---|
--load-format {auto,pt,safetensors,npcache,dummy,tensorizer,...} | 加载模型权重的格式 |
--download-dir DOWNLOAD_DIR | 下载和加载权重的目录，默认使用 Hugging Face 的默认缓存目录 |
--trust-remote-code | 信任来自 Hugging Face 的远程代码 |
LoRA 配置
| 参数 | 说明 |
|---|
--enable-lora | 启用 LoRA 适配器处理 |
--max-loras MAX_LORAS | 单个批次中的最大 LoRA 数量 |
--max-lora-rank MAX_LORA_RANK | 最大 LoRA 秩 |
--lora-modules LORA_MODULES | LoRA 模块配置，格式为 name=path 或 JSON 格式 |
高级功能配置
特殊功能配置
| 参数 | 说明 |
|---|
--chat-template CHAT_TEMPLATE | 聊天模板的文件路径或单行形式 |
--generation-config GENERATION_CONFIG | 生成配置的文件夹路径，默认为 auto |
--enable-auto-tool-choice | 为支持的模型启用自动工具选择 |
--enable-reasoning | 启用模型的推理内容生成能力 |
多模态支持
| 参数 | 说明 |
|---|
--allowed-local-media-path ALLOWED_LOCAL_MEDIA_PATH | 允许 API 请求从服务器文件系统指定的目录读取本地图像或视频 |
--limit-mm-per-prompt LIMIT_MM_PER_PROMPT | 每个提示允许的每个多模态插件的输入实例数量限制 |
--mm-processor-kwargs MM_PROCESSOR_KWARGS | 多模态输入映射/处理的覆盖参数，例如图像处理器 |
性能优化
| 参数 | 说明 |
|---|
--enable-chunked-prefill | 启用基于 max_num_batched_tokens 的分块预填充 |
--enable-prefix-caching | 启用自动前缀缓存 |
--cpu-offload-gb CPU_OFFLOAD_GB | 每个 GPU 卸载到 CPU 的空间大小（GiB），默认为 0，表示不卸载 |
--swap-space SWAP_SPACE | 每个 GPU 的 CPU 交换空间大小（GiB），默认为 4 |
配置文件
| 参数 | 说明 |
|---|
--config CONFIG | 从 YAML 格式的配置文件读取 CLI 选项 |
使用示例
基本服务启动
vllm serve --model meta-llama/Llama-2-7b-chat-hf --host 0.0.0.0 --port 8000
使用量化模型
vllm serve --model meta-llama/Llama-2-13b-chat-hf --quantization awq
多 GPU 分布式部署
vllm serve --model meta-llama/Llama-2-70b-chat-hf --tensor-parallel-size 4
配置最大批处理参数
vllm serve --model meta-llama/Llama-2-7b-chat-hf --max-num-batched-tokens 8192 --max-num-seqs 128
启用 LoRA
vllm serve --model meta-llama/Llama-2-7b-chat-hf --enable-lora --max-loras 4
指定生成参数配置
vllm serve --model meta-llama/Llama-2-7b-chat-hf --override-generation-config '{"temperature": 0.7, "top_p": 0.9}'
使用特定的聊天模板
vllm serve --model meta-llama/Llama-2-7b-chat-hf --chat-template path/to/template.jinja
启用多模态支持
vllm serve --model llava-hf/llava-1.5-7b-hf --allowed-local-media-path /path/to/images
