====== PWstudio gpu 版在 windows11_wsl2 下安装 ======

适用系统: window11\\

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

----

===== 1 我的系统 =====

先确认一下自己 Windows 系统的版本号。打开 ''cmd'' 或 ''powershell''（在开始菜单搜索框输入 "powershell" 就能找到），输入下面的命令：
<code powershell>
winver            # 我使用的版本是: Windows 11 25H2(26200.8655)
或
systeminfo | findstr "OS"
</code>

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

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

===== 2 wsl 安装 =====

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

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

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

<code powershell>
wsl --update --pre-release
</code>

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

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

<code powershell>
wsl --shutdown
</code>

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

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

<code powershell>
wslc --version
</code>

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

===== 3 容器功能验证 =====

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

验证 cpu 容器功能:

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

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

验证 gpu 容器功能:

<code powershell>
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
</code>

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

===== 4. 宿主机安装 server.py 服务 =====

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

===== 5. 导入镜像 =====

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

<code bash>
wslc pull ccr.ccs.tencentyun.com/lxkt/qflowgpu:latest
</code>

===== 6. 启动容器 =====

在 powershell 中:

<code 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
</code>

在 cmd 中:

<code 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
</code>

<WRAP center round info 10%>
在 powershell 或 cmd 下执行 ipconfig 查看对应 WSL 虚拟网卡的 ip, 如果提交作业报错, 可指定 ip 启动容器[[pwstudio:qa:q106|见列表1]]

或设置镜像网络
</WRAP>

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

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

===== 7 报错处理 =====

==== 7.1 错误代码: HCS_E_SERVICE_NOT_AVAILABLE ====

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

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

<wrap em>解决方法</wrap>

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

以管理员身份打开 PowerShell, 运行以下命令来启用它(如果已经启用, 命令会提示状态, 不会造成问题)
<code powershell>
Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -All
</code>

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

==== 7.2 GPU access blocked by the operating system ====

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

<code powershell>
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
</code>

<wrap em>🔍 问题原因</wrap>

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

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

<wrap em>🔧 解决方案</wrap>

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

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

> [[https://www.nvidia.cn/drivers|前往 NVIDIA 官网]] → 选择正确的显卡型号 → <wrap em>关键步骤:</wrap> 在操作系统(Operating System)下拉菜单中, 选择 Windows 11 或 Windows 10
>
> <wrap hi>选择 Game Ready 驱动</wrap>, (无论是 Game Ready 还是 Studio 都已经集成了对 WSL 2 中 CUDA 和 DirectML 的支持)
>
> 用 GPU 跑计算或 AI 相关任务，选用 Game Ready 驱动 会更合适

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

===== 登录访问使用 =====

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

~~DISCUSSION:off~~