vLLM 的并行推理与扩展

单个模型副本的分布式推理策略

为单个模型副本选择分布式推理策略时，可以采用以下原则：

• 单 GPU（不使用分布式推理）：如果模型能装入单张 GPU，通常没有必要分布式推理，直接在该 GPU 上运行即可。
• 单节点多 GPU，采用张量并行：如果模型超过单张 GPU 容量，但能装入同一节点的多张 GPU，使用张量并行。例如，节点有四张 GPU 时设 tensor_parallel_size=4。
• 多节点多 GPU，结合张量并行与流水线并行：如果模型超过单节点容量，把 tensor_parallel_size 设为每节点 GPU 数，pipeline_parallel_size 设为节点数。例如两个节点、每节点八张 GPU，设 tensor_parallel_size=8、pipeline_parallel_size=2。

逐步增加 GPU 和节点，直到 GPU 显存足以容纳模型；张量并行规模对应每节点 GPU 数，流水线并行规模对应节点数。

准备足够资源后运行 vllm，查找类似日志：

INFO 07-23 13:56:04 [kv_cache_utils.py:775] GPU KV cache size: 643,232 tokens
INFO 07-23 13:56:04 [kv_cache_utils.py:779] Maximum concurrency for 40,960 tokens per request: 15.70x

GPU KV cache size 表示 GPU KV 缓存同时能够保存的 token 总数。Maximum concurrency 估计当每个请求需要指定 token 数时，可以同时服务多少请求，本例每请求为 40,960 token。该数值来自模型配置的最大序列长度 ModelConfig.max_model_len。如果这些数值低于吞吐需求，应为集群增加 GPU 或节点。

混合专家（MoE）模型的分布式服务

利用专家本身的并行性、为专家层采用单独的并行策略，往往更有利。vLLM 支持大规模部署，把注意力层的数据并行与 MoE 层的专家并行或张量并行结合起来。详情见数据并行部署。

单节点部署

vLLM 支持分布式张量并行和流水线并行推理及服务，其中实现了 Megatron-LM 的张量并行算法。

多节点推理默认使用 Ray，单节点默认使用 Python 原生 multiprocessing。可在 LLM 类中设置 distributed_executor_backend，或在 API 服务器使用 --distributed-executor-backend 覆盖默认值；mp 表示 multiprocessing，ray 表示 Ray。

多 GPU 推理时，把 LLM 中的 tensor_parallel_size 设为 GPU 数。例如四张 GPU：

from vllm import LLM
llm = LLM("facebook/opt-13b", tensor_parallel_size=4)
output = llm.generate("San Francisco is a")

多 GPU 服务时，在启动命令中加入 --tensor-parallel-size。四张 GPU 的 API 服务器：

vllm serve facebook/opt-13b \
     --tensor-parallel-size 4

加入 --pipeline-parallel-size 可启用流水线并行。下面结合两种并行方式，使用共八张 GPU：

# Eight GPUs total
vllm serve gpt2 \
     --tensor-parallel-size 4 \
     --pipeline-parallel-size 2

多节点部署

单节点没有足够 GPU 容纳模型时，应跨节点部署 vLLM。每个节点都要有相同执行环境，包括模型路径和 Python 包。推荐容器镜像，因为它们便于保持环境一致，并隐藏宿主机差异。

什么是 Ray？

Ray 是用于扩展 Python 程序的分布式计算框架，可以作为多节点 vLLM 的运行引擎。vLLM 用它管理跨节点任务执行，并控制任务在哪个节点运行。

Ray 还提供大规模离线批量推理和在线服务的高层 API，以 vLLM 为引擎，为工作负载增加面向生产的容错、扩展和分布式可观测能力。

Ray 是可选依赖，使用基于 Ray 的执行方式之前，需要显式安装：

pip install "ray[cgraph]"

详情见 Ray 文档。

使用容器设置 Ray 集群

辅助脚本 examples/ray_serving/run_cluster.sh 会在各节点启动容器并初始化 Ray。默认无管理权限运行 Docker，因此性能分析或追踪时无法访问 GPU 性能计数器。要启用管理权限，在 Docker 命令中加入 --cap-add=CAP_SYS_ADMIN。

