基于 vLLM 0.7.1 部署 DeepSeek R1 模型避坑指南
vLLM 近期发布了 DeepSeek R1 的 PP（Pipeline Parallelism）支持，适合进行技术准备工作。假如训练的超大 MoE 上线了，也得做好技术准备工作。把踩坑经验给大家分享一下，希望能够相比于官方文档更白话一点。
Distributed Inference and Serving: https://docs.vllm.ai/en/latest/serving/distributed_serving.html#running-vllm-on-multiple-nodes
Step 0 Prepare weights & Environment
由于权重太大了，即使你网速可以，也不建议直连下载了。大家可以先从 HF 及或代理弄一份权重回来，直连大概率直接超时或者把公网 IP 打爆。我们今天展示的多机多卡 8xH20 (x2) 部署，对应 TP size 8，PP size 2，所以要搞两台这样的机器过来。同时有一个假设：两机的网络互通，不一定需要 IB，储存需要共享（NAS 或 OSS 均可），完成准备工作之后便可以做第一步。
Step 1 Setup up Ray & Cluster
官方文档里面简单带过了这一部分，但这个是我被卡时间太久的问题。首先我说一下官方文档的意思，就是让你准备好两个节点，之间用 ray start 这个 CLI 去建立好 ray 集群。因为后面要用，但是比较坑的有两点，第一点是启动的命令似乎有点点问题，我在前几次尝试的时候都遇到了 Ray 的 autoscaler 报错的问题：
(autoscaler +1m19s) Error: No available node types can fulfill resource request {'node:33.18.26.153': 0.001, 'GPU': 1.0}. Add suitable node types to this cluster to resolve this issue.
(autoscaler +1m54s) Error: No available node types can fulfill resource request {'GPU': 1.0, 'node:33.18.26.153': 0.001}. Add suitable node types to this cluster to resolve this issue.
INFO 02-02 09:39:14 ray_utils.py:212] Waiting for creating a placement group of specs for 150 seconds. specs=[{'node:33.18.26.153': 0.001, 'GPU': 1.0}, ...]. Check `ray status` to see if you have enough resources.
这看起来就很奇怪，因为 vLLM 找 Ray 集群要的 Resource 是 custom resource，'node:33.18.26.153':0.001，这可以理解成 vLLM 优先要 driver 节点。但是这个东西我印象中是需要启动 ray 的时候自己设置的：
https://docs.ray.io/en/latest/ray-core/scheduling/resources.html#custom-resources
像这样才会有这种 resource。背后的原因是对于多（虚拟）网卡的机器会有多个网段，vLLM assume 使用 POD IP 来做 Ray 的 master 寻址。
解法 1：设置 VLLM_HOST_IP
# Get local IP address and set on every node before Ray start
VLLM_HOST_IP=$(hostname -I | awk '{print $1}')
export VLLM_HOST_IP
解法 2：魔改 Ray 启动逻辑
def get_actual_ip():
"""Get the actual IP address of the current machine."""
try:
# Create a socket to connect to an external server (doesn't actually connect)
s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
s.connect(('8.8.8.8', 80))
ip = s.getsockname()[0]
s.close()
return ip
except Exception:
# Fallback to hostname-based IP resolution
return socket.gethostbyname(socket.gethostname())
def start_ray_cluster():
free_ports = get_free_ports()
port = free_ports[0]
node_manager_port = free_ports[1]
master_addr = get_master_addr()
rank = get_rank()
node_ip = get_actual_ip() # Use the new function to get actual IP
# Define custom resource based on node IP
resource_spec = f'--resources=\'{"node:{node_ip}": 1}\''
if rank == 0:
cmd = f"ray start --head --port={port} --node-ip-address={master_addr} --node-manager-port {node_manager_port} --node-name={master_addr} {resource_spec}"
else:
cmd = f"ray start --address={master_addr}:{port} --node-manager-port {node_manager_port} --node-name={get_addr()} {resource_spec}"
if ray.is_initialized():
print("Ray is already initialized, skipping node level init.")
else:
stop_cmd = "ray stop"
execute(stop_cmd, check=True)
print(f"Executing Ray start command: {cmd}")
execute(cmd, check=True)
其中 execute 可以这样写：
import time
import subprocess
def execute(cmd, check=False, retry=1):
ret = subprocess.run(cmd, shell=True, capture_output=True, text=True, check=check)
state = ret.returncode == 0
msg = ret.stdout if state else ret.stderr
if not state and retry > 1:
print(f"execute {cmd} got error {msg}, retry...")
time.sleep(1)
return execute(cmd, check, retry-1)
return state, msg
然后这里我稍微提一下 ray 的一些基础玩法：大家在使用 Ray 的时候一般都不是在裸机上面的，大部分深度学习的资源都是 k8s 结合 kubeflow 或者 volcano 这样的插件分发出来的。环境变量里面会有当前是第几个 rank，头结点 master_addr 这样的信息，大家可以根据自己的需要把这些函数实现一下。比较坑的 {resource_spec} 这里我已经替大家把坑给填了。
Step 2 Other small bugs
期间又报了两个错误，花了一点时间修复：
1. OpenCV 版本冲突
AttributeError: module 'cv2.dnn' has no attribute 'DictValue'
一个 opencv 封建余孽的问题，pin 住 opencv 的版本来解决：
pip install opencv-python-headless==4.5.4.58
2. pynvml 类型错误
TypeError: a bytes-like object is required, not 'str'
通过升级 pynvml 解决：
pip install pynvml -U
Step 3 Run the model
这一步反而是最简单的：
vllm serve /your/path/to_checkpoint_deepseek-r1/ --tensor-parallel-size 8 --pipeline-parallel-size 2 --trust-remote-code --host 0.0.0.0
由于有了 PP 加持，没有 IB 的同学也可以尝试把 sequence length 和 bsz 给稍微拉大一些拉。用 Reasoning Output，在同一台机器来试一把，或者换一台机器把 localhost 改了：
from openai import OpenAI
# Modify OpenAI's API key and API base to use vLLM's API server.
openai_api_key = "EMPTY"
openai_api_base = "http://localhost:8000/v1"
client = OpenAI(
api_key=openai_api_key,
base_url=openai_api_base,
)
models = client.models.list()
model = models.data[0].id
# Round 1
messages = [{"role": "user", "content": "9.11 and 9.8, which is greater?"}]
response = client.chat.completions.create(model=model, messages=messages)
reasoning_content = response.choices[0].message.reasoning_content
content = response.choices[0].message.content
print("reasoning_content:", reasoning_content)
print("content:", content)
对，你不是卡主了，是你的钱包不够厚。切到后台可以看到，这个 prompt 里面：
INFO 02-02 14:18:52 metrics.py:453] Avg prompt throughput: 1.7 tokens/s, Avg generation throughput: 0.1 tokens/s, Running: 1 reqs, Swapped: 0 reqs, Pending: 0 reqs, GPU KV cache usage: 0.0%, CPU KV cache usage: 0.0%.
INFO 02-02 14:19:07 metrics.py:453] Avg prompt throughput: 0.0 tokens/s, Avg generation throughput: 20.5 tokens/s, Running: 1 reqs, Swapped: 0 reqs, Pending: 0 reqs, GPU KV cacheusage: 0.0%, CPU KV cache usage: 0.0%.
稍等一会他就会告诉你 9.8 更大了。
祝大家捣鼓顺利，感谢 vLLM 社区的工作。
https://github.com/vllm-project/vllm/pull/12679
补充建议
在实际部署过程中，除了上述步骤外，还需注意以下性能优化与监控细节：
- 显存管理：DeepSeek R1 作为 MoE 模型，激活参数较多，需确保 GPU 显存充足。若遇到 OOM，可尝试减小
max_num_batched_tokens或调整gpu_memory_utilization参数。 - 网络带宽：虽然 PP 允许非 IB 环境运行，但高吞吐场景下仍建议万兆以太网以上互联，避免通信瓶颈影响推理延迟。
- 日志监控：利用 vLLM 内置的 Prometheus 指标或集成外部监控系统，实时观察 Request Latency、Throughput 及 KV Cache 命中率，以便及时调整配置。
通过合理配置硬件资源与软件参数，可以有效提升 DeepSeek R1 在生产环境的推理效率与稳定性。
