DeepSeek-OCR 本地运行：阅读其 PDF 已扫描

#为什么选择 DeepSeek-OCR 而不是传统 OCR

扫描版 PDF 不包含文本，只有文本图像。像 Tesseract 这样的传统 OCR 引擎只能从中提取原始行文本：它不知道某个区块是标题，会破坏表格，也会弄乱双栏页面的阅读顺序。DeepSeek-OCR 采用了不同的处理方式。它是一种视觉语言模型：先查看整页内容，然后直接生成带有标题、列表、表格和公式的 Markdown。

该模型由 DeepSeek 于 2025 年秋季发布，并附有一篇题为《Contexts Optical Compression》的文章。其核心思路是根据分辨率模式，用 64 到 400 个视觉令牌表示一个页面，而不是使用页面本身包含的数千个文本令牌。发布方称，当压缩比保持在十以下时，解码准确率约为 97%。这是发布方在自有数据集上测得的数据，不是我们的测量结果：最重要的是，该模型就其用途而言轻量且快速。

对于本地使用，有三点很重要。模型能够装入入门级显卡。它输出的 Markdown 可以原样编入 RAG 流程。并且它在 Ollama 的库中可用，因此无需像官方仓库要求的那样安装 PyTorch、Flash Attention 和 vLLM。完整规格请见模型规格页：https://quelllm.fr/modele/deepseek-ocr

#前置条件与所需内存

该网站的模型卡片按精度给出了 VRAM 参考值：在 8 192 个 token 的上下文下，Q4 约需 2 GB，Q8 约需 4 GB，FP16 约需 6 GB。实际需要下载的权重取决于 Ollama 在标签中打包了什么；库的标签页面会显示文件大小，应以该页面为准。此外还要加上上下文内存：一页密集内容转换成 Markdown 后，可能产生数千个输出 token。

NVIDIA GPU

任何 8 GB 或更大的显卡都能轻松应对。一张 RTX 3060 12 GB 或一张 RTX 4070 12 GB 显卡可以在 FP16 下运行该模型，并为上下文保留余量。

搭载 Apple Silicon 的 Mac

Ollama使用统一内存。单独运行该模型时，16 GB 的 Mac 就够了；如果还想在旁边加载一个聊天模型用于 RAG，则需要 24 GB。

无 GPU

可以，但图像编码和 Markdown 生成是在处理器上完成的。处理几页时尚可接受；处理一批一百页的文档时，根据机器性能，预计每页需要数分钟。

软件

最新的 Ollama、用于拆分 PDF 的 poppler-utils，以及用于批量自动处理的 Python 3 和 ollama 库。

#第 1 步：检查 Ollama 并获取正确的标签

DeepSeek-OCR 于 2025 年底进入 Ollama 库，此时模型已经发布。它采用一种特殊的视觉编码器 DeepEncoder，将局部窗口模块与全局注意力模块结合起来。Ollama 必须在其引擎中加入对这一架构的支持：较早的运行时会下载权重，却拒绝加载它们，并显示模型需要更新版本的消息。库页面会在适用时显示所需的最低版本。

# Version installée (comparez avec la version minimale affichée sur ollama.com/library/deepseek-ocr)
ollama -v

# Récupérer le modèle (le tag 3b est celui référencé par la fiche modèle)
ollama pull deepseek-ocr:3b

# Vérifier l'architecture, le contexte et la quantification empaquetée
ollama show deepseek-ocr:3b

show 命令是确认您刚刚下载内容的唯一可靠来源：它会显示模型系列、参数数量、上下文长度和量化级别。如果 latest 标签和 3b 标签指向同一个摘要，那么使用哪个都无所谓；本指南使用 3b 以保持明确。

#步骤 2：准备 PDF 页面

Ollama 不打开 PDF。它接受图像格式的 PNG 或 JPEG，每次请求一张。因此，第一步是逐页将文档栅格化。最简单的工具是 pdftoppm，它随 poppler-utils 提供，可在所有 Linux 发行版上使用，也可通过 macOS 上的 Homebrew 获取。

# Debian/Ubuntu : sudo apt install poppler-utils
# macOS : brew install poppler
# Arch : sudo pacman -S poppler

mkdir -p pages
pdftoppm -r 200 -png scan.pdf pages/page
ls pages
# pages/page-1.png  pages/page-2.png  ...  (numérotation complétée par des zéros selon le nombre de pages)

分辨率值得花一分钟考虑。DeepSeek-OCR 使用固定分辨率：根据模式不同，边长为 512、640、1024 或 1280 像素；此外还有一种称为 Gundam 的动态模式，会围绕 1024 的全局视图，将页面切分为 640 像素的图块。以每英寸 200 点栅格化的 A4 页面约为 1 650 × 2 340 像素；Ollama 会在将其发送给编码器前调整大小。提高到每英寸 300 点对模型没有帮助，只会让文件无谓变大。降到 100 点则会在模型看到脚注之前，就丢失其中的小字。

