大模型部署：VLLM部署Qwen3模型的详解

pip install https://github.com/vllm-project/vllm/releases/download/v${VLLM_VERSION}/vllm-${VLLM_VERSION}+cu118-cp${PYTHON_VERSION}-cp${PYTHON_VERSION}-manylinux1_x86_64.whl --extra-index-url https://download.pytorch.org/whl/cu118

从源代码安装（用于开发或获取最新功能）：

git clone https://github.com/vllm-project/vllm.git

cd vllm

# 安装开发依赖

pip install -e . # 这可能需要5-10分钟

2.3 验证 VLLM 安装

安装完成后，您可以通过以下命令验证 VLLM 是否正确安装：

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

如果输出了版本号，则说明 VLLM 已成功安装。接下来，您还需要验证 PyTorch 是否正确配置：

python -c "import torch; print(torch.cuda.is_available())"

如果输出为True，说明 CUDA 环境配置正确，可以正常使用 GPU 加速。

三、Qwen3 模型下载与准备

3.1 模型选择指南

Qwen3 系列包含多个版本，您需要根据硬件配置选择合适的模型：

Qwen3 密集模型系列：

Qwen3-0.6B：6 亿参数

Qwen3-1.7B：17 亿参数（层数 28，注意力头 Q 为 16 个、KV 为 8 个，上下文长度 32,768）

Qwen3-4B：40 亿参数

Qwen3-8B：80 亿参数

Qwen3-14B：148 亿参数（非嵌入参数 13.2B）

Qwen3-32B：320 亿参数

Qwen3 混合专家 (MoE) 模型系列：

Qwen3-30B-A3B：总参数 30B，激活参数 3B

Qwen3-235B-A22B：总参数 235B，激活参数 22B

3.2 使用 Hugging Face 下载模型

如果您的服务器可以访问外网，推荐使用 Hugging Face 官方渠道下载模型：

安装 Hugging Face 命令行工具：

pip install huggingface-hub

下载 Qwen3 模型（以 Qwen3-8B 为例）：

# 创建模型存储目录

mkdir -p /data/models/Qwen3-8B

# 下载模型文件

huggingface-cli download --local-dir /data/models/Qwen3-8B --local-dir-use-symlinks False Qwen/Qwen3-8B

下载 Qwen3-14B 模型：

mkdir -p /data/models/Qwen3-14B

huggingface-cli download --local-dir /data/models/Qwen3-14B --local-dir-use-symlinks False Qwen/Qwen3-14B

3.3 使用 ModelScope 下载模型（国内用户推荐）

如果您在中国大陆，使用 ModelScope 下载会更稳定和快速：

安装 ModelScope：

pip install modelscope

下载 Qwen3 模型：

# 下载Qwen3-8B

modelscope download --model Qwen/Qwen3-8B --local-dir /data/models/Qwen3-8B

# 下载Qwen3-14B

modelscope download --model Qwen/Qwen3-14B --local-dir /data/models/Qwen3-14B

# 下载Qwen3-32B

modelscope download --model Qwen/Qwen3-32B --local-dir /data/models/Qwen3-32B

3.4 模型格式转换（可选）

如果您需要使用特定的模型格式（如 GGUF），可以进行格式转换：

# 安装转换工具

pip install llama-cpp-python

# 转换Qwen3-8B模型为GGUF格式

python -m llama_cpp_convert --model /data/models/Qwen3-8B --outfile /data/models/Qwen3-8B.gguf

四、VLLM 启动脚本详解

4.1 基础启动脚本

以下是启动 VLLM 服务的基础脚本，您需要根据实际模型路径进行调整：

#!/bin/bash

# vllm_start.sh - 启动VLLM服务

# 激活虚拟环境

source /opt/vllm-qwen3-env/bin/activate

# 启动VLLM服务

python -m vllm.entrypoints.openai.api_server \

--model /data/models/Qwen3-8B \ # 模型路径

--host 0.0.0.0 \ # 监听所有IP地址

--port 8000 \ # 服务端口

--trust-remote-code \ # 信任远程代码（必要时）

--dtype auto \ # 自动选择数据类型

--quantization None \ # 不使用量化

--gpu-memory-utilization 0.9 \ # GPU内存利用率

--max-model-len 32768 \ # 最大模型长度

--max-num-batched-tokens 8192 \ # 最大批处理token数

--tensor-parallel-size 1 \ # 张量并行大小

--pipeline-parallel-size 1 \ # 流水线并行大小

--swap-space 16 \ # 交换空间大小(GB)

