> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/zh/mo-xing/tutorials/deepseek-ocr-2.md).

# DeepSeek-OCR 2：如何运行与微调指南

关于如何在本地运行和微调 DeepSeek-OCR-2 的指南。

**DeepSeek-OCR 2** 是 DeepSeek 于 2026 年 1 月 27 日发布的、拥有 30 亿参数的全新模型，面向最先进的视觉与文档理解。该模型专注于图像转文本，并具备更强的视觉推理能力，而不仅仅是提取文本。

DeepSeek-OCR 2 引入了 DeepEncoder V2，使模型能够像人类一样，按照相同的逻辑顺序“查看”图像。

传统视觉大语言模型会按固定网格扫描图像（从左上到右下）；与之不同，DeepEncoder V2 会先建立整体理解，再学习类似人类的阅读顺序，确定先关注什么、接着关注什么，依此类推。这通过更好地遵循分栏布局、关联标签与数值、连贯地读取表格，以及处理文本与结构混合的内容，提升了复杂布局中的 OCR 效果。

现在，你可以通过 Unsloth 使用我们的 [**免费微调笔记本**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Deepseek_OCR_\(3B\).ipynb)**.** 我们展示了 [提升 88.6%](#fine-tuning-deepseek-ocr) 的语言理解能力。

<a href="https://unsloth.ai/docs/zh/mo-xing/tutorials/deepseek-ocr-2.md#running-deepseek-ocr-2" class="button primary">运行 DeepSeek-OCR 2</a><a href="https://unsloth.ai/docs/zh/mo-xing/tutorials/deepseek-ocr-2.md#fine-tuning-deepseek-ocr-2" class="button secondary">微调 DeepSeek-OCR 2</a>

## 🖥️ **运行 DeepSeek-OCR 2**

为了运行该模型，DeepSeek-OCR 2 与第一个模型一样，经过了修改，以支持在最新版 transformers 上进行推理和训练（准确率没有变化）。你可以在 [这里](https://huggingface.co/unsloth/DeepSeek-OCR-2).

要在 [transformers](#transformers-run-deepseek-ocr-2-tutorial) 或 [Unsloth](#unsloth-run-deepseek-ocr-tutorial)中运行该模型，建议使用以下设置：

### :gear: 推荐设置

DeepSeek 推荐使用以下设置：

* <mark style="color:默认值;background-color:blue;">**Temperature = 0.0**</mark>
* `max_tokens = 8192`
* `ngram_size = 30`
* `window_size = 90`

**支持的模式——动态分辨率：**

* 默认值：(0-6)×768×768 + 1×1024×1024 — (0-6)×144 + 256 个视觉 token

**提示词示例：**

```
# document: <image>\n<|grounding|>Convert the document to markdown.
# other image: <image>\n<|grounding|>OCR this image.
# without layouts: <image>\nFree OCR.
# figures in document: <image>\nParse the figure.
# general: <image>\nDescribe this image in detail.
# rec: <image>\nLocate <|ref|>xxxx<|/ref|> in the image.
```

<div align="center"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FGff3UBRgiu0aFXsbwll2%2Ffig1.png?alt=media&amp;token=58864777-114a-450a-ab56-3cabc9219cf7" alt="" width="375"><figcaption><p>使用视觉因果流将任意文档转换为 Markdown。</p></figcaption></figure></div>

### 🦥 Unsloth：运行 DeepSeek-OCR 2 教程

1. 获取最新版 `unsloth` 请运行 `pip install --upgrade unsloth` 。如果你已经安装了 Unsloth，请运行以下命令进行更新： `pip install --upgrade --force-reinstall --no-deps --no-cache-dir unsloth unsloth_zoo`
2. 然后使用以下代码运行 DeepSeek-OCR 2：

{% code overflow="wrap" %}

```python
from unsloth import FastVisionModel
import torch
from transformers import AutoModel
import os
os.environ["UNSLOTH_WARN_UNINITIALIZED"] = '0'

from huggingface_hub import snapshot_download
snapshot_download("unsloth/DeepSeek-OCR-2", local_dir = "deepseek_ocr")
model, tokenizer = FastVisionModel.from_pretrained(
    "./deepseek_ocr",
    load_in_4bit = False, # Use 4bit to reduce memory use. False for 16bit LoRA.
    auto_model = AutoModel,
    trust_remote_code = True,
    unsloth_force_compile = True,
    use_gradient_checkpointing = "unsloth", # True or "unsloth" for long context
)

prompt = "<image>\nFree OCR. "
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, save_results = True, test_compress = False)
```

{% endcode %}

### 🤗 Transformers：运行 DeepSeek-OCR 2 教程

在 NVIDIA GPU 上使用 Hugging Face Transformers 进行推理。已测试的环境要求：Python 3.12.9 + CUDA11.8：

```bash
torch==2.6.0
transformers==4.46.3
tokenizers==0.20.3
einops
addict 
easydict
pip install flash-attn==2.7.3 --no-build-isolation
```

```python
from transformers import AutoModel, AutoTokenizer
import torch
import os
os.environ["CUDA_VISIBLE_DEVICES"] = '0'
model_name = 'unsloth/DeepSeek-OCR-2'

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 = "<image>\nFree OCR. "
prompt = "<image>\n<|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 = 768, crop_mode=True, save_results = True)
```

## 🦥 **微调 DeepSeek-OCR 2**

Unsloth 现已支持对 DeepSeek-OCR 2 进行微调。与第一代模型一样，你需要使用我们的 [自定义上传](https://huggingface.co/unsloth/DeepSeek-OCR-2) 才能让它在 `transformers` 上运行（精度没有变化）。与第一代模型一样，Unsloth 训练 DeepSeek-OCR-2 的速度快 1.4 倍、显存占用减少 40%，上下文长度延长 5 倍，且精度没有下降。\
\
现在，你可以通过我们的免费 Colab 笔记本微调 DeepSeek-OCR 2。

* DeepSeek-OCR 2： [仅用于微调的笔记本](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Deepseek_OCR_2_\(3B\).ipynb)

下方展示了波斯语的 CER（字符错误率）精度提升：

#### 逐样本 CER（10 个样本）

| 索引   | OCR1 微调前 | OCR1 微调后 | OCR2 微调前 | OCR2 微调后 |
| ---- | -------: | -------: | -------: | -------: |
| 1520 |   1.0000 |   0.8000 |  10.4000 |   1.0000 |
| 1521 |   0.0000 |   0.0000 |   2.6809 |   0.0213 |
| 1522 |   2.0833 |   0.5833 |   4.4167 |   1.0000 |
| 1523 |   0.2258 |   0.0645 |   0.8710 |   0.0968 |
| 1524 |   0.0882 |   0.1176 |   2.7647 |   0.0882 |
| 1525 |   0.1111 |   0.1111 |   0.9444 |   0.2222 |
| 1526 |   2.8571 |   0.8571 |   4.2857 |   0.7143 |
| 1527 |   3.5000 |   1.5000 |  13.2500 |   1.0000 |
| 1528 |   2.7500 |   1.5000 |   1.0000 |   1.0000 |
| 1529 |   2.2500 |   0.8750 |   1.2500 |   0.8750 |

#### 平均 CER（10 个样本）

* **OCR1：** 之前 **1.4866**，之后 **0.6409** (**-57%**)
* **OCR2：** 之前 **4.1863**，之后 **0.6018** (**-86%**)

## 📊 基准测试

DeepSeek-OCR 2 模型的基准测试数据取自官方研究论文。

**表 1：** OmniDocBench v1.5 文档阅读综合评测。V-token𝑚𝑎𝑥\
表示此基准测试中每页使用的最大视觉令牌数。R-order\
表示阅读顺序。除 DeepSeek OCR 和 DeepSeek OCR 2 外，本表中其他模型的结果\
均取自 OmniDocBench 仓库。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FhxyKqi0rT9Jm4Y9PFqBY%2FScreenshot%202026-01-27%20at%201.14.02%E2%80%AFAM.optimized.png?alt=media" alt="" width="375"><figcaption></figcaption></figure>

**表 2：** OmniDocBench v1.5 中不同文档元素类别的编辑距离。\
V-token𝑚𝑎𝑥 表示最低的最大视觉令牌数。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FcTVu52ugTwQAqLdnQLLz%2FScreenshot%202026-01-27%20at%201.14.15%E2%80%AFAM.png?alt=media&amp;token=ec92a4a1-facb-4b63-90cd-73d23a41dcfb" alt="" width="563"><figcaption><p>在 OmniDocBench 上优于 Gemini-3 Pro</p></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://unsloth.ai/docs/zh/mo-xing/tutorials/deepseek-ocr-2.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
