====== qflow gpu 容器版 windows11_wsl2 安装 ======

适用系统: window11\\
<WRAP alert 40% hide>待工程师改进...</WRAP>
----

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

打开 ''cmd'' 或 ''powershell'', 输入 ''winver'', 弹出窗口显示版本号
<code powershell>
winver            # 我使用的版本是: Windows 11 25H2(26200.8655)
或
systeminfo | findstr "OS"
</code>

安装驱动, 激活系统, 优化, 安装输入法等忽略

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

1. 以管理员身份打开 PowerShell: 在 "开始" 菜单搜索 ''PowerShell'', 右键选择 "以管理员身份运行"

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

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

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

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

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

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

如果看到类似 2.9.3.0 的版本号, 就说明 WSL 容器功能已经就绪了

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

验证 cpu 容器功能:

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

验证 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>

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

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

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

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

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

<code powershell>
docker run -d --name qflowgpu `
  --ulimit memlock=-1:-1 --ulimit stack=-1:-1 --gpus all --shm-size=128G `
  -e SELINUX=disabled -p 0.0.0.0:80:80 -p 0.0.0.0:81:81 -p 0.0.0.0:2297:2297 `
  --hostname=mstation ccr.ccs.tencentyun.com/lxkt/qflowgpu:latest
</code>

===== 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>, 让更改生效

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

<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 宿主机上)

访问 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 驱动 会更合适

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

跳转到: [[qflow:quickstart_gpu|5. 对容器登录、上传下载]] 跟着文档进行到文档结束。

~~DISCUSSION:off~~