Qwen2.5-1.5B Streamlit部署教程：WSL2+Docker Desktop+GPU Passthrough全链路

1. 项目概述

Qwen2.5-1.5B是基于阿里通义千问官方轻量级大语言模型构建的本地智能对话助手。这个项目实现了完全本地化部署的纯文本智能对话服务，通过Streamlit打造了简洁易用的可视化聊天界面。

核心特点：

• 无需复杂框架配置，直接调用本地模型文件完成推理
• 专门针对低显存GPU和轻量计算环境优化
• 1.5B超轻量参数兼顾推理速度与对话能力
• 支持多轮上下文连贯对话
• 所有对话数据全程本地处理，确保数据隐私安全

这个方案将轻量级大模型的能力落地到本地通用对话场景，为用户提供即时、流畅、无需额外配置的私有化AI对话助手。

2. 环境准备与安装

2.1 系统要求

在开始部署之前，请确保你的系统满足以下要求：

• 操作系统：Windows 10 版本 2004 或更高版本
• 内存：至少 8GB RAM（推荐 16GB）
• 存储空间：至少 20GB 可用空间
• GPU：NVIDIA GPU（支持CUDA）
• WSL2：已安装并配置

2.2 WSL2安装与配置

首先确保WSL2已正确安装：

# 检查WSL版本
wsl --list --verbose

# 如果尚未安装WSL2，使用以下命令安装
wsl --install

# 设置默认版本为WSL2
wsl --set-default-version 2

2.3 Docker Desktop安装

安装Docker Desktop并启用WSL2后端：

1. 下载并安装Docker Desktop for Windows
2. 打开Docker Desktop设置
3. 进入"General"选项卡，确保"Use the WSL 2 based engine"已勾选
4. 进入"Resources" → "WSL Integration"，启用你的WSL2发行版

2.4 NVIDIA驱动和CUDA工具包

确保已安装最新版NVIDIA驱动和CUDA工具包：

# 在WSL2中安装NVIDIA CUDA工具包
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.0-1_all.deb
sudo dpkg -i cuda-keyring_1.0-1_all.deb
sudo apt-get update
sudo apt-get -y install cuda

3. GPU Passthrough配置

3.1 检查GPU识别

首先确认系统能够识别到GPU：

# 在WSL2中检查GPU状态
nvidia-smi

# 检查CUDA是否可用
nvcc --version

3.2 Docker GPU支持配置

确保Docker能够使用GPU：

# 安装NVIDIA Container Toolkit
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-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

3.3 验证GPU Passthrough

测试Docker容器是否能够访问GPU：

# 运行测试容器验证GPU访问
docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

如果看到GPU信息输出，说明GPU Passthrough配置成功。

4. 模型部署与配置

4.1 准备模型文件

首先下载Qwen2.5-1.5B-Instruct模型文件：

# 创建模型存储目录
sudo mkdir -p /root/qwen1.5b
sudo chmod 777 /root/qwen1.5b

# 下载模型文件（这里以Hugging Face为例）
# 注意：需要提前获取模型下载权限
git lfs install
git clone https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct /root/qwen1.5b

4.2 创建Docker镜像

创建Dockerfile来构建部署环境：

# Dockerfile
FROM nvidia/cuda:11.8.0-runtime-ubuntu22.04

