老规矩，该教程是针对没有 sudo 权限的普通用户；以下是在 Conda 虚拟环境中使用 vLLM 部署 Qwen3.5-35B-A3B-GPTQ-Int4 模型的完整教程。

一、环境准备

1.1 硬件和系统要求

• 操作系统：Linux（推荐 Ubuntu 20.04+）
• GPU：NVIDIA GPU，Compute Capability 7.0 或以上（如 V100、RTX 30/40系列、A100、H100等）
• 显存：建议至少 24GB（如 RTX 4090 单卡可跑，双卡更稳定）
• CUDA：11.8 或更高版本
• 驱动：NVIDIA 驱动 525.60.13 以上

💡 该模型采用 MoE 架构，总参数量 35B，但单次仅激活约 3B 参数，因此显存需求比同尺寸密集模型低得多，一张 24GB 的 RTX 4090 即可部署。

1.2 安装 Miniconda / Anaconda

如果系统尚未安装 Conda，建议先安装 Miniconda：

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
source ~/.bashrc

1.3 创建 Conda 虚拟环境

官方文档推荐使用 Conda 创建独立 Python 环境，但请注意：建议仅用 Conda 创建 Python 环境，而非通过 Conda 安装 PyTorch 等包（因为 Conda 的 PyTorch 会静态链接 NCCL，可能导致 vLLM 运行时出现兼容性问题）。

# 创建虚拟环境，Python 版本选择 3.10～3.12
conda create -n vllm python=3.10 -y

# 激活环境
conda activate vllm

# 安装 pip（确保使用环境内的 pip）
pip install --upgrade pip

1.4 安装 vLLM

通过 pip 直接安装 vLLM（推荐使用最新稳定版）：

pip install vllm

如果需要使用最新功能或特定版本：

# 安装预发布版（nightly build）
pip install -U vllm --pre --extra-index-url https://wheels.vllm.ai/nightly

安装完成后，验证安装是否成功：

python -c "import vllm; print(vllm.__version__)"

---

二、下载模型

2.1 从魔搭社区等平台下载 GGUF 格式模型文件——推荐

安装 modelscope 工具，然后下载模型，建议将文件放在专用目录

# 安装
pip install modelscope
# 下载完整模型库到指定目录
modelscope download --model Qwen/Qwen3.5-35B-A3B-GPTQ-Int4  --local_dir ./dir
# 下载单个文件到指定本地文件夹（以下载README.md到当前路径下“dir”目录为例）
modelscope download --model Jackrong/Qwen3.5-9B-DeepSeek-V4-Flash-GGUF README.md --local_dir ./dir

[!NOTE]
更多关于modelscope下载的方式见：模型的下载 · 文档中心

2.2 使用 huggingface-cli 下载

首先安装 Hugging Face Hub 工具：

pip install huggingface-hub

然后下载模型：

# 下载模型到指定目录（以 ./models/Qwen3.5-35B-A3B-GPTQ-Int4 为例）
huggingface-cli download Qwen/Qwen3.5-35B-A3B-GPTQ-Int4 --local-dir ./models/Qwen3.5-35B-A3B-GPTQ-Int4

2.3 使用 git lfs 下载

# 安装 git-lfs（如未安装）
sudo apt-get install git-lfs
git lfs install

# 克隆模型仓库
git clone https://huggingface.co/Qwen/Qwen3.5-35B-A3B-GPTQ-Int4 ./models/Qwen3.5-35B-A3B-GPTQ-Int4

模型下载完成后，目录中应包含 config.json、model-*.safetensors 以及 GPTQ 量化配置文件（如 quantize_config.json）。

---

三、部署推理服务

3.1 启动 OpenAI 兼容 API 服务

vLLM 提供了 OpenAI 兼容的 API 服务器，是最常用的部署方式：

CUDA_VISIBLE_DEVICES=0 vllm serve ./models/Qwen3.5-35B-A3B-GPTQ-Int4 \
    --host 0.0.0.0 \
    --port 8000 \
    --tensor-parallel-size 1 \
    --gpu-memory-utilization 0.9 \
    --max-model-len 8192 \
    --trust-remote-code

参数说明：

参数	说明	推荐值
--host	监听地址，0.0.0.0 表示允许外部访问	0.0.0.0
--port	API 服务端口	8000
--tensor-parallel-size	GPU 张量并行数，1 表示单卡，多卡可设为 2/4/8	1（单卡24GB）
--gpu-memory-utilization	GPU 显存利用率	0.9
--max-model-len	最大上下文长度（tokens）	8192（可根据需求调整）
--trust-remote-code	信任远程代码（Qwen 系列需要）	必须添加

3.2 多 GPU 并行部署（双卡示例）

如果显存不足或需要更高吞吐，可使用多卡并行：

CUDA_VISIBLE_DEVICES=0,1 vllm serve ./models/Qwen3.5-35B-A3B-GPTQ-Int4 \
    --host 0.0.0.0 \
    --port 8000 \
    --tensor-parallel-size 2 \
    --gpu-memory-utilization 0.9 \
    --max-model-len 8192 \
    --trust-remote-code

3.3 启用 FP8 KV Cache 节省显存

对于需要处理长文本的场景，可通过 --kv-cache-dtype fp8 减少 KV Cache 的显存占用：

CUDA_VISIBLE_DEVICES=0,1 vllm serve ./models/Qwen3.5-35B-A3B-GPTQ-Int4 \
    --host 0.0.0.0 \
    --port 8000 \
    --tensor-parallel-size 2 \
    --gpu-memory-utilization 0.9 \
    --max-model-len 32768 \
    --kv-cache-dtype fp8 \
    --trust-remote-code

