一、核心命令：vllm serve

vllm serve 是 vllm 框架提供的模型部署命令，用于将指定模型加载到 GPU 中，并启动一个支持 HTTP/RESTful API 的推理服务。vllm 是一款高性能的 LLM 推理框架，基于 PagedAttention 内存管理技术，支持动态批处理（Dynamic Batching）、张量并行等特性，能显著提升大模型的推理吞吐量（Throughput）并降低延迟（Latency），广泛用于生产环境的大模型部署。

二、参数详解

--host 0.0.0.0

指定服务绑定的 IP 地址：

• 0.0.0.0 表示服务会监听主机上的所有网络接口（而非仅本地 localhost），允许其他机器通过主机的 IP 地址（如 192.168.x.x 或公网 IP）访问该服务。
• 若仅需本地访问，可改为 --host 127.0.0.1（默认值），但生产环境中通常需要对外暴露，因此设为 0.0.0.0。

--port 9097

指定服务监听的端口号：

• 客户端需通过该端口访问服务，例如发送推理请求到 http://<主机IP>:9097/v1/chat/completions。
• 端口需确保未被其他进程占用（可通过 netstat -tuln | grep 9097 检查），生产环境中建议选择 1024 以上的非特权端口，避免冲突。
• 需确保端口未被其他进程占用（可通过 lsof -i:8756 检查），避免冲突。

--gpu-memory-utilization 0.96

设置 GPU 内存的最大利用率（比例）：

• 0.96 表示允许 vllm 使用 GPU 总显存的 96%（剩余 4% 用于突发内存需求，避免 OOM 错误）。
• 作用：vllm 会根据该参数动态调整批处理大小（Batch Size）和 KV 缓存（Key-Value Cache）的分配，在充分利用 GPU 资源的同时，降低内存溢出风险。
• 注意：若模型本身占用显存较高（如 7B 模型通常需 10-15GB 显存），该值过高可能导致启动失败（需根据实际 GPU 显存调整，例如 24GB 显存卡可设 0.9-0.96，16GB 卡建议 0.85-0.9）。

--served-model-name "Qwen2.5-VL-7B-Instruct"

指定服务对外暴露的模型名称：

• 在多模型部署场景（如同一 vllm 服务部署多个模型），客户端可通过该名称指定调用哪个模型（例如在 OpenAI 兼容 API 中，model 参数需填写此名称）。
• 若仅部署单模型，该参数可省略（默认使用模型路径的最后一级目录名），但显式指定可增强可读性和可维护性。
• 客户端调用时，需在 API 请求的 model 参数中指定该名称（如 {"model": "qwen25-7b-full-sfxg-rewrite", "messages": [...]}），用于标识目标模型（尤其多模型部署时区分服务）。

--max-model-len 20480

设置模型支持的最大序列长度（输入 token 数 + 输出 token 数）：

• 20480 表示允许模型处理的上下文总长度为 20480 个 token（约 1.5-2 万字，具体取决于语言，中文单字约 1 token，英文单词约 1-2 token）（约 1.5-2 万字，或包含多图+长文本的混合输入）。
• 作用：限制单次推理的上下文长度，避免因输入/输出过长导致显存不足。Qwen2.5 系列模型原生支持较长上下文，此处设置为 20480 是为了适配长文本任务（如长文档理解、多轮对话）。
• 注意：最大序列长度越大，KV 缓存占用的显存越多（KV 缓存显存与序列长度成正比），需结合 --gpu-memory-utilization 平衡资源分配。
• 多模态场景常涉及长文本描述（如客服对话历史）+ 多张图像（如快递包裹问题照片），长序列支持可避免因输入过长被截断，适合复杂任务（如多轮图文对话、长文档+图像联合分析）。

--enable-auto-tool-choice --tool-call-parser hermes

这两个参数是实现模型自动工具调用能力的核心配置，也是该命令的关键特性：

• --enable-auto-tool-choice：
  允许模型根据输入内容自主决定是否调用外部工具（无需人工显式指令“调用工具”）。例如：
  • 当用户问“今天北京的天气如何？”，模型会自动判断需要调用“天气查询工具”，并生成工具调用指令；
  • 当用户问“总结一下这段话的核心观点”，模型判断无需工具，直接生成回答。
