PWstudio gpu 版在 windows11_wsl2 下安装

适用系统: window11

在开始之前，强烈建议先看一遍 PWstudio 安装前必看，建立一个整体概念。本篇里的命令，一部分是在 Windows 的 PowerShell 里执行的，一部分是在 WSL 内部（相当于一个 Linux 系统）执行的，请注意区分，文档里都有标注在哪个环境下执行。

先确认一下自己 Windows 系统的版本号。打开 cmd 或 powershell（在开始菜单搜索框输入 “powershell” 就能找到），输入下面的命令：

winver            # 我使用的版本是: Windows 11 25H2(26200.8655)
或
systeminfo | findstr "OS"

执行 winver 会弹出一个小窗口，直接显示版本号；如果没弹窗，说明命令打错了，检查一下有没有多余空格。

安装驱动, 激活系统, 优化, 安装输入法等这里不做展开，属于系统本身的基础配置，跟 PWstudio 无关。

WSL 全称 Windows Subsystem for Linux，简单说就是“在 Windows 里面跑一个 Linux 系统”的技术，PWstudio 就是运行在这个 Linux 环境里。以下命令均在 PowerShell 中执行：

1. 以管理员身份打开 PowerShell: 在 “开始” 菜单搜索 PowerShell, 右键选择 “以管理员身份运行”（注意，一定要用“以管理员身份运行”，普通打开可能会因为权限不够导致后面命令报错）

1. 更新到 WSL 预发布版：运行以下命令

wsl --update --pre-release

这条命令会联网下载更新，根据网速可能需要一两分钟，执行完会提示更新完成或者已经是最新版本，都是正常现象。

1. 重启 WSL 服务: 更新完成后, 运行此命令让更改生效

wsl --shutdown

这条命令执行后一般没有输出，属于正常现象，它的作用是把 WSL 后台服务关掉，下次打开时会用最新的配置重新启动。

1. 验证 wslc 是否可用: 关闭并重新打开你的终端(PowerShell 或 Windows 终端)

wslc --version

• 如果看到类似 2.9.4 的版本号，就说明 WSL 容器功能已经就绪了，可以继续下一步。
• 如果提示找不到命令，说明上面的更新步骤可能没有成功，或者需要重启一下电脑再试试。

以下命令同样在 PowerShell 中执行，用来验证容器功能是否正常。

验证 cpu 容器功能:

wslc run --rm swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/hello-world:latest

如果看到一段以 “Hello from Docker!” 开头的文字，说明基础容器功能是正常的。

验证 gpu 容器功能:

wslc run --rm --gpus all `
  swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

如果能看到显卡型号、驱动版本等信息的表格，说明 GPU 已经能被 WSL 容器正常识别和使用了。如果这里报错，请先看下面第 7 章“报错处理”，里面列出了两种最常见的报错和对应解决办法。

安装说明：点击链接, 在 Linux 下安装 server.py 服务 跟着文档安装好证书服务, 再进行下一步。

在 PowerShell 中执行（这一步是从镜像仓库下载 PWstudio 的 GPU 版镜像，体积比较大，根据网速可能需要十几分钟，请耐心等待，不要中途关闭窗口）：

wslc pull ccr.ccs.tencentyun.com/lxkt/qflowgpu:latest

在 powershell 中:

wslc run -d --name qflowgpu `
  -v $env:TEMP\pwmat:/var/tmp/pwmat_host_secret:ro `
  --ulimit memlock=-1:-1 --ulimit stack=-1:-1 --gpus all --shm-size=128G `
  -e SELINUX=disabled -p 80:80 -p 81:81 -p 2297:2297 -p 5010:5010 `
  --hostname=mstation ccr.ccs.tencentyun.com/lxkt/qflowgpu:latest

在 cmd 中:

wslc run -d --name qflowgpu ^
  -v %TEMP%\pwmat:/var/tmp/pwmat_host_secret:ro ^
  --ulimit memlock=-1:-1 --ulimit stack=-1:-1 --gpus all --shm-size=128G ^
  -e SELINUX=disabled -p 80:80 -p 81:81 -p 2297:2297 -p 5010:5010 ^
  --hostname=mstation ccr.ccs.tencentyun.com/lxkt/qflowgpu:latest

以上两段命令二选一，看你习惯用 PowerShell 还是 cmd（普通命令提示符）就用对应那一段，不要两段都执行。执行后如果没有报错，一般会输出一长串字符（容器 ID），这就说明容器已经在后台启动起来了。

反引号 ``` ` ``` （PowerShell 版本里每行结尾的符号）和脱字符 ``^``（cmd 版本里每行结尾的符号）都是各自命令行工具里的“续行符”，表示“这一条命令还没写完，下一行接着算同一条命令”，不要漏掉，也不要手动删除，建议整段复制粘贴执行。

如果执行验证命令时看到类似下面的报错：

PS C:\WINDOWS\system32> wslc run --rm hello-world
由于未安装所需的特性，无法启动操作。
错误代码: HCS_E_SERVICE_NOT_AVAILABLE

解决方法

检查并启用必需的 Windows 功能: WSL 2 依赖于 VirtualMachinePlatform 功能

以管理员身份打开 PowerShell, 运行以下命令来启用它(如果已经启用, 命令会提示状态, 不会造成问题)

Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -All

务必重启电脑, 让更改生效。重启完成后，重新打开 PowerShell 再试一次前面第 3 章的验证命令。

如果执行 GPU 验证命令时看到类似下面的报错：

PS C:\WINDOWS\system32> wslc run --rm --gpus all `
  swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi
Failed to initialize NVML: GPU access blocked by the operating system
Failed to properly shut down NVML: GPU access blocked by the operating system

🔍 问题原因

在 WSL 2 中访问物理 GPU, 需要满足以下条件, 否则就会出现这个错误:

1. 正确的驱动版本: 需要在 Windows 宿主机上安装专门为 WSL 2 设计的 NVIDIA 驱动. 而不是在 Linux 发行版(如 Ubuntu)内安装驱动
2. WSL 2 配置: 需要确保 WSL 2 的虚拟化平台功能已正确启用

🔧 解决方案

检查并安装正确的 NVIDIA 驱动(在 Windows 宿主机上，也就是你平时用的 Windows 桌面系统里装，不是在 WSL 里面装)

访问 NVIDIA 官网, 下载 “NVIDIA CUDA on WSL” 驱动, 或包含 WSL 支持的 Windows 驱动程序(通常版本号在 570 以上)

前往 NVIDIA 官网 → 选择正确的显卡型号 → 关键步骤: 在操作系统(Operating System)下拉菜单中, 选择 Windows 11 或 Windows 10

选择 Game Ready 驱动, (无论是 Game Ready 还是 Studio 都已经集成了对 WSL 2 中 CUDA 和 DirectML 的支持)

用 GPU 跑计算或 AI 相关任务，选用 Game Ready 驱动 会更合适

下载安装完成后，重启一次电脑，然后重新回到第 3 章重新验证 GPU 容器功能。

容器启动成功之后，接下来是通过网页浏览器访问 qstudio/qflow，以及通过 SSH 工具（比如 MobaXterm）登录容器上传下载文件的说明，跳转到: 5. 对容器登录、上传下载 跟着文档进行到文档结束。如果还不会用 MobaXterm，可以先看 MobaXterm 新手教程。