在大模型时代，单节点 GPU 资源往往难以满足大模型（如 7B/13B 参数模型）的部署需求。借助 Ray 分布式框架，我们可以轻松实现跨节点 GPU 资源调度，让大模型在多节点间高效运行。本文将以 DeepSeek-llm-7B-Chat 模型为例，详细讲解如何通过 Ray 搭建跨节点集群，结合 vLLM 实现分布式推理，并解决部署过程中的常见问题。

一、背景与目标

为什么需要跨节点 GPU 调用？

模型规模限制：7B 参数的 DeepSeek 模型单卡可加载，但更大的模型（如 33B）单卡显存不足，需多卡并行。
资源利用率：跨节点调用可整合多台服务器的 GPU 资源，避免单节点资源闲置。
分布式推理优势：通过 Ray 的张量并行（Tensor Parallelism），模型层可拆分到不同节点的 GPU，提升推理效率。

本文目标

搭建包含 1 个主节点、2 个工作节点的 Ray 集群。
跨节点调用 2 张 GPU，用 vLLM 部署 DeepSeek-llm-7B-Chat 模型。
实现 OpenAI 兼容的 API 服务，支持客户端调用。

二、环境准备

硬件要求

节点数量：3 台服务器（1 主 2 从，支持 GPU）。
- 主节点（master）：192.168.2.221，至少 1 张 GPU（本文用 Tesla V100-32GB）。
- 工作节点 1（worker1）：192.168.2.226，至少 1 张 GPU。
- 工作节点 2（worker2）：192.168.2.227，至少 1 张 GPU。
网络：节点间内网互通（推荐 10Gbps 以上带宽），支持 SSH 免密登录。

软件要求

工具 / 库	版本	作用
Python	3.9	运行环境
Ray	2.9.0	分布式集群管理
vLLM	0.9.2	高效大模型推理引擎
CUDA	11.8	GPU 加速
DeepSeek-llm-7B-Chat	-	目标部署模型

三、详细部署步骤

步骤 1：全节点初始化环境（所有节点执行）

1.1 安装系统依赖

解决后续可能出现的Python.h缺失问题（编译 C 扩展时需要）：

# 基于CentOS/RHEL的系统
dnf install -y python3-devel gcc gcc-c++# 基于Ubuntu的系统
# apt-get install -y python3-dev gcc g++

1.2 创建虚拟环境

统一环境避免依赖冲突：

# 安装virtualenv
pip3 install virtualenv# 创建并激活虚拟环境
cd /opt
virtualenv vllm_env --python=python3.9
source vllm_env/bin/activate  # 激活环境（后续所有操作均在此环境中执行）

1.3 安装核心依赖

# 安装Ray（包含集群管理和客户端组件）
pip install "ray[default,client]" --upgrade# 安装vLLM（支持分布式推理）
pip install vllm==0.9.2# 安装其他工具（可选，用于测试）
pip install requests  # 用于发送API请求

步骤 2：搭建 Ray 分布式集群

2.1 启动主节点（master：192.168.2.221）

# 启动Ray主节点，指定IP、端口和Dashboard
ray start --head \--node-ip-address 192.168.2.221 \  # 主节点IP--port 6379 \                      # 端口（集群元数据存储）--dashboard-host 0.0.0.0 \         # 允许外部访问Dashboard--dashboard-port 8265 \            # Dashboard端口（用于监控集群）--include-dashboard=True \         # 启用Dashboard

启动成功后，会显示工作节点加入命令（需记录）：

To add another node to this Ray cluster, run:ray start --address='192.168.2.221:6379'

2.2 加入工作节点（worker1：192.168.2.226 和 worker2：192.168.2.227）

在两个工作节点分别执行以下命令，加入主节点集群：

# 激活虚拟环境（同主节点路径）
source /opt/vllm_env/bin/activate# 加入集群（使用主节点输出的地址）
ray start \--address '192.168.2.221:6379' \  # 主节点地址--node-ip-address 192.168.2.226   # 当前工作节点IP（worker1填226，worker2填227）

2.3 验证集群状态（主节点执行）

# 查看集群节点信息
ray status

预期输出（显示 3 个节点，2 张 GPU 可用）：

Node status
---------------------------------------------------------------
Healthy:1 node_abc... (192.168.2.221)1 node_def... (192.168.2.226)1 node_ghi... (192.168.2.227)
Resources
---------------------------------------------------------------
Total Usage: 0.0/192.0 CPU, 0.0/2.0 GPU  # 2张GPU可用

步骤 3：部署 DeepSeek 模型（主节点执行）

3.1 准备模型

将 DeepSeek-llm-7B-Chat 模型下载到所有节点均可访问的路径（推荐用 NFS 共享，避免多节点重复下载）：

# 示例：通过Hugging Face Hub下载（需提前登录hf-cli）
huggingface-cli download deepseek-ai/deepseek-llm-7b-chat --local-dir /data/storage/data/VLLM_MODE/deepseek-llm-7b-chat

3.2 启动 vLLM 服务（支持跨节点 GPU 调用）

