故障排查与调试

在使用 vLLM 过程中，可能会遇到各种问题。本章整理了常见问题及其解决方案，帮助你快速定位和解决问题。

显存相关问题

CUDA Out of Memory

这是最常见的问题，通常表现为以下错误信息：

OutOfMemoryError: CUDA out of memory. Tried to allocate X.XX GiB

原因分析：

1. 模型太大，GPU 显存不足以容纳
2. max_model_len 设置过大，KV Cache 占用过多显存
3. 批处理参数设置不当，同时处理过多请求
4. 显存碎片化导致无法分配连续内存

解决方案：

方案一：降低显存利用率参数

from vllm import LLM

llm = LLM(
    model="meta-llama/Llama-2-7b-chat-hf",
    gpu_memory_utilization=0.7,  # 从默认 0.9 降低到 0.7
)

方案二：限制最大序列长度

llm = LLM(
    model="meta-llama/Llama-2-7b-chat-hf",
    max_model_len=2048,  # 从默认 4096 降低
)

方案三：使用量化

# 使用 AWQ 量化模型
llm = LLM(
    model="TheBloke/Llama-2-7B-AWQ",
    quantization="awq"
)

# 或使用 GPTQ 量化模型
llm = LLM(
    model="TheBloke/Llama-2-7B-GPTQ",
    quantization="gptq"
)

方案四：使用张量并行

# 将模型分布到多个 GPU
llm = LLM(
    model="meta-llama/Llama-2-70b-chat-hf",
    tensor_parallel_size=4
)

方案五：减少并发数

llm = LLM(
    model="meta-llama/Llama-2-7b-chat-hf",
    max_num_seqs=64,  # 减少最大并发序列数
    max_num_batched_tokens=2048  # 减少批次大小
)

显存碎片化

现象：虽然有足够的空闲显存，但仍然无法分配内存。

解决方案：

# 启动时设置环境变量，减少碎片化
export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
vllm serve meta-llama/Llama-2-7b-chat-hf

KV Cache 显存不足

现象：日志显示 GPU KV cache size 很小，并发能力不足。

解决方案：

1. 降低 max_model_len 以减少每个请求的 KV Cache 需求
2. 增加 GPU 数量使用张量并行
3. 启用 CPU 卸载（如果适用）

模型加载问题

模型下载超时或失败

现象：

ConnectionError: Couldn't reach https://huggingface.co/...
ReadTimeoutError: HTTPSConnectionPool...

解决方案：

方案一：使用国内镜像

# 设置 Hugging Face 镜像
export HF_ENDPOINT=https://hf-mirror.com

import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

方案二：使用代理

export HTTPS_PROXY=http://your-proxy:port
export HTTP_PROXY=http://your-proxy:port

方案三：手动下载模型

# 安装 huggingface-cli
pip install huggingface-hub

# 下载模型到本地
huggingface-cli download meta-llama/Llama-2-7b-chat-hf \
    --local-dir ./models/llama-2-7b-chat

# 使用本地路径
vllm serve ./models/llama-2-7b-chat

方案四：使用 ModelScope（国内用户）

from modelscope import snapshot_download

model_dir = snapshot_download("modelscope/Llama-2-7b-chat-ms")

模型格式不支持

现象：

ValueError: Model architecture 'xxx' is not supported
KeyError: 'xxx'

解决方案：

1. 检查 vLLM 版本，更新到最新版本
2. 查看 vLLM 支持的模型列表
3. 对于自定义模型，可能需要实现对应的模型加载器

权重文件损坏

现象：

RuntimeError: PytorchStreamReader failed reading zip archive

解决方案：

# 删除缓存重新下载
rm -rf ~/.cache/huggingface/hub/models--meta-llama--Llama-2-7b-chat-hf

# 重新运行
vllm serve meta-llama/Llama-2-7b-chat-hf

性能问题

推理速度慢

可能原因及解决方案：