如果扫描件倾斜或对比度很高，模型通常比逐行 OCR 表现更好，但预先校正仍然有益。网站上的 Tesseract 指南详细介绍了有用的预处理，这里同样适用：https://quelllm.fr/guide/tesseract-ocr-guide-local

#步骤 3：使用 deepseek ocr 获取 Markdown

官方仓库记录了多条指令，每条都会触发模型的不同行为。其中两条主要指令是用于结构化转换的“Convert the document to markdown.”，以及用于不带格式的原始转录的“Free OCR.”。这些指令在训练时使用英语；请保持原样，识别出的文本会以文档的语言输出。使用命令行客户端时，将图像路径直接放入 prompt。

# Conversion structurée (titres, listes, tableaux)
ollama run deepseek-ocr:3b "Convert the document to markdown. ./pages/page-1.png"

# Transcription brute, sans structure
ollama run deepseek-ocr:3b "Free OCR. ./pages/page-1.png"

通过本地 API 执行相同操作时，API 默认监听 http://localhost:11434，并在 images 字段中以 base64 编码图像。只要您需要连续处理多个页面，或从另一个程序调用模型，就应优先采用这种方式。

# Linux (GNU coreutils). Sur macOS, remplacez base64 -w0 par base64 -i pages/page-1.png
curl http://localhost:11434/api/generate -d "{
  \"model\": \"deepseek-ocr:3b\",
  \"prompt\": \"Convert the document to markdown.\",
  \"images\": [\"$(base64 -w0 pages/page-1.png)\"],
  \"stream\": false,
  \"options\": { \"num_ctx\": 8192, \"temperature\": 0 }
}"

有两个选项值得固定下来。将温度设为零可以使输出具有可复现性，这正是 OCR 所需要的。8 192 个 token 的上下文对应模型上限；低于此值时，内容密集的页面可能在表格单元格中途被截断。官方仓库还提到用于描述图形或通过坐标定位文本的专门提示词；对于只需建立索引的简单 PDF，这些提示词用处不大。

#第 4 步：处理完整 PDF

对于一份包含几十页的文档，只需几行 Python 脚本即可。脚本按数字顺序遍历图像，逐页调用 Ollama，删除模型可能插入的定位标签，并将全部内容拼接到一个 Markdown 文件中，每页使用一个标记。之后，您可以利用该标记在 RAG 引用某段内容时找到其源页面。

pip install ollama

import pathlib
import re
import ollama

MODEL = "deepseek-ocr:3b"
PROMPT = "Convert the document to markdown."

# Tri numérique : page-2 avant page-10
pages = sorted(
    pathlib.Path("pages").glob("page-*.png"),
    key=lambda p: int(re.search(r"(\d+)", p.stem).group(1)),
)

parts = []
for page in pages:
    r = ollama.generate(
        model=MODEL,
        prompt=PROMPT,
        images=[str(page)],
        options={"num_ctx": 8192, "temperature": 0},
    )
    md = r["response"]
    # Balises de localisation éventuelles : on garde le texte, on jette les coordonnées
    md = re.sub(r"<\|ref\|>(.*?)<\|/ref\|><\|det\|>.*?<\|/det\|>", r"\1", md, flags=re.S)
    parts.append(f"<!-- {page.name} -->\n{md.strip()}\n")
    print(f"{page.name} : {len(md)} caractères")

pathlib.Path("scan.md").write_text("\n\n".join(parts), encoding="utf-8")

每次调用彼此独立：模型不会保留上一页的任何记忆。对于跨越两页的表格，这是一个限制；但它也有利于稳健性，因为一页失败不会污染另一页。Ollama 会加载一次模型，并根据 OLLAMA_KEEP_ALIVE 变量的值在各次调用之间将其保留在内存中；批处理开始时才需要支付加载时间。

如果你的显卡还有余量，OLLAMA_NUM_PARALLEL 选项可以同时处理多个页面，但每个上下文都需要额外的 VRAM。在 12 GB 显卡上，使用这种大小的模型时并行处理两个请求仍然比较合理；请通过 nvidia-smi 确认不会溢出到系统内存中，因为一旦发生，速度会骤然下降。

#步骤 5：清理并检查输出

生成的 Markdown 适合阅读，但未必适合直接建立索引。在将其发送到向量数据库之前，请检查三点。

1. 01
   残留标记

   在转换指令下，模型会使用一个定位标记进行训练，并可能返回位于 ref 和 det 标签之间的坐标。上面的脚本会将其删除。还要检查文件开头是否也没有残留 image 标签或指令片段。
