vLLM Serve 参数详解

🔧 `vllm serve` 参数详解

🎯 这是 vLLM 的生产级服务启动命令，把模型变成 OpenAI 兼容的 API 服务，支持并发请求、多卡并行、量化加速等所有高级功能。

🆚 和 bench 系列的区别：

bench latency/throughput → 实验室测引擎性能（无网络）

bench serve → 模拟真实用户压测（含网络）

serve → 真正上线跑服务（处理真实请求）

📋 参数分类速览

复制代码

🔹 基础运行：--host / --port / --api-key / --config
🔹 模型配置：--model / --dtype / --quantization / --max-model-len
🔹 并行加速：-tp / -pp / -dp / --distributed-executor-backend
🔹 KV缓存：--block-size / --gpu-memory-utilization / --enable-prefix-caching
🔹 多模态：--limit-mm-per-prompt / --mm-processor-kwargs
🔹 LoRA：--enable-lora / --max-loras / --max-lora-rank
🔹 调度优化：--max-num-batched-tokens / --enable-chunked-prefill
🔹 编译加速：--compilation-config / --optimization-level
🔹 日志监控：--enable-log-requests / --otlp-traces-endpoint

🚀 一、基础运行参数（启动服务必备！）

🔹 核心参数表

参数	默认值	解释	典型取值
`--host`	`127.0.0.1`	服务监听哪个网卡地址	`0.0.0.0`（所有网卡）/ `192.168.1.100`（内网）
`--port`	`8000`	服务监听哪个端口	`8000`（默认）/ `8080`（避免冲突）
`--api-key`	-	API 访问密钥，保护服务安全	`--api-key sk-xxx`（生产环境必填）
`--config`	-	从 YAML 文件读取所有配置	`--config serve_config.yaml`（复杂配置推荐）
`--disable-log-stats`	`False`	是否关闭控制台性能日志	`--disable-log-stats`（自动化部署时用）

🔹 场景示例 1：本地开发测试

🎯 业务场景：刚写完代码，想在本地快速启动服务调试

bash 复制代码

# 🧪 直接复制运行：
vllm serve \
  --model meta-llama/Llama-3-8b \
  --host 127.0.0.1 \      # ✅ 只允许本机访问，安全
  --port 8000 \           # ✅ 默认端口
  --dtype bfloat16        # ✅ A100 推荐精度

🌐 访问方式：

bash 复制代码

# 测试聊天接口
curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3-8b",
    "messages": [{"role": "user", "content": "你好"}],
    "max_tokens": 100
  }'

🔹 场景示例 2：生产环境部署（带安全认证）

🎯 业务场景：服务要上线给团队使用，需要权限控制 + 外网访问

bash 复制代码

vllm serve \
  --model meta-llama/Llama-3-8b \
  --host 0.0.0.0 \              # ✅ 允许所有网卡访问
  --port 8080 \                 # ✅ 用非标准端口避免冲突
  --api-key sk-abc123xyz \      # ✅ 必填！客户端请求要带这个密钥
  --dtype bfloat16 \
  --gpu-memory-utilization 0.9  # ✅ 留 10% 显存给系统

🔐 客户端调用示例：

bash 复制代码

curl http://your-server:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-abc123xyz" \  # ✅ 必须带 API Key
  -H "Content-Type: application/json" \
  -d '{"model": "meta-llama/Llama-3-8b", "messages": [...]}'

💡 安全建议：

生产环境必须设置 --api-key

配合 Nginx 做 HTTPS + 限流 + IP 白名单

用 --allowed-origins 限制 CORS 来源

⚙️ 二、模型配置参数（加载模型的关键！）

🔹 核心参数表