# 设置工作目录
WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    python3 \
    python3-pip \
    git \
    && rm -rf /var/lib/apt/lists/*

# 安装Python依赖
COPY requirements.txt .
RUN pip3 install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY . .

# 暴露端口
EXPOSE 8501

# 启动命令
CMD ["streamlit", "run", "app.py", "--server.port=8501", "--server.address=0.0.0.0"]

创建requirements.txt文件：

streamlit>=1.28.0
torch>=2.0.0
transformers>=4.34.0
accelerate>=0.23.0
sentencepiece>=0.1.99
tiktoken>=0.5.0

4.3 构建和运行Docker容器

构建Docker镜像并运行容器：

# 构建镜像
docker build -t qwen-chatbot .

# 运行容器（启用GPU支持）
docker run -d \
  --name qwen-chatbot \
  --gpus all \
  -p 8501:8501 \
  -v /root/qwen1.5b:/app/model \
  qwen-chatbot

5. Streamlit应用开发

5.1 创建主应用文件

创建app.py文件实现聊天界面：

import streamlit as st
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch
import os

# 设置页面配置
st.set_page_config(
    page_title="Qwen2.5-1.5B 智能对话助手",
    page_icon="🤖",
    layout="wide"
)

# 模型路径配置
MODEL_PATH = "/app/model"

@st.cache_resource
def load_model():
    """加载模型和分词器"""
    st.write(f"🚀 正在加载模型: {MODEL_PATH}")
    
    # 检查模型文件是否存在
    if not os.path.exists(MODEL_PATH):
        st.error(f"模型路径不存在: {MODEL_PATH}")
        return None, None
    
    try:
        # 自动选择设备和数据类型
        tokenizer = AutoTokenizer.from_pretrained(
            MODEL_PATH, 
            trust_remote_code=True
        )
        
        model = AutoModelForCausalLM.from_pretrained(
            MODEL_PATH,
            device_map="auto",
            torch_dtype="auto",
            trust_remote_code=True
        )
        
        st.success("✅ 模型加载成功！")
        return model, tokenizer
        
    except Exception as e:
        st.error(f"❌ 模型加载失败: {str(e)}")
        return None, None

def main():
    st.title("🤖 Qwen2.5-1.5B 本地智能对话助手")
    st.markdown("基于阿里通义千问官方模型的完全本地化对话服务")
    
    # 初始化会话状态
    if "messages" not in st.session_state:
        st.session_state.messages = []
    
    if "model_loaded" not in st.session_state:
        st.session_state.model_loaded = False
    
    # 侧边栏配置
    with st.sidebar:
        st.header("⚙️ 设置")
        
        if st.button("🧹 清空对话"):
            st.session_state.messages = []
            torch.cuda.empty_cache()
            st.rerun()
        
        st.divider()
        st.info("💡 提示：所有对话数据仅在本地处理，确保隐私安全")
    
    # 加载模型
    if not st.session_state.model_loaded:
        with st.spinner("正在加载模型，请稍候..."):
            model, tokenizer = load_model()
            if model and tokenizer:
                st.session_state.model = model
                st.session_state.tokenizer = tokenizer
                st.session_state.model_loaded = True
    
    # 显示聊天消息
    for message in st.session_state.messages:
        with st.chat_message(message["role"]):
            st.markdown(message["content"])
    
    # 用户输入
    if prompt := st.chat_input("你好，我是Qwen2.5-1.5B，有什么可以帮您？"):
        # 添加用户消息
        st.session_state.messages.append({"role": "user", "content": prompt})
        with st.chat_message("user"):
            st.markdown(prompt)
        
        # 生成回复
        with st.chat_message("assistant"):
            with st.spinner("正在思考..."):
                try:
                    # 应用聊天模板
                    messages = [{"role": m["role"], "content": m["content"]} 
                               for m in st.session_state.messages]
                    
                    text = st.session_state.tokenizer.apply_chat_template(
                        messages,
                        tokenize=False,
                        add_generation_prompt=True
                    )
                    
                    # 生成参数配置
                    model_inputs = st.session_state.tokenizer(
                        [text], 
                        return_tensors="pt"
                    ).to(st.session_state.model.device)
                    
                    # 生成回复
                    with torch.no_grad():
                        generated_ids = st.session_state.model.generate(
                            **model_inputs,
                            max_new_tokens=1024,
                            do_sample=True,
                            temperature=0.7,
                            top_p=0.9,
                            pad_token_id=st.session_state.tokenizer.eos_token_id
                        )
                    
                    # 解码回复
                    response = st.session_state.tokenizer.batch_decode(
                        generated_ids, 
                        skip_special_tokens=True
                    )[0]
                    
                    # 提取最新回复
                    assistant_response = response[len(text):].strip()
                    st.markdown(assistant_response)
                    
                    # 添加助手消息
                    st.session_state.messages.append(
                        {"role": "assistant", "content": assistant_response}
                    )
                    
                except Exception as e:
                    st.error(f"生成回复时出错: {str(e)}")

if __name__ == "__main__":
    main()

5.2 优化配置

创建.streamlit/config.toml文件进行界面优化：

[theme]
primaryColor = "#FF4B4B"
backgroundColor = "#FFFFFF"
secondaryBackgroundColor = "#F0F2F6"
textColor = "#262730"
font = "sans serif"

[server]
maxMessageSize = 1024
enableCORS = false
enableXsrfProtection = true

6. 服务启动与测试

6.1 启动服务

确保所有文件准备就绪后，启动服务：

# 进入项目目录
cd /path/to/your/project

# 构建和运行Docker容器
docker build -t qwen-chatbot .
docker run -d --name qwen-chatbot --gpus all -p 8501:8501 -v /root/qwen1.5b:/app/model qwen-chatbot

6.2 测试服务

服务启动后，可以通过以下方式测试：

1. 检查容器状态：

docker logs qwen-chatbot

2. 访问Web界面： 打开浏览器访问 http://localhost:8501

3. 测试对话功能：

• 输入："解释Python列表推导式"
• 输入："写一段周末出游文案"
• 输入："翻译一段英文文本"

6.3 常见问题解决

问题1：GPU无法识别

# 检查NVIDIA驱动
nvidia-smi

# 检查Docker GPU支持
docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

问题2：模型加载失败

• 检查模型路径是否正确
• 确认模型文件完整
• 检查文件权限

问题3：显存不足

• 减少max_new_tokens参数
• 使用更小的模型
• 增加系统显存

7. 使用指南

7.1 基本操作

1. 发起对话：在页面底部输入框中输入问题或需求
2. 查看回复：AI将在数秒内完成本地推理并显示回复
3. 多轮对话：支持基于上下文进行连续提问
4. 清空对话：点击侧边栏"清空对话"按钮重置对话历史

7.2 最佳实践

• 清晰提问：尽量提供明确的指令和上下文
• 分段对话：复杂问题可以分解为多个简单问题
• 及时清理：长时间对话后清空对话释放显存
• 隐私保护：敏感信息无需担心，所有处理都在本地完成

7.3 性能优化建议

• 确保有足够的GPU显存（至少4GB推荐）
• 关闭其他占用GPU的应用程序
• 定期清理浏览器缓存
• 使用最新版本的驱动和软件

8. 总结

通过本教程，你成功搭建了一个基于Qwen2.5-1.5B模型的本地智能对话系统。这个方案具有以下优势：

技术优势：

• 完全本地化部署，数据零上传
• 基于官方模型，对话质量有保障
• Streamlit提供友好的用户界面
• GPU加速确保响应速度

实用价值：

• 开箱即用，无需复杂配置
• 支持多轮连贯对话
• 适用于各种文本交互场景
• 彻底保护用户隐私安全

扩展可能性：

• 可以集成更多本地模型
• 支持自定义功能扩展
• 能够部署到各种硬件环境
• 适合二次开发和定制

这个部署方案为你提供了一个强大而隐私安全的本地AI对话助手，无论是学习、工作还是创意创作，都能提供有力的支持。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。