vLLM 多卡并行 Tensor Parallelism 配置与踩坑：零基础 3 分钟极速上手教程

兄弟们，站长老实说，现在跑大模型，单卡 24G 显存连 7B 模型都费劲，更别说 70B 这种巨无霸了。你肯定搜过“vLLM 多卡并行 Tensor Parallelism 配置与踩坑”，网上教程一堆，但大部分要么是机翻文档，要么直接甩一堆参数让你自己悟。今天站长不讲虚的，直接给你一套零基础能跑通的配置流程，并且把站长自己踩过的三个大坑给你标出来。全程手把手，你照着复制粘贴，3 分钟内让模型在多卡上飞起来。

前置准备：别急着敲命令，先检查这三样

站长见过太多人上来就 –tensor-parallel-size 8，结果报错一脸懵。动手前，花 30 秒确认下面三件事，能帮你省下 2 小时排查时间。

第一，硬件拓扑。 不是所有 GPU 都能随便并行。你需要在终端跑 nvidia-smi topo -m 看输出。重点看 NVLink 连接。如果 GPU 0 和 GPU 1 之间是 NV#，说明有高速互联，适合做 Tensor Parallelism。如果显示 PIX 或者 PHB（走 PCIe 桥），并行效率会打折扣，但不是不能用。站长建议，TP 大小最好等于同一张卡上的 NVLink 连通数。比如你有 4 卡，但只有 0-1 和 2-3 分别有 NVLink，那你最好设 –tensor-parallel-size 2，而不是 4。强行设 4 会走 PCIe 通信，速度慢到怀疑人生。

第二，显存余量。 别以为多卡并行就是显存无限叠加。Tensor Parallelism 需要把每层权重切到每张卡上，但 KV Cache 和激活值还是会有冗余。站长给你个土办法：先单卡加载模型，看 nvidia-smi 里占用多少显存。然后估算，TP=2 时，每卡显存占用约等于单卡的 60%~70%。如果单卡 24G 跑 7B 模型用了 14G，那么 TP=2 时每卡大概 9G 左右，TP=4 时每卡大概 5G 左右。如果算下来爆显存，就调小 –max-model-len 或者 –gpu-memory-utilization。

第三，CUDA 和 vLLM 版本。 这一点站长必须敲黑板！vLLM 0.4.x 和 0.5.x 的 TP 通信实现有差异。站长踩过坑，0.4.2 版本用 TP=4 会偶发 NCCL 超时，升级到 0.5.0 后就好了。建议你直接用 pip install vllm --upgrade 装最新版。同时确认 torch.cuda.device_count() 返回的卡数跟你预期一致，别用了个假环境。

极速 3 步操作：复制粘贴就能跑

现在开始正题。站长给你一套最简命令，你直接替换模型路径和卡数就行。

第 1 步：写一个最基础的 TP 启动脚本

创建一个 run_tp.py 文件，内容如下（站长注释都给你写好了）：

from vllm import LLM, SamplingParams

# 核心就一行：tensor_parallel_size 参数
llm = LLM(
    model="meta-llama/Llama-2-7b-chat-hf",  # 换成你的模型路径
    tensor_parallel_size=2,                 # 关键！改成你的卡数，比如 2、4、8
    dtype="float16",                        # 混合精度，省显存
    gpu_memory_utilization=0.90,            # 允许用 90% 显存，留点余量给 NCCL
    max_model_len=4096,                     # 根据你模型上下文长度调
    trust_remote_code=True                  # 如果模型有自定义代码，必须开
)

# 测试推理
outputs = llm.generate(["请用一句话介绍 Tensor Parallelism"])
print(outputs[0].outputs[0].text)

站长提醒：如果你用的是 量化模型（比如 AWQ 或 GPTQ），需要额外加 quantization="awq" 参数，否则会报形状不匹配。

第 2 步：设置 NCCL 环境变量（防止卡死）

直接命令行启动时，加上下面两个环境变量，站长亲测能解决 90% 的通信卡死问题：

export NCCL_DEBUG=INFO                      # 打印通信日志，报错时能看原因
export NCCL_P2P_DISABLE=0                   # 强制开启 P2P 通信（如果 NVLink 正常）
export NCCL_IB_DISABLE=1                    # 如果没有 InfiniBand，必须关掉，否则会卡在等待 IB 设备

python run_tp.py

如果你在 Docker 容器 里跑，记得加 --shm-size=10g 和 --ipc=host，否则共享内存不够，NCCL 会直接崩。

第 3 步：验证并行是否真的生效

跑起来后，别急着看输出。你打开另一个终端，输入 nvidia-smi，观察是不是 每张卡都有显存占用。如果只有一张卡有占用，说明 TP 没生效，你八成是没传参或者环境变量没生效。另外，看日志里的 # GPU blocks: xxx，这个数字应该比单卡时大，说明 KV Cache 分到多卡了。

然后测速度。用 time 命令包住你的推理脚本，对比单卡和 TP=2 的时间。站长实测，7B 模型 TP=2 的吞吐量能提升 1.6~1.8 倍（不是 2 倍，因为通信有开销）。如果提升低于 1.3 倍，说明你的 PCIe 带宽是瓶颈，建议降低 TP 数。

避坑提示卡片：站长踩过的三个深坑

💡 关联延伸阅读：如果你在配置过程中遇到相关报错，请参阅站长之前的解决教程：大模型推理:vllm多机多卡分布式本地部署实测：显存/吞吐/硬件选型横向对比与配置指南

坑 1：NCCL 超时崩溃，报错 “Timeout at NCCL”
这通常是网络拓扑问题。站长第一次用 4 卡跑，0-1 有 NVLink，2-3 有 NVLink，但 1-2 之间走 PCIe。结果设了 TP=4，直接超时。解决办法：要么设 NCCL_P2P_LEVEL=LOC 限制通信范围，要么老老实实把 TP 改成 2。另外，检查 ulimit -n 文件描述符限制，调大到 65535，命令：ulimit -n 65535。

坑 2：显存不够，但明明有 4 张卡
很多人以为 TP=4 就能加载 4 倍大的模型。站长告诉你，权重是切分了，但中间激活值和 KV Cache 会翻倍。特别是长序列生成时，激活值占用可能比权重还大。解决办法：调小 --max-model-len（比如从 8192 降到 4096），或者调低 --gpu-memory-utilization 到 0.8，给激活值留空间。如果还爆，就上 FlashAttention 2（vLLM 默认开启），能省 30% 激活值显存。

坑 3：模型输出结果和单卡不一致，甚至乱码
这大概率是 dtype 不一致 导致的。比如你单卡用 float32，TP 时用了 float16，精度丢失。站长建议统一用 bfloat16（如果显卡支持，比如 A100/H100），它比 float16 更稳。另外，检查 tokenizer 是否一致，别用错 tokenizer 文件。最后，如果你用了 --enforce-eager 模式（关闭 CUDA Graph），TP 下可能触发 bug，建议去掉这个参数。

最后站长总结一句： Tensor Parallelism 不是银弹，卡间通信带宽决定了上限。如果你只有 2 张卡且没有 NVLink，那 TP 提升有限，不如用 Pipeline Parallelism（--pipeline-parallel-size 2）或者直接上 量化。但如果你有 4 张 A100 或者 4090 组了 NVLink，按站长上面的步骤来，3 分钟绝对能跑通。遇到任何报错，先把 NCCL_DEBUG=INFO 的日志贴到评论区，站长看到就回。

行了，别收藏吃灰了，现在就去跑一下。有问题回来找站长。