DeepSeek-OCR2：开源 OCR 新王者完整部署教程（vLLM+Transformers 双接口 + 动态分辨率 + 文档批量处理）

一、前置准备（零门槛避坑，命令直接复制）

1.1 硬件要求（精准适配，无多余说明）

• 入门配置（个人/测试，支持动态分辨率基础功能）：CPU≥4核、内存≥16G、GPU（NVIDIA，计算能力≥7.0）显存≥8G，SSD剩余≥20G（存储模型+数据）

• 进阶配置（生产/批量处理，vLLM加速）：CPU≥8核、内存≥32G、GPU显存≥16G（推荐24G），多卡部署支持2×3090/4090，适配CUDA 11.8

• 极简配置（仅Transformers接口，无GPU）：CPU≥8核、内存≥32G，仅支持小批量处理，推理速度较慢

1.2 软件要求（固定版本，杜绝兼容报错）

• 操作系统：Ubuntu 22.04（推荐，兼容性最佳）、Windows 10+/11（需启用WSL2），macOS仅支持Transformers接口

• 核心工具：Python 3.12.9（必选，其他版本易报错）、Docker≥24.0（可选，批量部署用）、Git≥2.40、CUDA 11.8（GPU部署必装）

• 依赖包：torch==2.6.0、torchvision==0.21.0、vllm==0.8.5、transformers==4.39.0、flash-attn==2.7.3（后续命令直接安装）

1.3 国内镜像源配置（必做，解决下载失败/缓慢）

# 1. Python清华源（全系统通用） pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple # 2. Git国内加速（拉取源码用） git config --global url."https://ghproxy.com/https://github.com/".insteadOf "https://github.com/" # 3. Docker国内镜像（如需Docker部署，全系统通用） mkdir -p /etc/docker cat > /etc/docker/daemon.json << EOF { "registry-mirrors": ["https://docker.mirrors.ustc.edu.cn", "https://hub-mirror.c.163.com"] } EOF systemctl daemon-reload && systemctl restart docker

1.4 虚拟环境配置（避坑核心，隔离依赖）

# 安装虚拟环境工具 pip install virtualenv virtualenvwrapper -y # 创建并激活虚拟环境（环境名：deepseek-ocr2，可自定义） virtualenv -p python3.12.9 deepseek-ocr2 # Ubuntu/WSL2激活 source deepseek-ocr2/bin/activate # Windows激活（管理员PowerShell） .\deepseek-ocr2\Scripts\activate # 激活后终端前缀会显示【deepseek-ocr2】，表明配置成功

二、双接口核心部署（vLLM+Transformers，任选其一，一键落地）

方案1：vLLM接口部署（首选，生产环境，速度提升3-5倍）

1. 安装核心依赖（严格按顺序执行，避免报错） # 1. 安装PyTorch套件（适配CUDA 11.8，关键步骤） ``pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu118 `` ``# 2. 安装vllm离线包（提前下载，替换文件名为实际下载的whl包） ``# 离线包下载地址（复制到浏览器）：https://github.com/vllm-project/vllm/releases/tag/v0.8.5 ``pip install vllm-0.8.5+cu118-cp38-abi3-manylinux1_x86_64.whl `` ``# 3. 安装flash-attn（提升推理速度，必加参数） ``pip install flash-attn==2.7.3 --no-build-isolation `` ``# 4. 安装其他依赖 ``pip install pillow==10.2.0 opencv-python==4.9.0.80 pymupdf==1.24.1 gradio==4.23.0

2. 拉取源码+下载模型（国内加速，5分钟完成） # 1. 克隆DeepSeek-OCR2源码（国内加速） ``git clone https://ghproxy.com/https://github.com/deepseek-ai/DeepSeek-OCR2.git ``cd DeepSeek-OCR2/DeepSeek-OCR2-vllm `` ``# 2. 下载模型（Hugging Face国内加速，自动适配vLLM） ``pip install huggingface-hub ``huggingface-cli login # 需注册Hugging Face账号，获取token ``# 下载模型（默认路径：./model/，可自定义） ``huggingface-cli download deepseek-ai/DeepSeek-OCR-2 \ `` --local-dir ./model \ `` --local-dir-use-symlinks False

