使用 vLLM 部署通义千问 2.5-7B-Instruct 及 Open WebUI 搭建聊天界面

vLLM 的安装非常简单，但要注意选择与你 CUDA 版本匹配的安装方式。CUDA 12.1 是较新的稳定版本。

# 使用 pip 安装 vLLM（CUDA 12.1 版本）
pip install vllm
# 安装过程可能会编译一些组件，稍等片刻即可。
# 同时安装一些必要的工具包
pip install openai requests

3.2 启动 vLLM 模型服务

安装好后，一行命令就能启动模型服务。这里我们直接使用通义千问 2.5-7B-Instruct 的模型 ID，vLLM 会自动从 Hugging Face 仓库下载。

重要提示：直接加载完整的 FP16 模型需要约 28GB 显存。如果你的显卡显存不足，可以使用 --quantization 参数进行量化。例如，使用 AWQ 量化可以大幅降低显存占用。

# 基础启动命令（需要足够显存）
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --port 8000 \
  --api-key token-abc123 \
  --served-model-name Qwen2.5-7B

# 如果你的显存不足（例如只有 8GB），使用 AWQ 量化启动
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --port 8000 \
  --quantization awq \
  --api-key token-abc123 \
  --served-model-name Qwen2.5-7B

命令参数解释：

• Qwen/Qwen2.5-7B-Instruct：Hugging Face 上的模型名称，vLLM 会自动下载。
• --port 8000：指定服务运行的端口号。
• --api-key token-abc123：设置一个简单的 API 密钥，用于客户端连接时的基础验证。
• --served-model-name Qwen2.5-7B：给服务中的模型起个名字，客户端调用时会用到。
• --quantization awq：使用 AWQ 量化技术，能显著减少显存占用，几乎不损失精度。

执行命令后，你会看到大量输出日志。当看到类似 'Uvicorn running on http://0.0.0.0:8000' 的信息时，恭喜你，模型服务已经成功在后台运行了！

3.3 测试 API 服务是否正常

服务启动后，我们打开另一个终端，用一段简单的 Python 代码测试一下。

# test_api.py
from openai import OpenAI

# 注意：这里设置的 base_url 和 api_key 要与启动 vLLM 时的一致
client = OpenAI(
    base_url="http://localhost:8000/v1", # vLLM 服务的地址
    api_key="token-abc123"
)

# 发起一个简单的对话请求
completion = client.chat.completions.create(
    model="Qwen2.5-7B", # 这里填写 --served-model-name 指定的名字
    messages=[
        {"role": "user", "content": "你好，请介绍一下你自己。"}
    ],
    max_tokens=100
)
print(completion.choices[0].message.content)

运行这个脚本，如果能看到通义千问模型返回的自我介绍，说明 vLLM 服务一切正常。至此，模型的'大脑'已经准备就绪。

4. 搭建聊天界面：安装 Open WebUI

只有 API 服务还不够友好，我们需要一个类似 ChatGPT 的网页界面。Open WebUI（原名 Ollama WebUI）是一个功能强大、界面美观的开源项目，完美兼容 vLLM 的 OpenAI API。

4.1 使用 Docker 快速部署 Open WebUI

最简单的方式是使用 Docker，它能处理好所有依赖。

# 拉取并运行 Open WebUI 容器
docker run -d \
  --name open-webui \
  -p 7860:8080 \
  -e OLLAMA_API_BASE_URL=http://host.docker.internal:8000 \
  # 关键！指向 vLLM 服务
  -v open-webui:/app/backend/data \
  --restart always \
  ghcr.io/open-webui/open-webui:main

参数解释：

• -p 7860:8080：将容器的 8080 端口映射到主机的 7860 端口，之后通过 http://localhost:7860 访问。
• -e OLLAMA_API_BASE_URL=...：这是连接 vLLM 的关键环境变量。host.docker.internal 是 Docker 中的一个特殊域名，指向宿主机的网络。它告诉 Open WebUI，模型 API 在宿主机的 8000 端口。
• -v open-webui:/app/backend/data：将数据持久化到名为 open-webui 的 Docker 卷中，这样你的聊天记录、设置等不会丢失。

4.2 配置 Open WebUI 连接 vLLM

容器启动后，打开浏览器访问 http://localhost:7860。

1. 首次进入会要求你创建管理员账号。
2. 创建账号并登录后，点击左下角的设置图标（齿轮⚙）。
3. 在设置页面的 '连接' 部分，你应该能看到 'Ollama' 选项。
4. 确保 'Ollama API URL' 已经自动填充为 http://host.docker.internal:8000（就是我们启动容器时设置的环境变量）。如果没有，请手动填写。
5. 点击 '测试连接'，如果显示成功，就说明 Open WebUI 已经找到了后台的 vLLM 服务。

4.3 开始聊天

回到主界面，点击右上角的 '+' 号来新建一个聊天。在模型选择下拉框中，你应该能看到我们之前通过 --served-model-name 指定的模型 'Qwen2.5-7B'。选中它，现在你就可以在优雅的网页界面里和通义千问 2.5-7B-Instruct 畅聊了！

你可以测试它的各种能力：

• 长文本处理：粘贴一篇长文章让它总结。
• 代码生成：让它用 Python 写一个快速排序算法。
• 逻辑推理：问它一些复杂的数学或逻辑问题。
• 多轮对话：体验连贯的上下文理解能力。

5. 总结与进阶建议

回顾一下，我们成功避开了直接部署的'坑'，通过 vLLM 这个高效的推理框架，将通义千问 2.5-7B-Instruct 模型稳健地运行起来，再通过 Docker 快速部署 Open WebUI 获得了绝佳的用户界面。这条路径清晰、可靠，是个人开发者和小团队部署开源大模型的优选方案。

5.1 核心要点回顾

1. 失败根源：直接部署常因框架兼容性、内存不足、依赖冲突而失败。
2. 关键工具：使用 vLLM 作为模型推理后端，它兼容性好、性能高。
3. 量化救星：如果显卡显存不足，在启动 vLLM 时使用 --quantization awq 参数。
4. 界面搭配：使用 Open WebUI 作为前端，通过 Docker 部署并配置 OLLAMA_API_BASE_URL 指向 vLLM 服务地址。
5. 连接关键：确保 Open WebUI 容器能通过网络访问到宿主机的 vLLM 服务端口（使用 host.docker.internal:8000）。

5.2 下一步可以做什么？

• 尝试量化：如果你还没用量化，可以试试不同的量化方式（如 AWQ, GPTQ），在精度和速度之间找到平衡。
• 探索功能：通义千问 2.5 支持 Function Calling（函数调用），可以尝试在 Open WebUI 中配置一些简单的工具，让模型能调用外部 API。
• 性能监控：使用 nvidia-smi 和 vLLM 自带的监控 API，观察服务的吞吐量、延迟和 GPU 利用率。
• 安全加固：为生产环境考虑，可以配置更安全的 API 密钥、启用 HTTPS、设置用户权限管理等。

希望这篇教程能帮你顺利跨过部署的门槛，真正开始享受通义千问 2.5-7B-Instruct 这个强大模型带来的便利。动手试试吧，你会发现一切并没有想象中那么难。