2. 02
   数字和表格

   视觉语言模型会生成文本，因此可能会在难以辨认的单元格中编造一个看似合理的值，而传统 OCR 可能只会留下异常字符。请将财务或技术表格与扫描件并排打开，每十行抽查一行。对于发票，网站的专门指南说明了如何与合计数交叉核对：https://quelllm.fr/guide/extraction-factures-ocr-llm
3. 03
   页眉和页脚

   页码、文档名称、重复出现的法律声明：它们会出现在每一页，干扰文本分段。通常，只需对出现在超过一半页面上的相同行使用正则表达式，就能将其移除。
4. 04
   法语重音符号和排版

   编辑器声称支持使用上百种语言进行训练。不过，仍应在样本中检查重音字母、法语引号以及双字符标点前的不换行空格：后续导致词汇搜索失真的隐蔽错误往往就藏在这里。

文件整理妥当后，就可以像任何 Markdown 一样进入 RAG 流水线：按标题切分、生成嵌入、写入向量数据库。该网站的本地 RAG 入门介绍了这些步骤：https://quelllm.fr/guide/rag-local-introduction

#限制与故障排除

模型不查看图像就作答

要么 Ollama 对这种架构来说太旧，要么图像没有传递过来。在命令行中，路径必须是绝对路径或相对于当前目录的路径，路径本身不能加引号。通过 API 时，请确认 images 字段确实包含没有换行的 base64。

输出在表格中间被截断

上下文太短，无法容纳整页。如果尚未设置，请将 num_ctx 调为 8192。如果页面仍然超出范围，请将其拆成上下两张图，并让两张图重叠几行。

页面阅读顺序错乱

在三栏布局或复选框表单中，模型可能会混淆各个区块。请尝试使用遵循空间顺序更简单的 Free OCR 提示词，或者改用 Docling，其布局分析更加明确。

异常缓慢

使用 ollama ps 检查模型是否确实加载在 GPU 上，而不是部分加载到处理器上。上下文过大或加载了第二个模型，都可能使其溢出到系统内存。

手写文本

DeepSeek-OCR是在印刷文档和页面渲染结果上训练的。对于手写内容，结果差异很大；未经预先测试不要依赖它。

长文档与跨页面上下文

每个页面都会被单独处理。跨到下一页的表格会丢失表头；必须手动重新注入表头，或使用后处理规则。

#PaddleOCR、Docling 或 Tesseract 足够应对的情况

DeepSeek-OCR 并不能处理所有扫描任务。当页面具有需要保留的结构，而你又想直接获得 Markdown、无需拼装处理流水线时，它表现出色。在许多常见情况下，更简单或更专门的工具同样能够胜任，同时资源消耗更少，产生虚构内容的风险也更低。

Tesseract

大量清晰、印刷在白色背景上的文本，而你只需要文本。它在处理器上运行，不生成任何内容，因此也不会凭空编造。指南：https://quelllm.fr/guide/tesseract-ocr-guide-local

PaddleOCR

页面上任意位置的文本、倾斜的扫描件，以及需要在读取前通过明确的检测步骤重建的表格。它的 VL 变体同样是视觉模型，但比 DeepSeek-OCR 更小。指南：https://quelllm.fr/guide/paddleocr-vl-ocr-local

Docling

原生 PDF、DOCX 和演示文稿：这些文档本身已经包含文本，主要需要提取其版式和表格。Docling 可以调用 OCR 引擎处理图像页面，但其核心是结构分析。指南：https://quelllm.fr/guide/docling-conversion-documents-ia

DeepSeek-OCR

带有标题、列表、表格或公式的页面扫描件或照片，以及在一张普通显卡上一次性获得可直接建立索引的 Markdown 的需求。

一个标准往往很关键：如果数字出错会造成后果，请优先选择只识别、不生成的工具，或者使用第二个引擎再次读取并比较输出。如果首要目标是让异构文档库变得易读且可查询，DeepSeek-OCR 的 Markdown 会在后续每一步节省时间。

#深入了解

DeepSeek-OCR 模型卡片

参数、不同精度下的 VRAM 占用、许可证和安装命令。https://quelllm.fr/modele/deepseek-ocr

安装 Ollama

Windows、macOS 和 Linux 上的安装、基本命令及故障排除。https://quelllm.fr/guide/installer-ollama

无需编码的本地 RAG

将得到的 Markdown 接入 Open WebUI 或 AnythingLLM，以便查询文档。https://quelllm.fr/guide/rag-local-ollama-sans-coder

官方来源

GitHub 仓库 deepseek-ai/DeepSeek-OCR（代码、说明和用于 PDF 的 vLLM 脚本），Hugging Face 页面 deepseek-ai/DeepSeek-OCR（权重和 MIT 许可证），以及 Ollama 页面 ollama.com/library/deepseek-ocr（标签、大小和最低版本）。