Add Deepseek-OCR-2 model

docs/source/en/_toctree.yml

@@ -559,6 +559,8 @@
         title: DeBERTa
       - local: model_doc/deberta-v2
         title: DeBERTa-v2
+      - local: model_doc/deepseek_ocr2
+        title: DeepSeek-OCR-2
       - local: model_doc/deepseek_v2
         title: DeepSeek-V2
       - local: model_doc/deepseek_v3

docs/source/en/model_doc/deepseek_ocr2.md

@@ -0,0 +1,116 @@
+<!--Copyright 2026 The HuggingFace Team. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+
+⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+
+-->
+*This model was published in HF papers on 2026-01-28 and contributed to Hugging Face Transformers on 2026-06-01.*
+
+# DeepSeek-OCR-2
+
+
+## Overview
+
+The DeepSeek-OCR-2 model was proposed in [Visual Causal Flow: A Novel Approach to OCR-Specialized Vision-Language Models](https://huggingface.co/papers/2601.20552) by the DeepSeek team.
+
+DeepSeek-OCR-2 is an OCR-specialized vision-language model built on a distinctive architecture: a SAM ViT-B vision encoder feeds into a Qwen2 hybrid attention encoder, which is connected through an MLP projector to a DeepSeek-V2 Mixture-of-Experts (MoE) language model. A key feature of the model is its hybrid attention mechanism, which applies bidirectional attention over image tokens and causal attention over query tokens, enabling efficient and accurate document understanding.
+
+<img src="https://huggingface.co/deepseek-ai/DeepSeek-OCR-2/resolve/main/assets/fig1.png" width="600">
+
+<small> DeepSeek-OCR 2: Visual Causal Flow.</small>
+
+This model was contributed by [thisisiron](https://huggingface.co/thisisiron).
+
+
+## Usage example
+
+### Plain OCR
+
+```python
+from transformers import AutoProcessor, AutoModelForImageTextToText
+
+model = AutoModelForImageTextToText.from_pretrained(
+    "deepseek-community/DeepSeek-OCR-2", device_map="auto"
+)
+processor = AutoProcessor.from_pretrained("deepseek-community/DeepSeek-OCR-2")
+
+image = "https://huggingface.co/datasets/hf-internal-testing/fixtures_got_ocr/resolve/main/image_ocr.jpg"
+inputs = processor(images=image, text="<image>\nFree OCR.", return_tensors="pt").to(model.device)
+
+generate_ids = model.generate(**inputs, do_sample=False, max_new_tokens=256)
+processor.decode(generate_ids[0, inputs["input_ids"].shape[1] :], skip_special_tokens=True)
+# "R&D QUALITY IMPROVEMENT\nSUGGESTION/SOLUTION FORM\nName/Phone Ext. : (...)"
+```
+
+### Grounding with markdown conversion
+
+The `<|grounding|>` token enables coordinate-aware output with `<|ref|>` and `<|det|>` tags.
+
+```python
+inputs = processor(
+    images=image,
+    text="<image>\n<|grounding|>Convert the document to markdown.",
+    return_tensors="pt",
+).to(model.device)
+
+generate_ids = model.generate(**inputs, do_sample=False, max_new_tokens=256)
+processor.decode(generate_ids[0, inputs["input_ids"].shape[1] :], skip_special_tokens=False)
+# "<|ref|>title<|/ref|><|det|>[[330, 198, 558, 230]]<|/det|>\n# R&D QUALITY (...)"
+```
+
+## DeepseekOcr2Config
+
+[[autodoc]] DeepseekOcr2Config
+
+## DeepseekOcr2VisionConfig
+
+[[autodoc]] DeepseekOcr2VisionConfig
+
+## DeepseekOcr2SamVisionConfig
+
+[[autodoc]] DeepseekOcr2SamVisionConfig
+
+## DeepseekOcr2VisionEncoderConfig
+
+[[autodoc]] DeepseekOcr2VisionEncoderConfig
+
+## DeepseekOcr2TextConfig
+
+[[autodoc]] DeepseekOcr2TextConfig
+
+## DeepseekOcr2ImageProcessor
+
+[[autodoc]] DeepseekOcr2ImageProcessor
+
+## DeepseekOcr2ImageProcessorPil
+
+[[autodoc]] DeepseekOcr2ImageProcessorPil
+
+## DeepseekOcr2Processor
+
+[[autodoc]] DeepseekOcr2Processor
+
+## DeepseekOcr2TextModel
+
+[[autodoc]] DeepseekOcr2TextModel
+
+## DeepseekOcr2VisionModel
+
+[[autodoc]] DeepseekOcr2VisionModel
+
+## DeepseekOcr2Model
+
+[[autodoc]] DeepseekOcr2Model
+
+## DeepseekOcr2ForConditionalGeneration
+
+[[autodoc]] DeepseekOcr2ForConditionalGeneration

src/transformers/conversion_mapping.py

@@ -519,6 +519,96 @@ def _build_checkpoint_conversion_mapping():
                 source_patterns=r"^model(?!\.(language_model|visual))", target_patterns="model.language_model"
             ),
         ],
