GPUStack v2 以高性能推理與生產級穩定性為核心演進方向，對整體架構進行了全面重構，實現了組件間的靈活解耦，並對多推理引擎和異構算力進行了深度優化，充分釋放推理引擎在吞吐、延遲與併發方面的性能潛力。

基於這一架構設計，GPUStack v2 聚焦 Linux 原生環境，以充分利用其在生態和 AI 基礎設施領域的成熟優勢。

對於 Windows 用户，推薦通過 WSL2（Windows Subsystem for Linux） 運行 GPUStack v2，在 Windows 上構建與 Linux 生產環境高度一致的 AI 運行環境，完整體驗 v2 帶來的性能優化與架構優勢。

整篇稍長，可先看以下總結的六點，有問題再細看全文：

1. 驅動安裝：在 Windows 主機安裝 NVIDIA 驅動，不要在 WSL 內部安裝。
2. CUDA 環境：無需 CUDA Toolkit（Windows/WSL 均不需要）。
3. 容器環境：請在 WSL 內部安裝原生 Docker Engine，不要使用 Docker Desktop。
4. （可選）局域網訪問：若需局域網訪問 Server，可在 "WSL Settings" 中將網絡模式配置為 Mirrored。
5. 環境檢測：運行環境檢測時，請使用 默認用户，不要使用 root 用户（nvidia-smi 在 WSL 中的非標準路徑中，此路徑不在 root 用户下的環境變量中）。
6. IP 配置：Worker IP 填寫 WSL 的具體 IP，使用 127.0.0.1 可能存在問題。

下面將詳細介紹如何在 WSL 環境中配置 NVIDIA GPU 並部署 GPUStack。

1. 實驗環境

本文基於以下實驗環境編寫，但適用於大多數支持 WSL 的 Windows 10/11 系統。

• 操作系統：Windows 11
• 硬件：GeForce RTX 4090D
• 虛擬化：需在 BIOS/UEFI 中開啓虛擬化支持

2. 關鍵架構説明

相關參考文檔：

• Microsoft WSL 官方文檔（GPU 支持）：https://learn.microsoft.com/en-us/windows/wsl/tutorials/gpu-c...
• NVIDIA CUDA on WSL 用户指南：https://docs.nvidia.com/cuda/wsl-user-guide/index.html

在 WSL 中部署 GPUStack 有兩點需要注意：

2.1 驅動安裝

在 Windows 系統中安裝 NVIDIA 顯卡驅動，不要在 WSL 中安裝。WSL 內部會自動通過 Passthrough 機制調用宿主機的驅動，在 WSL Linux 發行版中重複安裝 NVIDIA 驅動或 CUDA Toolkit 可能會破壞現有環境。

2.2 容器運行時

請使用原生 Docker Engine，不要使用 Docker Desktop 集成。Docker Desktop 的網絡模型與標準 Docker Engine 不同，會導致 GPUStack 組件間通信失敗。

如果已經安裝 Docker Desktop，請在 Docker Desktop 設置中關閉對目標子系統的集成。參考配置如圖所示：

3. 環境準備步驟

步驟 1：安裝 NVIDIA 驅動（Windows 端）

前往 NVIDIA 官方驅動下載頁面，根據顯卡型號下載並安裝Windows 版本的最新驅動程序。

• 下載地址：https://www.nvidia.com/en-us/drivers/

步驟 2：安裝或更新 WSL（Windows 端）

以管理員身份打開 PowerShell 或命令提示符，執行以下命令安裝或更新 WSL：

# 安裝 WSL（默認安裝 Ubuntu）
wsl --install

# 或者更新 WSL 至最新內核
wsl --update

• 注意：首次安裝 WSL 後，系統可能要求重啓計算機。
• 詳細步驟參考：https://learn.microsoft.com/en-us/windows/wsl/install

步驟 3：安裝 Docker Engine（WSL 端）

進入 WSL Linux 終端，按照 Docker 官方文檔安裝 Docker Engine。

• 官方文檔：https://docs.docker.com/engine/install/ubuntu/

步驟 4：安裝 NVIDIA Container Toolkit（WSL 端）

• 官方文檔：https://docs.nvidia.com/datacenter/cloud-native/container-too...

安裝完成後，需要執行如下配置命令：

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

4.（可選）局域網訪問配置

默認情況下，WSL 使用 NAT 模式，這意味着局域網內的其他設備無法直接訪問 WSL 中運行的服務（如 GPUStack Server）。

若需在局域網訪問，請使用 "WSL Settings" 工具配置 WSL 網絡模式為 "Mirrored"，如下圖所示

關於 WSL 網絡模式的詳細信息，請查看微軟官方文檔：https://learn.microsoft.com/en-us/windows/wsl/networking

5. 部署 GPUStack Server

環境準備就緒後，WSL 即可被視為一個標準的 Linux 環境。

請參考 GPUStack 官方文檔進行安裝：https://docs.gpustack.ai/latest/installation/installation/

6. 添加 Worker 時的注意事項

在 GPUStack UI 界面中按照引導添加 Worker 時，請務必注意以下兩點：

6.1 使用默認用户執行腳本

在執行添加 Worker 的驗證腳本時，請使用 WSL 的默認用户執行，不要使用 root 用户。

• 原因：在 WSL 中，nvidia-smi 命令的路徑可能未包含在 root 用户的環境變量中，而默認用户可以直接調用。若使用 root 執行，即使環境配置正確，GPU 檢測也會失敗。

6.2 正確填寫 Worker IP

在配置 Worker IP 地址時，請填寫 WSL 的實際 IP 地址（例如 172.x.x.x），可使用 ip addr 命令查看。

使用 127.0.0.1 可能導致添加 Worker 失敗。

7. 常見問題與注意事項

• 重啓生效：安裝 Windows 顯卡驅動和 WSL 後通常需要重啓 Windows 系統；安裝 NVIDIA Container Toolkit 後需重啓 WSL 中的 Docker 服務。
• WSL 侷限性：儘管 NVIDIA 對 WSL 的支持已非常完善，但仍有極少數特定場景可能存在兼容性差異。如遇未知錯誤，建議搜索 "WSL + [具體錯誤信息]" 獲取解決方案。
• 組件角色：本指南主要解決 GPU 算力供給（Worker）的問題。對於 GPUStack Server（管理端），由於其主要通過網絡通信，對 GPU 依賴較小，部署位置相對靈活，但在 WSL 中統一部署管理更為方便。

GPUStack 更多信息

開源地址：https://github.com/gpustack/gpustack

官網文檔：https://docs.gpustack.ai/

GPUStack v2 FAQ：https://p0p8qa0c0s.feishu.cn/wiki/U3rfw356JitxN3kQeyOcrabInAg

歡迎加入社區羣交流

如果二維碼失效，大家可前往 GPUStack 項目獲取最新入羣二維碼 https://github.com/gpustack/gpustack/blob/main/docs/assets/wechat-group-qrcode.jpg