📌 kv-cache-dtype fp8 以 FP8 格式存储 KV Cache，可将长文本推理场景下的显存占用降低约 50%。

---

四、验证部署

4.1 使用 curl 测试

服务启动后，在另一终端窗口执行以下命令测试：

curl http://localhost:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "./models/Qwen3.5-35B-A3B-GPTQ-Int4",
        "messages": [
            {"role": "user", "content": "介绍一下什么是大语言模型"}
        ],
        "max_tokens": 512,
        "temperature": 0.7
    }'

4.2 使用 Python 客户端测试

from openai import OpenAI

# 配置 OpenAI 客户端指向 vLLM 服务
client = OpenAI(
    api_key="EMPTY",
    base_url="http://localhost:8000/v1"
)

# 发送对话请求
response = client.chat.completions.create(
    model="./models/Qwen3.5-35B-A3B-GPTQ-Int4",
    messages=[
        {"role": "user", "content": "介绍一下什么是大语言模型"}
    ],
    max_tokens=512,
    temperature=0.7
)

print(response.choices[0].message.content)

4.3 查看服务日志

服务启动时会在控制台输出显存分配信息、模型加载进度等日志。正常加载完成后应看到类似以下信息：

INFO:     Started server process [xxxxx]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

---

五、常见问题及解决方案

5.1 显存不足（OOM）

问题现象：启动时或推理过程中提示 CUDA out of memory。

解决方法：

策略	操作
降低 --max-model-len	设为 4096 或 2048
降低 --gpu-memory-utilization	设为 0.7 或 0.5
增加 GPU 数量	使用多卡并行，--tensor-parallel-size 2
启用 FP8 KV Cache	添加 --kv-cache-dtype fp8
关闭 CUDA Graph	添加 --enforce-eager

# 显存受限时的推荐启动命令
vllm serve ./models/Qwen3.5-35B-A3B-GPTQ-Int4 \
    --gpu-memory-utilization 0.7 \
    --max-model-len 4096 \
    --enforce-eager \
    --trust-remote-code

5.2 模型加载失败 / 找不到量化配置

问题现象：提示 No quantized configuration found 或加载卡住。

解决方法：

• 确保模型目录中包含 GPTQ 量化配置文件（quantize_config.json）
• Qwen 官方发布的 GPTQ 模型已包含完整配置，可直接使用
• 如果从其他渠道下载，检查文件完整性

5.3 CUDA 版本不兼容

问题现象：安装或运行时提示 CUDA 版本相关错误。

解决方法：

• 检查 CUDA 版本：nvcc --version
• vLLM 要求 CUDA 11.8 或更高版本
• 如果版本不匹配，建议重新安装对应 CUDA 版本的 PyTorch：

  pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
  pip install vllm
  

5.4 推理速度慢 / 首 Token 延迟高

问题现象：回复生成速度慢，或第一条响应延迟过长。

解决方法：

• 确保 tensor-parallel-size 与 GPU 数量对齐
• 适当调高 max-num-batched-tokens（如 65536）以提升批处理效率
• 避免过于激进的显存限制（gpu-memory-utilization 不宜过低）

---

六、完整一键部署脚本

以下脚本整合了整个部署流程，可直接保存为 deploy_qwen35.sh 执行：

#!/bin/bash

# ============================================
# vLLM + Qwen3.5-35B-A3B-GPTQ-Int4 部署脚本
# ============================================

set -e

# 配置项
MODEL_NAME="Qwen/Qwen3.5-35B-A3B-GPTQ-Int4"
MODEL_DIR="./models/Qwen3.5-35B-A3B-GPTQ-Int4"
CONDA_ENV_NAME="vllm"
PYTHON_VERSION="3.10"
API_PORT=8000
TENSOR_PARALLEL_SIZE=1
GPU_MEM_UTIL=0.9
MAX_MODEL_LEN=8192

# 颜色输出
RED='\033[0;31m'
GREEN='\033[0;32m'
NC='\033[0m'

echo -e "${GREEN}Step 1: 创建 Conda 环境...${NC}"
conda create -n $CONDA_ENV_NAME python=$PYTHON_VERSION -y

echo -e "${GREEN}Step 2: 激活 Conda 环境...${NC}"
source $(conda info --base)/etc/profile.d/conda.sh
conda activate $CONDA_ENV_NAME

echo -e "${GREEN}Step 3: 安装 vLLM...${NC}"
pip install --upgrade pip
pip install vllm

echo -e "${GREEN}Step 4: 下载模型...${NC}"
pip install huggingface-hub
huggingface-cli download $MODEL_NAME --local-dir $MODEL_DIR

echo -e "${GREEN}Step 5: 启动 API 服务...${NC}"
CUDA_VISIBLE_DEVICES=0 vllm serve $MODEL_DIR \
    --host 0.0.0.0 \
    --port $API_PORT \
    --tensor-parallel-size $TENSOR_PARALLEL_SIZE \
    --gpu-memory-utilization $GPU_MEM_UTIL \
    --max-model-len $MAX_MODEL_LEN \
    --trust-remote-code

echo -e "${GREEN}服务已启动，访问 http://localhost:$API_PORT/v1${NC}"

赋予执行权限并运行：

chmod +x deploy_qwen35.sh
./deploy_qwen35.sh

参考资料

• vLLM 官方安装文档
• Qwen3.5-35B-A3B-GPTQ-Int4 Hugging Face 页面
• vLLM GPTQModel 量化支持文档