参数	默认值	解释	典型取值
`--model`	`Qwen/Qwen3-0.6B`	模型名称或本地路径	`meta-llama/Llama-3-8b` / `./models/my-model`
`--tokenizer`	-	指定 tokenizer（默认同 model）	`--tokenizer ./my-tokenizer`
`--dtype`	`auto`	模型精度：float16 / bfloat16 / float32	`bfloat16`（A100）/ `float16`（V100/4090）
`--quantization`, `-q`	-	量化方法：awq / gptq / fp8	`-q awq`（4bit 量化，速度快）
`--max-model-len`	自动	最大上下文长度	`4096`（短对话）/ `32768`（长文档）
`--runner`	`auto`	模型用途：生成/嵌入/草稿	`auto`（默认）/ `generate`（生成）/ `pooling`（嵌入）

🔹 场景示例 1：消费级显卡跑大模型

🎯 业务场景：只有 1 张 RTX 4090（24GB 显存），想部署 Llama-3-8B

bash 复制代码

vllm serve \
  --model meta-llama/Llama-3-8b \
  --dtype float16 \                 # ✅ 4090 不支持 bfloat16
  --quantization awq \              # ✅ 4bit 量化，显存减半
  --max-model-len 4096 \            # ✅ 限制长度，省显存
  --gpu-memory-utilization 0.85 \   # ✅ 留 15% 给系统防崩溃
  --host 0.0.0.0 \
  --port 8000

💡 显存估算技巧：

8B 模型 float16 ≈ 16GB

AWQ 4bit 量化 ≈ 5GB

KV cache（4K 上下文）≈ 2GB

✅ 总计 ≈ 7GB < 24GB → 安全！

🔹 场景示例 2：部署嵌入模型（非生成任务）

🎯 业务场景：用 BGE-M3 做向量检索服务，用户发文本，返回 embedding

bash 复制代码

vllm serve \
  --model BAAI/bge-m3 \
  --runner pooling \           # ✅ 关键！声明这是嵌入模型
  --dtype float16 \
  --host 0.0.0.0 \
  --port 8001                  # ✅ 用不同端口区分服务

🔍 调用示例（获取向量）：

bash 复制代码

curl http://localhost:8001/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "BAAI/bge-m3",
    "input": "今天天气真好"
  }'
# 返回：{"data": [{"embedding": [0.123, -0.456, ...]}]}

💡 注意：嵌入模型不能用 --runner generate，否则会报错！

🚀 三、并行加速参数

🔹 参数表

参数	缩写	解释	典型取值
`--tensor-parallel-size`	`-tp`	把模型切到多张卡上算（适合大模型）	`-tp 2`（2 卡）/ `-tp 4`（4 卡）
`--pipeline-parallel-size`	`-pp`	把模型分层，不同卡算不同层（适合超大模型）	`-pp 2`（80B+ 模型）
`--data-parallel-size`	`-dp`	复制多份模型，同时处理不同请求（适合高并发）	`-dp 4`（4 副本）
`--distributed-executor-backend`	-	分布式后端：`mp`(单机)/`ray`(多机)	`mp`（默认）/ `ray`（多机集群）

🔹 场景示例：2 卡部署 70B 大模型

🎯 业务场景：Llama-3-70B 单卡跑不动，用 2 张 A100（80GB）张量并行

bash 复制代码

vllm serve \
  --model meta-llama/Llama-3-70b \
  -tp 2 \                        # ✅ 2 卡张量并行
  --dtype bfloat16 \
  --gpu-memory-utilization 0.9 \
  --host 0.0.0.0 \
  --port 8000

📊 效果对比（示例）：

配置显存占用/卡单请求延迟是否可行

单卡 80GB 75GB ❌ OOM 崩溃 ❌ 不可行

2 卡 TP 40GB/卡 3.2 秒 ✅ 可上线

4 卡 TP 22GB/卡 1.8 秒 ✅ 更优（资源够的话）

配置	显存占用/卡	单请求延迟	是否可行
单卡 80GB	75GB	❌ OOM 崩溃	❌ 不可行
2 卡 TP	40GB/卡	3.2 秒	✅ 可上线
4 卡 TP	22GB/卡	1.8 秒	✅ 更优（资源够的话）