原因一：GPU 利用率低

# 监控 GPU 使用情况
nvidia-smi -l 1

# 如果 GPU 利用率低，尝试增加批次大小
vllm serve meta-llama/Llama-2-7b-chat-hf \
    --max-num-seqs 256 \
    --max-num-batched-tokens 8192

原因二：没有使用 Flash Attention

# 确保安装了 Flash Attention
pip install flash-attn --no-build-isolation

# vLLM 会自动检测并使用

原因三：CPU-GPU 数据传输瓶颈

# 减少数据传输，使用 pinned memory
llm = LLM(
    model="meta-llama/Llama-2-7b-chat-hf",
    enforce_eager=True  # 在某些情况下可以提高性能
)

首 Token 延迟高

解决方案：

# 启用 Chunked Prefill
vllm serve meta-llama/Llama-2-7b-chat-hf \
    --enable-chunked-prefill \
    --max-num-batched-tokens 2048

吞吐量不足

解决方案：

1. 增加 max_num_seqs 和 max_num_batched_tokens
2. 使用数据并行扩展服务能力
3. 启用前缀缓存减少重复计算

vllm serve meta-llama/Llama-2-7b-chat-hf \
    --max-num-seqs 512 \
    --max-num-batched-tokens 16384 \
    --enable-prefix-caching \
    --data-parallel-size 2

网络和服务问题

API 服务无响应

排查步骤：

1. 检查服务是否正常启动

# 检查进程
ps aux | grep vllm

# 检查端口
netstat -tlnp | grep 8000

2. 检查防火墙设置

# Linux
sudo ufw allow 8000

# 或使用 iptables
sudo iptables -A INPUT -p tcp --dport 8000 -j ACCEPT

3. 检查绑定地址

# 确保绑定到所有接口
vllm serve meta-llama/Llama-2-7b-chat-hf \
    --host 0.0.0.0 \
    --port 8000

请求超时

现象：

ReadTimeoutError: HTTPConnectionPool(host='localhost', port=8000): Read timed out.

解决方案：

1. 检查服务器负载
2. 增加客户端超时时间

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed",
    timeout=300.0  # 增加超时时间
)

3. 减少请求的 max_tokens

流式输出中断

现象：流式输出突然中断，不完整。

解决方案：

检查网络连接稳定性，必要时增加重试逻辑：

from openai import OpenAI
import time

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")

def generate_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            stream = client.chat.completions.create(
                model="meta-llama/Llama-2-7b-chat-hf",
                messages=[{"role": "user", "content": prompt}],
                stream=True,
                timeout=60
            )
            
            full_response = ""
            for chunk in stream:
                if chunk.choices[0].delta.content:
                    content = chunk.choices[0].delta.content
                    full_response += content
                    yield content
            return  # 成功完成
            
        except Exception as e:
            if attempt == max_retries - 1:
                raise e
            time.sleep(2 ** attempt)  # 指数退避

分布式部署问题

Ray 集群连接失败

现象：

RayConnectionError: Could not connect to Ray head node

解决方案：

1. 检查 Ray 集群状态

ray status
ray list nodes

2. 检查网络连接

# 确保 head 节点可达
ping head-node-ip
telnet head-node-ip 6379

3. 检查防火墙

# Ray 默认使用以下端口
# 6379: Redis（Ray head）
# 8265: Ray Dashboard
# 10001-19999: 临时端口

节点间通信超时

现象：

NCCL error: unhandled system error
NCCL WARN Call to connect returned Connection refused

解决方案：

1. 增加超时时间

export NCCL_TIMEOUT=1800  # 30 分钟
export NCCL_BLOCKING_WAIT=1

2. 检查 InfiniBand 配置

# 验证 IB 接口
ibv_devinfo

# 检查 NCCL 使用的网络
NCCL_DEBUG=INFO vllm serve ...

GPU 不可见

现象：多卡系统只检测到部分 GPU。

解决方案：

