一 、安装

二、启动入口

VLLM 提供了多种入口方式启动模型，以适应不同的使用场景（如命令行交互、API 服务、自定义集成等）。除了最常用的 openai.api_server（OpenAI 兼容 API 服务），还有以下主要入口：

1. cli：命令行交互式推理

适合快速测试模型，直接在终端进行对话交互。

python -m vllm.entrypoints.cli \
  --model lmsys/vicuna-7b-v1.5 \
  --tensor-parallel-size 1 \
  --max-model-len 2048

特点：

• 启动后进入交互式命令行，可直接输入 prompt 与模型对话
• 支持设置采样参数（如 --temperature、–top-p 等）
• 适合用于快速验证模型功能或调试

2.api_server：通用 RESTful API 服务

python -m vllm.entrypoints.api_server \
  --model facebook/opt-13b \
  --port 8000 \
  --tensor-parallel-size 2

特点：

• 提供 /generate 和 /generate_stream 接口，支持同步和流式输出
• 请求 / 响应格式为 VLLM 自定义结构（与 OpenAI API 不同）
• 适合需要轻量 API 服务的场景，无需兼容 OpenAI 格式

3. grpc_server：GRPC 服务

通过 GRPC 协议提供高性能的模型推理服务，适合低延迟、高并发的后端集成。

python -m vllm.entrypoints.grpc_server \
  --model meta-llama/Llama-2-70b-chat-hf \
  --tensor-parallel-size 4 \
  --port 50051

特点：

• 基于 GRPC 协议，比 REST API 具有更低的序列化开销
• 需配合 VLLM 定义的 .proto 协议文件开发客户端
• 适合高性能、分布式系统中的服务间调用

4. controller 与 worker：分布式部署入口

用于大规模分布式部署，支持多 worker 节点协同工作，由 controller 负责负载均衡。

（1）启动 controller

python -m vllm.entrypoints.controller \
  --host 0.0.0.0 \
  --port 8000

（2）启动 worker（需指定 controller 地址）

python -m vllm.entrypoints.worker \
  --model bigscience/bloom \
  --controller http://localhost:8000 \
  --worker http://localhost:8001 \
  --tensor-parallel-size 2

（3）启动 api_server 连接分布式集群

python -m vllm.entrypoints.openai.api_server \
  --served-model-name bloom \
  --controller http://localhost:8000 \
  --port 8002

特点：

• 支持横向扩展（增加 worker 节点提升吞吐量）
• 适合生产环境中大规模部署，支持动态扩缩容
• 需要 controller 协调多个 worker 节点的任务分配

可通过 python -m vllm.entrypoints.<入口名> --help 查看各入口的具体参数（如 python -m vllm.entrypoints.cli --help）。

三、openai.api_server入口启动参数

1.常用启动脚本

CUDA_VISIBLE_DEVICES=4,5  nohup python -m vllm.entrypoints.openai.api_server --model /data/models/Qwen3-32B --trust-remote-code --served-model-name Qwen3-32B  --tensor-parallel-size 2  --gpu-memory-utilization 0.9 --max-model-len 32768  --port 40113 --swap-space 16  --disable-log-requests --enable-chunked-prefill --enable-prefix-caching  >> startQwen32B.log 2>&1 &

2.常见参数

VLLM 启动模型时的主要可选参数分类及说明（以最常用的 openai.api_server 入口为例）：

(1).模型与权重配置

• model MODEL_PATH
  必选参数，指定模型权重路径（本地路径或 Hugging Face Hub 模型名，如 lmsys/vicuna-7b-v1.5）。
• trust-remote-code
  允许加载模型中定义的远程代码（适用于自定义模型结构，如 Qwen、LLaMA 等）。
• revision REVISION
  指定模型在 Hugging Face Hub 上的版本（分支名或 commit hash）。
• code-path CODE_PATH
  自定义模型代码的本地路径（当 trust_remote_code 不适用时）。
• tokenizer TOKENIZER_PATH
  自定义分词器路径（默认与模型路径相同）。
