注意: 请确认你的 Windows 版本支持 WSL2,且满足 GPU 透传(如果要启用 GPU 加速)所需的最低要求。
0. 前置说明
-
适用场景:
- 你在 Windows 主机上启用了 WSL2(基于 Ubuntu 20.04/22.04 等)。
- 你想在 WSL2 Ubuntu 中部署并运行微软的 Phi-4 14B 参数量开源模型,用于本地推理。
- 你可以接受命令行操作,并对 Linux 系统有基本的理解。
-
GPU 加速与否:
- CPU-only 模式不需要任何 GPU 驱动或 CUDA 工具链,但推理速度会相对较慢。
- GPU 加速 在 WSL 中,需要 Windows 主机安装对应的显卡驱动和 WSL CUDA 支持。请先查阅 NVIDIA Docs 或 WSL 官方说明 进行安装配置。
- 下文主要会介绍如何在 WSL Ubuntu 下启用 GPU,但若你不具备满足条件的显卡或对应驱动,也可略过相关步骤,只做 CPU 推理。
1. 启用并配置 WSL 环境
1.1 启用 WSL2
为什么要做这一步?
在 Windows 上能用 Ubuntu,需要先开启 WSL 功能,并升级到 WSL2 才能使用 GPU 透传。
- 在 Windows Powershell(以管理员身份)输入:
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart wsl --set-default-version 2
- 重启计算机后,在 Microsoft Store 或者官网下载 Ubuntu WSL 应用。
- 安装完成后,打开 Ubuntu(WSL),创建用户名和密码。
1.2 (可选)配置 GPU 透传
为什么要做这一步?
如果你需要使用 NVIDIA GPU 加速,在 WSL 内进行 CUDA 推理,这一步是必要的。
-
在 Windows 主机上安装最新的 NVIDIA 驱动
- 可通过 NVIDIA 官网 下载驱动。
- 安装完成后确保
nvidia-smi
在 Windows PowerShell 中能正常执行。
-
在 Ubuntu(WSL)下安装 CUDA 工具包
# Ubuntu 20.04/22.04 示例 sudo apt update sudo apt install -y build-essential # 添加 NVIDIA CUDA 仓库 (以 11.8 为例,可根据自己需求更换) wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/cuda-keyring_1.0-1_all.deb sudo dpkg -i cuda-keyring_1.0-1_all.deb sudo apt-get update sudo apt-get -y install cuda
- 安装完成后,执行
nvidia-smi
或nvcc -V
检查是否成功。 - 如果在 WSL 里运行
nvidia-smi
输出了 GPU 信息,说明 GPU 透传成功。
- 安装完成后,执行
2. 安装必要的依赖与工具
2.1 更新并安装基础包
为什么要做这一步?
保障后续编译/运行各种推理框架或模型管理工具时不会缺少依赖,减少出错率。
sudo apt update
sudo apt upgrade -y
# 安装常见开发与网络工具
sudo apt install -y git curl wget build-essential \
cmake python3 python3-pip \
libssl-dev libffi-dev
2.2 (可选)安装 Docker (如果需要容器部署)
为什么需要 Docker?
Docker 能让你打包部署环境,便于分发与版本管理。不过在 WSL 下使用 GPU 需要额外配置docker-desktop
的 GPU 支持,比较复杂。如果你想更简单,可以跳过 Docker,直接在 WSL 下裸跑。
# 若仅想在WSL里装docker客户端,需要配合Windows上的docker desktop
# 也可以参考官方文档: https://docs.docker.com/engine/install/ubuntu/
sudo apt-get remove docker docker-engine docker.io containerd runc
sudo apt-get update
sudo apt-get install -y ca-certificates gnupg lsb-release
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
| sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \
| sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io
# 建议把当前用户添加到docker组
sudo usermod -aG docker $USER
newgrp docker
3. 选择并安装推理框架
你有多种方式加载 Phi-4:
- llama.cpp / text-generation-webui / GPTQ-for-LLaMa / Ollama
- 这里我们示范比较通用、易扩展的 text-generation-webui,也能配合多种量化模型;以及llama.cpp 的轻量级方案。
3.1 text-generation-webui 方案
为什么使用 text-generation-webui?
- 提供网页界面+API接口,调试、查看与调用都很方便。
- 对多种模型格式(GPTQ, GGML, bitsandbytes 8bit/4bit)都有支持。
3.1.1 安装 webui
# 进入家目录
cd ~
# 克隆仓库
git clone https://github.com/oobabooga/text-generation-webui.git
cd text-generation-webui
# 建议创建 Python 虚拟环境
python3 -m venv venv
source venv/bin/activate
# 安装依赖时可指定一些适配GPU的参数
pip install --upgrade pip setuptools
pip install -r requirements.txt
# 若需要GPU 4bit加载, 会安装bitsandbytes等依赖
3.1.2 下载 Phi-4 模型
为什么单独下载?
webui 并不会自动拉取所有模型,需要你手动下载到models/
文件夹或使用其脚本。
-
方式 1:直接用 webui 提供的下载脚本
许多模型有自动下载脚本,但 Phi-4 可能是新模型,脚本不一定收录。可以尝试:# 在webui目录下 cd text-generation-webui python download-model.py phi-4
如果不成功,可查看 webui 文档如何自定义下载链接。
-
方式 2:从 Ollama 或其他第三方提供的链接获取
如果社区已有phi4-ggml-q4_0.bin
或者phi4-ggml-q4_K_M.bin
等量化文件,你可以:wget <模型下载直链> -O phi4-ggml-q4_K_M.bin mkdir -p models/Phi-4 mv phi4-ggml-q4_K_M.bin models/Phi-4/
有时文件会比较大(几GB),请耐心等待。
3.1.3 启动 webui 并进行测试
cd ~/text-generation-webui
source venv/bin/activate
# 最简单启动
python server.py --model "Phi-4"
# 常见可选参数:
# --wbits 4 (指定 4bit 量化)
# --model_type llama (让webui知道它是兼容LLaMA结构)
# --listen 0.0.0.0 (允许局域网访问)
# --auto-devices (自动选择CPU/GPU)
-
为什么这些参数重要?
--wbits 4
:如果下载的量化版本是 4bit,需要显式声明以确保正确加载。--model_type llama
:有些 LLaMA 结构衍生模型(Phi-4 也类似)在 webui 中需这个标记才能正确处理 tokenizer 等。--listen 0.0.0.0
:默认只允许本机访问,如果你想用浏览器从 Windows 端访问,需要监听 0.0.0.0 并记住 WSL 分配的端口。
-
测试
- 在浏览器中输入:
http://localhost:7860
(或你在 server.py 显示的端口),可以看到一个界面。 - 输入文本测试,观察推理速度和输出。
- 在浏览器中输入:
3.2 llama.cpp 方案(更轻量)
为什么 llama.cpp?
- 性能轻量,C++ 实现;在 WSL CPU 或 Apple Silicon 上都有很好的社区支持。
- 适合只做简单推理,不需要花哨的 WebUI。
3.2.1 安装编译 llama.cpp
cd ~
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
# 编译
make
3.2.2 准备 Phi-4 GGML 模型
- 假设你已有
phi4-ggml-q4_k_m.bin
。 - 创建文件夹并放进去:
mkdir -p ~/llama.cpp/models/phi4 mv /path/to/phi4-ggml-q4_k_m.bin ~/llama.cpp/models/phi4/
3.2.3 运行推理测试
cd ~/llama.cpp
./main -m models/phi4/phi4-ggml-q4_k_m.bin -p "Hello, can you introduce yourself?" -n 200
-p
指定 prompt,-n
指定输出的 token 上限。- 如果可以正常输出,就代表部署成功。
4. 将 Phi-4 部署为“服务”并对外提供 API
为什么要这么做?
手动在命令行里跑还不够实用,多数场景要以 HTTP API 形式供前端或其他业务系统调用。
4.1 在 text-generation-webui 中启用 API
在 server.py
启动时加上 --api
参数,比如:
cd ~/text-generation-webui
source venv/bin/activate
python server.py --model "Phi-4" --wbits 4 --model_type llama --api --listen 0.0.0.0
- 调用示例:
返回的 JSON 中就包含模型的回复。curl -X POST http://localhost:7860/run/textgen \ -H 'Content-Type: application/json' \ -d '{ "data": [ "Hello, how are you today?" ] }'
4.2 在 llama.cpp 中使用服务器模式(C++ HTTP 服务器)
llama.cpp 原生也有简易的服务器模式,可以参考仓库中的
server
分支或社区贡献的 REST API 工具。
如果没有内置 HTTP 服务器,你可以自己封装 Python/C++ 代码,把llama.cpp
的推理能力暴露成 REST 接口。
5. 性能与资源检查
为什么要专门监控?
大模型推理极易消耗 CPU/GPU/内存,尤其是 14B 级模型。长时间运行后若资源不足会导致 OOM 或系统卡死。
-
系统资源
# 查看WSL内存与CPU占用 htop free -h nvidia-smi # GPU资源使用
-
推理速度
- text-generation-webui 会在日志里显示
xx tokens/s
。 - 如果速度过慢,可使用更低比特量化、缩短上下文大小等方法提升。
- text-generation-webui 会在日志里显示
-
并发请求
- 一般情况下,单实例大模型推理并不擅长处理高并发;可在后端做请求队列或限流。
- 如果业务量大,需要分布式或多机多卡扩容。
6. 常见问题与解法
-
问题:GPU 加速不起作用,实测速度跟 CPU 差不多
- 可能原因:WSL CUDA 未正确安装,或者 text-generation-webui/llama.cpp 版本还不支持 GPU offloading,你使用的量化方式也影响 GPU 调用。
- 解决:确保
nvidia-smi
在 WSL 内可用;使用支持 GPU offload 的分支,比如 llama.cpp CUDA fork 或 webui 的--gpu
参数。
-
问题:内存不足,加载模型时报错
- 可能原因:14B 模型在 4-bit 量化下仍可能需要数GB内存;如果上下文开太大(16k),内存飙升。
- 解决:换更低量化(Q4_0 → Q2/K?),或缩减上下文窗口,或升级内存到 32GB 以上。
-
问题:长上下文退化,回答不一致
- 可能原因:Phi-4 虽标称支持16k tokens,但仍会有记忆衰减或混乱现象。
- 解决:考虑检索增强 (RAG)、分块上下文、或者将历史对话压缩/总结后再传给模型。
-
问题:中文或其他语言效果不好
- 原因:Phi-4 主要针对英文优化,对于多语言可能不如专门的多语种模型。
- 解决:如果中文需求强烈,考虑换 ChatGLM 或其他专门中文模型,或二次微调 Phi-4。
7. 后续优化与生产级实践
-
微调 (Fine-tuning)
- 可对领域数据做 LoRA / PEFT 微调,让 Phi-4 更贴合特定业务需求。
- 在 WSL Ubuntu 上,需安装
transformers
,peft
等 Python 库,按照相应教程操作。
-
容器化 & CI/CD
- 如果你希望多人协作开发或在服务器集群上快速部署,可将 webui + Phi-4 + 依赖打包进 Docker,并在 CI/CD 中自动构建镜像,推送到私有仓库。
-
监控 & 日志
- 建议整合 Prometheus + Grafana 或 ELK Stack,实时监控 GPU/CPU 占用、接口调用量、推理响应时长等。
-
安全合规
- 对生产环境开放的接口,要做请求鉴权和内容审查 (Prompt Filtering + Output Filtering),避免被滥用或生成违规信息。
8. 完整命令示例(集合版)
以下示例假设:
- 你已在 WSL (Ubuntu 20.04) 中,并启用了 GPU 透传;
- 你想使用 text-generation-webui 来运行 Phi-4;
- 你打算先尝试 4-bit 量化 Q4_K_M 模型;
- 你要以 API 的形式对外提供服务。
# 1. 更新系统并安装依赖
sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential git python3 python3-pip cmake
# 2. (可选)安装 CUDA(略, 参考NVIDIA官方文档) 并验证 nvidia-smi
# 3. 克隆并安装 webui
cd ~
git clone https://github.com/oobabooga/text-generation-webui.git
cd text-generation-webui
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# 4. 下载Phi-4模型(假设你已经获取了直链或者自己准备好模型文件)
# 这里演示把模型放到 models/Phi-4/ 下
mkdir -p models/Phi-4
cd models/Phi-4
wget https://<somewhere>/phi4-ggml-q4_k_m.bin
cd ../..
# 5. 运行webui并启用API
source venv/bin/activate
python server.py --model "Phi-4" \
--model_type llama \
--wbits 4 \
--api \
--listen 0.0.0.0 \
--auto-devices
# 6. 在另一个WSL终端 或 Windows主机浏览器测试
# 浏览器访问 http://<WSL_IP>:7860 可交互对话
# 或者发起API请求:
curl -X POST http://<WSL_IP>:7860/run/textgen \
-H 'Content-Type: application/json' \
-d '{"data": ["Hello, can you tell me what is Phi-4?"]}'