DevOps

Windows WSL环境下用vLLM运行DeepSeek-OCR的完整实践记录

环境配置与重要前提条件

首先说明我的硬件环境：Windows 11笔记本，WSL2，32G内存和8G显存的RTX 4060移动版显卡。实践证明这个配置完全能够运行DeepSeek-OCR模型。对于此类大语言模型，显存容量是关键因素，8G显存刚好满足基础要求，内存方面16G或24G应该也足够应对。

DeepSeek-OCR官方文档虽然明确了CUDA 11.8和torch 2.6.0等依赖版本要求，但实际在WSL环境中部署时会遇到许多文档未提及的兼容性问题。下面是我在实践中总结的关键注意事项。

WSL版本必须为WSL2

只有WSL2提供完整的CUDA支持，这是由架构差异决定的。WSL2使用真实的Linux内核并在轻量级VM中运行，而WSL1只是Windows内核的转换层。WSL2通过GPU帕鲁虚拟化技术，使得Linux应用能够直接调用Windows主机上的NVIDIA GPU驱动，从而实现近乎原生的GPU性能。

验证WSL版本的方法：

1
2
# 在PowerShell中检查
wsl -l -v

如果版本显示为1，需要转换为WSL2：

1
2
wsl --set-version Ubuntu-22.04 2
wsl --set-default-version 2

同时确保使用最新WSL内核：wsl --update。

Ubuntu版本选择：22.04而非24.04

这是我踩过的一个重要坑。虽然Ubuntu 24.04是更新的LTS版本，但深度学习工具链的兼容性尚未充分验证。Ubuntu 22.04经过长期市场检验，与CUDA、PyTorch等生态的适配更为稳定。最重要的是24.04版本中有个库跟项目依赖的flash-attn版本不兼容。

具体原因包括：

  • Ubuntu 22.04的软件库与CUDA 11.8兼容性已得到充分验证
  • 主流深度学习框架（PyTorch、TensorFlow）官方优先确保与22.04的兼容性
  • 社区遇到的问题和解决方案更多基于22.04环境

新发布的Ubuntu 24.04虽然内核更新（6.8），但可能存在未被发现的驱动或软件兼容性问题，对于生产环境而言风险较高。

WSL子系统磁盘空间管理

默认WSL安装到C盘，而深度学习模型通常占用大量空间（DeepSeek-OCR模型文件可能达数十GB）。为避免C盘空间不足，需要将WSL迁移到其他分区。

备份和迁移方法：

1
2
3
4
5
# 导出WSL系统
wsl --export Ubuntu D:\wsl-backup\ubuntu-backup.tar

# 导入到新位置
wsl --import Ubuntu D:\NewPath\Ubuntu D:\wsl-backup\ubuntu-backup.tar

模型下载源选择：魔搭而非HuggingFace

在国内环境下载大型模型文件时，魔搭社区（ModelScope）的国内CDN加速明显优于HuggingFace。这不仅节省时间，还避免了因网络不稳定导致的下载中断。

魔搭社区提供了DeepSeek系列的国内镜像，下载速度可提升数倍至数十倍。对于多GB的模型文件，这一优势尤为明显。

PIP镜像源选择：清华而非阿里

虽然阿里云镜像也提供PyTorch包，但清华镜像的同步更新更及时，特别是对PyTorch和CUDA相关库的版本支持更为全面。而且阿里云似乎对非阿里云上的ip做了限速。

配置方法：

1
2
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

对于需要从官方源安装的特殊包，可以临时使用--index-url参数覆盖设置。

CUDA版本选择：WSL专用版本

必须使用NVIDIA官方提供的WSL专用CUDA工具包，而非常规Linux版本。这是因为WSL环境下GPU驱动的工作方式特殊：只需在Windows主机安装NVIDIA驱动，WSL内部安装CUDA Toolkit即可。

关键步骤：

  1. 在Windows上安装最新NVIDIA驱动（R495或更新版本）
  2. 在WSL内安装适用于WSL-Ubuntu的CUDA Toolkit 11.8：

切勿安装”cuda-drivers”等元数据包，这些包会尝试在WSL内安装Linux显卡驱动，导致冲突。

完整实施步骤

前面提到的各个点都做到了，后面的事情就相当丝滑了。

1. 安装Miniconda

在WSL环境中安装Miniconda来管理Python环境：

1
2
3
4
5
6
7
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
# 安装后初始化conda
source ~/.bashrc

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

2. 创建并激活conda环境

1
2
conda create -n deepseek-ocr python=3.12.9
conda activate deepseek-ocr

3. 安装CUDA

1
2
3
4
5
6
7
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-wsl-ubuntu.pin
sudo mv cuda-wsl-ubuntu.pin /etc/apt/preferences.d/cuda-repository-pin-600
wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda-repo-wsl-ubuntu-11-8-local_11.8.0-1_amd64.deb
sudo dpkg -i cuda-repo-wsl-ubuntu-11-8-local_11.8.0-1_amd64.deb
sudo cp /var/cuda-repo-wsl-ubuntu-11-8-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get -y install cuda

4. 下载DeepSeek-OCR项目代码

1
2
git clone https://github.com/deepseek-ai/DeepSeek-OCR.git
cd DeepSeek-OCR

5. 安装项目依赖

按照requirements.txt安装基础依赖后，需要手动安装特定版本的PyTorch：

1
2
3
4
pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu118
pip install vllm-0.8.5+cu118-cp38-abi3-manylinux1_x86_64.whl
pip install -r requirements.txt
pip install flash-attn==2.7.3 --no-build-isolation

注意使用CUDA 11.8对应的PyTorch版本。

6. 下载模型

从魔搭社区下载模型：

1
2
pip install modelscope
modelscope download --model deepseek-ai/DeepSeek-OCR --local_dir ./models/deepseek-ai/DeepSeek-OCR

7. 运行推理测试

调整DeepSeek-OCR-master/DeepSeek-OCR-vllm/config.py中的MODEL_PATH/INPUT_PATH/OUTPUT_PATH并执行测试代码

1
python run_dpsk_ocr_image.py

故障排除与优化建议

常见问题解决

  1. CUDA版本不匹配：确保Windows驱动、WSL内CUDA Toolkit和PyTorch的CUDA版本一致
  2. GPU不可用：运行python -c "import torch; print(torch.cuda.is_available())"检查GPU是否可用
  3. 显存不足：调整-gpu-memory-utilization参数，或使用更小的模型变体

性能优化建议

  • 使用-gpu-memory-utilization 0.92合理分配显存
  • 对长文档采用分块处理策略，避免显存溢出
  • 启用Tensor并行推理（如有多GPU）

通过以上步骤，我成功在WSL2环境下配置了能够高效运行DeepSeek-OCR的环境。关键是要严格遵循版本要求，特别是WSL版本、Ubuntu发行版和CUDA工具包的选择。这些经验对于在Windows环境下部署其他大型AI模型也具有参考价值。

各位如果在实操的过程中，还碰到其他问题，欢迎在评论区补充讨论。