💡 选择建议：

模型 ≤ 13B → 单卡足够

模型 30~70B → 2~4 卡 TP

模型 ≥ 100B → TP+PP 组合 + Ray 后端

🧠 四、KV Cache 配置参数

🔹 参数表

参数	默认值	解释	优化效果
`--block-size`	自动	KV cache 分块大小（1/8/16/32/64）	16（省显存）/ 32（平衡）/ 64（快）
`--gpu-memory-utilization`	`0.9`	用多少比例显存给模型	0.85（稳）/ 0.95（极限）
`--kv-cache-dtype`	`auto`	KV cache 精度	`fp8`（省 50% 显存）/ `bfloat16`（准）
`--enable-prefix-caching`	`False`	相同开头的问题，复用已算的 KV	多轮对话提速 30%+
`--swap-space`	`4`	CPU 交换空间大小（显存不够时借用）	8~16（大模型建议调大）

🔹 场景示例：多轮对话优化

🎯 业务场景：用户连续问"北京天气？""那上海呢？"，每轮只改城市名

bash 复制代码

vllm serve \
  --model meta-llama/Llama-3-8b \
  --enable-prefix-caching \    # ✅ 开启前缀缓存
  --block-size 16 \            # ✅ 小 block 更适合缓存复用
  --kv-cache-dtype fp8 \       # ✅ KV cache 用 fp8，再省 50% 显存
  --gpu-memory-utilization 0.9 \
  --host 0.0.0.0 \
  --port 8000

📊 效果（示例）：

轮次无前缀缓存延迟有前缀缓存延迟加速比

第 1 轮 1.2 秒 1.2 秒 1.0x

第 2 轮 1.2 秒 0.4 秒 3.0x 🔥

第 3 轮 1.2 秒 0.3 秒 4.0x 🔥

轮次	无前缀缓存延迟	有前缀缓存延迟	加速比
第 1 轮	1.2 秒	1.2 秒	1.0x
第 2 轮	1.2 秒	0.4 秒	3.0x 🔥
第 3 轮	1.2 秒	0.3 秒	4.0x 🔥

💡 适用场景：

✅ 多轮对话 / 代码补全 / 文档续写

❌ 每个请求完全独立（如批量翻译）

📚 五、调度器参数（让服务更智能！）

🔹 参数表

参数	默认值	解释	典型取值
`--max-num-batched-tokens`	-	单次迭代最多处理多少 token	`8192`（小模型）/ `32768`（大模型）
`--max-num-seqs`	-	单次迭代最多处理多少个请求	`128`（低并发）/ `512`（高并发）
`--enable-chunked-prefill`	`False`	长 prompt 分块预填充，减少首字延迟	`--enable-chunked-prefill`（长文本推荐）
`--scheduling-policy`	`fcfs`	调度策略：先来先服务 / 优先级	`priority`（VIP 用户优先）

🔹 场景示例：优化长文档首字延迟

🎯 业务场景：用户上传 1 万字文档让模型总结，不想让用户等太久才看到第一个字

bash 复制代码

vllm serve \
  --model meta-llama/Llama-3-8b \
  --max-model-len 32768 \           # ✅ 支持长上下文
  --enable-chunked-prefill \        # ✅ 关键！长 prompt 分块处理
  --max-num-batched-tokens 16384 \  # ✅ 控制每批处理量
  --max-num-seqs 32 \               # ✅ 限制并发请求数
  --host 0.0.0.0 \
  --port 8000

💡 原理：

不开 chunked-prefill：1 万字 prompt 要全部算完才返回第一个字 → 用户等 5 秒

开启后：每算 2000 token 就返回一些 → 用户 1 秒内看到第一个字，体验大幅提升！

🎨 六、高级功能参数

🔹 LoRA 适配（多任务微调）

🎯 场景：主模型 + 多个行业 LoRA（医疗/法律/金融），动态切换

bash 复制代码