选择一个节点作为头节点，运行：

bash run_cluster.sh \
                vllm/vllm-openai \
                <HEAD_NODE_IP> \
                --head \
                /path/to/the/huggingface/home/in/this/node \
                -e VLLM_HOST_IP=<HEAD_NODE_IP>

每个工作节点运行：

bash run_cluster.sh \
                vllm/vllm-openai \
                <HEAD_NODE_IP> \
                --worker \
                /path/to/the/huggingface/home/in/this/node \
                -e VLLM_HOST_IP=<WORKER_NODE_IP>

每个工作节点的 VLLM_HOST_IP 都必须不同。保持执行命令的 shell 打开，关闭任何一个都会终止集群。确保各节点可以通过 IP 相互通信。

从任一节点进入容器，运行 ray status 和 ray list nodes，核对发现的节点与 GPU 数是否符合预期。

在 Ray 集群中运行 vLLM

集群启动后，可以像单节点一样使用 vLLM。Ray 集群的全部资源对 vLLM 可见，因此在一个节点执行一个 vllm 命令即可。

通常把张量并行规模设为每节点 GPU 数，把流水线并行规模设为节点数。例如两个节点、共16张 GPU、每节点八张：

vllm serve /path/to/the/model/in/the/container \
    --tensor-parallel-size 8 \
    --pipeline-parallel-size 2 \
    --distributed-executor-backend ray

也可以把 tensor_parallel_size 设为集群 GPU 总数：

vllm serve /path/to/the/model/in/the/container \
     --tensor-parallel-size 16 \
     --distributed-executor-backend ray

使用 MultiProcessing 运行 vLLM

除 Ray 外，多节点部署也可用 multiprocessing 作为运行引擎。以下示例跨两个节点、每节点八张 GPU，设置 tp_size=8、pp_size=2。

选择一个头节点运行：

vllm serve /path/to/the/model/in/the/container \
  --tensor-parallel-size 8 --pipeline-parallel-size 2 \
  --nnodes 2 --node-rank 0 \
  --master-addr <HEAD_NODE_IP>

在另一个工作节点运行：

vllm serve /path/to/the/model/in/the/container \
  --tensor-parallel-size 8 --pipeline-parallel-size 2 \
  --nnodes 2 --node-rank 1 \
  --master-addr <HEAD_NODE_IP> --headless

优化张量并行的网络通信

高效的张量并行需要快速的节点间通信，最好使用 InfiniBand 等高速网络适配器。为集群启用 InfiniBand，可向 run_cluster.sh 增加 --privileged -e NCCL_IB_HCA=mlx5 等参数。所需参数详情应咨询系统管理员。

启用 GPUDirect RDMA

GPUDirect RDMA（远程直接内存访问）是 NVIDIA 的技术，允许网络适配器直接访问 GPU 显存，绕过 CPU 和系统内存。这会降低延迟与 CPU 开销，有利于跨节点 GPU 间的大规模传输。

要配合 vLLM 启用它，应配置：

• IPC_LOCK 安全上下文：为容器增加该 capability，锁定内存页，防止交换到磁盘。
• /dev/shm 共享内存：在 Pod 配置中挂载它，提供进程间通信（IPC）共享内存。

Docker 容器示例：

docker run --gpus all \
    --ipc=host \
    --shm-size=16G \
    -v /dev/shm:/dev/shm \
    vllm/vllm-openai

Kubernetes Pod 配置示例：

...
spec:
  containers:
    - name: vllm
      image: vllm/vllm-openai
      securityContext:
        capabilities:
          add: ["IPC_LOCK"]
      volumeMounts:
        - mountPath: /dev/shm
          name: dshm
      resources:
        limits:
          nvidia.com/gpu: 8
        requests:
          nvidia.com/gpu: 8
  volumes:
    - name: dshm
      emptyDir:
        medium: Memory
...

分布式部署故障排查

分布式调试详情见分布式部署故障排查。