+        "deepseek_ocr2": [
+            WeightRenaming(
+                source_patterns=r"sam_model\.blocks\.(\d+)\.norm1\.",
+                target_patterns=r"vision_tower.sam_encoder.layers.\1.layer_norm1.",
+            ),
+            WeightRenaming(
+                source_patterns=r"sam_model\.blocks\.(\d+)\.norm2\.",
+                target_patterns=r"vision_tower.sam_encoder.layers.\1.layer_norm2.",
+            ),
+            WeightRenaming(
+                source_patterns=r"sam_model\.blocks\.(\d+)\.attn\.",
+                target_patterns=r"vision_tower.sam_encoder.layers.\1.attn.",
+            ),
+            WeightRenaming(
+                source_patterns=r"sam_model\.blocks\.(\d+)\.mlp\.",
+                target_patterns=r"vision_tower.sam_encoder.layers.\1.mlp.",
+            ),
+            WeightRenaming(
+                source_patterns=r"sam_model\.patch_embed\.proj\.",
+                target_patterns="vision_tower.sam_encoder.patch_embed.projection.",
+            ),
+            WeightRenaming(
+                source_patterns=r"sam_model\.pos_embed",
+                target_patterns="vision_tower.sam_encoder.pos_embed",
+            ),
+            WeightRenaming(
+                source_patterns=r"sam_model\.neck\.0\.",
+                target_patterns="vision_tower.sam_encoder.neck.conv1.",
+            ),
+            WeightRenaming(
+                source_patterns=r"sam_model\.neck\.1\.",
+                target_patterns="vision_tower.sam_encoder.neck.layer_norm1.",
+            ),
+            WeightRenaming(
+                source_patterns=r"sam_model\.neck\.2\.",
+                target_patterns="vision_tower.sam_encoder.neck.conv2.",
+            ),
+            WeightRenaming(
+                source_patterns=r"sam_model\.neck\.3\.",
+                target_patterns="vision_tower.sam_encoder.neck.layer_norm2.",
+            ),
+            WeightRenaming(
+                source_patterns=r"sam_model\.net_2\.",
+                target_patterns="vision_tower.sam_encoder.proj.conv1.",
+            ),
+            WeightRenaming(
+                source_patterns=r"sam_model\.net_3\.",
+                target_patterns="vision_tower.sam_encoder.proj.conv2.",
+            ),
+            WeightRenaming(
+                source_patterns=r"qwen2_model\.model\.model\.layers\.",
+                target_patterns="vision_tower.vision_encoder.layers.",
+            ),
+            WeightRenaming(
+                source_patterns=r"qwen2_model\.model\.model\.norm\.",
+                target_patterns="vision_tower.vision_encoder.norm.",
+            ),
+            WeightRenaming(
+                source_patterns=r"qwen2_model\.query_768\.",
+                target_patterns="vision_tower.query_768_resolution.",
+            ),
+            WeightRenaming(
+                source_patterns=r"qwen2_model\.query_1024\.",
+                target_patterns="vision_tower.query_1024_resolution.",
+            ),
+            WeightRenaming(
+                source_patterns=r"projector\.layers\.",
+                target_patterns="multi_modal_projector.",
+            ),
+            WeightRenaming(source_patterns=r"view_seperator", target_patterns="view_separator"),
+            WeightRenaming(
+                source_patterns=r"(^|model\.)embed_tokens\.",
+                target_patterns=r"\1language_model.embed_tokens.",
+            ),
+            WeightRenaming(source_patterns=r"(^|model\.)layers\.", target_patterns=r"\1language_model.layers."),
+            WeightRenaming(source_patterns=r"(^|model\.)norm\.", target_patterns=r"\1language_model.norm."),
+            WeightConverter(
+                source_patterns=[
+                    "mlp.experts.*.gate_proj.weight",
+                    "mlp.experts.*.up_proj.weight",
+                ],
+                target_patterns="mlp.experts.gate_up_proj",
+                operations=[MergeModulelist(dim=0), Concatenate(dim=1)],
+            ),
+            WeightConverter(
+                source_patterns="mlp.experts.*.down_proj.weight",
+                target_patterns="mlp.experts.down_proj",
+                operations=[MergeModulelist(dim=0)],
+            ),
+        ],
         "colqwen2": [PrefixChange(prefix_to_remove="model", model_prefix="vlm")],
         "shieldgemma2": [PrefixChange(prefix_to_add="model", model_prefix="model")],
         "timm_wrapper": [PrefixChange(prefix_to_add="timm_model")],

src/transformers/models/__init__.py

@@ -92,6 +92,7 @@
     from .deberta import *
     from .deberta_v2 import *
     from .decision_transformer import *