vllm serve \
  --model meta-llama/Llama-3-8b \
  --enable-lora \
  --max-loras 4 \              # 同时加载 4 个 LoRA
  --max-lora-rank 64 \         # LoRA 的 rank
  --lora-modules medical=/path/to/medical_lora,legal=/path/to/legal_lora \
  --host 0.0.0.0 \
  --port 8000

🔍 调用示例（指定 LoRA）：

bash 复制代码

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3-8b",
    "messages": [...],
    "extra_body": {"lora_request": {"lora_name": "medical"}}
  }'

🔹 多模态支持（图文/视频理解）

🎯 场景：部署 Qwen-VL，支持用户上传图片提问

bash 复制代码

vllm serve \
  --model Qwen/Qwen2-VL-7B-Instruct \
  --limit-mm-per-prompt '{"image": 4}' \       # ✅ 每请求最多 4 张图
  --mm-processor-kwargs '{"num_crops": 4}' \   # ✅ 图片裁剪参数
  --max-model-len 8192 \
  --host 0.0.0.0 \
  --port 8000

🔍 调用示例（图文问答）：

bash 复制代码

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2-VL-7B-Instruct",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}},
        {"type": "text", "text": "这是什么猫？"}
      ]
    }]
  }'

🔹 编译优化（极致性能）

🎯 场景：追求极致吞吐，启用 torch.compile + CUDA Graph

bash 复制代码

vllm serve \
  --model meta-llama/Llama-3-8b \
  --optimization-level 3 \     # ✅ 最高优化级别
  -cc '{"mode": 3, "cudagraph_capture_sizes": [1,2,4,8,16,32]}' \  # ✅ 自定义 CUDA 图
  --host 0.0.0.0 \
  --port 8000

⚠️ 注意：首次启动会慢（编译开销），但后续推理更快 → 适合长期运行的服务

📊 七、可观测性参数（监控+调试）

🔹 参数表

参数	默认值	解释	使用场景
`--enable-log-requests`	`False`	记录每个请求的详细信息（ID/参数/LoRA）	调试问题、审计日志
`--otlp-traces-endpoint`	-	发送追踪数据到 OpenTelemetry 后端	接入 Jaeger/Prometheus 监控
`--disable-log-stats`	`False`	关闭控制台性能日志	自动化部署/日志集中收集
`--uvicorn-log-level`	`info`	控制框架日志级别	`debug`（调试）/ `warning`（生产）

🔹 场景示例：接入 Prometheus 监控

🎯 业务场景：运维团队需要监控服务性能指标（QPS/延迟/显存）

bash 复制代码

vllm serve \
  --model meta-llama/Llama-3-8b \
  --host 0.0.0.0 \
  --port 8000 \
  --disable-log-stats \              # ✅ 关闭控制台日志，避免重复
  --uvicorn-log-level warning        # ✅ 只记录警告以上日志

🔍 获取指标：

bash 复制代码

# 访问 /metrics 端点（默认开启）
curl http://localhost:8000/metrics

# 输出示例：
# vllm:num_requests_running 3
# vllm:gpu_cache_usage_perc 0.75
# vllm:time_to_first_token_seconds_sum 2.34

💡 配置 Prometheus：

yaml 复制代码

# prometheus.yml
scrape_configs:
  - job_name: 'vllm'
    static_configs:
      - targets: ['your-server:8000']
    metrics_path: '/metrics'

🚀 完整实战工作流

🎯 目标：部署智能客服服务

bash 复制代码

#!/bin/bash
# deploy_chatbot.sh

MODEL="meta-llama/Llama-3-8b-Instruct"
API_KEY="sk-chatbot-prod-2026"

echo "🚀 启动 vLLM 服务..."

