环境

```
好的，信息已经很完整了！帮你整理一份从零开始、针对 RTX 4090 + Ubuntu 部署 vLLM + Qwen3.5 的完整指南。

---

# Ubuntu + RTX 4090 搭建 vLLM 跑 Qwen3.5 完整指南

---

## 📋 前置了解：4090 能跑哪个 Qwen3.5 模型？

Qwen3.5 目前发布的尺寸包括：0.8B、4B、9B、27B、35B-A3B（MoE）、397B-A17B（MoE）等。

针对 RTX 4090（24GB VRAM），推荐选择：

| 模型 | 显存占用 | 推荐程度 |
|------|---------|---------|
| `Qwen/Qwen3.5-9B` | ~18GB（FP16） | ✅ 单卡跑满 |
| `Qwen/Qwen3.5-4B` | ~8GB | ✅ 很宽裕 |
| `Qwen/Qwen3.5-35B-A3B` | 需量化到 INT4 | ⚠️ 需 GPTQ/AWQ |

> **推荐首选 `Qwen/Qwen3.5-9B`**，单卡 4090 跑 FP16 很舒服，效果好，无需量化。

---

## 第一步：安装 NVIDIA 驱动

```bash
# 更新系统
sudo apt update && sudo apt upgrade -y

# 自动安装推荐驱动
sudo ubuntu-drivers autoinstall

# 或手动安装（推荐 535+ 版本）
sudo apt install -y nvidia-driver-550

# 重启
sudo reboot
```

重启后验证：
```bash
nvidia-smi
```

如果 `nvidia-smi` 执行失败，请不要继续后面的步骤，驱动问题必须先解决。

---

## 第二步：安装 CUDA Toolkit（12.x）

```bash
# 检查当前 CUDA 版本
nvidia-smi  # 右上角会显示最高支持的 CUDA 版本

# Ubuntu 22.04 安装 CUDA 12.4 示例（按 nvidia-smi 显示版本选择）
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update
sudo apt install -y cuda-toolkit-12-4

# 写入环境变量
echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

# 验证
nvcc --version
```

---

## 第三步：安装 Python 环境管理工具（推荐 uv）

官方推荐使用 `uv` 这个速度很快的 Python 环境管理器来创建和管理 Python 虚拟环境。

```bash
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.cargo/env
source $HOME/.local/bin/env

# 创建 Python 3.12 虚拟环境
uv venv vllm-env --python 3.12 --seed
source vllm-env/bin/activate
```

---

## 第四步：安装 vLLM

可以用 `uv pip install` 安装 vLLM，使用 `--torch-backend=auto` 自动选择合适的 torch 后端。

```bash
# 激活环境（如果还没激活）
source vllm-env/bin/activate

# 安装 vLLM（推荐方式）
uv pip install -U vllm --torch-backend=auto

# 验证安装
python -c "import vllm; print(vllm.__version__)"
```

> 国内网络慢的话可以加镜像源：  
> `uv pip install -U vllm --torch-backend=auto -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple`

---

## 第五步：下载 Qwen3.5 模型

```bash
# 安装 huggingface_hub
uv pip install huggingface_hub

# 下载模型（以 9B 为例）
huggingface-cli download Qwen/Qwen3.5-9B --local-dir ./models/Qwen3.5-9B
```

**国内用户推荐用 ModelScope 下载：**

国内无法访问 HuggingFace 的用户，强烈推荐使用 ModelScope，通过设置环境变量 `VLLM_USE_MODELSCOPE=true` 即可让 vLLM 自动从 ModelScope 下载。

```bash
# 方法：直接在启动命令前加环境变量
VLLM_USE_MODELSCOPE=true vllm serve Qwen/Qwen3.5-9B ...
```

---

## 第六步：启动 vLLM 服务

### 基础启动（9B 模型，单卡 4090）

官方推荐的 Qwen3.5-9B vLLM 启动命令如下：

```bash
vllm serve Qwen/Qwen3.5-9B \
  --port 8000 \
  --tensor-parallel-size 1 \
  --max-model-len 32768 \
  --reasoning-parser qwen3 \
  --gpu-memory-utilization 0.9
```

### 如果 OOM 了（显存不够）
```bash
# 缩短上下文窗口
vllm serve Qwen/Qwen3.5-9B \
  --port 8000 \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.85 \
  --reasoning-parser qwen3
```

### 启用工具调用（Function Calling）
```bash
vllm serve Qwen/Qwen3.5-9B \
  --port 8000 \
  --tensor-parallel-size 1 \
  --max-model-len 32768 \
  --reasoning-parser qwen3 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_coder
```

---

## 第七步：测试 API

```bash
# 测试是否正常响应（OpenAI 兼容格式）
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3.5-9B",
    "messages": [
      {"role": "user", "content": "你好，介绍一下你自己"}
    ],
    "max_tokens": 512
  }'
```

---

## 📝 关键注意事项

**关于 Qwen3.5 的思考模式：**
Qwen3.5 模型默认以思考模式运行，会先生成 `<think>...</think>` 内容再输出最终答案。如果想关闭思考模式，可以在请求体中指定相关参数。

**关于 `--max-model-len`：**
Qwen3.5 默认上下文长度为 262,144 tokens，如遇 OOM 错误需调低该参数，但官方建议至少保持 128K 以上以保留思考能力。单卡 4090 建议设为 `32768` 或 `16384`。

**关于量化运行 35B-A3B（进阶）：**
如果想在 4090 上跑 35B-A3B MoE 模型，需要使用 GPTQ Int4 量化版本，并配合 `--quantization gptq_marlin --dtype bfloat16 --kv-cache-dtype fp8` 参数。

---

## 🚀 快速参考命令汇总

```bash
# 1. 进入虚拟环境
source vllm-env/bin/activate

# 2. 启动服务（推荐配置）
vllm serve Qwen/Qwen3.5-9B \
  --port 8000 \
  --max-model-len 32768 \
  --gpu-memory-utilization 0.9 \
  --reasoning-parser qwen3

# 3. 后台运行
nohup vllm serve Qwen/Qwen3.5-9B \
  --port 8000 \
  --max-model-len 32768 \
  --gpu-memory-utilization 0.9 \
  --reasoning-parser qwen3 > vllm.log 2>&1 &
```

有什么步骤卡住了随时告诉我，比如驱动报错、显存不够、网络下载问题等，我可以帮你具体排查！
```