Windows 本地大模型部署实战：WSL2 + SGLang + RedHatAI Qwen3.8-27B-INT4，一键跑起来

一句话概括：不需要双 3090，也不需要裸金属 Linux。Windows 11 + 一张 NVIDIA 显卡，用 WSL2 里的 SGLang 推理引擎 + RedHatAI 官方 INT4 量化版 Qwen3.8-27B，就能得到一个全本地、零费用、10 万 token 上下文的大模型服务。本文所有数字均为真实部署后的实测值，参数原理、踩坑清单、一键脚本和零基础教程一次讲全。

写在前面：为什么是这套组合

想在 Windows 上跑一个 27B 级别的大模型，通常有三条路：租云服务器（按月烧钱）、下载 Ollama/llama.cpp（串行推理，速度一般）、或者折腾一个完整的 Linux 环境（对多数人不现实）。

这套方案走的是第四条路：WSL2 + SGLang + 官方 INT4 量化模型。三个组件各干各的活：

WSL2 解决”Windows 上跑 Linux 生态”的问题，而且 GPU 直通，性能接近原生；
SGLang 是 LMSYS 出品的推理引擎，靠连续批处理 + RadixAttention 前缀缓存把并发吞吐拉满；
RedHatAI Qwen3.8-27B-INT4 是 Red Hat 官方用 vLLM 团队 LLM Compressor 量化的版本，19GB 就能装进 24GB 显存的显卡，SGLang/vLLM 原生加载、零补丁。

下面按顺序讲：环境怎么备、两个组件各是什么、配置怎么写、参数为什么这么调、实测数据如何、最后给出一键脚本和零基础保姆级教程。两类读者都能各取所需——技术爱好者看参数原理，零基础用户照教程走一遍就能部署成功。

一、WSL2 环境准备

1.1 WSL2 是什么

WSL2 是 Windows 11+ 内置功能，本质是一台带 Linux 内核的轻量虚拟机。关键差异在于：它不是”翻译”，而是GPU 直通。根据 NVIDIA 官方 CUDA on WSL User Guide（13.3 节），WSL2 的 GPU 加速性能接近原生 Linux，跑大模型完全够用。

1.2 核心规则：只装 Windows 驱动，WSL 内什么都不装

这是 WSL2 部署最容易踩的坑，必须放在最前面：

只需安装 Windows NVIDIA 驱动（R495+，Pascal 架构及以上的显卡），WSL 内不要安装任何 Linux GPU 驱动。
原理：Windows 驱动会在 WSL2 内以 stub 形式暴露为 libcuda.so，CUDA 调用直接走 Windows 驱动。如果你在 WSL 里装了 Linux 驱动，会把这份 stub 覆盖掉，环境直接坏掉，而且恢复起来很麻烦。
WSL 内可以用 nvidia-smi 验证（实际路径是 /usr/lib/wsl/lib/nvidia-smi，root 用户需要手动加 PATH）。如果它显示 Limited Feature Set，那是正常现象（WSL 复用 Windows 驱动的典型特征），什么都不用做。

1.3 安装步骤

# Windows PowerShell
wsl.exe --install        # 安装 WSL + Ubuntu
wsl.exe --update         # 更新 WSL 内核
wsl.exe                  # 进入 Ubuntu

1.4 Docker 支持与两个 WSL2 限制

Docker：Windows 驱动 + NVIDIA Container Toolkit（v2.6.0+）或 Docker Desktop 即可支持容器 GPU 直通。
限制一：多 GPU 系统。WSL2 里 --gpus all 不能按索引筛选特定 GPU（枚举限制）。本文单卡部署不受影响；双卡用户要么分别起容器抢全部 GPU，要么接受这张限制。
限制二：UVM（统一内存）在 WSL2 受限；CUDA 工具链要用 WSL-Ubuntu 专用安装包，避免覆盖驱动。

对本文的结论：单张 24GB/32GB 显卡的 Windows 11 机器，装好 Windows NVIDIA 驱动 + Docker（WSL2 backend）即可开工。

二、SGLang 框架介绍

仓库：https://github.com/sgl-project/sglang（LMSYS 出品）
最新稳定版 v0.5.18，底层换代为 torch 2.13 + triton 3.7.1 + FlashInfer 0.6.17
官方 Docker 镜像：lmsysorg/sglang:latest

SGLang 的核心优势是并发吞吐。它做两件事：

