LLM工程化实践——vLLM serve 命令行参数详细总结

vLLM serve 命令行参数详细总结vllm serve是 vLLM 框架提供的模型服务启动命令支持灵活配置模型加载、服务部署、并行执行、缓存优化等核心能力以下按功能模块整理关键参数及用法。一、JSON CLI 参数传递规则支持两种等效的 JSON 参数传递方式列表类型可通过拼接完整 JSON 字符串形式\--json-arg {key1: value1, key2: {key3: value2}} \--json-arg {key4: \[value3, value4, value5]}分层键值对形式\--json-arg.key1 value1 --json-arg.key2.key3 value2 \--json-arg.key4 value3 --json-arg.key4value4,value5二、基础服务配置参数说明默认值--headless无头模式运行适用于多节点数据并行场景False--api-server-count (-asc)API 服务器进程数未指定时默认等于data_parallel_size---config从 YAML 配置文件读取参数配置项参考官方链接---disable-log-stats禁用统计日志False--aggregate-engine-logging数据并行时记录聚合统计而非单引擎统计False--enable-log-requests启用请求日志记录INFO 级记录请求 ID / 参数DEBUG 级记录提示文本False三、前端服务配置OpenAI 兼容1. 基础网络配置参数说明默认值--host服务主机名---port服务端口8000--udsUnix 域套接字路径设置后忽略 host/port---api-key访问密钥需在请求头中携带-2. 安全与跨域配置参数说明默认值--ssl-keyfileSSL 密钥文件路径---ssl-certfileSSL 证书文件路径---allowed-origins允许的跨域源[*]--allowed-methods允许的 HTTP 方法[*]--allowed-headers允许的请求头[*]3. 日志与文档配置参数说明默认值--uvicorn-log-levelUvicorn 日志级别可选critical/debug/error/info/trace/warninginfo--disable-uvicorn-access-log禁用 Uvicorn 访问日志False--disable-access-log-for-endpoints排除指定端点的访问日志例“/health,/metrics”---disable-fastapi-docs禁用 FastAPI 文档OpenAPI/Swagger UI/ReDocFalse--enable-offline-docs启用离线文档适用于无网络环境False4. 聊天与工具配置参数说明默认值--chat-template聊天模板路径---chat-template-content-format聊天模板内容格式可选auto/openai/stringauto--response-role响应角色名称assistant--enable-auto-tool-choice启用自动工具选择False四、模型配置ModelConfig1. 核心模型参数参数说明默认值--modelHugging Face 模型名称 / 路径Qwen/Qwen3-0.6B--tokenizer分词器名称 / 路径未指定时使用模型名称---tokenizer-mode分词器模式可选auto/deepseek_v32/hf/mistral/slowauto--dtype模型权重 / 激活数据类型可选auto/bfloat16/float/float16/float32/halfauto--max-model-len模型上下文长度支持 k/M/G 单位-1/auto 自动适配自动从模型配置推导--quantization (-q)量化方法优先使用模型配置中的quantization_config-2. 模型加载与版本控制参数说明默认值--revision模型版本分支 / 标签 / 提交 ID默认版本--code-revision模型代码版本Hugging Face Hub默认版本--trust-remote-code信任远程代码从 Hugging Face 下载时False--hf-tokenHugging Face 访问令牌自动读取~/.cache/huggingface/token-3. 生成与解析配置参数说明默认值--generation-config生成配置路径auto 从模型路径加载vllm 使用默认配置auto--override-generation-config覆盖生成配置例{temperature: 0.5}{}--max-logprobs返回的最大对数概率数-1 表示无限制20--logprobs-mode对数概率返回模式可选processed_logits/processed_logprobs/raw_logits/raw_logprobsraw_logprobs五、模型加载配置LoadConfig参数说明默认值--load-format权重加载格式可选auto/pt/safetensors/npcache/dummy 等auto--download-dir模型下载目录默认使用 Hugging Face 缓存目录---safetensors-load-strategySafetensors 加载策略lazy/eager/torchaolazy--pt-load-map-locationPyTorch checkpoint 加载设备映射cpu--use-tqdm-on-load加载时显示进度条True六、并行执行配置ParallelConfig1. 核心并行参数参数说明默认值--distributed-executor-backend分布式执行后端可选external_launcher/mp/ray/uni---tensor-parallel-size (-tp)张量并行组数1--pipeline-parallel-size (-pp)流水线并行组数1--data-parallel-size (-dp)数据并行组数MoE 层按 tp*dp 分片12. 多节点配置参数说明默认值--master-addr主节点地址mp 后端127.0.0.1--master-port主节点端口mp 后端29501--nnodes (-n)节点数1--node-rank (-r)节点序号03. MoE 相关并行配置参数说明默认值--enable-expert-parallel (-ep)MoE 层使用专家并行而非张量并行False--expert-placement-strategy专家放置策略可选linear/round_robinlinear--all2all-backendMoE 全连接后端可选allgather_reducescatter/deepep_high_throughput 等allgather_reducescatter七、缓存配置CacheConfig参数说明默认值--block-sizeKV 缓存块大小可选1/8/16/32/64/128/256平台自动配置--gpu-memory-utilizationGPU 内存利用率0-1 之间0.9--kv-cache-memory-bytes单 GPU KV 缓存大小优先级高于gpu-memory-utilization---swap-space单 GPU 对应的 CPU 交换空间GiB4--kv-cache-dtypeKV 缓存数据类型可选auto/bfloat16/fp8 等auto--enable-prefix-caching启用前缀缓存---prefix-caching-hash-algo前缀缓存哈希算法可选sha256/sha256_cbor/xxhash/xxhash_cborsha256八、内存优化配置OffloadConfig参数说明默认值--offload-backend卸载后端可选auto/prefetch/uvaauto--cpu-offload-gb单 GPU 卸载到 CPU 的内存大小GiB0--offload-group-size分层卸载的组大小0 表示禁用0--offload-num-in-group每组卸载的层数需 ≤offload-group-size1九、多模态配置MultiModalConfig参数说明默认值--language-model-only仅启用语言模型禁用所有多模态输入False--limit-mm-per-prompt单提示的多模态输入限制支持 JSON 配置例{image: 5}{}--enable-mm-embeds启用多模态嵌入输入需信任用户避免传入错误形状False--mm-processor-cache-gb多模态处理器缓存大小GiB4--video-pruning-rate视频令牌剪枝率0-1 之间-十、LoRA 配置LoRAConfig参数说明默认值--enable-lora启用 LoRA 适配器支持---max-loras单批次支持的最大 LoRA 数量1--max-lora-rank最大 LoRA 秩可选1/8/16/32/64 等16--lora-dtypeLoRA 数据类型auto 继承模型 dtypeauto--fully-sharded-loras启用 LoRA 全分片计算False十一、性能优化配置参数说明默认值--optimization-level优化级别-O0 启动最快-O3 性能最优2--performance-mode性能模式可选balanced/interactivity/throughputbalanced--async-scheduling启用异步调度提升 GPU 利用率---stream-interval流式输出的令牌缓冲大小1 表示逐令牌输出1--enable-flashinfer-autotune启用 FlashInfer 内核自动调优---moe-backendMoE 内核后端可选auto/triton/cutlass/flashinfer_trtllm 等auto十二、观测性配置ObservabilityConfig参数说明默认值--otlp-traces-endpointOpenTelemetry 追踪端点 URL---collect-detailed-traces收集详细追踪数据可选all/model/worker 等组合---kv-cache-metrics启用 KV 缓存指标监控False--enable-mfu-metrics启用模型 FLOPs 利用率指标False--enable-layerwise-nvtx-tracing启用层级 NVTX 追踪不兼容 CUDA 图False十三、编译配置CompilationConfig核心参数通过--compilation-config (-cc)传递支持 JSON 格式或分层键值对\# 示例设置编译模式和 CUDA 图捕获大小 \--cc.mode3 --cc.cudagraph\_capture\_sizes\[1,2,4,8]关键配置项包括mode编译模式cudagraph_capture_sizesCUDA 图捕获的批量大小列表backend编译后端默认inductorcompile_mm_encoder是否编译多模态编码器