vLLM 高性能推理部署指南 / 14 - 故障排查
14 - 故障排查
遇到问题不要慌，本章汇总了 vLLM 使用中最常见的故障现象和解决方案。
14.1 故障排查通用流程
问题发生
│
▼
┌──────────────────┐
│ 1. 收集信息 │
│ - 错误日志 │
│ - nvidia-smi │
│ - 系统日志 │
└────────┬─────────┘
│
┌────────▼─────────┐
│ 2. 定位类别 │
│ - CUDA/GPU │
│ - 内存 │
│ - 模型加载 │
│ - API/网络 │
│ - 性能 │
└────────┬─────────┘
│
┌────────▼─────────┐
│ 3. 查阅对应章节 │
│ 本章按类别组织 │
└────────┬─────────┘
│
┌────────▼─────────┐
│ 4. 尝试解决方案 │
│ 逐一排查 │
└──────────────────┘
快速诊断命令
# 系统状态一览
nvidia-smi # GPU 状态
nvidia-smi --query-gpu=temperature.gpu,power.draw,utilization.gpu --format=csv # GPU 指标
free -h # 系统内存
df -h # 磁盘空间
dmesg | tail -50 # 内核日志
journalctl -u docker --since "10 minutes ago" # Docker 日志
# vLLM 状态
curl http://localhost:8000/health # 健康检查
curl http://localhost:8000/v1/models # 模型列表
curl http://localhost:8000/metrics | grep vllm # Prometheus 指标
# 进程状态
ps aux | grep vllm # vLLM 进程
nvidia-smi --query-compute-apps=pid,process_name,used_memory --format=csv # GPU 进程
14.2 CUDA 与 GPU 错误
14.2.1 CUDA 版本不匹配
错误信息：
RuntimeError: CUDA error: no kernel image is available for execution on the device
或
The NVIDIA driver on your system is too old (found version 11040).
原因：CUDA 版本与 GPU Compute Capability 不匹配，或驱动版本过旧。
解决方案：
# 1. 检查 GPU Compute Capability
nvidia-smi --query-gpu=compute_cap --format=csv,noheader
# 2. 检查 CUDA 版本
nvcc --version
python -c "import torch; print(torch.version.cuda)"
# 3. 检查驱动版本
nvidia-smi | head -5
# 4. 更新驱动（如需要）
sudo apt-get update
sudo apt-get install -y nvidia-driver-535
# 5. 重新安装匹配的 PyTorch
pip install torch --index-url https://download.pytorch.org/whl/cu124
# 6. 重新安装 vLLM
pip install --force-reinstall vllm
版本兼容性表：
| CUDA 版本 | 最低驱动版本 | 支持的 GPU |
|---|---|---|
| CUDA 11.8 | 525.60+ | Compute Capability 5.0+ |
| CUDA 12.1 | 530.30+ | Compute Capability 6.0+ |
| CUDA 12.4 | 550.54+ | Compute Capability 7.0+ |
14.2.2 GPU 无法访问
错误信息：
RuntimeError: No CUDA GPUs are available
解决方案：
# 1. 检查 GPU 是否被识别
nvidia-smi
# 2. 检查 CUDA_VISIBLE_DEVICES
echo $CUDA_VISIBLE_DEVICES
# 3. 检查 GPU 是否被其他进程占用
nvidia-smi --query-compute-apps=pid,process_name --format=csv
# 4. 检查 Docker 中 GPU 是否可用
docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi
# 5. 重启 NVIDIA 驱动
sudo systemctl restart nvidia-persistenced
14.2.3 CUDA 非法内存访问
错误信息：
RuntimeError: CUDA error: an illegal memory access was encountered
可能原因及解决方案：
| 原因 | 解决方案 |
|---|---|
| GPU 硬件故障 | 检查 dmesg 中的 XID 错误 |
| 驱动 bug | 更新到最新稳定驱动 |
| 显存溢出 | 减小 gpu-memory-utilization |
| vLLM bug | 尝试 --enforce-eager 禁用 CUDA Graph |
# 检查 GPU 硬件错误
dmesg | grep -i "NVRM\|XID"
# 运行 GPU 诊断
sudo nvidia-smi -q | grep -A5 "Error"
14.2.4 XID 错误
错误信息（在 dmesg 中）：
NVRM: Xid (PCI:0000:00:04): 79, pid=12345, GPU has fallen off the bus
| XID Code | 含义 | 建议 |
|---|---|---|
| 13 | GR: Graphics Engine exception | 更新驱动 |
| 31 | GPU memory page fault | 检查显存/更新驱动 |
| 43 | GPU stopped processing | 重启 GPU/检查温度 |
| 79 | GPU fallen off bus | 严重：硬件问题或电源不足 |
| 94 | Contained ECC error | 检查 GPU 健康状态 |
# 重置 GPU
sudo nvidia-smi --gpu-reset -i 0
14.3 内存问题
14.3.1 GPU 显存不足（OOM）
错误信息：
torch.cuda.OutOfMemoryError: CUDA out of memory.
Tried to allocate X MiB (GPU 0; 80.00 GiB total capacity)
诊断：
# 查看当前显存使用
nvidia-smi
# 查看 GPU 进程
nvidia-smi --query-compute-apps=pid,process_name,used_memory --format=csv
解决方案（按优先级排序）：
# 方案 1：减小 GPU 显存使用率（最直接）
vllm serve model --gpu-memory-utilization 0.85 # 从默认 0.9 降到 0.85
# 方案 2：减小最大序列长度
vllm serve model --max-model-len 2048 # 从模型默认值减小
# 方案 3：使用量化
vllm serve model --quantization awq # 4-bit 量化
# 方案 4：增加张量并行（多卡分担）
vllm serve model --tensor-parallel-size 2
# 方案 5：减小批处理大小
vllm serve model --max-num-seqs 64 # 从默认 256 减小
# 方案 6：使用 FP8 KV Cache（H100/H200）
vllm serve model --kv-cache-dtype fp8
显存估算公式：
总显存 ≈ 模型权重 + KV Cache + 运行时开销
模型权重（FP16）≈ 参数量 × 2 bytes
7B → 14 GB
13B → 26 GB
70B → 140 GB
KV Cache ≈ 2 × num_layers × num_kv_heads × head_dim × seq_len × batch_size × 2 bytes
运行时开销 ≈ 1-3 GB
14.3.2 共享内存不足
错误信息：
Bus error (core dumped)
或
torch.multiprocessing.spawn: Process exited with error
解决方案：
# Docker 中
docker run --ipc=host --shm-size=16g ...
# 系统中
sudo mount -o remount,size=16G /dev/shm
# 检查当前大小
df -h /dev/shm
14.3.3 系统内存不足
错误信息：
Cannot allocate memory
解决方案：
# 1. 检查系统内存
free -h
# 2. 减小 swap 空间配置
vllm serve model --swap-space 2 # 从默认 4GB 减小
# 3. 增加系统 swap
sudo fallocate -l 32G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
14.4 模型加载问题
14.4.1 模型下载失败
错误信息：
OSError: [Errno 28] No space left on device
或
requests.exceptions.ConnectionError: Failed to download
解决方案：
# 1. 检查磁盘空间
df -h ~/.cache/huggingface
# 2. 使用自定义缓存目录
export HF_HOME=/data/huggingface
# 3. 使用 HuggingFace 镜像（国内）
export HF_ENDPOINT=https://hf-mirror.com
# 4. 提前下载模型
huggingface-cli download Qwen/Qwen2.5-7B-Instruct
# 5. 使用本地模型
vllm serve /data/models/Qwen2.5-7B-Instruct
14.4.2 模型格式不支持
错误信息：
ValueError: Model architectures ['MixtralForCausalLM'] are not supported
解决方案：
# 1. 检查支持的模型列表
python -c "from vllm.model_executor.models import MODEL_REGISTRY; print(list(MODEL_REGISTRY.keys()))"
# 2. 更新 vLLM 到最新版本
pip install --upgrade vllm
# 3. 使用 trust_remote_code（某些模型需要）
vllm serve model --trust-remote-code
14.4.3 Tokenizer 加载失败
错误信息：
OSError: Can't load tokenizer for 'model-name'
解决方案：
# 1. 指定 tokenizer 路径
vllm serve model --tokenizer /path/to/tokenizer
# 2. 使用慢速 tokenizer
vllm serve model --tokenizer-mode slow
# 3. 确认 tokenizer 文件完整
ls ~/.cache/huggingface/hub/models--Qwen--Qwen2.5-7B-Instruct/snapshots/*/
14.4.4 权重加载错误
错误信息：
RuntimeError: Error(s) in loading state_dict
可能原因：
- 权重文件损坏
- 模型架构不匹配
- 量化配置错误
解决方案：
# 1. 重新下载模型
rm -rf ~/.cache/huggingface/hub/models--model-name
huggingface-cli download model-name
# 2. 检查模型完整性
python -c "
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained('model-name')
print('模型加载成功')
"
14.5 API 与网络问题
14.5.1 连接拒绝
错误信息：
ConnectionRefusedError: [Errno 111] Connection refused
排查步骤：
# 1. 检查 vLLM 是否在运行
ps aux | grep vllm
# 2. 检查端口是否监听
ss -tlnp | grep 8000
# 3. 检查防火墙
sudo iptables -L -n | grep 8000
# 4. 检查健康端点
curl http://localhost:8000/health
# 5. 检查 vLLM 日志
docker logs vllm-server # Docker
journalctl -u vllm # systemd
14.5.2 请求超时
错误信息：
openai.APITimeoutError: Request timed out
解决方案：
# 1. 增加客户端超时
client = OpenAI(
base_url="http://localhost:8000/v1",
api_key="none",
timeout=300.0, # 5 分钟
max_retries=3,
)
# 2. 减小 max_tokens
response = client.chat.completions.create(
model="qwen-7b",
messages=[...],
max_tokens=256, # 不要太大
)
# 3. 使用流式输出（避免长等待）
response = client.chat.completions.create(
model="qwen-7b",
messages=[...],
stream=True,
)
14.5.3 模型名不匹配
错误信息：
{
"error": {
"message": "The model `my-model` does not exist.",
"type": "NotFoundError",
"code": 404
}
}
解决方案：
# 检查当前加载的模型名
curl http://localhost:8000/v1/models
# 使用正确的模型名
# --served-model-name 指定的名字才是 API 中使用的模型名
vllm serve model --served-model-name my-model
14.6 性能问题
14.6.1 推理速度慢
排查清单：
□ 检查 GPU 利用率
nvidia-smi → GPU-Util 应该 > 80%
□ 检查是否在用 GPU（而非 CPU）
nvidia-smi → 确认 vLLM 进程在 GPU 上
□ 检查批处理效率
curl localhost:8000/metrics | grep num_requests_running
→ 如果 < max_num_seqs，说明 GPU 未充分利用
□ 检查是否启用了 CUDA Graph
启动日志中应有 "CUDA Graph capturing" 相关信息
如果使用了 --enforce-eager，性能会下降 10-30%
□ 检查 Prompt 长度
长 Prompt 的 prefill 阶段很慢
→ 考虑启用 Chunked Prefill
□ 检查量化
未量化的模型推理较慢
→ 考虑 AWQ 或 FP8 量化
14.6.2 首 Token 延迟高（TTFT）
# 优化 TTFT 的措施：
# 1. 启用 Chunked Prefill
vllm serve model --enable-chunked-prefill --max-num-batched-tokens 512
# 2. 启用前缀缓存
vllm serve model --enable-prefix-caching
# 3. 减小 max_num_seqs（减少批大小对延迟的影响）
vllm serve model --max-num-seqs 32
# 4. 使用更快的 GPU（H100 比 A100 快 2-3x）
14.6.3 吞吐量低
# 优化吞吐量的措施：
# 1. 增大并发
vllm serve model --max-num-seqs 256
# 2. 增大 token 预算
vllm serve model --max-num-batched-tokens 16384
# 3. 使用张量并行
vllm serve model --tensor-parallel-size 4
# 4. 使用量化模型
vllm serve model --quantization awq
# 5. 增大 GPU 显存使用率
vllm serve model --gpu-memory-utilization 0.95
14.7 LoRA 相关问题
14.7.1 LoRA 加载失败
错误信息：
ValueError: LoRA adapter 'my-lora' not found
解决方案：
# 1. 确认适配器路径存在
ls /path/to/adapter/adapter_config.json
ls /path/to/adapter/adapter_model.bin
# 2. 确认启用了 LoRA
vllm serve model --enable-lora --lora-modules my-lora=/path/to/adapter
# 3. 确认 rank 一致
cat /path/to/adapter/adapter_config.json | grep r
# max-lora-rank 必须 >= 适配器的 rank
14.7.2 LoRA 精度问题
错误信息：
RuntimeError: Expected all tensors to be on the same device
解决方案：确保 LoRA 适配器是在与基础模型相同精度（FP16/BF16）上训练的。
14.8 Docker 相关问题
14.8.1 容器启动后立即退出
# 查看容器日志
docker logs vllm-server
# 常见原因及解决方案：
# 1. --ipc=host 缺失
# 错误: Bus error / segfault
docker run --ipc=host ...
# 2. 共享内存不足
docker run --shm-size=16g ...
# 3. GPU 不可见
docker run --gpus all ...
# 4. 模型下载失败（网络问题）
# → 挂载预下载的模型目录
docker run -v /data/models:/models ...
14.8.2 Docker 中 GPU 不可用
# 1. 检查 NVIDIA Container Toolkit
nvidia-ctk --version
# 2. 检查 Docker runtime
docker info | grep -i runtime
# 应该有 nvidia
# 3. 重新配置
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
# 4. 测试
docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi
14.9 分布式推理问题
14.9.1 张量并行初始化失败
错误信息：
RuntimeError: NCCL error: unhandled system error
解决方案：
# 1. 检查 GPU 间通信
nvidia-smi topo -m
# 2. 测试 NCCL
NCCL_DEBUG=INFO python -c "
import torch
torch.distributed.init_process_group('nccl')
print('NCCL 初始化成功')
"
# 3. 设置 NCCL 环境变量
export NCCL_DEBUG=INFO
export NCCL_P2P_DISABLE=0
export NCCL_SOCKET_IFNAME=eth0
14.9.2 Ray 集群问题
# 1. 检查 Ray 集群状态
ray status
# 2. 重启 Ray
ray stop
ray start --head
# 3. 清理 Ray 状态
ray stop
rm -rf /tmp/ray
ray start --head
14.10 问题速查表
| 症状 | 可能原因 | 快速解决方案 |
|---|---|---|
Bus error | 共享内存不足 | --ipc=host --shm-size=16g |
CUDA out of memory | 显存不足 | 减小 max-model-len 或 gpu-memory-utilization |
Connection refused | 服务未启动 | 检查进程和端口 |
| 模型下载慢 | 网络问题 | 使用镜像或预下载 |
| 推理速度慢 | 未充分利用 GPU | 检查批处理配置 |
| 容器启动后退出 | 配置错误 | 查看 docker logs |
| GPU 不可见 | NVIDIA 运行时未配置 | 安装 nvidia-container-toolkit |
| API 返回 404 | 模型名不匹配 | 检查 --served-model-name |
| 流式输出不工作 | Nginx 缓冲 | 设置 proxy_buffering off |
| TTFT 延迟高 | Prefill 慢 | 启用 Chunked Prefill |
14.11 获取帮助
如果上述方案都无法解决问题：
# 1. 收集诊断信息
echo "=== vLLM Version ===" && python -c "import vllm; print(vllm.__version__)"
echo "=== Python Version ===" && python --version
echo "=== CUDA Version ===" && nvcc --version
echo "=== GPU Info ===" && nvidia-smi
echo "=== PyTorch CUDA ===" && python -c "import torch; print(torch.version.cuda)"
echo "=== OS ===" && cat /etc/os-release
echo "=== Memory ===" && free -h
echo "=== Disk ===" && df -h
# 2. 开启调试日志
export VLLM_LOGGING_LEVEL=DEBUG
# 3. 提交 Issue
# GitHub: https://github.com/vllm-project/vllm/issues
14.12 扩展阅读
上一章：13 - Docker 容器化部署 | 下一章：15 - 生产最佳实践