3. 启动服务（核心命令，直接复制，支持动态分辨率） # 1. 单图推理（流式输出，实时查看识别进度） ``python run_dpsk_ocr2_image.py --model-path ./model --image-input ./test.jpg --stream True `` ``# 2. PDF批量处理（自动拆分页面，合并识别结果） ``python run_dpsk_ocr2_pdf.py --model-path ./model --pdf-input ./test.pdf --output ./ocr-result `` ``# 3. 启动Gradio可视化界面（新手友好，浏览器操作） ``python deepseek_ocr2_gradio.py --model-path ./model --port 8080

4. 验证部署成功（10秒完成） # 方式1：命令行验证（单图推理无报错，输出识别结果即成功） ``python run_dpsk_ocr2_image.py --model-path ./model --image-input ./test.jpg `` ``# 方式2：可视化验证（浏览器访问） ``http://本机IP:8080 ``# 上传图片/PDF，能正常识别并输出结果即成功

方案2：Transformers接口部署（灵活适配，支持二次开发）

1. 安装核心依赖（复制即用，无需额外配置）# 激活虚拟环境后，执行以下命令 ``pip install torch==2.6.0 torchvision==0.21.0 --index-url https://download.pytorch.org/whl/cu118 ``pip install transformers==4.39.0 accelerate==0.30.0 sentencepiece==0.1.99 ``pip install pillow==10.2.0 opencv-python==4.9.0.80 pymupdf==1.24.1

2. 下载模型+启动服务（直接调用，无需复杂配置） # 创建启动文件 transformers_infer.py，复制完整代码 ``from transformers import AutoModelForCausalLM, AutoProcessor ``import torch ``from PIL import Image `` ``# 加载模型和处理器（替换为自己的模型路径） ``model_path = "./model/DeepSeek-OCR-2" ``model = AutoModelForCausalLM.from_pretrained( `` model_path, `` torch_dtype=torch.float16, `` device_map="auto", `` trust_remote_code=True ``) ``processor = AutoProcessor.from_pretrained(model_path, trust_remote_code=True) `` ``# 单图识别函数（可直接调用） ``def ocr_single_image(image_path): `` image = Image.open(image_path).convert("RGB") `` inputs = processor(images=[image], return_tensors="pt").to("cuda", torch.float16) `` outputs = model.generate(**inputs, max_new_tokens=4096) `` result = processor.decode(outputs[0], skip_special_tokens=True) `` return result `` ``# 测试识别（替换为自己的图片路径） ``if __name__ == "__main__": `` image_path = "./test.jpg" `` ocr_result = ocr_single_image(image_path) `` print("【OCR识别结果】") `` print(ocr_result) `` # 保存结果到文件 `` with open("./ocr_result.txt", "w", encoding="utf-8") as f: `` f.write(ocr_result)

3. 启动并验证 # 启动识别 ``python transformers_infer.py ``# 输出识别结果，且生成ocr_result.txt文件即部署成功

三、核心功能实战（动态分辨率+文档批量处理，直接落地）

实战1：动态分辨率配置（Gundam Mode，细节无损，适配长图/小字号）

核心优势：自动根据图片长宽比，动态切片（滑窗切片），全局+局部融合，避免小字号模糊，无需手动调整分辨率

# 1. 进入模型配置目录（vLLM/Transformers部署通用） cd DeepSeek-OCR2/DeepSeek-OCR2-vllm/model # 2. 修改model_config.json，配置动态分辨率（复制完整配置替换原有内容） cat > model_config.json << EOF { "dynamic_resolution": true, "max_resolution": [4000, 4000], # 最大分辨率，按需调整 "min_resolution": [336, 336], # 最小分辨率，固定 "slice_size": [336, 336], # 切片尺寸，固定（Gundam Mode核心） "global_local_fusion": true # 全局+局部融合，开启 } EOF # 3. 重启服务生效（以vLLM可视化为例） python deepseek_ocr2_gradio.py --model-path ./model --port 8080 # 验证：上传4K长图/小字号图片，识别结果无模糊、无遗漏即配置成功

