DeepSeek-OCR 作为一款先进的光学字符识别工具，能够高效准确地将图片和 PDF 文档转换为结构化的文本与 Markdown 格式。本文将提供一份详尽的从零开始指南，涵盖环境搭建、模型配置及使用技巧，帮助您快速上手。
开源项目地址：https://github.com/deepseek-ai/DeepSeek-OCR/tree/main
第一步：环境准备
系统要求
- 操作系统：支持 Linux、Windows 或 macOS
- Python 版本：推荐使用 3.12.9
- CUDA 版本：需 11.8 或更高版本（GPU运行必需）
- PyTorch 版本：建议 2.6.0
硬件要求
- 推荐 GPU：A100-40G 或性能相近的显卡
- 内存：建议不少于 16GB RAM
- 存储空间：至少预留 10GB 可用空间用于模型和依赖
第二步：下载和克隆项目
克隆 GitHub 仓库
git clone https://github.com/deepseek-ai/DeepSeek-OCR.git
cd DeepSeek-OCR查看项目结构
克隆后，项目主要包含以下目录与文件：
DeepSeek-OCR-master/– 核心源代码目录assets/– 示例图片等资源文件requirements.txt– Python 依赖包清单README.md– 项目详细说明文档
第三步：环境配置
创建 Conda 环境
conda create -n deepseek-ocr python=3.12.9 -y
conda activate deepseek-ocr安装 PyTorch
pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu118安装 vLLM（推荐）
# 下载并安装vLLM-0.8.5 whl文件
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第四步：模型下载和配置
自动下载模型
首次运行 DeepSeek-OCR 时，程序会自动从 Hugging Face 仓库下载所需模型文件：
model_name = 'deepseek-ai/DeepSeek-OCR'配置文件设置
根据您的需求，编辑配置文件 DeepSeek-OCR-master/DeepSeek-OCR-vllm/config.py，主要调整以下参数：
- 输入路径（
INPUT_PATH）：指定待处理文件的位置 - 输出路径（
OUTPUT_PATH）：指定结果文件的保存目录 - 其他相关参数：如批次大小、分辨率等，可按实际需求调整
第五步：使用方法详解
使用 vLLM 进行推理（推荐）
方法一：处理单张图像
cd DeepSeek-OCR-master/DeepSeek-OCR-vllm
python run_dpsk_ocr_image.py方法二：处理 PDF 文档
python run_dpsk_ocr_pdf.py注：使用 A100-40G GPU 处理 PDF 时，推理速度可达到约 2500 tokens/s。
方法三：批量评估
python run_dpsk_ocr_eval_batch.py使用 Transformers 进行推理
创建 Python 脚本
from transformers import AutoModel, AutoTokenizer
import torch
import os
# 设置GPU
os.environ["CUDA_VISIBLE_DEVICES"] = '0'
# 加载模型和分词器
model_name = 'deepseek-ai/DeepSeek-OCR'
tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
model = AutoModel.from_pretrained(model_name,
_attn_implementation='flash_attention_2',
trust_remote_code=True,
use_safetensors=True)
# 设置模型参数
model = model.eval().cuda().to(torch.bfloat16)
# 定义提示词和图像路径
prompt = "<|grounding|>Convert the document to markdown."
image_file = 'your_image.jpg'
output_path = 'your/output/dir'
# 执行推理
res = model.infer(tokenizer,
prompt=prompt,
image_file=image_file,
output_path=output_path,
base_size=1024,
image_size=640,
crop_mode=True,
sa ve_results=True,
test_compress=True) 或使用现成脚本
cd DeepSeek-OCR-master/DeepSeek-OCR-hf
python run_dpsk_ocr.py第六步：支持的模式和配置
原生分辨率模式
- Tiny: 512×512（消耗 64 个视觉 tokens）
- Small: 640×640（消耗 100 个视觉 tokens）
- Base: 1024×1024（消耗 256 个视觉 tokens）
- Large: 1280×1280（消耗 400 个视觉 tokens）
动态分辨率模式
- Gundam: n×640×640 + 1×1024×1024（混合分辨率处理）
第七步：提示词模板
为提高效率，以下是针对不同 OCR 场景的常用提示词模板：
# 文档转换（保留格式）
prompt = "\n<|grounding|>Convert the document to markdown."
# 通用图片文字识别
prompt = "\n<|grounding|>OCR this image."
# 无格式纯文本提取
prompt = "\nFree OCR."
# 图表数据解析
prompt = "\nParse the figure."
# 图像内容详细描述
prompt = "\nDescribe this image in detail."
# 特定文本定位
prompt = "\nLocate <|ref|>目标文字<|/ref|> in the image." 第八步：常见问题解决
安装问题
安装 vLLM 时若出现 transformers 版本警告：
vllm 0.8.5+cu118 requires transformers>=4.51.1此警告通常不影响核心功能，可暂时忽略，或尝试升级 transformers 包。
内存不足
- 在配置文件中降低
batch_size参数。 - 选择 Tiny 或 Small 等较小的分辨率模式。
- 清理系统内存，关闭非必要的应用程序。
GPU 显存不足
- 考虑使用量化版本的模型以减少显存占用。
- 减少同时处理的文件数量（并发数）。
- 适当调小输入图像的尺寸。
第九步：性能优化建议
硬件优化
- 使用高性能 GPU，如 NVIDIA A100、H100。
- 确保 GPU 显存容量满足模型运行需求。
- 采用固态硬盘（SSD）以加速文件读写。
软件优化
- 优先使用 vLLM 推理后端，相较于 Transformers 通常有更好的吞吐性能。
- 确保启用 Flash Attention 2 以加速注意力计算。
- 根据任务复杂度（如文档版式复杂性）选择最合适的分辨率模式，平衡速度与精度。
总结
遵循本教程，您将能够：
- 成功完成 DeepSeek-OCR 的完整环境部署与配置。
- 掌握使用 vLLM 或 Transformers 进行图像与 PDF 文字识别的基本操作。
- 理解不同分辨率模式的应用场景与选择依据。
- 具备诊断和解决安装、内存、显存等常见问题的能力。
- 了解通过硬件选型和软件设置进一步提升识别效率的优化方向。
如果在实践过程中遇到其他未涵盖的问题，建议查阅项目 GitHub 仓库的 Issues 讨论区或官方技术文档，通常能找到相应的解决方案。