+    from .deepseek_ocr2 import *
     from .deepseek_v2 import *
     from .deepseek_v3 import *
     from .deepseek_v4 import *

src/transformers/models/auto/auto_mappings.py

@@ -121,6 +121,11 @@
         ("deberta", "DebertaConfig"),
         ("deberta-v2", "DebertaV2Config"),
         ("decision_transformer", "DecisionTransformerConfig"),
+        ("deepseek_ocr2", "DeepseekOcr2Config"),
+        ("deepseek_ocr2_encoder", "DeepseekOcr2VisionEncoderConfig"),
+        ("deepseek_ocr2_sam_vision_model", "DeepseekOcr2SamVisionConfig"),
+        ("deepseek_ocr2_text", "DeepseekOcr2TextConfig"),
+        ("deepseek_ocr2_vision", "DeepseekOcr2VisionConfig"),
         ("deepseek_v2", "DeepseekV2Config"),
         ("deepseek_v3", "DeepseekV3Config"),
         ("deepseek_v4", "DeepseekV4Config"),
@@ -698,6 +703,10 @@
         ("data2vec-text", "data2vec"),
         ("data2vec-vision", "data2vec"),
         ("deberta-v2", "deberta_v2"),
+        ("deepseek_ocr2_encoder", "deepseek_ocr2"),
+        ("deepseek_ocr2_sam_vision_model", "deepseek_ocr2"),
+        ("deepseek_ocr2_text", "deepseek_ocr2"),
+        ("deepseek_ocr2_vision", "deepseek_ocr2"),
         ("dia_decoder", "dia"),
         ("dia_encoder", "dia"),
         ("donut-swin", "donut"),
@@ -889,6 +898,7 @@
             {"pil": "ConditionalDetrImageProcessorPil", "torchvision": "ConditionalDetrImageProcessor"},
         ),
         ("convnext", {"pil": "ConvNextImageProcessorPil", "torchvision": "ConvNextImageProcessor"}),
+        ("deepseek_ocr2", {"pil": "DeepseekOcr2ImageProcessorPil", "torchvision": "DeepseekOcr2ImageProcessor"}),
         ("deepseek_vl", {"pil": "DeepseekVLImageProcessorPil", "torchvision": "DeepseekVLImageProcessor"}),
         (
             "deepseek_vl_hybrid",

src/transformers/models/auto/modeling_auto.py

@@ -112,6 +112,7 @@ class _BaseModelWithGenerate(PreTrainedModel, GenerationMixin):
         ("deberta", "DebertaModel"),
         ("deberta-v2", "DebertaV2Model"),
         ("decision_transformer", "DecisionTransformerModel"),
+        ("deepseek_ocr2", "DeepseekOcr2Model"),
         ("deepseek_v2", "DeepseekV2Model"),
         ("deepseek_v3", "DeepseekV3Model"),
         ("deepseek_v4", "DeepseekV4Model"),
@@ -1000,6 +1001,7 @@ class _BaseModelWithGenerate(PreTrainedModel, GenerationMixin):
         ("blip-2", "Blip2ForConditionalGeneration"),
         ("chameleon", "ChameleonForConditionalGeneration"),
         ("cohere2_vision", "Cohere2VisionForConditionalGeneration"),
+        ("deepseek_ocr2", "DeepseekOcr2ForConditionalGeneration"),
         ("deepseek_vl", "DeepseekVLForConditionalGeneration"),
         ("deepseek_vl_hybrid", "DeepseekVLHybridForConditionalGeneration"),
         ("emu3", "Emu3ForConditionalGeneration"),

src/transformers/models/auto/processing_auto.py

@@ -69,6 +69,7 @@
             ("colmodernvbert", "ColModernVBertProcessor"),
             ("colpali", "ColPaliProcessor"),
             ("colqwen2", "ColQwen2Processor"),
+            ("deepseek_ocr2", "DeepseekOcr2Processor"),
             ("deepseek_vl", "DeepseekVLProcessor"),
             ("deepseek_vl_hybrid", "DeepseekVLHybridProcessor"),
             ("dia", "DiaProcessor"),

src/transformers/models/deepseek_ocr2/__init__.py

@@ -0,0 +1,30 @@
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from typing import TYPE_CHECKING
+
+from ...utils import _LazyModule
+from ...utils.import_utils import define_import_structure
+
+
+if TYPE_CHECKING:
+    from .configuration_deepseek_ocr2 import *
+    from .image_processing_deepseek_ocr2 import *
+    from .image_processing_pil_deepseek_ocr2 import *
+    from .modeling_deepseek_ocr2 import *
+    from .processing_deepseek_ocr2 import *
+else:
+    import sys
+
+    _file = globals()["__file__"]
+    sys.modules[__name__] = _LazyModule(__name__, _file, define_import_structure(_file), module_spec=__spec__)