• --tool-call-parser hermes：
  指定工具调用指令的解析器为 hermes。模型生成的工具调用指令通常是结构化格式（如 JSON），例如：

  {"name": "get_weather", "parameters": {"city": "北京", "date": "today"}}
  

  hermes 解析器专门适配遵循 Hermes 工具调用规范的模型输出，能精准提取工具名称（name）和参数（parameters），确保后续工具调用流程（如调用外部 API）可正确执行。

--tensor-parallel-size 1

设置张量并行度为 1：

• 张量并行是将模型层拆分到多张 GPU 的分布式部署技术，tensor-parallel-size=1 表示不拆分模型，仅用 1 张 GPU 部署（适合 8B 参数量模型，单卡显存足够承载）。
• 若模型参数量更大（如 70B），需增大该值（如 --tensor-parallel-size 2 表示用 2 张 GPU 拆分模型）。

--dtype bfloat16

指定模型推理时的数据类型为 bfloat16（Brain Float 16）：

• bfloat16 是一种 16 位浮点数格式，精度介于 float16（半精度）和 float32（单精度）之间，尤其适合深度学习推理：
  • 相比 float32：显存占用减少 50%，计算速度更快；
  • 相比 float16：保留更多有效位数（ exponent 范围与 float32 一致），在复杂推理任务（如多模态特征融合）中精度损失更小，减少推理错误。
• 多模态模型需处理图像像素和文本 token 的混合特征，对精度更敏感，bfloat16 是兼顾性能和精度的优选。
• bfloat16 精度平衡显存占用与推理精度，避免多模态特征融合时的精度损失；

--max-num-seqs 64

设置动态批处理的最大并发序列数（即同时处理的请求数量上限）：

• vllm 的核心优势之一是“动态批处理”：自动将多个请求合并为一个批次推理，提升 GPU 利用率。max-num-seqs=64 表示最多同时处理 64 个请求。
• 该值需结合 GPU 显存和单请求序列长度调整：值过高可能导致显存不足（尤其长序列请求多的时候）；值过低则 GPU 利用率低，吞吐量下降。对于 7B 多模态模型，64 是平衡并发和显存的合理设置。

--enable-prefix-caching

启用前缀缓存（Prefix Caching） 优化：

• 核心原理：当多个请求包含相同的“前缀内容”（如对话历史中的共同上下文、相同的系统提示词）时，vllm会缓存前缀对应的KV缓存（推理中间状态），避免重复计算。
• 效果：显著减少重复前缀的计算量，提升批量请求的推理速度（尤其适用于多轮对话场景，上下文重复度高）。

--enable-chunked-prefill

启用分块预填充（Chunked Prefill） 机制：

• 核心作用：处理超长输入时，将输入序列拆分为多个“块（Chunk）”，分批次进行预填充计算（模型对输入的初始处理阶段），而非一次性加载整个序列。
• 优势：降低超长序列预填充阶段的瞬时显存峰值，避免因单批输入过长导致的OOM错误，同时提升长文本处理的稳定性（配合--max-model-len使用效果更佳）。

三、补充说明

• 性能优化：动态批处理（默认开启）会将多个请求合并为一个批次推理，大幅提升吞吐量；PagedAttention 技术则通过碎片化管理 KV 缓存，减少显存浪费。
• vllm 的 PagedAttention 技术优化了 KV 缓存的内存分配，动态批处理功能可合并多个请求并行推理，相比原生 PyTorch 推理，吞吐量提升 5-10 倍，响应延迟降低 30% 以上。
• 服务启动成功后，日志会输出类似 Uvicorn running on http://0.0.0.0:9097 的信息（默认绑定所有网络接口，若需限制本地访问，可添加 --host 127.0.0.1）。
• 若模型需要处理长文本，可通过 --max-model-len <长度> 扩展最大序列长度（如 --max-model-len 8192），但需注意更长序列会增加显存占用。
• 动态批处理（max-num-seqs=64）提升并发能力，支持高流量场景。