--cpu-offload-gb 0 \ # CPU卸载大小(GB)

--max-num-seqs 2048 \ # 最大序列数

--served-model-name qwen3-8b \ # 服务模型名称

--log-requests \ # 记录请求日志

--logstats

4.2 脚本功能说明

环境激活部分：

source /opt/vllm-qwen3-env/bin/activate

这行命令用于激活之前创建的虚拟环境，确保在正确的 Python 环境中运行 VLLM。

模型配置部分：

--model /data/models/Qwen3-8B \

--trust-remote-code \

--dtype auto \

--quantization None

--model：指定模型路径，这里使用本地路径/data/models/Qwen3-8B

--trust-remote-code：允许加载远程代码，这对于某些模型是必需的

--dtype auto：自动选择合适的数据类型，通常为bfloat16或float16

--quantization None：不使用量化，保持原始精度

服务配置部分：

--host 0.0.0.0 \

--port 8000 \

--served-model-name qwen3-8b

--host 0.0.0.0：允许所有 IP 地址访问，生产环境建议设置为具体 IP

--port 8000：服务监听端口，可根据需要修改

--served-model-name：指定服务中模型的名称，用于 API 调用

资源配置部分：

--gpu-memory-utilization 0.9 \

--max-model-len 32768 \

--max-num-batched-tokens 8192 \

--tensor-parallel-size 1 \

--pipeline-parallel-size 1 \

--swap-space 16 \

--cpu-offload-gb 0

--gpu-memory-utilization 0.9：设置 GPU 内存利用率为 90%，为系统保留 10%

--max-model-len 32768：支持最大 32768 个 token 的上下文长度

--max-num-batched-tokens 8192：每次批处理的最大 token 数

--tensor-parallel-size 1：单卡部署，如需多卡可设置为 GPU 数量

--pipeline-parallel-size 1：不使用流水线并行

--swap-space 16：设置 16GB 的 CPU 交换空间，应对突发内存需求

--cpu-offload-gb 0：不启用 CPU 卸载，如需更大模型可设置为 10-20GB

性能优化部分：

--max-num-seqs 2048 \

--log-requests \

--logstats

--max-num-seqs 2048：最大并发序列数，可根据 GPU 内存调整

--log-requests：记录所有 API 请求日志

--logstats：记录性能统计信息

4.3 针对不同模型的配置调整

Qwen3-14B 模型配置：

由于 Qwen3-14B 需要更多显存，建议使用以下配置：

--model /data/models/Qwen3-14B \

--dtype bfloat16 \ # 使用bfloat16节省内存

--gpu-memory-utilization 0.95 \ # 提高内存利用率

--max-num-batched-tokens 4096 \ # 适当降低批大小

--tensor-parallel-size 1 \ # 如果是24GB GPU

--swap-space 32 \ # 增加交换空间

--cpu-offload-gb 10 \ # 启用CPU卸载

Qwen3-32B 模型配置：

Qwen3-32B 需要 64GB 以上显存，建议使用多卡部署：

--model /data/models/Qwen3-32B \

--tensor-parallel-size 2 \ # 使用2张A100 40GB或H100

--pipeline-parallel-size 1 \

--gpu-memory-utilization 0.85 \ # 多卡情况下降低利用率

--max-num-batched-tokens 2048 \

--swap-space 64 \

--cpu-offload-gb 20

4.4 量化配置（显存优化）

如果您的 GPU 显存不足，可以考虑使用量化技术：

FP8 量化配置：

--quantization fp8 \

--kv-cache-dtype fp8_e4m3 \ # 使用E4M3格式的FP8

GPTQ 4-bit 量化配置（需要模型支持）：

--quantization gptq \

--gptq-checkpoint /data/models/Qwen3-8B/gptq_model.bin \ # GPTQ模型文件

--gptq-act-order \ # 使用激活顺序（如果模型支持）

AWQ 量化配置：

--quantization awq \

--awq-params /data/models/Qwen3-8B/awq_config.json \ # AWQ配置文件

五、生产环境部署配置

5.1 使用 systemd 管理服务

为了实现服务的自动启动和管理，建议使用 systemd：

创建 systemd 服务文件：

sudo nano /etc/systemd/system/vllm-qwen3.service

服务文件内容：

[Unit]

Description=VLLM Qwen3 Service

After=network.target

[Service]

User=root

Environment="CUDA_VISIBLE_DEVICES=0" # 指定使用的GPU

Environment="PATH=/opt/vllm-qwen3-env/bin:$PATH"

