> 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 日发布的全新 3B 参数 SOTA 视觉与文档理解模型。该模型专注于图像转文本，具备更强的视觉推理能力，而不仅仅是文本提取。

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

不同于传统视觉 LLM 以固定网格扫描图像（左上 → 右下），DeepEncoder V2 会先建立全局理解，再学习类似人类的阅读顺序：先关注什么、接着关注什么，依此类推。这通过更好地遵循列布局、将标签与数值关联、连贯地读取表格以及处理混合文本 + 结构，从而提升复杂版式下的 OCR 表现。

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

<a href="/docs/zh/mo-xing/tutorials/deepseek-ocr-2.md#running-deepseek-ocr-2" class="button primary">运行 DeepSeek-OCR 2</a><a href="/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="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

**提示示例：**

```
# 文档：<image>\n<|grounding|>将该文档转换为 markdown。
# 其他图像：<image>\n<|grounding|>对这张图像进行 OCR。
# 无布局：<image>\n自由 OCR。
# 文档中的图表：<image>\n解析该图表。
# 通用：<image>\n详细描述这张图像。
# 识别：<image>\n在图像中定位 <|ref|>xxxx<|/ref|>。
```

<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>使用 Visual Causal Flow 将任何文档转换为 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, # 使用 4bit 以减少内存占用。False 表示 16bit LoRA。
    auto_model = AutoModel,
    trust_remote_code = True,
    unsloth_force_compile = True,
    use_gradient_checkpointing = "unsloth", # 长上下文时可设为 True 或 "unsloth"
)

prompt = "<image>\n自由 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 上使用 Huggingface 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>\n自由 OCR。 "
prompt = "<image>\n<|grounding|>将文档转换为 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 倍，而不会降低准确率。\n\n你现在可以通过我们免费的 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𝑚𝑎𝑥 表示该基准中每页使用的最大视觉 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%2F7CjBxsi10P3kqyF3utpq%2FScreenshot%202026-01-27%20at%201.14.02%E2%80%AFAM.png?alt=media&amp;token=08fc9963-15d1-4d7a-9fb5-93749913928c" alt="" width="375"><figcaption></figcaption></figure>

**表 2：** OmniDocBench v1.5 中不同类别文档元素的编辑距离。V-token𝑚𝑎𝑥 表示最低的最大视觉 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.