从零开始：通义千问1.5-1.8B-Chat-GPTQ-Int4 WebUI在Windows系统的部署与调试

对于很多在Windows上工作的开发者来说，想上手体验一下开源大模型，第一步往往就卡在了环境部署上。Linux的命令行、复杂的依赖关系，让人望而却步。今天，我们就来彻底解决这个问题，手把手带你，在熟悉的Windows系统上，从零开始，把通义千问1.5-1.8B-Chat-GPTQ-Int4这个轻量级模型跑起来，并且配上一个好用的Web界面。

整个过程，我们会尽量绕开那些让人头疼的坑，用最直接、最清晰的方式，让你在Windows上也能轻松玩转大模型。无论你是想快速体验，还是为后续开发调试做准备，这篇指南都能帮到你。

1. 准备工作：选择你的Windows作战方案

在Windows上运行这类项目，主要有两条路：Windows原生Python环境和WSL2（Windows Subsystem for Linux）。我们分别看看怎么选。

方案一：Windows原生环境

• 优点：最直接，不需要额外安装子系统，所有操作都在你熟悉的Windows界面下完成。
• 缺点：可能会遇到一些依赖库的兼容性问题，尤其是某些深度学习的底层库，在Windows上编译安装可能比较麻烦。
• 适合谁：想最快速体验，不介意处理一些小问题，或者机器资源有限不想开WSL2的用户。

方案二：WSL2环境

• 优点：本质上是一个轻量级的Linux虚拟机，兼容性最好，99%的Linux项目都能无缝运行，几乎不会遇到依赖问题。
• 缺点：需要开启Windows功能并安装一个Linux发行版（如Ubuntu），会占用一些磁盘空间和内存。
• 适合谁：追求最稳定、最省心的部署体验，或者未来有更多Linux环境开发需求的用户。

我的建议：如果你是新手，或者希望一次成功、少折腾，强烈推荐使用WSL2方案。它能把环境问题降到最低。本教程会以WSL2 (Ubuntu) 方案为主线进行讲解，并在关键步骤指出原生Windows环境的差异。

1.1 基础工具安装（无论哪种方案都需要）

1. 安装 Git：这是获取代码的必备工具。去 Git 官网 下载Windows版本安装包，安装时一路“Next”即可，记得在“Adjusting your PATH environment”这一步选择“Git from the command line and also from 3rd-party software”，这样在命令行里就能直接用git命令了。

2. 安装 Python：去 Python官网 下载最新版的Python 3.8-3.11版本（建议3.10）。安装时务必勾选 “Add Python to PATH” 这个选项，这样系统才能识别Python命令。

安装完成后，打开Windows的命令提示符（CMD）或PowerShell，分别输入以下命令检查是否安装成功：

git --version
python --version

如果都能正确显示版本号，说明基础工具就绪。

1.2 配置WSL2环境（如果选择此方案）

如果你选择WSL2，请按照以下步骤设置：

1. 启用WSL功能：以管理员身份打开PowerShell，输入以下命令并回车：

   wsl --install
   

   这个命令会默认安装Ubuntu发行版。完成后需要重启电脑。

2. 初始化Ubuntu：重启后，你会在开始菜单找到“Ubuntu”应用，点击启动。第一次启动会进行安装，需要你设置一个Linux用户名和密码（这个密码在输入时不会显示，正常输入后回车即可）。

3. 更新系统：在Ubuntu终端里，先更新一下软件包列表：

   sudo apt update && sudo apt upgrade -y
   

至此，你的WSL2环境就准备好了。后续的所有命令行操作，除非特别说明，都将在Ubuntu终端中进行。

2. 获取并运行模型镜像

为了最大程度简化部署，我们使用集成了模型和WebUI的完整镜像。这里以星图GPU平台的镜像为例，它已经打包好了所有环境，真正做到开箱即用。

1. 获取镜像：你需要找到“通义千问1.5-1.8B-Chat-GPTQ-Int4”这个模型的WebUI镜像。通常平台会提供一个拉取或一键部署的命令。假设你获取到的镜像名称为 registry.cn-hangzhou.aliyuncs.com/qwen/qwen1.5-1.8b-chat-gptq-webui:latest。

2. 运行容器：在WSL2的Ubuntu终端中（如果你用原生Windows，则在PowerShell中，但需要确保Docker Desktop已安装并运行），使用docker run命令启动容器。

   # 这是一个示例命令，端口映射和名称请根据实际情况调整
   docker run -d \
     --name qwen-webui \
     -p 7860:7860 \
     --gpus all \
     registry.cn-hangzhou.aliyuncs.com/qwen/qwen1.5-1.8b-chat-gptq-webui:latest
   

   • -d：后台运行。
   • --name：给你的容器起个名字，方便管理。
   • -p 7860:7860：将容器内的7860端口映射到宿主机的7860端口。WebUI通常在这个端口提供服务。
   • --gpus all：将宿主机的GPU资源分配给容器，这是模型加速的关键。确保你的Windows机器有NVIDIA GPU并已安装好驱动和Docker的GPU支持。