WorkingDirectory=/opt/vllm-qwen3-env

ExecStart=/opt/vllm-qwen3-env/bin/python -m vllm.entrypoints.openai.api_server \

--model /data/models/Qwen3-8B \

--host 0.0.0.0 --port 8000 \

--trust-remote-code \

--dtype auto \

--quantization None \

--gpu-memory-utilization 0.9 \

--max-model-len 32768 \

--max-num-batched-tokens 8192 \

--tensor-parallel-size 1 \

--swap-space 16 \

--max-num-seqs 2048 \

--log-requests

Restart=always

RestartSec=5

LimitNOFILE=65535

[Install]

WantedBy=multi-user.target

启动和管理服务：

sudo systemctl daemon-reload

sudo systemctl enable vllm-qwen3

sudo systemctl start vllm-qwen3

# 查看服务状态

sudo systemctl status vllm-qwen3

# 查看日志

journalctl -u vllm-qwen3 -f

5.2 性能优化配置

在生产环境中，您可以通过以下配置进一步优化性能：

启用分块预填充（Chunked Prefill）：

--enable-chunked-prefill \

--max-num-batched-tokens 2048 \ # 分块预填充建议设置为2048

分块预填充允许将大的预填充分解为更小的块，并与解码请求一起批处理，从而改善延迟和 GPU 利用率。

启用前缀缓存（Prefix Caching）：

--enable-prefix-caching \

--num-lookahead-slots 2 \ # 预加载的块数

前缀缓存可以显著提高长文本生成的性能，特别是在处理对话场景时。

优化内存管理：

--block-size 32 \ # 减少内存碎片

--num-gpu-blocks-override 1024 \ # 覆盖GPU块数（根据GPU调整）

5.3 多卡部署配置

如果您拥有多块 GPU，可以通过张量并行来支持更大的模型或更高的并发：

双 GPU 部署 Qwen3-14B：

CUDA_VISIBLE_DEVICES=0,1 python -m vllm.entrypoints.openai.api_server \

--model /data/models/Qwen3-14B \

--tensor-parallel-size 2 \

--pipeline-parallel-size 1 \

--gpu-memory-utilization 0.85 \

--max-num-batched-tokens 4096 \

--swap-space 32

四 GPU 部署 Qwen3-32B：

CUDA_VISIBLE_DEVICES=0,1,2,3 python -m vllm.entrypoints.openai.api_server \

--model /data/models/Qwen3-32B \

--tensor-parallel-size 4 \

--pipeline-parallel-size 1 \

--gpu-memory-utilization 0.8 \

--max-num-batched-tokens 2048 \

--swap-space 64

5.4 API 密钥认证配置

为了保证服务安全，建议启用 API 密钥认证：

生成 API 密钥：

# 安装passlib用于生成密码哈希

pip install passlib

# 生成哈希密码

python -c "from passlib.hash import bcrypt; print(bcrypt.hash('your_secure_password'))"

配置认证：

在启动脚本中添加：

--api-key your_api_key \ # 简单密钥认证

--api-key-file /etc/vllm/api_keys.txt \ # 使用密钥文件

--api-key-hash your_hashed_password \ # 使用哈希密码

六、监控与运维

6.1 系统监控

GPU 监控：

使用 nvidia-smi 命令监控 GPU 使用情况：

nvidia-smi -l 5 # 每5秒刷新一次

关注指标：

GPU 利用率（GPU Usage）

显存使用情况（Memory Usage）

温度（Temperature）

功耗（Power Draw）

VLLM 性能监控：

VLLM 提供了丰富的性能指标，可以通过以下方式查看：

# 查看详细的性能统计

curl http://localhost:8000/metrics

关键指标：

vllm_batch_size：批大小

vllm_latency：延迟

vllm_throughput：吞吐量

vllm_gpu_memory_utilization：GPU 内存利用率

6.2 日志配置

配置文件日志：

在启动脚本中添加：

--log-file /var/log/vllm/qwen3.log \ # 日志文件路径

--log-level INFO \ # 日志级别

--log-format json \ # JSON格式日志（便于分析）

轮转日志配置（使用 logrotate）：

sudo nano /etc/logrotate.d/vllm-qwen3

/var/log/vllm/qwen3.log {

daily

rotate 7

compress

delaycompress

missingok

notifempty

create 644 root adm

}

6.3 性能调优建议

根据负载调整参数：

如果延迟过高：降低max-num-batched-tokens

如果吞吐量不足：提高max-num-batched-tokens

