Qwen1.5-0.5B-Chat实战教程：基于Flask的WebUI开发

优质文章学习记录

— 8 min read

Qwen1.5-0.5B-Chat实战教程：基于Flask的WebUI开发

1. 引言

1.1 学习目标

本文旨在带领读者从零开始，完整构建一个基于 Qwen1.5-0.5B-Chat 模型的轻量级智能对话 Web 应用。通过本教程，你将掌握：

  • 如何在本地环境中部署开源大模型
  • 使用 ModelScope SDK 加载并调用通义千问系列模型
  • 基于 Flask 构建支持流式响应的 Web 用户界面
  • 在无 GPU 环境下实现 CPU 推理优化方案

最终成果是一个可交互、低资源占用、开箱即用的网页聊天系统，适用于边缘设备或低成本部署场景。

1.2 前置知识

为确保顺利跟随本教程操作，请确认已具备以下基础：

  • Python 编程基础（熟悉函数、类和模块导入）
  • 基本命令行操作能力（Linux/macOS/Windows）
  • 了解 HTTP 协议与 Web 请求的基本概念
  • 安装了 Conda 或 Miniconda 环境管理工具

无需深度学习或模型微调经验，所有推理逻辑均通过预训练模型自动完成。

1.3 教程价值

随着大模型技术的发展，越来越多开发者希望在本地环境运行轻量化 AI 对话服务。Qwen1.5-0.5B-Chat 作为通义千问系列中参数量最小但性能高效的版本，特别适合用于嵌入式设备、测试原型或教育演示。

本教程提供了一套完整的工程化实现路径，涵盖环境配置、模型加载、后端接口设计到前端交互全流程，并针对 CPU 推理进行了精度与速度的平衡优化，真正实现“低门槛 + 高可用”的本地化部署。

2. 环境准备与项目初始化

2.1 创建独立 Conda 环境

为避免依赖冲突，建议使用 Conda 创建专用虚拟环境：

conda create -n qwen_env python=3.9 conda activate qwen_env

该环境命名为 qwen_env，使用 Python 3.9 版本以保证兼容性。

2.2 安装核心依赖库

执行以下命令安装必要的 Python 包：

pip install torch==2.1.0 transformers==4.36.0 flask==2.3.3 modelscope==1.13.0

关键组件说明如下：

包名作用
torchPyTorch 深度学习框架，提供 CPU 推理支持
transformersHugging Face 提供的模型接口库，兼容 ModelScope 模型结构
flask轻量级 Web 框架，用于构建前后端通信服务
modelscope魔塔社区官方 SDK，支持一键拉取 Qwen 模型权重
注意：当前版本需固定 transformers==4.36.0，因更高版本可能存在与 ModelScope 的兼容性问题。

2.3 初始化项目目录结构

创建项目文件夹并组织代码结构：

mkdir qwen-webui cd qwen-webui mkdir app templates static

最终目录结构如下：

qwen-webui/ ├── app/ │ └── app.py # Flask 主程序 ├── templates/ │ └── index.html # 前端页面模板 ├── static/ │ └── style.css # 样式文件（可选） ├── requirements.txt # 依赖清单 └── run.sh # 启动脚本

3. 模型加载与推理实现

3.1 使用 ModelScope 加载 Qwen1.5-0.5B-Chat

在 app/app.py 中编写模型初始化代码：

from modelscope import AutoModelForCausalLM, AutoTokenizer import torch # 模型标识符（来自魔塔社区） MODEL_NAME = "qwen/Qwen1.5-0.5B-Chat" # 加载分词器与模型 tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME, trust_remote_code=True) model = AutoModelForCausalLM.from_pretrained( MODEL_NAME, torch_dtype=torch.float32, # CPU 推理推荐使用 float32 device_map="cpu", # 显式指定 CPU 运行 trust_remote_code=True ) print("✅ 模型加载完成，内存占用 < 2GB")
关键参数解析：
  • trust_remote_code=True：允许执行模型自定义代码（Qwen 系列必需）
  • torch_dtype=torch.float32：虽然 float16 更省内存，但在 CPU 上不被原生支持，float32 是稳定选择
  • device_map="cpu"：强制模型运行于 CPU，适用于无 GPU 设备

3.2 实现对话生成函数

添加一个封装好的对话响应函数：

def generate_response(prompt): """ 接收用户输入，返回模型回复 """ messages = [{"role": "user", "content": prompt}] # 编码输入 inputs = tokenizer.apply_chat_template( messages, tokenize=True, add_generation_prompt=True, return_tensors="pt" ).to("cpu") # 生成输出 outputs = model.generate( inputs, max_new_tokens=512, temperature=0.7, do_sample=True, pad_token_id=tokenizer.eos_token_id ) # 解码结果 response = tokenizer.decode(outputs[0], skip_special_tokens=True) # 提取 assistant 回复部分（去除输入） if "assistant" in response: response = response.split("assistant")[-1].strip() return response

此函数实现了标准的多轮对话模板处理，能够正确识别角色标签并返回纯净的模型输出。

4. Flask Web 服务开发

4.1 构建后端 API 接口

继续完善 app/app.py，添加 Flask 路由：