连续批处理（continuous batching）：不等一个请求做完再服务下一个，而是动态把多个请求拼成一个批，GPU 利用率远高于串行推理。
RadixAttention 前缀缓存：多个请求共享相同前缀（比如系统提示词）时，前缀的 KV 计算只做一次，后续请求直接命中缓存，长系统提示词场景提速显著。

本文实测（27B INT4 单卡）：3 并发聚合吞吐 130.2 t/s，而 llama.cpp 串行模式下同等负载只有 73 t/s。另外 SGLang 的长上下文 prefill 也明显更快，本文实测 72K token 输入约 44 秒通过。

三、RedHatAI Qwen3.8-27B-INT4 模型介绍

地址：https://huggingface.co/RedHatAI/Qwen3.8-27B-INT4
基础模型：Qwen/Qwen3.8-27B（Apache-2.0，https://huggingface.co/Qwen/Qwen3.8-27B）

这是 Red Hat 官方发布的量化版本，几个关键点：

量化管线：用 vLLM 团队的 LLM Compressor 工具链量化，产物是 compressed-tensors 格式——vLLM 和 SGLang 都能原生加载，零补丁、零魔改。
量化方案：AWQ + GPTQ 双算法（duo_scaling），W4A16：权重压到 int4、group size 128、actorder=WEIGHT；计算激活保持 16 位。
选择性量化：只量化 transformer 线性层，视觉塔 + 输出头保留原始 BF16——所以它支持图像输入（多模态），且输出层精度不受损。
体积：权重约 19GB，这就是它能装进 24GB 显存显卡的原因。

一句话评价：想要”官方量化 + 原生框架加载 + 多模态保留”，这个模型是目前 Qwen3.8-27B 里省心的选择。

四、docker-compose 配置

下面是最终生产配置（Linux 双 3090 的 GPU1 上运行，156K 上下文实测）。WSL2 单卡用户照抄可用，显存参数按文末说明微调：

sgl-qwen27b-gpu1:
  image: lmsysorg/sglang:latest          # v0.5.18
  ports: ["15433:30000"]
  environment:
    - CUDA_VISIBLE_DEVICES=1
    - SGLANG_MAX_NEW_TOKENS_LIMIT=32000
    - PYTORCH_CUDA_ALLOC_CONF=expandable_segments:False
  command: >
    python3 -m sglang.launch_server
      --model-path /models/RedHatAI-Qwen3.8-27B-INT4
      --port 30000 --host 0.0.0.0
      --dtype bfloat16
      --context-length 102400
      --mem-fraction-static 0.95
      --max-total-tokens 102400
      --mamba-full-memory-ratio 0.5
      --max-mamba-cache-size 15
      --mamba-radix-cache-strategy no_buffer
      --disable-overlap-schedule
      --mm-feature-transport cpu
      --attention-backend flashinfer     # fp8 KV 必须
      --mamba-ssm-dtype bfloat16
      --kv-cache-dtype fp8_e4m3
      --trust-remote-code
      --reasoning-parser qwen3
      --tool-call-parser qwen3_coder
      --sleep-on-idle

（注：此参数组合为”RedHatAI 19GB 权重”适用版；32GB 卡用户可把 mem-fraction 提到 0.95，24GB 卡建议 0.92-0.93。）

单卡用户把 CUDA_VISIBLE_DEVICES=1 改成 0 或删掉即可（WSL2 下多 GPU 索引筛选受限，单卡用默认即可）。

五、参数优化原理：每个参数为什么这么设

调优参数借鉴自双 3090 Linux 实测结论，全部经过验证。逐条讲原理。

5.1 `--mem-fraction-static`：显存预算的起点，甜点是实测出来的

它定义模型权重 + KV 池占 GPU 显存的比例。27B INT4 在 24GB 卡上的实测扫描结果：

mem-fraction	KV 池 (tokens)	CUDA Graph	推理
0.92	56,991	✅	✅ 安全
0.95	78,608	✅	✅ 48.8 t/s 精确甜点
0.96	85,813	✅	❌ OOM（假成功：捕获成功但推理 activation 缺 256MB）
0.97/0.98	—	✅/❌	❌

为什么 0.95 是精确甜点：0.95 时 KV 池 78,608 tokens，单请求稳定 48.8 t/s；再往上调，KV 池继续变大但推理启动 OOM。这里藏着踩坑清单里最阴险的一条——“假成功”：0.96/0.97 时服务启动、CUDA Graph 捕获成功，看起来一切正常，但真正推理时 activation 需要额外 256MB，此时 OOM。所以判断标准不是”服务起没起来”，而是”推理能不能跑通”。