• tokenizer-mode {auto,slow}
  分词器模式，slow 用于不支持快速分词的模型。

(2).并行与硬件配置

• tensor-parallel-size N
  张量并行的 GPU 数量（需与可用 GPU 数量匹配，如 --tensor-parallel-size 2 表示用 2 张卡并行）。
• gpu-memory-utilization RATIO
  GPU 内存利用率上限（0~1 之间，如 0.9 表示使用 90% 的 GPU 内存）。
• cpu-offloading
  启用 CPU 卸载（将部分层转移到 CPU 内存，缓解 GPU 内存压力，速度会降低）。
• disable-custom-all-reduce
  禁用自定义的 all-reduce 通信优化（适用于某些不兼容的 GPU 环境）。
• pipeline-parallel-size N
  流水线并行的 GPU 数量（较少使用，通常与张量并行配合）。

(3).推理性能与缓存配置

• max-model-len LENGTH
  模型支持的最大序列长度（输入 + 输出，如 32768 表示 32k 长度）。
• swap-space SWAP_SIZE
  CPU 交换空间大小（GB），用于临时存储超出 GPU 内存的 KV 缓存（如 16 表示 16GB）。
• enable-chunked-prefill
  启用分块预填充（将长输入的 Prefill 阶段分块处理，减少峰值内存占用）。
• enable-prefix-caching
  启用前缀缓存（复用相同 prompt 前缀的 KV 缓存，加速重复请求）。
• kv-cache-dtype {fp8,fp16,bf16,auto}
  KV 缓存的数据类型（如 fp8 可减少内存占用，需 GPU 支持）。
• max-num-batched-tokens NUM
  批处理中允许的最大 token 总数（控制单批处理量，影响吞吐量）。
• max-num-seqs NUM
  批处理中允许的最大序列数（并发请求数上限）。

(4).API 服务配置（OpenAI 兼容接口）

• host HOST
  服务绑定的 IP 地址（默认 0.0.0.0，允许外部访问）。
• port PORT
  服务监听的端口（如 8000）。
• served-model-name NAME
  对外暴露的模型名称（API 调用时使用，默认与模型名相同）。
• allow-credentials
  允许跨域请求携带 credentials（用于前端跨域调用）。
• allowed-origins ORIGINS
  允许的跨域来源（如 http://localhost:3000，多个用逗号分隔）。
• allowed-methods METHODS
  允许的 HTTP 方法（默认 GET,POST,OPTIONS）。
  -allowed-headers HEADERS
  允许的 HTTP 头（默认 *）。

(5).日志与调试配置

• log-level {debug,info,warn,error}
  日志级别（默认 info）。
• disable-log-requests
  禁用请求日志（不记录 API 调用详情）。
• debug
  启用调试模式（输出更详细的日志）。

(6).其他高级配置

• seed SEED
  随机种子（确保推理结果可复现）。
• temperature TEMPERATURE
  采样温度（默认 1.0，值越低输出越确定）。
• top-p TOP_P
  核采样参数（默认 1.0，控制输出多样性）。
• max-log-probs MAX_LOG_PROBS
  返回的最大对数概率数量（用于 token 概率分析）。
• quantization {awq,gptq,sq,int4,int8}
  启用模型量化（如 awq 或 gptq，减少内存占用）。
• rope-scaling {linear,dynamic}
  RoPE 缩放方式（用于扩展模型的上下文长度）。
• rope-factor FACTOR
  RoPE 缩放因子（配合 rope-scaling 使用）。

3.参数查询方式

python -m vllm.entrypoints.openai.api_server --help

四、测试

curl --location --request POST 'http://XXXX:30113/v1/chat/completions' \
--header 'Content-Type: application/json' \
--data-raw '{
    "model": "Qwen3-32B",
    "stream": false,
    "chat_template_kwargs": {"enable_thinking": false},
    "messages": [
        {
            "role": "user",
            "content": "你是谁"
        }
    ]
}'