本文基于实战经验，提供从环境准备到性能调优的全流程避坑指南。

一、环境准备：驱动与硬件兼容性

1. NVIDIA 驱动与 CUDA 版本对齐

确保NVIDIA驱动和CUDA版本相互匹配是关键。例如，CUDA 12.x需要至少525.60+的驱动版本。

# 使用 nvidia-smi 查看驱动状态
nvidia-smi
# 确认 CUDA 版本是否与 PyTorch 安装版本一致
nvcc --version

2. 物理设备识别与资源竞争

多GPU环境下，通过设置 CUDA_VISIBLE_DEVICES 来指定使用的GPU，以避免资源争抢。

export CUDA_VISIBLE_DEVICES=0,1 # 仅使用 GPU 0 和 1

二、依赖安装：PyTorch 与 vLLM 版本管理

1. PyTorch 版本选择

为了确保PyTorch能够正确调用GPU，需选择与CUDA版本相匹配的PyTorch版本。

pip install torch==2.1.2 torchvision==0.16.2 --extra-index-url https://download.pytorch.org/whl/cu121

2. vLLM 安装与更新

建议从源码编译安装以启用最新优化功能。

git clone https://github.com/vllm-project/vllm.git
cd vllm && pip install -e . # 开发模式安装

三、模型部署：配置与启动

1. 模型加载参数优化

为防止显存不足(OOM)，特别是在处理长文本时，应调整相关参数。

python -m vllm.entrypoints.api_server \
  --model deepseek-ai/deepseek-llm-7b-base \
  --tensor-parallel-size 2 \          # 多卡并行
  --gpu-memory-utilization 0.9 \      # 显存利用率上限
  --max-num-batched-tokens 4096       # 批处理 token 数

2. API 服务端口冲突

为了避免默认端口被占用的问题，可以指定一个未使用的端口号。

python -m vllm.entrypoints.api_server --port 8001
curl http://localhost:8001/v1/models # 测试连通性

四、性能调优：吞吐量与延迟平衡

1. 连续批处理（Continuous Batching）

启用动态批处理机制可以提高GPU利用率。

from vllm import SamplingParams
sampling_params = SamplingParams(max_tokens=512, batch_type="auto")

2. 量化与显存压缩

利用AWQ/GPTQ技术进行模型量化，减少显存需求。

python -m vllm.entrypoints.api_server \
  --model deepseek-ai/deepseek-llm-7b-base-awq \
  --quantization awq \
  --dtype half

五、常见错误与排查

对于常见的错误如CUDA Out of Memory或模型加载失败，提供详细的排查步骤和解决方案。

六、监控与日志

使用 nvidia-smi 实时监控GPU利用率，并分析vLLM的日志文件来定位潜在问题。

vllm链接：https://vllm.hyper.ai/docs/getting-started/installation/
deepseek 开源链接：https://www.modelscope.cn/docs/models/download