DeepSeek-OCR VLLM 环境配置指南

本文记录了在离线服务器上搭建 DeepSeek-OCR 推理环境的完整过程，包括依赖安装、版本兼容问题排查及解决方案。

---

一、系统基础环境准备

# 1. 更新系统包并安装 zsh
apt update && apt install -y zsh

# 2. 安装 Oh My Zsh（可选，提升终端体验）
sh -c "$(wget -qO- http://qiniu.dywlkj.com/install-omz.sh)"

# 3. 安装 uv 包管理器（高性能 Python 包管理工具）
wget http://qiniu.dywlkj.com/uv_for_linux_x86/install.sh -O - | sh

# 4. 安装 NVM（Node Version Manager）和 Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh |bash

说明 ：uv 是新一代 Python 包管理器，速度比 pip 快 10-100 倍，推荐在生产环境中使用。

---

二、创建项目目录并初始化虚拟环境

# 创建项目目录并进入
mkdir deepseek-ocr-vllm && cd deepseek-ocr-vllm

# 使用 Python 3.12 创建 uv 虚拟环境
uv venv --python 3.12

# 配置国内镜像源（加速下载）
cat << 'EOF' > uv.toml
[[index]]
name = "aliyun"
url = "https://mirrors.aliyun.com/pypi/simple/"
default = true
EOF

配置说明：使用阿里云镜像源可以大幅提升 Python 包的下载速度，尤其适合网络环境较差的服务器。

---

三、安装 PyTorch 和 vLLM

# 1. 安装 PyTorch 2.6.0（适配 CUDA 12.4）
# 使用代理加速下载
HTTPS_PROXY=http://127.0.0.1:8080 uv pip install torch==2.6.0 \
  --index-url https://download.pytorch.org/whl/cu124 \
  --no-cache

# 2. 安装 vLLM 推理框架
uv pip install vllm==0.8.5

版本说明：

• torch==2.6.0：DeepSeek-OCR 推荐的 PyTorch 版本
• cu124：表示适配 CUDA 12.4，需确保显卡驱动支持
• vllm==0.8.5：当前项目测试通过的版本

---

四、验证当前环境版本

安装完成后，运行以下命令检查各依赖版本是否匹配：

uv pip show torch transformers tokenizers einops addict easydict

当前安装版本清单：

库名	当前安装版本	DeepSeek-OCR 推荐版本	状态
torch	2.6.0	2.6.0	✅ 匹配
transformers	4.57.6	4.46.3	⚠️ 偏高
tokenizers	0.22.2	0.20.3	⚠️ 偏高
einops	0.8.1	(未指定)	✅ 兼容
vllm	0.8.5	0.8.5	✅ 匹配

注意事项 ：若 transformers 版本过高，可能遇到兼容性问题，建议降级至 4.46.3。

---

五、显卡驱动与 CUDA 环境检查

# 查看 CUDA 编译器版本
nvcc --version

# 查看 GPU 状态和驱动信息
nvidia-smi

# 检查 flash-attn 是否已安装
uv pip show flash-attn

Python 环境深度检测：

python -c "import torch; print(f'PyTorch version: {torch.__version__}'); print(f'CUDA available: {torch.cuda.is_available()}'); print(f'GPU: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else \"None\"}')"

预期输出示例：

PyTorch version: 2.6.0+cu124
CUDA available: True
GPU: NVIDIA A10

---

六、解决 vLLM 的 CUDA 版本问题

vLLM 默认下载的是 CUDA 12 的二进制文件，如果显卡驱动只支持 CUDA 11.8，可能会报错。

解决方案：安装适配 CUDA 11.8 的 vLLM 版本

# 使用国内镜像源下载 cu118 版本
uv venv --python 3.12 -v
# 安装地址示例：http://qiniu.dywlkj.com/vllm-0.8.5/vllm-0.8.5%2Bcu118-cp38-abi3-manylinux1_x86_64.whl

---

七、安装 flash-attn（核心依赖）

flash-attn 是 DeepSeek-OCR 加速推理的关键依赖，需要与 PyTorch 版本严格匹配。

# 1. 先安装基础依赖
uv pip install einops numpy

# 2. 强制编译匹配当前环境的 flash-attn
export MAX_JOBS=8
export TORCH_CUDA_ARCH_LIST="8.6"   # 针对 A10 显卡（A10 架构为 8.6）
HTTPS_PROXY=http://127.0.0.1:8<PASSWORD> pip install flash-attn==2.7.3 --no-build-isolation

参数说明：