为什么 24GB 卡建议 0.92-0.93：24GB 卡上 KV 池余量更小，0.95 是 32GB 卡的甜点，24GB 卡留点安全边际更稳（脚本会自动按显存大小选择）。

5.2 `--max-total-tokens`：KV 池精确匹配上下文，大输入 OOM 的解药

设成与 --context-length 相等（本文 102400）。原理：默认情况下 KV 池和请求的 token 预算是分开算的，超长输入会额外申请 prefill 临时空间，导致 OOM。把 --max-total-tokens 精确对齐 context-length 后，KV 池边界就是请求边界，prefill 不再额外占显存——这是修复”大输入 OOM”的利器。

一个反直觉的结论（踩坑清单）：--context-length 本身不影响 KV 池大小，KV 池由 mem-fraction 决定。也就是说，想扩大上下文窗口，调 context-length 没用，得从显存预算（mem-fraction）入手。

5.3 `--kv-cache-dtype fp8_e4m3` + `--attention-backend flashinfer`：KV 池翻倍，还更快

fp8 KV 把 KV 池单位 token 的显存占用砍半，同样显存预算下 KV 池 token 数直接翻倍，而且计算上 fp8 比 bf16 更快。但 fp8 KV 必须配 flashinfer：用 triton 后端会直接崩溃（fp8e4nv not supported）。这是踩坑清单第一条，没有商量余地。

5.4 `--max-mamba-cache-size`：它决定并发上限

Qwen3.8 是 GDN 混合架构（含 mamba 类线性注意力层），每个并发请求要占一块 mamba state 缓存。--max-mamba-cache-size 15 在实测中使日志输出 max_running_requests is capped to 3——即并发上限为 3。这个值就是并发吞吐的天花板：它同时约束 KV 池和 mamba state 的总量，想提高并发就得先算清楚这两块的显存账。3 并发时聚合 130.2 t/s，就是在这个约束下达到的。

5.5 `--mamba-ssm-dtype bfloat16`：混合架构的 state 减半

GDN 混合架构的 SSM state 如果按 fp32 存会非常占显存，显式指定 bfloat16 后 state 直接减半。配合 --dtype bfloat16（GDN 混合架构必选，fp8 KV 之外另一个架构硬要求），整条链路的精度/显存账才平。

5.6 `--mm-feature-transport cpu`：白捡 1GB 显存

SGLang 默认会给多模态特征传输预留约 1GB 显存。纯文本场景用不上它，把特征传输放到 CPU 后这 1GB 就被回收，直接扩大 KV 池——下文”上下文扩展三轮”的第三步就靠它。纯文本用户零影响。

5.7 上下文扩展三轮：+82%，零额外显存投入

这是把上面几条原理组合拳的实测过程：

初始（extra_buffer + cache15）：KV 66,640 / ctx 65,536
no_buffer + cache9 + disable-overlap：KV 81,006 / ctx 80,000
- mm-feature-transport=cpu（回收 1GB 多模态池）：KV 120,079 / ctx 119,000

总结：从 65,536 到 119,000，上下文扩展 82%，没有加一分钱显存，全靠把默认预留的空间一项项要回来。这就是参数调优的全部意义——不是拍脑袋调大，而是逐项搞清每块显存花在哪、能不能要回来。

六、测试验证数据（实测）

双 3090 单卡（GPU1）部署后的实测数据：

场景	数据
单请求速度	46.1 t/s
2 并发聚合	88.9 t/s
3 并发聚合	130.2 t/s
3 并发长 prompt	TTFT 0.8s, prefill 2153 tok/s
36K token 输入	~25s 通过，无 OOM
72K token 输入	~44s 通过，无 OOM
prefill 吞吐	1300-1600 token/s
KV 池 (0.95)	78,608 tokens

验证方式（部署后照做）：

# 启动后验证
docker logs <容器>   # 核对 max_running_requests / KV Cache #tokens
curl http://localhost:30000/v1/chat/completions -d '{...}'

重点看日志两行：max_running_requests（是否等于你预期的并发上限）和 KV Cache #tokens（是否与你预期的 mem-fraction 一致）。两者都对，再发真实请求验证输出质量。

七、Windows 一键部署脚本

