1. 环境准备与基础配置

1.1 系统要求

依赖组件：

# 基础工具安装
sudo apt-get install -y lsof git-lfs nvidia-cuda-toolkit

1.2 虚拟环境配置

使用conda创建隔离环境，避免依赖冲突：

conda create -n vllm python=3.10 -y
conda activate vllm

# 配置conda源加速
conda config --add channels conda-forge
conda config --set channel_priority strict
conda install sqlite=3.42.0

1.3 vLLM与依赖安装

# 安装xFormers加速组件
pip install xformers-0.0.27.post2-cp310-cp310-manylinux2014_x86_64.whl

# 通过清华源安装vLLM
pip install vllm==0.5.4 -i https://pypi.tuna.tsinghua.edu.cn/simple

# 安装Ray分布式框架
conda install -c conda-forge ray-default

2. 分布式集群搭建

2.1 Ray集群配置

主节点启动（假设IP为192.168.1.1）：

ray start --head --port=6379 \
          --node-ip-address=192.168.1.1 \
          --dashboard-host=0.0.0.0 \
          --num-gpus=4 \
          --object-store-memory=4294967296

工作节点加入：

ray start --address=192.168.1.1:6379 \
          --node-ip-address=192.168.1.2 \
          --num-gpus=4

关键参数说明：

–num-gpus：必须与物理GPU数量一致
–object-store-memory：建议设置为可用内存的70%

2.2 网络优化配置

# 设置通信网卡（根据实际网卡名称调整）
export GLOO_SOCKET_IFNAME=eth0
export NCCL_SOCKET_IFNAME=eth0
export NCCL_ALGO=Tree
export NCCL_NSOCKS_PERTHREAD=4
export NCCL_SOCKET_NTHREADS=2

常见问题：

若出现Gloo connectFullMesh failed错误，需检查防火墙设置并确认网卡名称正确

跨节点通信延迟高时，可尝试export NCCL_NET_GDR_LEVEL=PHB启用高性能模式

3. 模型部署与启动

3.1 模型下载

从ModelScope下载模型（以Qwen2.5-1.5B为例）：

modelscope download --model qwen/Qwen2.5-1.5B

模型默认保存在~/.cache/modelscope/hub/目录

3.2 分布式启动命令

两节点部署示例（每节点4卡）：

节点0启动命令

GLOO_SOCKET_IFNAME=eth0 NCCL_SOCKET_IFNAME=eth0 RAY_USE_IPV4=1 \
vllm serve qwen/Qwen2.5-1.5B \
    --dtype half \
    --tensor-parallel-size 4 \
    --pipeline-parallel-size 2 \
    --distributed-executor-backend ray \
    --gpu-memory-utilization 0.9 \
    --max-model-len 2048 \
    --host 0.0.0.0 \
    --port 6397 \
    --api-key key-abc123 \
    --cpu-offload-gb 64 \
    --block-size 8 \
    --swap-space 16

参数解析：

参数	作用	推荐值
–tensor-parallel-size	单节点内GPU并行数	通常等于单节点GPU数
–pipeline-parallel-size	跨节点并行数	通常等于节点数
–cpu-offload-gb	CPU内存卸载量	显存不足时可设为物理内存的50%
–swap-space	SSD交换空间	建议16-32GB

3.3 服务验证

健康检查：

curl http://localhost:6397/health

正常响应应包含200 OK状态码

模型列表查询：

curl http://localhost:6397/v1/models \
    -H "Authorization: Bearer key-abc123"

对话测试：

curl -X POST http://localhost:6397/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer key-abc123" \
    -d '{
        "model": "qwen/Qwen2.5-1.5B",
        "messages": [
            {"role": "system", "content": "你是一个专业的中文助手"},
            {"role": "user", "content": "用200字介绍下你自己"}
        ],
        "temperature": 0.1,
        "max_tokens": 300,
        "stop": ["<|im_end|>"]
    }'

4. 性能优化策略

4.1 显存管理

分块处理：通过–block-size 8减小内存块大小，提升显存利用率
交换空间：启用–swap-space 16利用SSD扩展内存
动态卸载：设置–cpu-offload-gb 64将部分计算卸载到CPU

4.2 通信优化

拓扑感知：通过nvidia-smi topo -m查看GPU连接方式，优先使用NVLink互联的GPU组
协议调优：

export NCCL_IB_DISABLE=1  # 非InfiniBand环境禁用
export NCCL_SOCKET_NTHREADS=2  # 增加通信线程

4.3 批处理优化

连续批处理：vLLM默认启用，通过–max-num-seqs 256控制并发量
预填充优化：添加–enable-chunked-prefill参数减少延迟

5. 常见问题排查

5.1 部署阶段问题

问题1：Ray节点无法加入集群
解决方案：
检查防火墙设置：sudo ufw allow 6379/tcp
验证网络连通性：ping <主节点IP>
确认Ray版本一致：ray --version

问题2：NCCL通信超时
解决方案：

export NCCL_DEBUG=INFO
export NCCL_P2P_DISABLE=1  # 临时禁用P2P

5.2 推理阶段问题

问题3：显存不足(OOM)
解决方案：
降低–gpu-memory-utilization至0.7-0.8
启用量化：–quantization awq
减少–max-model-len值

问题4：响应延迟高
解决方案：
检查GPU利用率：nvidia-smi -l 1
调整–tensor-parallel-size与–pipeline-parallel-size比例

6. 监控与维护

6.1 集群监控

Ray Dashboard：访问http://:8265查看集群状态
Prometheus：集成vLLM指标导出：

vllm serve ... --enable-prometheus

6.2 日志分析

关键日志路径：
Ray日志：/tmp/ray/session_latest/logs/
vLLM日志：启动时添加> vllm.log 2>&1

注：实际性能取决于硬件配置和模型特性