部署目标

• 机器：8×A800 80G（仅用 0–3 共4张卡）
• 系统：Ubuntu 22.04（裸机）
• 模型：qwen/qwen2.5-vl-72b-instruct
• 下载：魔搭 ModelScope
• 部署：vLLM（OpenAI 兼容 API）
• 精度：优先 BF16（或 FP16），多卡张量并行（TP=4）

---

一、环境与版本约定

• NVIDIA Driver: 535.154.05
• CUDA Toolkit: 12.1.0
• Python: 3.10.x
• PyTorch: 2.1.2+cu121
• vLLM: 0.6.3.post1
• transformers: 4.45.2
• accelerate: 0.34.2
• pillow: 10.4.0
• modelscope: 1.15.0

---

二、系统与基础环境

# 基础工具
sudo apt update && sudo apt upgrade -y
sudo apt install -y wget curl git build-essential software-properties-common net-tools

# 驱动（若未安装）
sudo add-apt-repository ppa:graphics-drivers/ppa -y
sudo apt update
sudo apt install -y nvidia-driver-535
sudo reboot

# 验证
nvidia-smi

CUDA 12.1（工具包可选，PyTorch wheel 已含 CUDA Runtime）

wget https://developer.download.nvidia.com/compute/cuda/12.1.0/local_installers/cuda_12.1.0_530.30.02_linux.run
sudo sh cuda_12.1.0_530.30.02_linux.run --silent --toolkit
echo 'export PATH=/usr/local/cuda-12.1/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc
nvcc --version

Python 3.10 与虚拟环境

sudo apt install -y python3.10 python3.10-venv python3.10-dev python3-pip
mkdir -p ~/llm-env && cd ~/llm-env
python3.10 -m venv llm
source llm/bin/activate
pip install --upgrade pip setuptools wheel

---

三、模型获取（魔搭 ModelScope）

pip install modelscope==1.15.0

# 下载到用户目录 ~/models 下（推荐）
python - << 'PY'
import os
from modelscope import snapshot_download
cache_dir = os.path.expanduser('~/models')
path = snapshot_download('qwen/Qwen2.5-VL-72B-Instruct', cache_dir=cache_dir)
print('Model Path:', path)
PY

# 创建统一的模型路径软链，便于后续 vLLM 启动脚本使用
ln -sfn ~/models/qwen/Qwen2.5-VL-72B-Instruct ~/models/qwen2.5-vl-72b-instruct

注意：VL 模型体积很大（权重+视觉编码器），确保磁盘 > 200GB，网络稳定。

---

四、使用 vLLM 启动模型

安装依赖

source ~/llm-env/llm/bin/activate
pip install torch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 --index-url https://download.pytorch.org/whl/cu121
pip install vllm==0.6.3.post1 transformers==4.45.2 accelerate==0.34.2 pillow==10.4.0
python -c "import torch, vllm; print(torch.__version__, vllm.__version__)"

多卡环境变量（仅用 0–3 四张 A800）

export CUDA_VISIBLE_DEVICES=0,1,2,3
export NCCL_P2P_LEVEL=SYS
export NCCL_IB_DISABLE=1         # 若无 IB 网络
export NVIDIA_TF32_OVERRIDE=0

启动脚本（OpenAI 兼容 API）

cat > ~/start_vllm_qwen25vl72b.sh << 'EOF'
#!/bin/bash
source ~/llm-env/llm/bin/activate
export CUDA_VISIBLE_DEVICES=0,1,2,3
export NCCL_P2P_LEVEL=SYS
export NCCL_IB_DISABLE=1

MODEL_DIR=~/models/qwen2.5-vl-72b-instruct

python -m vllm.entrypoints.openai.api_server \
  --model ${MODEL_DIR} \
  --served-model-name qwen2.5-vl-72b-instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --dtype bfloat16 \
  --tensor-parallel-size 4 \
  --max-model-len 8192 \
  --max-num-seqs 64 \
  --gpu-memory-utilization 0.9 \
  --trust-remote-code \
  --enable-chunked-prefill \
  --disable-log-requests
EOF

chmod +x ~/start_vllm_qwen25vl72b.sh
nohup ~/start_vllm_qwen25vl72b.sh > ~/vllm_72b.log 2>&1 &
tail -f ~/vllm_72b.log

连通性/健康检查

netstat -tunlp | grep 8000
nvidia-smi

文本测试

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-vl-72b-instruct",
    "messages": [{"role":"user","content":"你好，简单自我介绍一下"}],
    "max_tokens": 128,
    "temperature": 0.7
  }'

多模态（图片）测试

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-vl-72b-instruct",
    "messages": [{
      "role": "user", 
      "content": [
        {"type":"text","text":"这张图片的主要内容是什么？"},
        {"type":"image_url","image_url":{"url":"https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen-VL/assets/demo.jpeg"}}
      ]
    }],
    "max_tokens": 256,
    "temperature": 0.2
  }'

性能与内存建议

• 初始参数：--dtype bfloat16 --max-model-len 8192 --max-num-seqs 64 --gpu-memory-utilization 0.9
• 若 OOM：降低 --max-model-len 到 4096/6144，或降低 --max-num-seqs 到 32
• 生产：固定 CUDA_VISIBLE_DEVICES=0,1,2,3，TP=4；其余 GPU 可作备机或部署他模

---

五、网关与暴露（可选 Nginx）

sudo apt install -y nginx
sudo tee /etc/nginx/sites-available/llm << 'EOF'
server {
    listen 80;
    server_name _;

    location /v1/ {
        proxy_pass http://127.0.0.1:8000;   # vLLM 服务
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 300s;
    }
}
EOF
sudo ln -sf /etc/nginx/sites-available/llm /etc/nginx/sites-enabled/llm
sudo nginx -t && sudo systemctl restart nginx

---

六、调优建议（72B × 4卡）

• vLLM 初始：--dtype bfloat16 --max-model-len 8192 --max-num-seqs 64 --gpu-memory-utilization 0.9
• OOM 解决：降低上下文（4096/6144）与并发（max-num-seqs / cache entry）
• 首 Token 延迟：开启 --enable-chunked-prefill
• 多模态额外显存：VL 模型需为视觉塔和图像特征预留 2–6GB/GPU
• 稳定性：将 CUDA_VISIBLE_DEVICES 固定为 0–3；其余 4 卡可独立部署其他服务

---

七、常见问题

• 启动显存不足
  • 降低 max-model-len、max-num-seqs/cache_max_entry_count
  • 确保无其他进程占用（nvidia-smi）
• 模型加载失败
  • 检查目录是否含 config.json、*.safetensors、tokenizer.json、vision 模块文件
  • 使用 --trust-remote-code
• 多模态不工作
  • 确保使用 chat.completions 且 content 为数组，含 image_url 结构
  • 网络能访问图片 URL；本地图片需转 data URI 或用可访问的 URL

---

八、版本与健康检查清单

• 驱动 535.154.05，nvidia-smi 正常
• CUDA 12.1，nvcc --version 正常
• PyTorch 2.1.2+cu121，torch.cuda.is_available() 为 True
• vLLM 0.6.3.post1 可正常启动
• 端口监听：vLLM:8000
• 文本与图片请求均返回正常
• GPU 显存占用符合期望（72B×BF16×TP4，8K上下文下单实例稳态）

---

文档版本：v1.1
更新日期：2025-10-30