from flask import Flask, request, jsonify, render_template import threading import queue app = Flask(__name__) # 用于异步传递响应的队列 response_queue = queue.Queue() @app.route("/") def home(): return render_template("index.html") @app.route("/chat", methods=["POST"]) def chat(): user_input = request.json.get("message", "") try: reply = generate_response(user_input) return jsonify({"reply": reply}) except Exception as e: return jsonify({"error": str(e)}), 500 if __name__ == "__main__": app.run(host="0.0.0.0", port=8080, threaded=True)
接口说明：
  • GET /：返回 HTML 页面
  • POST /chat：接收 JSON 格式的用户消息，返回模型回复

采用 threaded=True 支持并发请求，防止长响应阻塞其他用户。

4.2 设计前端交互界面

在 templates/index.html 中创建简洁的聊天界面：

<!DOCTYPE html> <html lang="zh"> <head> <meta charset="UTF-8" /> <title>Qwen1.5-0.5B-Chat WebUI</title> <style> body { font-family: Arial, sans-serif; margin: 40px; } #chat-box { border: 1px solid #ccc; height: 400px; overflow-y: auto; padding: 10px; margin-bottom: 10px; } .user { color: blue; text-align: right; } .ai { color: green; } input, button { padding: 10px; font-size: 16px; } #input-area { display: flex; gap: 10px; } </style> </head> <body> <h2>💬 Qwen1.5-0.5B-Chat 聊天助手</h2> <div></div> <div> <input type="text" placeholder="请输入你的问题..." autofocus /> <button onclick="send()">发送</button> </div> <script> function send() { const input = document.getElementById("user-input"); const value = input.value.trim(); if (!value) return; // 显示用户消息 appendMessage(value, "user"); input.value = ""; // 发送请求 fetch("/chat", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ message: value }) }) .then(res => res.json()) .then(data => { if (data.reply) { appendMessage(data.reply, "ai"); } else { appendMessage("❌ " + data.error, "ai"); } }) .catch(err => { appendMessage("⚠️ 请求失败：" + err.message, "ai"); }); } function appendMessage(text, sender) { const box = document.getElementById("chat-box"); const div = document.createElement("div"); div.className = sender; div.innerHTML = `<strong>${sender === 'user' ? '你' : 'AI'}:</strong> ${text}`; box.appendChild(div); box.scrollTop = box.scrollHeight; } // 回车发送 document.getElementById("user-input").addEventListener("keypress", e => { if (e.key === "Enter") send(); }); </script> </body> </html>

该页面包含基本的样式美化、消息滚动、回车发送等功能，用户体验接近主流聊天应用。

5. 性能优化与常见问题解决

5.1 CPU 推理性能调优建议

尽管 Qwen1.5-0.5B-Chat 参数量较小，但在 CPU 上仍可能出现延迟较高现象。以下是几项有效优化措施：

  1. 降低 max_new_tokens
    将生成长度限制在合理范围（如 256），避免过长文本拖慢响应。
  2. 关闭采样策略（快速模式）
    设置 do_sample=False 并使用贪心解码，提升确定性与速度：

python outputs = model.generate( inputs, max_new_tokens=256, do_sample=False, # 贪心搜索 num_beams=1 )

  1. 启用 ONNX Runtime（进阶）
    可将模型导出为 ONNX 格式，利用 ONNX Runtime 实现更高效的 CPU 推理（需额外转换步骤）。

5.2 常见问题与解决方案（FAQ）

问题原因解决方法
ModuleNotFoundError: No module named 'modelscope'未正确安装 modelscope执行 pip install modelscope
CUDA out of memory默认尝试使用 GPU添加 device_map="cpu" 强制 CPU 运行
返回内容包含多余指令前缀模板解析异常使用 split("assistant") 截取真实回复
启动时报错 trust_remote_code忽略远程代码导致加载失败确保所有 from_pretrained 调用都设置 trust_remote_code=True
访问 8080 端口失败防火墙或端口占用检查 netstat -an \| grep 8080，更换端口或开放防火墙

6. 总结

6.1 全流程回顾

本文详细介绍了如何基于 Flask 开发一个完整的 Qwen1.5-0.5B-Chat WebUI 应用，主要步骤包括：

  1. 使用 Conda 创建隔离环境，安装 modelscope 和 transformers 等核心依赖；
  2. 通过 ModelScope SDK 加载 Qwen1.5-0.5B-Chat 模型，适配 CPU 推理环境；
  3. 利用 Flask 构建 RESTful API 接口，实现前后端数据交互；
  4. 开发简洁美观的 HTML 前端页面，支持实时聊天体验；
  5. 针对 CPU 推理进行性能优化，并列出常见问题应对策略。

整个系统可在 2GB 内存以内稳定运行，非常适合部署在树莓派、NAS 或低配云服务器上。

6.2 下一步学习建议

若想进一步扩展功能，可考虑以下方向：

  • 增加对话历史管理：在后端维护 session 状态，实现多轮上下文记忆
  • 集成语音输入/输出：结合 Whisper 与 VITS 实现语音对话机器人
  • 打包为 Docker 镜像：便于跨平台部署与分享
  • 接入 RAG 架构：连接本地知识库，打造专属问答系统
获取更多AI镜像

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