如果出现 OOM：降低gpu-memory-utilization或启用量化

如果 GPU 利用率低：增加max-num-seqs

针对不同场景的优化：

对话场景：

--max-model-len 16384 \ # 减少上下文长度

--max-num-batched-tokens 4096 \

--chunked-prefill \ # 启用分块预填充

--enable-prefix-caching \ # 启用前缀缓存

长文档处理

--max-model-len 32768 \ # 最大上下文长度

--max-num-batched-tokens 2048 \ # 降低批大小

--cpu-offload-gb 20 \ # 启用CPU卸载

--swap-space 32 \

--quantization fp8 \ # 使用FP8量化

七、常见问题与解决方案

7.1 模型加载问题

问题现象：模型加载失败，提示找不到文件或不支持的格式。

解决方案：

检查模型路径是否正确：

ls -l /data/models/Qwen3-8B

确保目录中包含config.json、pytorch_model.bin等必要文件。

如果使用的是 HF 格式，确保设置了--trust-remote-code：

--trust-remote-code

如果模型是从其他来源下载的，可能需要转换格式

# 转换为VLLM支持的格式

python -m vllm.entrypoints.convert_hf_to_vllm --model /data/models/Qwen3-8B --output /data/models/Qwen3-8B-vllm

7.2 显存不足问题

问题现象：启动时出现 OOM（Out of Memory）错误。

解决方案：

降低 GPU 内存利用率：

--gpu-memory-utilization 0.85

启用 CPU 卸载：

--cpu-offload-gb 10

使用量化技术：

--quantization fp8 # 显存占用减少约50%

减少批大小：

--max-num-batched-tokens 2048

如果是多卡环境，增加张量并行：

--tensor-parallel-size 2

7.3 性能问题

问题现象：推理速度慢或 GPU 利用率低。

解决方案：

检查是否启用了 CUDA：

python -c "import torch; print(torch.cuda.is_available())"

如果输出False，检查 CUDA 环境配置。

调整批处理参数

--max-num-batched-tokens 8192 # 增加批大小提高吞吐量

--max-num-seqs 2048 # 增加并发序列数

启用分块预填充

--enable-chunked-prefill

优化内存管理

--block-size 32 # 减少内存碎片

7.4 API 调用问题

问题现象：API 返回错误或格式不正确。

解决方案：

检查 API 请求格式是否正确：

{

"model": "qwen3-8b",

"messages": [{"role": "user", "content": "Hello!"}],

"temperature": 0.7,

"max_tokens": 50

}

检查模型名称是否与served-model-name一致：

--served-model-name qwen3-8b

如果使用了 API 密钥，确保请求中包含：

{

"model": "qwen3-8b",

"messages": [{"role": "user", "content": "Hello!"}],

"api_key": "your_api_key"

}

7.5 兼容性问题

问题现象：Qwen3 模型与 VLLM 版本不兼容。

解决方案：

确保使用最新版本的 VLLM：

pip install vllm --upgrade

如果遇到特定问题，可以尝试：

--disable-custom-all-reduce # 禁用自定义all-reduce

--enforce-eager # 强制使用eager模式

对于 Qwen3-30B 及以上模型，可能需要特定配置：

VLLM_USE_V1=0 # 使用VLLM v0版本API

八、安全注意事项

8.1 网络安全

防火墙配置：

在生产环境中，强烈建议配置防火墙只允许必要的网络访问：

# 使用ufw配置防火墙

sudo ufw allow 8000/tcp # 允许API访问

sudo ufw allow 22/tcp # 允许SSH访问

sudo ufw deny any # 拒绝其他所有访问

sudo ufw enable

使用 HTTPS：

虽然 VLLM 本身不直接支持 HTTPS，但您可以通过反向代理（如 Nginx）来实现：

sudo nano /etc/nginx/sites-available/vllm