vllm serve \
  --model $MODEL \
  \
  # 🔐 安全配置
  --host 0.0.0.0 \
  --port 8000 \
  --api-key $API_KEY \
  --allowed-origins "https://your-app.com" \
  \
  # ⚙️ 模型配置
  --dtype bfloat16 \
  --quantization awq \
  --max-model-len 4096 \
  --gpu-memory-utilization 0.9 \
  \
  # 🧠 缓存优化
  --enable-prefix-caching \
  --block-size 16 \
  --kv-cache-dtype fp8 \
  \
  # 📚 调度优化
  --max-num-batched-tokens 8192 \
  --max-num-seqs 128 \
  --enable-chunked-prefill \
  \
  # 📊 监控配置
  --disable-log-stats \
  --uvicorn-log-level warning \
  \
  # 🎨 高级功能
  --enable-lora \
  --max-loras 2 \
  --lora-modules "finance=/models/lora-finance,tech=/models/lora-tech" \
  \
  # 🔧 编译优化
  --optimization-level 2 \
  -cc '{"mode": 2}'

✅ 上线后验证：

bash 复制代码

# 1️⃣ 健康检查
curl http://localhost:8000/health

# 2️⃣ 测试聊天（带 API Key）
curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3-8b-Instruct",
    "messages": [{"role": "user", "content": "怎么退款？"}],
    "max_tokens": 200
  }'

# 3️⃣ 查看指标
curl http://localhost:8000/metrics | grep "vllm:num_requests"

⚠️ 常见问题速查表

问题现象	可能原因	解决方案
❌ `CUDA out of memory`	batch 太大 / 模型太长 / 精度太高	↓ `--max-model-len` / 加 `-q awq` / ↓ `--gpu-memory-utilization`
🐢 首次启动极慢	模型加载 + CUDA 图编译	正常！后续请求会快；或加 `--optimization-level 1` 减少编译
🔐 401 Unauthorized	没带 API Key 或 Key 错误	检查 `--api-key` 设置 + 客户端 `Authorization: Bearer xxx`
🌐 无法外网访问	`--host` 设成了 127.0.0.1	改成 `--host 0.0.0.0` + 检查防火墙
🔁 量化模型报错	量化格式不匹配 / 缺依赖	确认模型支持该量化 + `pip install autoawq bitsandbytes`
🧩 LoRA 不生效	没设 `--enable-lora` 或路径错误	检查 `--lora-modules` 格式 + 确认 LoRA 文件存在

🎁 最后 Checklist：

✅ 生产环境必须设 --api-key + --host 0.0.0.0

✅ 显存紧张时优先试 --kv-cache-dtype fp8 + --enable-prefix-caching

✅ 长文本场景必加 --enable-chunked-prefill

✅ 多卡部署前确认 nvidia-smi 能看到所有 GPU + 设 -tp

✅ 首次启动慢是正常的，预热后性能会稳定

vLLM Serve 参数详解

🔧 vllm serve 参数详解

📋 参数分类速览

🚀 一、基础运行参数（启动服务必备！）

🔹 核心参数表

🔹 场景示例 1：本地开发测试

🔹 场景示例 2：生产环境部署（带安全认证）

⚙️ 二、模型配置参数（加载模型的关键！）

🔹 核心参数表

🔹 场景示例 1：消费级显卡跑大模型

🔹 场景示例 2：部署嵌入模型（非生成任务）

🚀 三、并行加速参数

🔹 参数表

🔹 场景示例：2 卡部署 70B 大模型

🧠 四、KV Cache 配置参数

🔹 参数表

🔹 场景示例：多轮对话优化

📚 五、调度器参数（让服务更智能！）

🔹 参数表

🔹 场景示例：优化长文档首字延迟

🎨 六、高级功能参数

🔹 LoRA 适配（多任务微调）

🔹 多模态支持（图文/视频理解）

🔹 编译优化（极致性能）

📊 七、可观测性参数（监控+调试）

🔹 参数表

🔹 场景示例：接入 Prometheus 监控

🚀 完整实战工作流

🎯 目标：部署智能客服服务

⚠️ 常见问题速查表

🔧 `vllm serve` 参数详解