3. 验证运行：命令执行后，使用 docker ps 查看容器是否在运行。然后，打开你的Windows浏览器，访问 http://localhost:7860。如果看到WebUI的界面，恭喜你，最核心的一步已经完成了！

3. 连接与调试：用VS Code驯服容器

模型跑起来了，但如果我们想看看代码、修改配置，或者调试一下，该怎么办呢？最佳拍档就是VS Code。

3.1 配置VS Code远程连接

1. 安装扩展：在VS Code中安装官方扩展 “Dev Containers” 和 “WSL”（如果你用WSL2）。

2. 连接到WSL（WSL2方案）：

   • 按 F1 打开命令面板，输入并选择 “Remote-WSL: New WSL Window”。
   • 这会打开一个新的VS Code窗口，左下角状态栏会显示 “WSL: Ubuntu”，表示你已经连接到WSL子系统了。

3. 连接到容器：

   • 在连接到WSL的VS Code中，再次按 F1，输入并选择 “Dev Containers: Attach to Running Container...”。
   • 从列表中选择刚才我们启动的 qwen-webui 容器。
   • VS Code会打开一个新的窗口，并开始加载容器内的环境。加载完成后，你就相当于在容器内部进行操作了！你可以打开集成终端（Terminal），命令行的前缀会显示容器ID。

3.2 在容器内进行探索和调试

现在，你可以在VS Code里像操作本地文件夹一样，浏览容器内的项目文件了。

1. 定位WebUI代码：通常，WebUI的主程序文件可能叫 app.py、webui.py 或者 server.py。你可以在容器内的根目录或/app目录下找找看。用VS Code打开它。

2. 修改配置：你可以找到模型加载、服务器端口、主题样式等配置文件（可能是config.json、settings.py等），并直接修改。例如，如果你想改变WebUI的默认端口，可以修改对应的配置项，然后在容器内部重启服务。

   • 在VS Code的集成终端里，先找到启动WebUI的进程（比如用ps aux | grep python），然后停止它，再用正确的命令重启。
   • 更简单的方法是，修改完配置后，回到Windows的终端，执行 docker restart qwen-webui 重启整个容器。

3. 查看日志：调试时查看日志非常重要。你有两种方式：

   • 容器日志：在Windows终端运行 docker logs -f qwen-webui，可以实时查看容器的标准输出日志。
   • 应用日志：在容器内部，WebUI应用本身可能会将日志写入某个文件（如logs/app.log），你可以在VS Code中直接打开这个文件查看。

4. Windows环境下的常见问题与解决

即使在WSL2下，也可能遇到一些Windows特有的小麻烦，这里列举几个：

• 路径问题：在WSL2中访问Windows文件，路径格式是 /mnt/c/Users/YourName/...（C:盘对应/mnt/c）。反过来，在Windows中访问WSL2的文件，可以通过 \\wsl$\Ubuntu\home\yourname\... 这样的网络路径。在配置挂载卷（-v参数）时要特别注意路径转换。
• 编码问题：确保你的终端和VS Code都使用UTF-8编码，避免中文乱码。在PowerShell中可以通过 $OutputEncoding = [System.Text.Encoding]::UTF8 临时设置。
• 端口占用：如果7860端口被其他程序占用，docker run时会报错。可以改用其他端口，比如 -p 8860:7860，然后访问 http://localhost:8860。
• GPU不可用：如果--gpus all报错，请确认：
  1. Windows已安装最新的NVIDIA显卡驱动。
  2. 已安装 Docker Desktop 并在其设置中启用了“Use the WSL 2 based engine”和“Enable GPU support for WSL 2”。
  3. 在WSL2的Ubuntu中，可能需要安装NVIDIA Container Toolkit，但Docker Desktop新版通常已集成。

5. 总结

走完这一趟，你会发现，在Windows上部署和调试一个带WebUI的大模型，并没有想象中那么困难。核心思路就是利用容器化技术，把复杂的Linux环境打包成一个“即开即用”的镜像，再通过VS Code强大的远程开发功能，无缝切入容器内部进行操控。

WSL2方案几乎抹平了系统差异，让你能享受到原生Linux的兼容性，同时又不必离开Windows的舒适区。当你成功在浏览器里和通义千问对话，或者在VS Code里随意浏览项目代码时，那种成就感就是最好的回报。

这套方法不仅适用于通义千问，对于其他开源模型和AI项目，思路也是相通的。掌握了这个流程，你就拥有了在Windows上探索更广阔AI世界的基础能力。接下来，你可以尝试修改WebUI的样式，集成新的功能插件，或者基于这个模型进行微调，玩法还有很多。

---

获取更多AI镜像

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