vLLM + Open-WebUI 部署通义千问 2.5-7B 完整教程
1. 引言
1.1 学习目标
本文将详细介绍如何使用 vLLM 和 Open-WebUI 联合部署阿里云发布的开源大模型——通义千问 2.5-7B-Instruct。通过本教程,你将掌握:
- 如何在本地或服务器环境中部署 Qwen2.5-7B 模型
介绍如何使用 vLLM 和 Open-WebUI 部署阿里云开源模型通义千问 2.5-7B-Instruct。涵盖环境准备(GPU、Docker)、模型获取、服务启动及 Web 界面配置。通过 vLLM 实现高性能推理,结合 Open-WebUI 提供类 ChatGPT 交互体验。包含性能优化建议、常见问题排查及工具调用支持,适用于本地私有化部署及研究实验场景。
本文将详细介绍如何使用 vLLM 和 Open-WebUI 联合部署阿里云发布的开源大模型——通义千问 2.5-7B-Instruct。通过本教程,你将掌握:
最终实现:通过浏览器访问 http://localhost:7860,即可与通义千问进行流畅对话。
为顺利执行本教程,请确保具备以下基础:
相比直接使用 transformers 加载模型,本方案具有以下优势:
| 特性 | 说明 |
|---|---|
| 高吞吐 | vLLM 支持 PagedAttention,提升并发处理能力 |
| 快响应 | Token 生成速度可达 100+ tokens/s(FP16) |
| 易用性 | Open-WebUI 提供图形化界面,无需编程即可交互 |
| 可扩展 | 支持多用户、API 接口调用、Agent 集成 |
| 组件 | 最低要求 | 推荐配置 |
|---|---|---|
| GPU | NVIDIA RTX 3060 (12GB) | A100 / RTX 4090 |
| 显存 | ≥14 GB(FP16) | ≥24 GB |
| 内存 | 32 GB | 64 GB |
| 存储 | 50 GB SSD | 100 GB NVMe |
注意:若使用量化版本(如 GGUF Q4_K_M),可在 8GB 显存设备运行,但本教程以 FP16 全精度为主。
请依次安装以下软件:
# 1. 更新系统包
sudo apt update && sudo apt upgrade -y
# 2. 安装 NVIDIA 驱动和 CUDA
# 根据你的显卡型号选择合适驱动,参考官方文档:
# https://docs.nvidia.com/cuda/cuda-installation-guide-linux/
# 3. 安装 Docker 和 nvidia-docker2
curl -fsSL https://get.docker.com | sh
sudo systemctl enable docker --now
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt update
sudo apt install -y nvidia-docker2
sudo systemctl restart docker
验证 GPU 是否可用:
docker run --rm --gpus all nvidia/cuda:12.1-base nvidia-smi
预期输出包含 GPU 型号和显存信息。
从 Hugging Face 下载模型权重(需登录并接受协议):
# 登录 HF CLI(首次使用)
huggingface-cli login
# 创建模型目录
mkdir -p /opt/models/qwen2.5-7b-instruct
# 使用 git-lfs 拉取模型(约 28GB)
git lfs install
git clone https://huggingface.co/Qwen/Qwen2.5-7B-Instruct /opt/models/qwen2.5-7b-instruct
若网络不稳定,可使用国内镜像加速(如阿里云 ModelScope):
使用 Docker 运行 vLLM 推理服务:
docker run -d --gpus all --shm-size 1g \
-p 8000:8000 \
-v /opt/models/qwen2.5-7b-instruct:/model \
--name vllm-server \
vllm/vllm-openai:latest \
--model /model \
--tensor-parallel-size 1 \
--dtype half \
--max-model-len 131072 \
--enable-prefix-caching \
--gpu-memory-utilization 0.95
| 参数 | 含义 |
|---|---|
--tensor-parallel-size | 多卡并行数(单卡设为 1) |
--dtype half | 使用 FP16 精度,节省显存 |
--max-model-len 131072 | 支持最大上下文长度 128k |
--enable-prefix-caching | 缓存 prompt KV,提升重复提问效率 |
--gpu-memory-utilization | 显存利用率控制 |
等待容器启动完成(约 2~5 分钟),可通过日志查看状态:
docker logs -f vllm-server
当出现 "Uvicorn running on http://0.0.0.0:8000" 表示服务已就绪。
拉取并运行 Open-WebUI 容器:
docker run -d -p 7860:8080 \
-e OPEN_WEBUI_URL="http://host.docker.internal:8000" \
-v open-webui:/app/backend/data \
--name open-webui \
ghcr.io/open-webui/open-webui:main
⚠️ 注意:
host.docker.internal是 Docker 内部访问宿主机的服务地址。
若为 Linux 系统且 Docker 版本较旧,可替换为宿主机 IP 地址。
设置完成后,访问 http://localhost:7860 即可进入 Web 界面。
首次访问 Open-WebUI 时需要注册账号。根据提示创建管理员账户,或使用预设演示账户登录。
登录后可修改密码并绑定邮箱。
进入设置页面(Settings → General → Model Settings),填写:
OpenAIhttp://host.docker.internal:8000/v1EMPTY(vLLM 不强制认证)点击 'Save',系统会自动获取模型名称 Qwen2.5-7B-Instruct 并显示在聊天窗口。
尝试输入以下指令进行测试:
请用 Python 编写一个快速排序函数,并添加详细注释。
预期输出应包含完整代码与解释,体现其强大代码生成能力。
再试一道数学题:
求解方程:x^2 + 5x + 6 = 0
模型应返回正确解法与结果(x = -2, -3)。
界面简洁直观,支持 Markdown 渲染、代码高亮、历史会话管理等功能。
在 vLLM 启动命令中加入:
--enforce-eager
或编译支持 FlashAttention-2 的版本,可进一步提升推理速度 20%~30%。
对于高并发场景,增加以下参数:
--max-num-seqs 256 \
--max-num-batched-tokens 4096
若显存不足,可转换为 GPTQ 或 AWQ 量化模型:
# 示例:使用 AutoGPTQ 转换
pip install auto-gptq
python -c "
from transformers import AutoTokenizer
from auto_gptq import AutoGPTQForCausalLM
model = AutoGPTQForCausalLM.from_pretrained('Qwen/Qwen2.5-7B-Instruct', device_map='auto')
model.quantize('path/to/qwen2.5-7b-instruct-gptq')
"
然后在 vLLM 中加载量化模型。
通义千问 2.5 支持结构化输出,可用于构建 Agent。示例请求:
{
"messages": [
{
"role": "user",
"content": "查询北京今天的天气"
}
],
"functions": [
{
"name": "get_weather",
"description": "获取指定城市的天气信息",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名"}
},
"required": ["city"]
}
}
],
"function_call": "auto"
}
模型将返回 JSON 格式调用指令,便于后端解析执行。
尝试输入非中文请求:
Write a poem about autumn in French.
模型能高质量输出法语诗歌,展现其优秀的多语言能力。
原因:显存不足或未启用半精度。
解决方案:
--dtype half--max-model-len 至 32768检查项:
OPEN_WEBUI_URL 正确指向 vLLM 服务curl http://host.docker.internal:8000/health解决方法:
max_tokens=4096编辑 Open-WebUI 启动命令,暴露端口并设置鉴权:
-e WEBUI_AUTH=True \
-p 0.0.0.0:7860:8080
并配合 Nginx + HTTPS + Basic Auth 实现安全外网访问。
本文完整实现了 通义千问 2.5-7B-Instruct 模型的本地化部署,关键技术点包括:
该方案适用于企业私有化部署、研究实验、个人 AI 助手等场景。
建议继续探索:

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
使用加密算法(如AES、TripleDES、Rabbit或RC4)加密和解密文本明文。 在线工具,加密/解密文本在线工具,online
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具,curl 转代码在线工具,online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online