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

**DeepSeek-OCR** 是一个用于光学字符识别和文档理解的3B参数视觉模型。它使用 *上下文光学压缩* 将二维布局转换为视觉标记，从而实现高效的长上下文处理。

DeepSeek-OCR 能处理表格、论文和手写内容，在精度上达到97%，同时使用的视觉标记比文本标记少10× —— 使其比基于文本的LLM高效10倍。

您可以对 DeepSeek-OCR 进行微调以提升其视觉或语言性能。在我们的 Unsloth [**免费微调笔记本**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Deepseek_OCR_\(3B\).ipynb)中，我们展示了 [88.26% 的提升](#fine-tuning-deepseek-ocr) 用于语言理解。

<a href="#running-deepseek-ocr" class="button primary">运行 DeepSeek-OCR</a><a href="#fine-tuning-deepseek-ocr" class="button primary">微调 DeepSeek-OCR</a>

> **我们的模型上传，支持微调 + 更多推理支持：** [**DeepSeek-OCR**](https://huggingface.co/unsloth/DeepSeek-OCR)

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

要在以下环境中运行该模型 [vLLM](#vllm-run-deepseek-ocr-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`

### 📖 vLLM：运行 DeepSeek-OCR 教程

1. 通过以下方式获取最新的 `vLLM` 通过：

```bash
uv venv
source .venv/bin/activate
# 在 v0.11.1 发行版之前，您需要从 nightly 构建安装 vLLM
uv pip install -U vllm --pre --extra-index-url https://wheels.vllm.ai/nightly
```

2. 然后运行以下代码：

{% code overflow="wrap" %}

```python
from vllm import LLM, SamplingParams
from vllm.model_executor.models.deepseek_ocr import NGramPerReqLogitsProcessor
from PIL import Image

# 创建模型实例
llm = LLM(
    model="unsloth/DeepSeek-OCR",
    enable_prefix_caching=False,
    mm_processor_cache_gb=0,
    logits_processors=[NGramPerReqLogitsProcessor]
)

# 使用您的图像文件准备批量输入
image_1 = Image.open("path/to/your/image_1.png").convert("RGB")
image_2 = Image.open("path/to/your/image_2.png").convert("RGB")
prompt = "<image>\nFree OCR."

model_input = [
    {
        "prompt": prompt,
        "multi_modal_data": {"image": image_1}
    },
    {
        "prompt": prompt,
        "multi_modal_data": {"image": image_2}
    }
]

sampling_param = SamplingParams(
    temperature=0.0,
    max_tokens=8192,
    # ngram logits 处理器参数
    extra_args=dict(
        ngram_size=30,
        window_size=90,
        whitelist_token_ids={128821, 128822},  # 白名单: <td>, </td>
    ),
    skip_special_tokens=False,
)
# 生成输出
model_outputs = llm.generate(model_input, sampling_param)

# 打印输出
for output in model_outputs:
    print(output.outputs[0].text)
```

{% endcode %}

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

1. 通过以下方式获取最新的 `unsloth` 通过 `pip install --upgrade unsloth` . 如果您已经安装了 Unsloth，请通过以下方式更新它 `pip install --upgrade --force-reinstall --no-deps --no-cache-dir unsloth unsloth_zoo`
2. 然后使用下面的代码运行 DeepSeek-OCR：

{% 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", local_dir = "deepseek_ocr")
model, tokenizer = FastVisionModel.from_pretrained(
    "./deepseek_ocr",
    load_in_4bit = False, # 使用 4bit 可降低内存使用。16bit LoRA 请设为 False。
    auto_model = AutoModel,
    trust_remote_code = True,
    unsloth_force_compile = True,
    use_gradient_checkpointing = "unsloth", # 对于长上下文使用 True 或 "unsloth"
)

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 %}

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

Unsloth 支持对 DeepSeek-OCR 的微调。由于默认模型在最新的 `transformers` 版本上无法运行，我们采纳了 [Stranger Vision HF](https://huggingface.co/strangervisionhf) 团队的更改，从而启用推理。如往常一样，Unsloth 训练 DeepSeek-OCR 的速度提高 1.4 倍，显存减少 40%，上下文长度增加 5 倍——且没有准确性下降。\
\
我们创建了两个免费的 DeepSeek-OCR Colab 笔记本（带评估与不带评估）：

* DeepSeek-OCR： [仅微调笔记本](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Deepseek_OCR_\(3B\).ipynb)
* DeepSeek-OCR： [微调 + 评估 笔记本](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Deepseek_OCR_\(3B\)-Eval.ipynb) (A100)

在一个包含 20 万样本的波斯语数据集上微调 DeepSeek-OCR 后，在波斯语文本检测和理解方面取得了显著提升。我们在 200 个波斯语抄本样本上对基础模型和微调模型进行了评估，观察到 **88.26% 的绝对提升** 在字符错误率（CER）上。仅在 60 步训练（批量大小 = 8）之后，平均 CER 从 **149.07%** 降到平均为 **60.81%**。这意味着微调后的模型在理解波斯语方面 **57%** 更准确。

您可以用自己的数据集替换波斯语数据集，以改进 DeepSeek-OCR 在其他用例中的表现。\
\
有关 replica-table 的评估结果，请使用上面的评估笔记本。有关详细的评估结果，请参见下文：

### 微调后的评估结果：

{% columns fullWidth="true" %}
{% column %}
**DeepSeek-OCR 基线**

该评估集的基线模型平均表现：149.07% 的 CER！

```
============================================================
基线模型性能
============================================================
样本数量：200
平均 CER：149.07%
中位数 CER：80.00%
标准差：310.39%
最小 CER：0.00%
最大 CER：3500.00%
============================================================

 最佳预测（最低 CER）：

样本 5024（CER：0.00%）
参考：  چون هستی خیلی زیاد...
预测： چون هستی خیلی زیاد...

样本 3517（CER：0.00%）
参考：  تو ایران هیچوقت از اینها وجود نخواهد داشت...
预测： تو ایران هیچوقت از اینها وجود نخواهد داشت...

样本 9949（CER：0.00%）
参考：  کاش میدونستم هیچی بیخیال...
预测： کاش میدونستم هیچی بیخیال...

 最差预测（最高 CER）：

样本 11155（CER：3500.00%）
参考：  خسو...
预测： \[ \text{CH}_3\text{CH}_2\text{CH}_2\text{CH}_2\text{CH}_2\text{CH}_2\text{CH}_2\text{CH}_2\text{CH}...

样本 13366（CER：1900.00%）
参考：  مشو...
预测： \[\begin{align*}\underline{\mathfrak{su}}_0\end{align*}\]...

样本 10552（CER：1014.29%）
参考：  هیییییچ...
预测： e
```

{% endcolumn %}

{% column %}
**DeepSeek-OCR 微调后**

在 60 步中，我们将 CER 从 149.07% 降至 60.43%（CER 改善 89%）

<pre><code><strong>============================================================
</strong>微调模型性能
============================================================
样本数量：200
平均 CER：60.43%
中位数 CER：50.00%
标准差：80.63%
最小 CER：0.00%
最大 CER：916.67%
============================================================

 最佳预测（最低 CER）：

样本 301（CER：0.00%）
参考：  باشه بابا تو لاکچری، تو خاص، تو خفن...
预测： باشه بابا تو لاکچری، تو خاص، تو خفن...

样本 2512（CER：0.00%）
参考：  از شخص حاج عبدالله زنجبیلی میگیرنش...
预测： از شخص حاج عبدالله زنجبیلی میگیرنش...

样本 2713（CER：0.00%）
参考：  نمی دونم والا تحمل نقد ندارن ظاهرا...
预测： نمی دونم والا تحمل نقد ندارن ظاهرا...

 最差预测（最高 CER）：

样本 14270（CER：916.67%）
参考：  ۴۳۵۹۴۷۴۷۳۸۹۰...
预测： پروپریپریپریپریپریپریپریپریپریپریپریپریپریپریپریپریپریپیپریپریپریپریپریپریپریپریپریپریپر...

样本 3919（CER：380.00%）
参考：  ۷۵۵۰۷۱۰۶۵۹...
预测： وادووووووووووووووووووووووووووووووووووو...

样本 3718（CER：333.33%）
参考：  ۳۲۶۷۲۲۶۵۵۸۴۶...
预测： پُپُسوپُسوپُسوپُسوپُسوپُسوپُسوپُسوپُسوپُ...
</code></pre>

{% endcolumn %}
{% endcolumns %}

我们使用的 20 万样本波斯语数据集中的一个示例（您也可以使用自己的数据），左侧显示图像，右侧显示对应文本。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-2afa75f90055db094d5cae1c635b200c05e97aac%2FScreenshot%202025-11-04%20at%206.10.16%E2%80%AFAM.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://unsloth.ai/docs/zh/mo-xing/tutorials/deepseek-ocr-how-to-run-and-fine-tune.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.