# 检查 GPU 可见性
echo $CUDA_VISIBLE_DEVICES

# 指定可见 GPU
CUDA_VISIBLE_DEVICES=0,1,2,3 vllm serve ...

# 或在代码中设置
import os
os.environ["CUDA_VISIBLE_DEVICES"] = "0,1,2,3"

量化相关问题

量化模型加载失败

现象：

ValueError: Cannot find the quantization config file
KeyError: 'quantization_config'

解决方案：

确保使用正确的量化模型名称或路径：

# AWQ 量化模型
llm = LLM(model="TheBloke/Llama-2-7B-AWQ")

# GPTQ 量化模型
llm = LLM(model="TheBloke/Llama-2-7B-GPTQ")

# 或明确指定量化类型
llm = LLM(
    model="meta-llama/Llama-2-7b-chat-hf",
    quantization="awq",
    load_format="auto"
)

量化精度问题

现象：量化后模型输出质量下降明显。

解决方案：

1. 尝试不同的量化方法（AWQ 通常比 GPTQ 精度更高）
2. 使用更高精度的量化（如 INT8 而非 INT4）
3. 对特定任务进行量化感知微调

调试技巧

启用详细日志

# 启用 vLLM 调试日志
export VLLM_LOGGING_LEVEL=DEBUG
vllm serve meta-llama/Llama-2-7b-chat-hf

# 启用 NCCL 调试日志
export NCCL_DEBUG=INFO
vllm serve meta-llama/Llama-2-7b-chat-hf

# 同时启用多个调试输出
VLLM_LOGGING_LEVEL=DEBUG NCCL_DEBUG=INFO vllm serve meta-llama/Llama-2-7b-chat-hf

检查 GPU 状态

# 实时监控 GPU
watch -n 1 nvidia-smi

# 详细 GPU 信息
nvidia-smi -q

# 查看 GPU 进程
nvidia-smi pmon -c 10

性能分析

import time
from vllm import LLM, SamplingParams

llm = LLM(model="meta-llama/Llama-2-7b-chat-hf")
sampling_params = SamplingParams(max_tokens=100)

# 性能测试
prompts = ["Hello"] * 100

start = time.time()
outputs = llm.generate(prompts, sampling_params)
end = time.time()

total_tokens = sum(len(o.outputs[0].token_ids) for o in outputs)
throughput = total_tokens / (end - start)

print(f"吞吐量: {throughput:.2f} tokens/s")
print(f"平均延迟: {(end-start)/len(prompts):.2f} s")

内存分析

import torch

# 打印 GPU 内存使用情况
def print_memory():
    allocated = torch.cuda.memory_allocated() / 1024**3
    reserved = torch.cuda.memory_reserved() / 1024**3
    print(f"已分配: {allocated:.2f} GB, 已预留: {reserved:.2f} GB")

print_memory()
# 运行推理
outputs = llm.generate(prompts, sampling_params)
print_memory()

常见错误代码参考

错误信息	可能原因	解决方案
CUDA out of memory	显存不足	降级参数、使用量化、增加 GPU
RuntimeError: CUDA error: device-side assert triggered	CUDA 内核错误	检查输入数据、更新驱动
ValueError: Model architecture not supported	模型不支持	更新 vLLM 或使用支持的模型
ConnectionError	网络问题	检查网络、使用镜像
KeyError: 'quantization_config'	量化配置缺失	使用正确的量化模型
NCCL error	分布式通信问题	检查网络、防火墙配置

获取帮助

如果以上方法都无法解决问题，可以：

1. 查看 vLLM GitHub Issues 中是否有类似问题
2. 在 GitHub 上提交新的 Issue，包含：
   • vLLM 版本
   • GPU 型号和驱动版本
   • 完整的错误信息
   • 复现步骤
3. 加入 vLLM 社区讨论

参考资料

• vLLM GitHub Issues
• vLLM 故障排查文档
• NCCL 文档