两个脚本：setup-wsl.ps1（Windows PowerShell 内，管理员运行）负责环境检查与准备；deploy.sh（WSL 内）负责下载模型、生成 compose、启动验证。

脚本 1：setup-wsl.ps1（保存后在管理员 PowerShell 运行）

# WSL2 + CUDA 环境一键准备 (管理员 PowerShell 运行)
Write-Host "=== Step 1/3: 检查 Windows NVIDIA 驱动 ===" -ForegroundColor Cyan
try {
    $smi = & nvidia-smi --query-gpu=name,driver_version --format=csv,noheader 2>&1
    if ($LASTEXITCODE -ne 0) { throw "nvidia-smi 不可用" }
    Write-Host "  检测到 GPU: $smi" -ForegroundColor Green
} catch {
    Write-Host "  未检测到 NVIDIA 驱动! 请先安装:" -ForegroundColor Red
    Write-Host "  https://www.nvidia.com/Download/index.aspx (R495+)" -ForegroundColor Yellow
    exit 1
}

Write-Host "=== Step 2/3: 安装/更新 WSL2 ===" -ForegroundColor Cyan
wsl.exe --install --no-distribution 2>$null
wsl.exe --update

Write-Host "=== Step 3/3: 检查 Docker ===" -ForegroundColor Cyan
$docker = Get-Command docker -ErrorAction SilentlyContinue
if ($docker) {
    Write-Host "  Docker 已安装, 确保启用 WSL2 backend" -ForegroundColor Green
} else {
    Write-Host "  未检测到 Docker, 请安装 Docker Desktop (勾选 Use WSL 2 based engine)" -ForegroundColor Yellow
    Write-Host "  https://www.docker.com/products/docker-desktop/" -ForegroundColor Yellow
}

Write-Host "`n=== 完成! 下一步: 在 WSL 内运行 deploy.sh ===" -ForegroundColor Green
Write-Host "  wsl.exe`n  bash /mnt/c/Users/<你>/deploy-sglang/deploy.sh"

脚本 2：deploy.sh（放入 WSL 的 `~/deploy-sglang/` 后执行）

#!/usr/bin/env bash
set -euo pipefail
# SGLang + RedHatAI Qwen3.8-27B 一键部署 (WSL2 内执行)

WORKDIR="$HOME/deploy-sglang"
MODEL_DIR="$WORKDIR/models"
MODEL_ID="RedHatAI/Qwen3.8-27B-INT4"
PORT=15433

echo "=== [1/4] 安装依赖 (docker + nvidia-container-toolkit) ==="
if ! command -v docker &>/dev/null; then
    sudo apt-get update && sudo apt-get install -y docker.io docker-compose-plugin
    # WSL2 无 systemd 时用 service 兜底
    if systemctl is-system-running &>/dev/null; then
        sudo systemctl enable --now docker
    else
        sudo service docker start
    fi
fi
if ! docker compose version &>/dev/null; then
    sudo apt-get install -y docker-compose-plugin
fi
if ! docker info 2>/dev/null | grep -q "Runtimes.*nvidia"; then
    curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
      | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
    curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
      | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
      | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
    sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
    sudo nvidia-ctk runtime configure --runtime=docker
    if systemctl is-system-running &>/dev/null; then
        sudo systemctl restart docker
    else
        sudo service docker restart
    fi
fi
sudo usermod -aG docker "$USER" || true

echo "=== [2/4] 下载模型 (RedHatAI Qwen3.8-27B-INT4, ~19GB) ==="
mkdir -p "$MODEL_DIR"
if [ ! -f "$MODEL_DIR/config.json" ]; then
    sudo apt-get install -y git-lfs
    git lfs install
    GIT_LFS_SKIP_SMUDGE=0 git clone --depth 1 https://huggingface.co/$MODEL_ID "$MODEL_DIR"