server {

listen 443 ssl;

server_name your-domain.com;

ssl_certificate /etc/ssl/certs/your-cert.pem;

ssl_certificate_key /etc/ssl/private/your-key.pem;

location / {

proxy_pass http://localhost:8000;

proxy_set_header Host $host;

proxy_set_header X-Real-IP $remote_addr;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

}

8.2 数据安全

模型文件权限：

确保模型文件的权限设置正确：

chown -R root:root /data/models/Qwen3-8B

chmod -R 700 /data/models/Qwen3-8B

敏感数据保护：

不要将敏感数据（如 API 密钥）硬编码在脚本中

使用环境变量或配置文件来存储敏感信息

定期轮换 API 密钥

8.3 合规性要求

数据本地化：

如果您的业务有数据本地化要求，请确保：

模型和数据存储在本地服务器

不使用外部 API 服务

配置防火墙阻止数据外流

审计日志：

建议启用完整的审计日志：

--log-requests \ # 记录所有API请求

--log-responses \ # 记录所有响应

--log-headers \ # 记录请求头信息

九、总结

通过本文，可以掌握了使用 VLLM 部署 Qwen3 模型的完整流程。从环境准备到生产部署，从基础配置到性能优化，从日常运维到故障排除，本手册提供了全面的指导。

关键要点回顾：

环境要求：确保硬件满足最低配置，特别是 GPU 显存要求

安装配置：使用虚拟环境，正确安装依赖，验证 CUDA 环境

模型准备：选择合适的 Qwen3 版本，使用官方渠道下载

启动配置：根据模型大小和使用场景调整参数

生产部署：使用 systemd 管理服务，配置日志和监控

性能优化：根据负载特征调整批大小、并发数等参数

安全配置：设置 API 认证，配置防火墙，保护敏感数据

在实际部署过程中，请根据具体的硬件环境和业务需求进行调整。如果遇到问题，建议先查阅官方文档和本手册中的常见问题部分。

腾讯云开发者社区

腾讯云面向开发者汇聚海量精品云计算使用和开发经验，营造开放的云计算技术生态圈。

更多推荐

终极指南：Flink SQL连接器版本管理从混乱到有序的升级之路

Apache Flink作为流处理领域的佼佼者，其SQL连接器的版本管理一直是开发者面临的核心挑战。本文将系统讲解Flink SQL连接器版本管理的最佳实践，帮助你轻松应对版本兼容性问题，实现从混乱到有序的升级之旅。## 连接器版本管理的常见痛点 😫在Flink应用开发中，连接器版本管理常常让开发者头疼不已。不同版本的连接器可能导致各种兼容性问题，例如API变更、功能差异甚至运行时错误。

腾讯云开发者社区

Elasticsearch复杂数据类型终极指南：从入门到精通

Elasticsearch作为功能强大的搜索引擎，支持多种复杂数据类型，让开发者能够灵活处理各种结构化和非结构化数据。本文将带你全面了解Elasticsearch中的复杂数据类型，从基础概念到实际应用，助你轻松掌握数据建模的核心技巧。## 内部对象：构建层级化数据结构在Elasticsearch中，对象类型（Object）是最基础的复杂数据类型之一，用于表示具有嵌套关系的数据。例如，我们可

腾讯云开发者社区

如何快速搭建Neon无服务器PostgreSQL：面向初学者的完整指南

Neon是一款革命性的无服务器PostgreSQL解决方案，它通过分离存储和计算层，实现了自动扩缩容、类代码式数据库分支以及零级扩展能力。本指南将帮助你从零开始搭建Neon开发环境，体验这款创新数据库的强大功能。## 准备工作：环境要求与依赖项在开始搭建Neon环境前，请确保你的系统满足以下要求：- Linux操作系统（推荐Ubuntu 20.04+或Debian 11+）- Git

腾讯云开发者社区

所有评论(0)

查看更多评论

SmartBrain

@Peter_Changyb

已为社区贡献15条内容

大模型部署：VLLM部署Qwen3模型的详解

SmartBrain

一、系统环境要求与准备

1.1 硬件环境要求

1.2 软件环境要求

二、VLLM 安装与配置

2.1 创建虚拟环境

2.2 安装 VLLM

2.3 验证 VLLM 安装

三、Qwen3 模型下载与准备

3.1 模型选择指南

3.2 使用 Hugging Face 下载模型

3.3 使用 ModelScope 下载模型（国内用户推荐）

3.4 模型格式转换（可选）

四、VLLM 启动脚本详解

4.1 基础启动脚本

4.2 脚本功能说明

4.3 针对不同模型的配置调整

4.4 量化配置（显存优化）

五、生产环境部署配置

5.1 使用 systemd 管理服务

5.2 性能优化配置

5.3 多卡部署配置

5.4 API 密钥认证配置

六、监控与运维

6.1 系统监控

6.2 日志配置

6.3 性能调优建议

七、常见问题与解决方案

7.1 模型加载问题

7.2 显存不足问题

7.3 性能问题

7.4 API 调用问题

7.5 兼容性问题

八、安全注意事项

8.1 网络安全

8.2 数据安全

8.3 合规性要求

九、总结

所有评论(0)

温馨提示：您尚未绑定手机号

SmartBrain