• --no-build-isolation：禁止独立编译环境，使用当前环境的 PyTorch
• MAX_JOBS=8：设置并行编译线程数
• TORCH_CUDA_ARCH_LIST="8.6"：指定编译目标架构（A10/A100 为 8.0/8.6）

7.1 flash-attn 三层依赖架构

依赖层级	关键组件	必须版本
Python 层	python	3.11 或 3.12
框架层	torch	2.6.0+cu124
硬件层	flash-attn	2.7.3
底层库	nvidia-*-cu12	12.x

---

八、flash-attn 安装验证

按以下三个层级逐步验证：

8.1 基础导入检测

python -c "import torch; import flash_attn; print(f'导入成功! 版本: {flash_attn.__version__}')"

8.2 算子加载检测

python -c "
import torch
from flash_attn import flash_attn_func

if not torch.cuda.is_available():
    print('错误: CUDA 不可用')
    exit(1)

import flash_attn_2_cuda as spec
print('✅ CUDA 算子加载成功!')
print(f'GPU 型号: {torch.cuda.get_device_name()}')
"

8.3 运行逻辑检测

uv run python "
import torch
from flash_attn import flash_attn_func

q, k, v = [torch.randn(1, 12, 128, 64, device='cuda', dtype=torch.float16) for _ in range(3)]
try:
    out = flash_attn_func(q, k, v, dropout_p=0.0, softmax_scale=None, causal=True)
    print('🚀 Flash Attention 运算测试通过!')
except Exception as e:
    print(f'❌ 运算失败: {e}')
"

验证结果判断：

• ✅ 全部通过 → 环境配置成功
• ❌ ImportError → flash-attn 版本不匹配，需重新编译
• ❌ undefined symbol → PyTorch 与 flash-attn 版本不一致

---

九、从 ModelScope 下载模型

from modelscope import snapshot_download
import os

# 模型信息
MODEL_NAME = "deepseek-ai/DeepSeek-OCR"
MODEL_ID = "DeepSeek-OCR"
SAVE_DIR = f"/mnt/workspace/models/{MODEL_ID}"

if __name__ == "__main__":
    print(f"正在从 ModelScope 下载模型: {MODEL_NAME}")
    print(f"保存目录: {SAVE_DIR}")
    print("-" * 50)

    # 确保目录存在
    os.makedirs(SAVE_DIR, exist_ok=True)

    # 下载模型（使用 local_dir 直接平铺文件）
    model_dir = snapshot_download(
        MODEL_NAME,
        local_dir=SAVE_DIR,
        cache_dir="/mnt/workspace/models/.cache",
        revision="master",
    )

    print("-" * 50)
    print(f"模型下载完成！")
    print(f"模型路径: {model_dir}")

---

十、离线环境打包清单

如果需要在离线服务器部署，可以导出所有相关依赖：

uv pip freeze | grep -E "torch|flash-attn|einops|nvidia-" > offline_requirements.txt

离线安装包清单（必须包含）：

• torch-2.6.0-*.whl
• vllm-0.8.5-*.whl
• flash_attn-2.7.3-*.whl
• einops-*.whl
• nvidia-*-cu12 相关 wheel 文件

---

十一、常见问题排查

问题 1：undefined symbol: _ZN3c105ErrorC2...

原因：flash-attn 编译时链接的 PyTorch 版本与当前环境不一致

解决：

uv pip uninstall flash-attn
export MAX_JOBS=8
HTTPS_PROXY=http://127.0.0.1:8080 uv pip install flash-attn==2.7.3 --no-build-isolation

问题 2：libcuda.so.1 cannot be found

原因：显卡驱动版本与 CUDA 版本不匹配

解决：检查驱动版本或安装对应 CUDA 版本的 vLLM

nvidia-smi  # 查看驱动支持的 CUDA 版本

问题 3：No module named 'numpy'

解决：

uv pip install numpy

---

十二、获取已编译的 flash-attn Wheel

安装成功后，编译生成的 wheel 文件位于：

~/.cache/uv

可将其复制到离线服务器使用：

cp ~/.cache/uv/flash_attn-*.whl /mnt/backup/

---

十三、克隆项目源码

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

---

总结

本指南涵盖了：

1. ✅ 系统基础环境配置
2. ✅ Python 虚拟环境与依赖管理
3. ✅ PyTorch + vLLM 安装
4. ✅ flash-attn 编译与验证
5. ✅ 模型下载与离线部署

如有问题，请参考「常见问题排查」章节或提交 Issue。