# 激活虚拟环境
source /opt/vllm_env/bin/activate# 设置Ray集群地址
export RAY_ADDRESS="192.168.2.221:6379"# 启动OpenAI兼容的API服务
python -m vllm.entrypoints.openai.api_server \--model /data/storage/data/VLLM_MODE/deepseek-llm-7b-chat \  # 模型路径--port 9001 \                                              # API服务端口--host 0.0.0.0 \                                           # 允许外部访问--tensor-parallel-size 2 \                                 # 张量并行数（=总GPU数）--distributed-executor-backend ray \                       # 使用Ray作为分布式后端--gpu-memory-utilization 0.9                               # GPU内存利用率（90%）

启动成功的关键日志：

步骤 4：验证跨节点 GPU 调用

4.1 检查 GPU 使用情况（工作节点执行）

在 worker1（192.168.2.226）和 worker2（192.168.2.227）分别执行nvidia-smi，可看到 GPU 被 vLLM 进程占用：

nvidia-smi

预期输出（关键信息）：

+-----------------------------------------------------------------------------+
| Processes:                                                                    |
|  GPU   GI   CI        PID   Type   Process name                            GPU Memory |
|        ID   ID                                                             Usage      |
|=============================================================================|
|    0   N/A  N/A    872773      C   ...vllm_env/bin/python                   28511MiB |  # vLLM进程占用
+-----------------------------------------------------------------------------+

说明两个节点的 GPU 均被成功调用（每张卡负载约 28GB，符合 7B 模型 + 90% 内存利用率的预期）。

4.2 测试模型推理（客户端执行）

通过 API 发送请求测试：

# 发送推理请求
curl http://192.168.2.221:9001/v1/chat/completions \-H "Content-Type: application/json" \-d '{"model": "deepseek-llm-7b-chat","messages": [{"role": "user", "content": "介绍一下Ray和vLLM的关系"}]}'

成功响应示例（部分）：

json

{"id": "chatcmpl-xxx","object": "chat.completion","created": 1689523456,"model": "deepseek-llm-7b-chat","choices": [{"message": {"role": "assistant","content": "Ray是一个分布式计算框架，可用于管理跨节点的GPU资源...vLLM是高效的大模型推理引擎，通过Ray实现分布式部署..."},"finish_reason": "stop","index": 0}]
}

步骤 5：Ray 集群的停止与清理

当需要更新配置或重启集群时，需彻底停止 Ray 进程并清理残留数据，避免旧会话信息干扰：

# 停止当前节点的 Ray 进程
ray stop# 若 ray stop 无效，直接 kill 残留进程（谨慎使用，确保只 kill Ray 相关进程）
pkill -f ray# 清理 Ray 临时目录（包含Redis数据、会话信息等）
rm -rf /tmp/ray/*

注意：以上命令需在所有节点执行（主节点 + 工作节点），确保集群完全停止。清理完成后，可重新执行步骤 2 和步骤 3 启动新集群。

四、常见问题与解决方案

问题 1：`Python.h: No such file or directory`

原因：缺少 Python 开发库，编译 C 扩展时失败。

解决：安装python3-devel：

dnf install python3-devel  # CentOS/RHEL
# 或 apt-get install python3-dev  # Ubuntu

问题 2：`ModuleNotFoundError: No module named 'vllm'`

原因：工作节点未安装 vLLM。
解决：在所有工作节点的虚拟环境中安装 vLLM：
```
source /opt/vllm_env/bin/activate
pip install vllm==0.9.2
```

问题 3：Ray Client 连接超时

原因：6379 端口未开放或 Ray Client 服务未启动。

解决：

# 主节点开放端口
firewall-cmd --add-port=6379/tcp --permanent
firewall-cmd --reload# 重启Ray时显式指定Client端口
ray start --head ... --ray-client-server-port 6379

问题 4：GPU 资源不足

原因：tensor-parallel-size超过实际 GPU 数量。
解决：确保--tensor-parallel-size等于集群总 GPU 数（本文为 2）。

关键代码
pip install "ray[default]" --upgrade
ray start --head   --node-ip-address 192.168.2.221   --port 6379   --dashboard-host 0.0.0.0    --dashboard-port 8265   --include-dashboard=True  创建master ray主节点
ray start   --address '192.168.2.221:6379'   --node-ip-address 192.168.2.226 
ray start   --address '192.168.2.221:6379'   --node-ip-address 192.168.2.227cd /opt/
source vllm_env/bin/activateexport HF_ENDPOINT=https://hf-mirror.com 
huggingface-cli download --resume-download deepseek-ai/deepseek-llm-7b-chat --local-dir /data/storage/data/VLLM_MODE/deepseek-llm-7b-chatRAY_ADDRESS="192.168.2.221:6379" python -m vllm.entrypoints.openai.api_server   --model /data/storage/data/VLLM_MODE/deepseek-llm-7b-chat   --port 9001 --host 0.0.0.0    --tensor-parallel-size 2   --distributed-executor-backend ray  --gpu-memory-utilization 0.9