实战2：文档批量处理（图片+PDF，自动识别+导出，高效办公）

场景1：多图片批量处理（支持jpg/png/jpeg，批量导出）

# 创建批量处理脚本 batch_image_ocr.py，复制完整代码 import os from transformers import AutoModelForCausalLM, AutoProcessor import torch from PIL import Image # 加载模型（替换为自己的模型路径） model_path = "./model/DeepSeek-OCR-2" model = AutoModelForCausalLM.from_pretrained( model_path, torch_dtype=torch.float16, device_map="auto", trust_remote_code=True ) processor = AutoProcessor.from_pretrained(model_path, trust_remote_code=True) # 配置批量路径（必改：替换为自己的图片目录和输出目录） image_dir = "./batch-images" # 批量图片存放目录 output_dir = "./batch-ocr-results" # 识别结果输出目录 os.makedirs(output_dir, exist_ok=True) # 批量识别 for img_name in os.listdir(image_dir): if img_name.endswith((".jpg", ".png", ".jpeg")): img_path = os.path.join(image_dir, img_name) image = Image.open(img_path).convert("RGB") inputs = processor(images=[image], return_tensors="pt").to("cuda", torch.float16) outputs = model.generate(**inputs, max_new_tokens=4096) result = processor.decode(outputs[0], skip_special_tokens=True) # 保存结果（每个图片对应一个txt文件） output_path = os.path.join(output_dir, f"{os.path.splitext(img_name)[0]}.txt") with open(output_path, "w", encoding="utf-8") as f: f.write(result) print(f"【处理完成】{img_name} → 保存至 {output_path}") print("所有图片批量处理完成！")

# 执行批量处理 python batch_image_ocr.py

场景2：多PDF批量处理（自动拆分页面，合并结果，支持表格识别）

# vLLM接口批量处理（推荐，速度快） python run_dpsk_ocr2_pdf.py \ --model-path ./model \ --pdf-input ./batch-pdfs \ # PDF批量存放目录 --output ./batch-pdf-results \ # 输出目录 --merge-result True \ # 合并多页PDF结果（单文件） --table-recognition True # 开启表格识别（保留表格结构） # 验证：输出目录生成每个PDF对应的Markdown文件，表格结构完整即成功

实战3：双接口灵活切换（按需选择，无需重新部署）

# 1. 从vLLM接口切换到Transformers接口 # 关闭vLLM服务，直接运行Transformers脚本即可（虚拟环境不变） python transformers_infer.py # 2. 从Transformers接口切换到vLLM接口 # 关闭当前脚本，运行vLLM脚本 python run_dpsk_ocr2_image.py --model-path ./model --image-input ./test.jpg # 核心：双接口共享模型和虚拟环境，无需重复安装依赖/下载模型

四、常见问题排查（高频报错）

1. 报错1：CUDA error: no kernel image is available for execution on the device（CUDA版本不匹配） # 解决方案：卸载当前torch，重新安装适配CUDA 11.8的版本 ``pip uninstall torch torchvision torchaudio -y ``pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu118

2. 报错2：安装flash-attn失败（编译报错） # 解决方案：更换国内镜像源，重新安装 ``pip install flash-attn==2.7.3 --no-build-isolation -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 报错3：模型下载失败/缓慢（Hugging Face连接超时） # 解决方案：使用国内代理，重新下载 ``huggingface-cli download deepseek-ai/DeepSeek-OCR-2 \ `` --local-dir ./model \ `` --local-dir-use-symlinks False \ `` --proxy http://你的代理地址:端口

