目标：在本地 GPU 服务器上运行 DeepSeek-OCR，支持图像/PDF 输入，输出结构化 Markdown 或纯文本。
一、环境要求
表格
| 组件 | 要求 |
|---|---|
| OS | Linux（推荐 Ubuntu 22.04+） |
| GPU | NVIDIA A100/A10/L4 等（≥24GB 显存，A100-40G 可跑 PDF 模式） |
| CUDA | ≥11.8 |
| Python | 3.12.9（官方指定） |
| PyTorch | 2.6.0 + cu118 |
| vLLM | 0.8.5（官方提供 wheel） |
| Disk | ≥20GB（模型约 15GB） |
⚠️ 注意：不支持 CPU 推理，必须使用 GPU。
二、环境配置（Conda + 官方依赖）
bash
编辑
1# 1. 克隆仓库
2git clone https://github.com/deepseek-ai/DeepSeek-OCR.git
3cd DeepSeek-OCR
4
5# 2. 创建 Conda 环境（Python 3.12.9）
6conda create -n deepseek-ocr python=3.12.9 -y
7conda activate deepseek-ocr
8
9# 3. 安装 PyTorch（CUDA 11.8）
10pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 \
11 --index-url https://download.pytorch.org/whl/cu118
12
13# 4. 下载并安装 vLLM 0.8.5（官方提供 wheel）
14# 从 https://github.com/vllm-project/vllm/releases/tag/v0.8.5 下载对应 wheel
15wget https://github.com/vllm-project/vllm/releases/download/v0.8.5/vllm-0.8.5+cu118-cp312-abi3-manylinux1_x86_64.whl
16pip install vllm-0.8.5+cu118-cp312-abi3-manylinux1_x86_64.whl
17
18# 5. 安装其他依赖
19pip install -r requirements.txt
20pip install flash-attn==2.7.3 --no-build-isolation✅
requirements.txt包含 transformers、Pillow、pdf2image 等。
三、模型下载
模型托管于 Hugging Face：
🔗 模型地址：https://huggingface.co/deepseek-ai/DeepSeek-OCR
自动下载（通过代码）
首次运行推理脚本时会自动从 HF 下载（需登录）：
bash
编辑
1huggingface-cli login # 输入你的 HF Token（需同意协议）手动下载（可选）
bash
编辑
1git lfs install
2git clone https://huggingface.co/deepseek-ai/DeepSeek-OCR ./models/DeepSeek-OCR然后在代码中指定 model_name="./models/DeepSeek-OCR"。
四、推理方式选择
DeepSeek-OCR 提供两种后端：
表格
| 方式 | 优点 | 适用场景 |
|---|---|---|
| vLLM | 高吞吐（PDF 达 2500 tokens/s） | 批量处理、生产部署 |
| Transformers | 调试友好、支持 infer() 接口 | 单图测试、结果可视化 |
五、调用示例
方式 1：使用 Transformers（单图测试）
python
编辑
1from transformers import AutoModel, AutoTokenizer
2import torch
3
4model_name = "deepseek-ai/DeepSeek-OCR"
5tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
6model = AutoModel.from_pretrained(
7 model_name,
8 _attn_implementation="flash_attention_2",
9 trust_remote_code=True,
10 use_safetensors=True,
11 torch_dtype=torch.bfloat16
12).eval().cuda()
13
14# 推理
15result = model.infer(
16 tokenizer=tokenizer,
17 prompt="<image>\n<|grounding|>Convert the document to markdown.",
18 image_file="your_doc.jpg",
19 output_path="./output",
20 base_size=1024,
21 image_size=640,
22 crop_mode=True,
23 save_results=True,
24 test_compress=True
25)
26
27print("OCR Result:\n", result["text"])方式 2：使用 vLLM（高并发）
编辑 DeepSeek-OCR-vllm/config.py 设置路径，然后运行：
bash
编辑
1cd DeepSeek-OCR-vllm
2python run_dpsk_ocr_image.py # 处理单图
3python run_dpsk_ocr_pdf.py # 处理 PDF（A100-40G 支持）或直接 API 调用（参考官方 vLLM 示例）：
python
编辑
1from vllm import LLM, SamplingParams
2from vllm.model_executor.models.deepseek_ocr import NGramPerReqLogitsProcessor
3from PIL import Image
4
5llm = LLM(
6 model="deepseek-ai/DeepSeek-OCR",
7 enable_prefix_caching=False,
8 mm_processor_cache_gb=0,
9 logits_processors=[NGramPerReqLogitsProcessor]
10)
11
12image = Image.open("invoice.png").convert("RGB")
13prompt = "<image>\n<|grounding|>Convert the document to markdown."
14
15sampling_params = SamplingParams(
16 temperature=0.0,
17 max_tokens=8192,
18 extra_args=dict(
19 ngram_size=30,
20 window_size=90,
21 whitelist_token_ids={128821, 128822} # <td>, </td>
22 ),
23 skip_special_tokens=False
24)
25
26outputs = llm.generate(
27 {"prompt": prompt, "multi_modal_data": {"image": image}},
28 sampling_params
29)
30
31print(outputs[0].outputs[0].text)六、提示词（Prompt）模板
DeepSeek-OCR 使用特殊 token 控制行为：
表格
| 任务 | Prompt |
|---|---|
| 通用 OCR（无布局） | <image>\nFree OCR. |
| 文档转 Markdown | `\n< |
| 表格解析 | <image>\nParse the table in markdown format. |
| 图表理解 | <image>\nParse the figure. |
| 全文描述 | <image>\nDescribe this image in detail. |
| 关键词定位 | `\nLocate < |
✅
<|grounding|>是关键 token，启用 layout-aware 模式。
七、输出示例
输入一张发票图片，输出 Markdown：
markdown
编辑
1# 增值税专用发票
2
3| 项目 | 内容 |
4|--------------|--------------------------|
5| 发票代码 | 144032400110 |
6| 发票号码 | 89237465 |
7| 开票日期 | 2024年05月01日 |
8| 销售方名称 | 深圳市科技有限公司 |
9| 金额（不含税）| ¥1,280.00 |
10
11> 备注：此发票仅用于内部报销。八、Docker 化部署（可选）
虽然官方未提供 Dockerfile，但可自行构建：
dockerfile
编辑
1# Dockerfile
2FROM nvidia/cuda:11.8-devel-ubuntu22.04
3
4ENV DEBIAN_FRONTEND=noninteractive
5RUN apt update && apt install -y python3.12 python3-pip git wget
6
7WORKDIR /app
8COPY . /app
9
10RUN pip install torch==2.6.0+cu118 torchvision==0.21.0+cu118 torchaudio==2.6.0 --extra-index-url https://download.pytorch.org/whl/cu118
11RUN pip install vllm-0.8.5+cu118-cp312-abi3-manylinux1_x86_64.whl
12RUN pip install -r requirements.txt
13RUN pip install flash-attn==2.7.3 --no-build-isolation
14
15EXPOSE 8000
16CMD ["python", "DeepSeek-OCR-vllm/run_dpsk_ocr_image.py"]构建 & 运行：
bash
编辑
1docker build -t deepseek-ocr .
2docker run --gpus all -v $(pwd)/input:/input -v $(pwd)/output:/output deepseek-ocr九、性能与限制
表格
| 模式 | 分辨率 | Vision Tokens | 显存占用 | 速度（A100-40G） |
|---|---|---|---|---|
| Tiny | 512×512 | 64 | ～12GB | 极快 |
| Base | 1024×1024 | 256 | ～20GB | 快 |
| Large | 1280×1280 | 400 | ～28GB | 中 |
| PDF（动态） | Gundam | n×640 + 1×1024 | ～35GB | ～2500 tok/s |
💡 建议：普通文档用
Base模式，表格/复杂布局用Large。
十、参考链接
- GitHub: https://github.com/deepseek-ai/DeepSeek-OCR
- Paper: DeepSeek-OCR: Contexts Optical Compression
- Model: https://huggingface.co/deepseek-ai/DeepSeek-OCR
- vLLM 集成: https://docs.vllm.ai/projects/recipes/en/latest/DeepSeek/DeepSeek-OCR.html
✅ 至此，你已掌握 DeepSeek-OCR 的完整部署链路。该模型在中文票据、学术 PDF、表格重建等场景表现优异，是当前开源 OCR 领域的 SOTA 方案之一。