fi
# 校验模型完整性 (必须存在 safetensors 权重)
if ! ls "$MODEL_DIR"/*.safetensors >/dev/null 2>&1; then
    echo "错误: 模型权重不完整 (缺少 .safetensors), 请检查网络/磁盘后重跑" >&2
    exit 1
fi

# 显存检测: 24GB 卡用 0.92 (安全), 32GB 卡用 0.95 (甜点)
TOTAL_MEM=$(nvidia-smi --query-gpu=memory.total --format=csv,noheader,nounits 2>/dev/null | head -1 | tr -d ' ')
if [ -n "$TOTAL_MEM" ] && [ "$TOTAL_MEM" -lt 26000 ]; then
    MEM_FRACTION=0.92
else
    MEM_FRACTION=0.95
fi

echo "=== [3/4] 生成 docker-compose.yml (检测显存: ${TOTAL_MEM:-未知}MB → mem-fraction $MEM_FRACTION) ==="
cat > "$WORKDIR/docker-compose.yml" <<'YAML'
services:
  sglang:
    image: lmsysorg/sglang:latest        # v0.5.18
    container_name: sglang-redhatai-27b
    restart: unless-stopped
    runtime: nvidia
    ports:
      - "15433:30000"
    volumes:
      - ./models:/models:ro
    environment:
      - SGLANG_MAX_NEW_TOKENS_LIMIT=32000
      - PYTORCH_CUDA_ALLOC_CONF=expandable_segments:False
    ipc: host
    command: >
      python3 -m sglang.launch_server
        --model-path /models/RedHatAI-Qwen3.8-27B-INT4
        --port 30000 --host 0.0.0.0
        --dtype bfloat16
        --context-length 102400
        --mem-fraction-static __MEM_FRACTION__
        --max-total-tokens 102400
        --mamba-full-memory-ratio 0.5
        --max-mamba-cache-size 15
        --mamba-radix-cache-strategy no_buffer
        --disable-overlap-schedule
        --mm-feature-transport cpu
        --attention-backend flashinfer
        --mamba-ssm-dtype bfloat16
        --kv-cache-dtype fp8_e4m3
        --trust-remote-code
        --reasoning-parser qwen3
        --tool-call-parser qwen3_coder
        --sleep-on-idle
YAML

# 注: heredoc 用引号包裹 (不展开变量), mem-fraction 用占位符 + sed 注入
sed -i "s/__MEM_FRACTION__/$MEM_FRACTION/" "$WORKDIR/docker-compose.yml"
grep -q "mem-fraction-static $MEM_FRACTION" "$WORKDIR/docker-compose.yml" || { echo "错误: mem-fraction 注入失败" >&2; exit 1; }

echo "=== [4/4] 启动并验证 ==="
cd "$WORKDIR"
docker compose up -d
sleep 20
echo "服务启动中, 检查日志:"
docker logs sglang-redhatai-27b 2>&1 | grep -E "max_running_requests|KV Cache" || true
echo ""
echo "验证接口:"
curl -s http://localhost:$PORT/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"/models/RedHatAI-Qwen3.8-27B-INT4","messages":[{"role":"user","content":"你好, 用一句话介绍你自己"}],"max_tokens":100}'
echo ""
echo "=== 部署完成! API: http://localhost:$PORT/v1 ==="

说明：脚本 1 由用户手动保存并在 PowerShell 运行；脚本 2 放 WSL 内执行。模型下载依赖 huggingface 网络，下载前先确认 git lfs 可访问 huggingface.co。单卡 24GB 建议 mem-fraction 0.92，32GB 卡可 0.95（脚本默认 0.95，备注提示 24GB 改 0.92）。

八、保姆级使用教程（零基础版）

这一节面向完全没摸过 Linux 的读者。前面几节是”为什么”，这一节是”怎么做”。照着做，十分钟到半小时（取决于网速）就能跑起来。

这是什么、装完能得到什么？
装完后，你的 Windows 电脑会变成一个”本地 AI 服务器”：不用联网、不用付费，就能和 27B 参数的 Qwen3.8 对话、写代码、处理文档。它提供一个网址 http://localhost:15433，任何 AI 工具（比如支持自定义 API 的聊天软件）都可以连上它使用。

开始前，先检查你的电脑合不合格（3 项）：
1. Windows 11（64 位）
2. NVIDIA 显卡（RTX 20/30/40 系或更新），显存建议 24GB 或以上（显存就是显卡的”内存”，越大越好，8GB 以下跑不动这个模型）
3. 磁盘剩余空间 ≥ 50GB（模型本身 19GB + 运行环境）

第一步：装 Windows 显卡驱动（5 分钟，只需一次）
1. 打开浏览器访问 https://www.nvidia.com/Download/index.aspx
2. 选好你的显卡型号 → 点”搜索” → 点”下载” → 安装（一路”下一步”即可）
3. 装完重启电脑

⚠️ 注意：Windows 的驱动会自动”共享”给 WSL 使用，千万不要再去 WSL 里安装任何 Linux 驱动，否则会弄坏环境。

第二步：运行一键环境脚本（2 分钟）
1. 在桌面新建一个文件夹，命名 deploy-sglang（或者随便你喜欢的名字）
2. 把文章中的第一个脚本（setup-wsl.ps1）复制成文件，命名为 setup-wsl.ps1，放进这个文件夹
– 怎么把代码存成文件：打开”记事本” → 粘贴代码 → 文件 → 另存为 → 文件名填 setup-wsl.ps1，编码选 UTF-8 → 保存
3. 在 Windows 开始菜单搜索”PowerShell”，右键 → “以管理员身份运行”
4. 输入 cd 桌面\deploy-sglang（把”桌面”换成你的实际路径，看不懂路径的话，直接把文件夹拖进 PowerShell 窗口也行）
5. 输入 .\setup-wsl.ps1 回车
6. 看到绿色 完成 字样 = 成功。它会自动帮你：检查显卡 → 安装/更新 WSL2 → 检查 Docker

第三步：进入 WSL（1 分钟）
1. 在开始菜单搜索 “Ubuntu”（或 “WSL”），点击打开——这是一个”Linux 子系统”的黑色终端窗口
2. 第一次打开会要求设置用户名和密码，随便设，记住密码就行
3. 在终端里输入 mkdir -p ~/deploy-sglang 回车（创建一个工作目录，不会报错就对了）

第四步：运行一键部署脚本（10-30 分钟，取决于网速）
1. 把文章中的第二个脚本（deploy.sh）用同样方法复制成文件，命名 deploy.sh，放进 ~/deploy-sglang 目录
– 在 WSL 终端输入 cd ~/deploy-sglang 回车，然后输入 ls 回车，应能看到 deploy.sh 这个文件
2. 输入 bash deploy.sh 回车，然后……等着它跑完
3. 它会依次显示四个步骤，最后出现 === 部署完成! API: http://localhost:15433/v1 === 就是成功了
– 期间会下载约 19GB 的模型文件，中途网络断了没关系，重新运行 bash deploy.sh 会接着下载（不会从头开始）

第五步：怎么确认真的能用了（1 分钟）
1. 打开任意浏览器，访问 http://localhost:15433/v1/models
2. 如果看到一个包含 RedHatAI-Qwen3.8-27B-INT4 的网页/JSON，说明服务已在运行
3. 想快速对话，可以复制这段命令到 PowerShell 或 WSL 终端：

curl http://localhost:15433/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"/models/RedHatAI-Qwen3.8-27B-INT4","messages":[{"role":"user","content":"你好"}],"max_tokens":50}'

看到 reply 里有中文回答 = 成功！

以后怎么用？
– 想连到 AI 聊天软件：在软件里把”API 地址/base_url”填 http://localhost:15433/v1，模型名填 /models/RedHatAI-Qwen3.8-27B-INT4
– 想关掉服务器（省电）：在 WSL 终端输入 cd ~/deploy-sglang && docker compose down
– 想再次启动：cd ~/deploy-sglang && docker compose up -d
– 电脑重启后：Docker 服务会自动启动，通常不需要手动操作

遇到问题怎么办（先看这张表）：

现象	什么意思	怎么办
运行 setup 时说”未检测到 NVIDIA 驱动”	显卡驱动没装好	重新安装 Windows 驱动并重启
nvidia-smi 显示 Limited Feature Set	正常现象（WSL 复用 Windows 驱动）	什么都不用做
部署脚本下载到一半停了	网络中断	重新运行 `bash deploy.sh`，会自动续传
容器启动几秒后消失 / 内存不足	显存不够	编辑 `docker-compose.yml`，把 `0.92` 改成 `0.88` 再运行
提示 `initialization error`	驱动或 WSL 版本过旧	管理员 PowerShell 运行 `wsl --update`，并更新 Windows 驱动
提示”端口被占用”	15433 已被别的程序使用	编辑 compose 把 `15433:30000` 改成 `15434:30000`，访问时也用新端口
页面一直打不开	服务还在启动（首次约 1-3 分钟）	等 2 分钟再刷新；或 `docker logs sglang-redhatai-27b` 看日志

九、踩坑清单（全部来自实测，按踩中频率排序）

fp8 KV + triton 崩溃：--kv-cache-dtype fp8_e4m3 必须配 --attention-backend flashinfer，triton 后端会报 fp8e4nv not supported 直接崩。
0.96/0.97 mem-fraction 假成功：服务启动、CUDA Graph 捕获都正常，但真正推理时 OOM（activation 缺 256MB）。判断标准永远是”推理能跑通”，不是”服务起来了”。
context-length 不影响 KV 池：KV 池大小只由 mem-fraction 决定。想扩上下文，调 context-length 没用，要从显存预算下手。
大请求体 curl 的假故障：shell 命令行参数有 ARG_MAX 限制，超大 prompt 直接写在 -d 里会失败，要用 -d @file.json 从文件读。
WSL2 中勿装 Linux 驱动：会覆盖 Windows 驱动 stub 下来的 libcuda.so，环境即坏，恢复麻烦。只装 Windows 驱动（R495+）。
WSL2 多 GPU 不能按索引筛选：--gpus all 无法只指定某一张 GPU（枚举限制）。双卡用户规划容器时要避开这个限制。

十、下载地址

SGLang: https://github.com/sgl-project/sglang
RedHatAI Qwen3.8-27B-INT4: https://huggingface.co/RedHatAI/Qwen3.8-27B-INT4
Qwen3.8-27B 原版: https://huggingface.co/Qwen/Qwen3.8-27B
NVIDIA Windows 驱动: https://www.nvidia.com/Download/index.aspx

结语

这套方案的价值不在于”能跑”，而在于参数全部有据可查：哪个值甜、哪个值假成功、每块显存花在哪、上下文怎么白捡 82%——每一条都来自实测，而不是一句”建议调大试试”。

对 Windows 用户来说，WSL2 已经把”必须有一台 Linux 服务器”这个门槛拆掉了：一张 24GB 显存的显卡、一个周末的傍晚，你就能拥有一个 10 万 token 上下文、3 并发 130 t/s 的全本地大模型服务。数据不出本机，不用按月付费，这是私有化部署最现实的起点。

按第八节教程走一遍，十到三十分钟后你就有了一台自己的 AI 服务器。跑起来之后，剩下的调参空间，第五节的原理就是你的地图。

Windows 本地大模型部署实战：WSL2 + SGLang + RedHatAI Qwen3.8-27B-INT4，一键跑起来

Windows 本地大模型部署实战：WSL2 + SGLang + RedHatAI Qwen3.8-27B-INT4，一键跑起来

写在前面：为什么是这套组合

一、WSL2 环境准备

1.1 WSL2 是什么

1.2 核心规则：只装 Windows 驱动，WSL 内什么都不装

1.3 安装步骤

1.4 Docker 支持与两个 WSL2 限制

二、SGLang 框架介绍

三、RedHatAI Qwen3.8-27B-INT4 模型介绍

四、docker-compose 配置

五、参数优化原理：每个参数为什么这么设

5.1 --mem-fraction-static：显存预算的起点，甜点是实测出来的

5.2 --max-total-tokens：KV 池精确匹配上下文，大输入 OOM 的解药

5.3 --kv-cache-dtype fp8_e4m3 + --attention-backend flashinfer：KV 池翻倍，还更快

5.4 --max-mamba-cache-size：它决定并发上限

5.5 --mamba-ssm-dtype bfloat16：混合架构的 state 减半

5.6 --mm-feature-transport cpu：白捡 1GB 显存

5.7 上下文扩展三轮：+82%，零额外显存投入

六、测试验证数据（实测）

七、Windows 一键部署脚本

脚本 1：setup-wsl.ps1（保存后在管理员 PowerShell 运行）

脚本 2：deploy.sh（放入 WSL 的 ~/deploy-sglang/ 后执行）

八、保姆级使用教程（零基础版）

九、踩坑清单（全部来自实测，按踩中频率排序）

十、下载地址

结语

5.1 `--mem-fraction-static`：显存预算的起点，甜点是实测出来的

5.2 `--max-total-tokens`：KV 池精确匹配上下文，大输入 OOM 的解药

5.3 `--kv-cache-dtype fp8_e4m3` + `--attention-backend flashinfer`：KV 池翻倍，还更快

5.4 `--max-mamba-cache-size`：它决定并发上限

5.5 `--mamba-ssm-dtype bfloat16`：混合架构的 state 减半

5.6 `--mm-feature-transport cpu`：白捡 1GB 显存

脚本 2：deploy.sh（放入 WSL 的 `~/deploy-sglang/` 后执行）