4. 报错4：显存溢出（out of memory） # 解决方案：1. 启用动态分辨率，降低max_resolution；2. 减少批量处理数量；3. 启用量化 ``# 修改model_config.json，降低最大分辨率 ``"max_resolution": [2000, 2000]

5. 报错5：端口8080被占用（Gradio启动失败） # Ubuntu/WSL2 ``sudo lsof -i:8080 | grep -v PID | awk '{print $2}' | xargs sudo kill -9 ``# Windows（管理员PowerShell） ``netstat -ano | findstr 8080 ``taskkill /f /pid 对应PID

6. 报错6：识别结果顺序混乱、表格错位（语义识别异常） # 解决方案：开启视觉因果流语义重排，修改model_config.json ``"visual_causal_flow": true ``# 重启服务生效

五、进阶优化（可选，提升性能，干货补充）

1. 推理速度优化（提升30%-50%，复制即用） # vLLM接口启用量化+并发处理 ``python run_dpsk_ocr2_pdf.py \ `` --model-path ./model \ `` --pdf-input ./batch-pdfs \ `` --output ./batch-pdf-results \ `` --quantize w8a8 \ # 启用8位量化，节省显存 `` --max-concurrent 10 # 最大并发数，按需调整 `` ``# Transformers接口启用加速 ``model = AutoModelForCausalLM.from_pretrained( `` model_path, `` torch_dtype=torch.float16, `` device_map="auto", `` trust_remote_code=True, `` load_in_8bit=True # 8位量化 ``)

2. 开机自启配置（服务不中断，Ubuntu/WSL2） # 1. 创建启动脚本 start_ocr.sh ``cat > start_ocr.sh << EOF ``#!/bin/bash ``source /root/deepseek-ocr2/bin/activate # 替换为自己的虚拟环境激活路径 ``cd /root/DeepSeek-OCR2/DeepSeek-OCR2-vllm # 替换为自己的部署路径 ``python deepseek_ocr2_gradio.py --model-path ./model --port 8080 ``EOF `` ``# 2. 赋予执行权限 ``chmod +x start_ocr.sh `` ``# 3. 设置开机自启 ``echo "/root/start_ocr.sh" >> /etc/rc.local ``chmod +x /etc/rc.local

3. 数据备份（防止模型/配置/结果丢失） # 备份模型+配置 ``cp -r ./model /本地备份路径 ``cp -r ./model_config.json /本地备份路径 `` ``# 备份批量处理结果 ``cp -r ./batch-ocr-results /本地备份路径

4. 多格式导出（Markdown/Word/Excel，适配办公需求） # 批量导出为Markdown（保留表格结构） ``python run_dpsk_ocr2_pdf.py \ `` --model-path ./model \ `` --pdf-input ./test.pdf \ `` --output ./ocr-result \ `` --export-format markdown `` ``# 批量导出为Word（需安装python-docx） ``pip install python-docx ``python run_dpsk_ocr2_pdf.py \ `` --model-path ./model \ `` --pdf-input ./test.pdf \ `` --output ./ocr-result \ `` --export-format word

六、核心补充

• 核心优势：DeepSeek-OCR2采用视觉因果流技术，语义驱动识别，动态分辨率（Gundam Mode）解决小字号/长图模糊问题，双接口适配不同场景，开源无调用限制，识别准确率达91.09%[SOTA]。

• 模型版本：默认下载FP16版本（约6GB），显存不足可选择INT8量化版（约3GB），下载时添加--revision int8参数。

• 适配场景：图片OCR、PDF批量识别、表格识别、公式识别、长图/扫描件识别，可用于办公自动化、文档数字化。

• 官方链接：模型仓库（Hugging Face）：https://huggingface.co/deepseek-ai/DeepSeek-OCR-2；源码仓库：https://github.com/deepseek-ai/DeepSeek-OCR2。

• 后续更新：将支持PDF批注识别、手写体混合识别，无需重新部署，直接拉取最新源码即可升级。