### Install Latest vLLM from Nightly Build

Source: https://github.com/deepseek-ai/deepseek-ocr/blob/main/README.md

Install the latest vLLM from its nightly build using uv for environment management. This is recommended until v0.11.1 is officially released.

```shell
uv venv
source .venv/bin/activate
# Until v0.11.1 release, you need to install vLLM from nightly build
uv pip install -U vllm --pre --extra-index-url https://wheels.vllm.ai/nightly
```

--------------------------------

### vLLM Batch Image Inference Setup

Source: https://context7.com/deepseek-ai/deepseek-ocr/llms.txt

Configuration for running asynchronous streaming inference with `AsyncLLMEngine` for a single image. Ensure model and input paths are set in `config.py`.

```python
# Set in config.py first:
#   MODEL_PATH = 'deepseek-ai/DeepSeek-OCR'
#   INPUT_PATH = 'figures/diagram.png'
#   OUTPUT_PATH = 'out/diagram'
```

--------------------------------

### DeepSeek-OCR Prompt Examples

Source: https://github.com/deepseek-ai/deepseek-ocr/blob/main/README.md

A collection of example prompts for various OCR tasks, including document conversion, general OCR, figure parsing, and locating specific elements within an image using grounding tokens.

```python
# 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.
# '先天下之忧而忧'
```

--------------------------------

### Clone DeepSeek-OCR Repository

Source: https://github.com/deepseek-ai/deepseek-ocr/blob/main/README.md

Clone the DeepSeek-OCR repository to your local machine. Navigate into the cloned directory to proceed with the setup.

```bash
git clone https://github.com/deepseek-ai/DeepSeek-OCR.git
```

--------------------------------

### Install PyTorch and vLLM

Source: https://github.com/deepseek-ai/deepseek-ocr/blob/main/README.md

Install PyTorch with CUDA 11.8 support and a specific version of vLLM. Ensure compatibility with your system's CUDA version.

```shell
pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu118
pip install vllm-0.8.5+cu118-cp38-abi3-manylinux1_x86_64.whl
pip install -r requirements.txt
pip install flash-attn==2.7.3 --no-build-isolation
```

--------------------------------

### vLLM Inference with DeepSeek-OCR Model

Source: https://github.com/deepseek-ai/deepseek-ocr/blob/main/README.md

Perform inference using the DeepSeek-OCR model with vLLM. This example demonstrates loading the model, preparing batched image inputs, and setting sampling parameters including ngram logit processor arguments.

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

# Create model instance
llm = LLM(
    model="deepseek-ai/DeepSeek-OCR",
    enable_prefix_caching=False,
    mm_processor_cache_gb=0,
    logits_processors=[NGramPerReqLogitsProcessor]
)

# Prepare batched input with your image file
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 logit processor args
            extra_args=dict(
                ngram_size=30,
                window_size=90,
                whitelist_token_ids={128821, 128822},  # whitelist: <td>, </td>
            ),
            skip_special_tokens=False,
        )
```

--------------------------------

### Dynamic Tiling with `dynamic_preprocess` and `count_tiles`

Source: https://context7.com/deepseek-ai/deepseek-ocr/llms.txt

Splits an image into optimal 640x640 tiles. Use `count_tiles` to estimate the grid layout without processing, and `dynamic_preprocess` to perform the actual tiling.

```python
from PIL import Image
from process.image_process import dynamic_preprocess, count_tiles

image = Image.open("wide_table.png").convert("RGB")  # e.g., 1920×600

# Estimate tile layout without processing
w, h = image.size
ratio = count_tiles(w, h, min_num=2, max_num=6, image_size=640)
print(f"Tile grid: {ratio[0]}w × {ratio[1]}h → {ratio[0]*ratio[1]} crops")
# → Tile grid: 3w × 1h → 3 crops

# Actually split into tiles
tiles, aspect_ratio = dynamic_preprocess(image, min_num=2, max_num=6, image_size=640)
print(f"Number of tiles: {len(tiles)}, each: {tiles[0].size}")
# → Number of tiles: 3, each: (640, 640)

for i, tile in enumerate(tiles):
    tile.save(f"tile_{i}.png")
```

--------------------------------

### Initialize Deepseek OCR with vLLM

Source: https://context7.com/deepseek-ai/deepseek-ocr/llms.txt

Sets up the Deepseek OCR model within the vLLM framework for efficient inference. Ensure necessary environment variables and model paths are configured.

```python
import os, glob
os.environ["VLLM_USE_V1"] = "0"
os.environ["CUDA_VISIBLE_DEVICES"] = "0"

from PIL import Image
from concurrent.futures import ThreadPoolExecutor
from tqdm import tqdm
from vllm import LLM, SamplingParams
from vllm.model_executor.models.registry import ModelRegistry
from deepseek_ocr import DeepseekOCRForCausalLM
from process.image_process import DeepseekOCRProcessor
from process.ngram_norepeat import NoRepeatNGramLogitsProcessor
from config import MODEL_PATH, INPUT_PATH, OUTPUT_PATH, PROMPT, CROP_MODE, MAX_CONCURRENCY, NUM_WORKERS

ModelRegistry.register_model("DeepseekOCRForCausalLM", DeepseekOCRForCausalLM)

llm = LLM(model=MODEL_PATH,
          hf_overrides={"architectures": ["DeepseekOCRForCausalLM"]},
          block_size=256, max_model_len=8192, enforce_eager=False,
          trust_remote_code=True, max_num_seqs=MAX_CONCURRENCY,
          tensor_parallel_size=1, gpu_memory_utilization=0.9)

sampling_params = SamplingParams(
    temperature=0.0, max_tokens=8192,
    logits_processors=[NoRepeatNGramLogitsProcessor(40, 90, {128821, 128822})],
    skip_special_tokens=False,
)

images_path = glob.glob(f"{INPUT_PATH}/*")
images = [Image.open(p).convert("RGB") for p in images_path]

def preprocess(image):
    return {"prompt": PROMPT,
            "multi_modal_data": {"image": DeepseekOCRProcessor().tokenize_with_images(
                [image], bos=True, eos=True, cropping=CROP_MODE)}}

with ThreadPoolExecutor(max_workers=NUM_WORKERS) as ex:
    batch_inputs = list(tqdm(ex.map(preprocess, images), total=len(images)))

outputs_list = llm.generate(batch_inputs, sampling_params=sampling_params)

os.makedirs(OUTPUT_PATH, exist_ok=True)
for output, path in zip(outputs_list, images_path):
    stem = os.path.basename(path).replace(".jpg", "")
    with open(f"{OUTPUT_PATH}/{stem}.md", "w") as f:
        f.write(output.outputs[0].text)
```

--------------------------------

### Tokenize Image for vLLM

Source: https://context7.com/deepseek-ai/deepseek-ocr/llms.txt

Prepares an image for vLLM inference by tokenizing it. Set `cropping=True` for dynamic tiling or `False` for a single global view.

```python
processed = processor.tokenize_with_images(
    images=[image],
    bos=True,
    eos=True,
    cropping=True,   # False = no dynamic tiling (single global view)
)

# Wrap for vLLM
vllm_input = {
    "prompt": "<image>\n<|grounding|>Convert the document to markdown.",
    "multi_modal_data": {"image": processed},
}
```

--------------------------------

### Run DeepSeek-OCR from Command Line

Source: https://github.com/deepseek-ai/deepseek-ocr/blob/main/README.md

Execute the DeepSeek-OCR model directly from the command line using the provided Python script. Navigate to the 'DeepSeek-OCR-hf' directory first.

```shell
cd DeepSeek-OCR-master/DeepSeek-OCR-hf
python run_dpsk_ocr.py
```

--------------------------------

### Generate and Print Model Output

Source: https://github.com/deepseek-ai/deepseek-ocr/blob/main/README.md

This snippet demonstrates how to generate output from the LLM model and then print the generated text. Ensure the 'llm' object is properly initialized.

```python
model_outputs = llm.generate(model_input, sampling_param)

# Print output
for output in model_outputs:
    print(output.outputs[0].text)
```

--------------------------------

### Run DeepSeek-OCR Batch Evaluation with vLLM

Source: https://github.com/deepseek-ai/deepseek-ocr/blob/main/README.md

Execute the batch evaluation script for benchmarks using vLLM. This is useful for performance testing and comparison.

```shell
cd DeepSeek-OCR-master/DeepSeek-OCR-vllm
python run_dpsk_ocr_eval_batch.py
```

--------------------------------

### Run DeepSeek-OCR Image Inference with vLLM

Source: https://github.com/deepseek-ai/deepseek-ocr/blob/main/README.md

Execute the image inference script using vLLM. Ensure the configuration file 'config.py' has the correct INPUT_PATH and OUTPUT_PATH.

```shell
cd DeepSeek-OCR-master/DeepSeek-OCR-vllm
python run_dpsk_ocr_image.py
```

--------------------------------

### Configure vLLM Inference Stack

Source: https://context7.com/deepseek-ai/deepseek-ocr/llms.txt

Edit this Python script to set model paths, resolution modes, I/O paths, concurrency, and prompt templates for the vLLM inference stack. Ensure `MODEL_PATH` points to your model.

```python
# config.py — edit before running any vLLM script

BASE_SIZE = 1024       # global-view resolution fed to vision encoder
IMAGE_SIZE = 640       # tile size for dynamic cropping (Gundam mode)
CROP_MODE = True       # True = Gundam (n local tiles + 1 global), False = single view
MIN_CROPS = 2          # minimum number of crops
MAX_CROPS = 6          # max crops; reduce to 4-5 if GPU VRAM < 40 GB
MAX_CONCURRENCY = 100  # max simultaneous vLLM sequences
NUM_WORKERS = 64       # threads for image pre-processing
PRINT_NUM_VIS_TOKENS = False
SKIP_REPEAT = True     # skip pages where EOS is missing (likely repeat)
MODEL_PATH = 'deepseek-ai/DeepSeek-OCR'  # HuggingFace Hub ID or local path

INPUT_PATH = '/data/input/document.pdf'   # .pdf | .jpg | .png | directory
OUTPUT_PATH = '/data/output/results'

# Commonly used prompts — uncomment the one you need:
PROMPT = '<image>
<|grounding|>Convert the document to markdown.'
# PROMPT = '<image>
Free OCR.'
# PROMPT = '<image>
<|grounding|>OCR this image.'
# PROMPT = '<image>
Parse the figure.'
# PROMPT = '<image>
Describe this image in detail.'
# PROMPT = '<image>
Locate <|ref|>table<|/ref|> in the image.'

from transformers import AutoTokenizer
TOKENIZER = AutoTokenizer.from_pretrained(MODEL_PATH, trust_remote_code=True)
```

--------------------------------

### Async Image to Markdown Generation with vLLM

Source: https://context7.com/deepseek-ai/deepseek-ocr/llms.txt

Use this snippet for asynchronous generation of markdown from a single image using Deepseek OCR and vLLM. Ensure the model path and input image are correctly configured.

```python
import asyncio, os
os.environ["VLLM_USE_V1"] = "0"
os.environ["CUDA_VISIBLE_DEVICES"] = "0"

from vllm import AsyncLLMEngine, SamplingParams
from vllm.engine.arg_utils import AsyncEngineArgs
from vllm.model_executor.models.registry import ModelRegistry
from deepseek_ocr import DeepseekOCRForCausalLM
from process.image_process import DeepseekOCRProcessor
from process.ngram_norepeat import NoRepeatNGramLogitsProcessor
from config import MODEL_PATH, INPUT_PATH, OUTPUT_PATH, PROMPT, CROP_MODE
from PIL import Image, ImageOps
import time

ModelRegistry.register_model("DeepseekOCRForCausalLM", DeepseekOCRForCausalLM)

async def stream_generate(image=None, prompt=""):
    engine_args = AsyncEngineArgs(
        model=MODEL_PATH,
        hf_overrides={"architectures": ["DeepseekOCRForCausalLM"]},
        block_size=256,
        max_model_len=8192,
        enforce_eager=False,
        trust_remote_code=True,
        tensor_parallel_size=1,
        gpu_memory_utilization=0.75,
    )
    engine = AsyncLLMEngine.from_engine_args(engine_args)
    logits_processors = [NoRepeatNGramLogitsProcessor(30, 90, {128821, 128822})]
    sampling_params = SamplingParams(
        temperature=0.0, max_tokens=8192,
        logits_processors=logits_processors,
        skip_special_tokens=False,
    )
    request = {"prompt": prompt, "multi_modal_data": {"image": image}}
    printed_length = 0
    async for out in engine.generate(request, sampling_params, f"req-{int(time.time())}"):
        new = out.outputs[0].text[printed_length:]
        print(new, end="", flush=True)
        printed_length = len(out.outputs[0].text)
    return out.outputs[0].text

image = ImageOps.exif_transpose(Image.open(INPUT_PATH)).convert("RGB")
image_features = DeepseekOCRProcessor().tokenize_with_images([image], bos=True, eos=True, cropping=CROP_MODE)
result = asyncio.run(stream_generate(image_features, PROMPT))
# Outputs: result_ori.mmd, result.mmd, result_with_boxes.jpg, images/*.jpg
```

--------------------------------

### Create and Activate Conda Environment

Source: https://github.com/deepseek-ai/deepseek-ocr/blob/main/README.md

Create a new Conda environment named 'deepseek-ocr' with Python 3.12.9 and activate it. This isolates project dependencies.

```shell
conda create -n deepseek-ocr python=3.12.9 -y
conda activate deepseek-ocr
```

--------------------------------

### vLLM Inference - Image Processing

Source: https://github.com/deepseek-ai/deepseek-ocr/blob/main/README.md

This snippet demonstrates how to perform OCR on images using the vLLM library. It shows how to load the model, prepare image inputs, and set sampling parameters, including ngram logit processor arguments for advanced control.

```APIDOC
## vLLM Inference - Image Processing

### Description
This example shows how to use the DeepSeek-OCR model with vLLM for image-based OCR. It includes setting up the LLM instance with specific configurations and preparing batched inputs containing images and prompts.

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

# Create model instance
llm = LLM(
    model="deepseek-ai/DeepSeek-OCR",
    enable_prefix_caching=False,
    mm_processor_cache_gb=0,
    logits_processors=[NGramPerReqLogitsProcessor]
)

# Prepare batched input with your image file
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 logit processor args
            extra_args=dict(
                ngram_size=30,
                window_size=90,
                whitelist_token_ids={128821, 128822},  # whitelist: <td>, </td>
            ),
            skip_special_tokens=False,
        )

# Generate output (example)
# outputs = llm.generate(model_input, sampling_params=sampling_param)
# print(outputs)
```

### Parameters
#### Model Initialization Parameters
- **model** (str): The name or path of the DeepSeek-OCR model.
- **enable_prefix_caching** (bool): Whether to enable prefix caching.
- **mm_processor_cache_gb** (int): Size of the multimodal processor cache in GB.
- **logits_processors** (list): A list of logits processors to use, including `NGramPerReqLogitsProcessor`.

#### Input Data Structure
- **prompt** (str): The input prompt, typically including `<image>` token.
- **multi_modal_data** (dict): A dictionary containing multimodal data, with an `image` key pointing to a PIL Image object.

#### Sampling Parameters
- **temperature** (float): Controls randomness in generation. Set to 0.0 for deterministic output.
- **max_tokens** (int): The maximum number of tokens to generate.
- **extra_args** (dict): Additional arguments for ngram logit processor.
  - **ngram_size** (int): The ngram size for the logit processor.
  - **window_size** (int): The window size for the logit processor.
  - **whitelist_token_ids** (set): A set of token IDs to whitelist.
- **skip_special_tokens** (bool): Whether to skip special tokens in the output.
```

--------------------------------

### Run DeepSeek-OCR PDF Inference with vLLM

Source: https://github.com/deepseek-ai/deepseek-ocr/blob/main/README.md

Execute the PDF inference script using vLLM. This script is optimized for processing PDFs and can achieve high concurrency.

```shell
cd DeepSeek-OCR-master/DeepSeek-OCR-vllm
python run_dpsk_ocr_pdf.py
```

--------------------------------

### vLLM PDF Batch Inference with Deepseek OCR

Source: https://context7.com/deepseek-ai/deepseek-ocr/llms.txt

Process all pages of a PDF in parallel using vLLM's batch inference. This script converts PDF pages to images, preprocesses them, and sends the entire batch to the LLM. Outputs include per-page markdown, a bounding-box annotated PDF, and extracted image crops.

```python
# config.py: INPUT_PATH = 'report.pdf', OUTPUT_PATH = 'out/report'
import os, io
os.environ["VLLM_USE_V1"] = "0"
os.environ["CUDA_VISIBLE_DEVICES"] = "0"

import fitz, img2pdf
from PIL import Image
from concurrent.futures import ThreadPoolExecutor
from tqdm import tqdm
from vllm import LLM, SamplingParams
from vllm.model_executor.models.registry import ModelRegistry
from deepseek_ocr import DeepseekOCRForCausalLM
from process.image_process import DeepseekOCRProcessor
from process.ngram_norepeat import NoRepeatNGramLogitsProcessor
from config import MODEL_PATH, INPUT_PATH, OUTPUT_PATH, PROMPT, CROP_MODE, MAX_CONCURRENCY, NUM_WORKERS

ModelRegistry.register_model("DeepseekOCRForCausalLM", DeepseekOCRForCausalLM)

llm = LLM(
    model=MODEL_PATH,
    hf_overrides={"architectures": ["DeepseekOCRForCausalLM"]},
    block_size=256, max_model_len=8192,
    enforce_eager=False, trust_remote_code=True,
    swap_space=0, max_num_seqs=MAX_CONCURRENCY,
    tensor_parallel_size=1, gpu_memory_utilization=0.9,
    disable_mm_preprocessor_cache=True,
)
sampling_params = SamplingParams(
    temperature=0.0, max_tokens=8192,
    logits_processors=[NoRepeatNGramLogitsProcessor(20, 50, {128821, 128822})],
    skip_special_tokens=False, include_stop_str_in_output=True,
)

# Render PDF pages to PIL images at 144 DPI
doc = fitz.open(INPUT_PATH)
images = [Image.open(io.BytesIO(doc[i].get_pixmap(matrix=fitz.Matrix(2, 2), alpha=False).tobytes("png")))
          for i in range(doc.page_count)]
doc.close()

def preprocess(image):
    return {"prompt": PROMPT,
            "multi_modal_data": {"image": DeepseekOCRProcessor().tokenize_with_images(
                [image], bos=True, eos=True, cropping=CROP_MODE)}}

with ThreadPoolExecutor(max_workers=NUM_WORKERS) as ex:
    batch_inputs = list(tqdm(ex.map(preprocess, images), total=len(images)))

outputs_list = llm.generate(batch_inputs, sampling_params=sampling_params)
# → writes report.mmd, report_det.mmd, report_layouts.pdf to OUTPUT_PATH

```

--------------------------------

### Perform Single-Image Inference with Transformers

Source: https://context7.com/deepseek-ai/deepseek-ocr/llms.txt

Use this high-level method for interactive use or development. It handles image loading, encoding, and text generation. Ensure CUDA is available and the model is loaded in `bfloat16` for efficiency.

```python
from transformers import AutoModel, AutoTokenizer
import torch, os

os.environ["CUDA_VISIBLE_DEVICES"] = "0"
model_name = "deepseek-ai/DeepSeek-OCR"

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)

# --- Resolution modes (pick one) ---
# Tiny:   base_size=512,  image_size=512,  crop_mode=False   (~64 vision tokens)
# Small:  base_size=640,  image_size=640,  crop_mode=False   (~100 vision tokens)
# Base:   base_size=1024, image_size=1024, crop_mode=False   (~256 vision tokens)
# Large:  base_size=1280, image_size=1280, crop_mode=False   (~400 vision tokens)
# Gundam: base_size=1024, image_size=640,  crop_mode=True    (dynamic, best for docs)

result = model.infer(
    tokenizer,
    prompt="<image>\n<|grounding|>Convert the document to markdown. ",
    image_file="invoice.jpg",
    output_path="./output",
    base_size=1024,
    image_size=640,
    crop_mode=True,     # dynamic multi-tile cropping
    save_results=True,  # write .mmd files to output_path
    test_compress=True,
)
# result is the raw model output string (markdown / grounding tokens / plain text)
print(result[:500])
```

--------------------------------

### Process Images for vLLM Inference

Source: https://context7.com/deepseek-ai/deepseek-ocr/llms.txt

This function converts PIL images into input bundles for vLLM, including global-view and local crop tensors, spatial metadata, and token sequences. It reads configuration from `config.py`.

```python
from PIL import Image
from process.image_process import DeepseekOCRProcessor

processor = DeepseekOCRProcessor()  # reads MODEL_PATH / TOKENIZER from config.py

image = Image.open("page.png").convert("RGB")

# Returns a nested list: [[input_ids, pixel_values, images_crop,

```

--------------------------------

### Transformers Inference with DeepSeek-OCR

Source: https://github.com/deepseek-ai/deepseek-ocr/blob/main/README.md

Perform inference using the DeepSeek-OCR model with Hugging Face Transformers. This requires setting up the model and tokenizer, and preparing the prompt and image file. The model is configured for CUDA and bfloat16 precision.

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

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 = 640, crop_mode=True, save_results = True, test_compress = True)
```

--------------------------------

### Replace Grounding Tokens with Markdown Image References

Source: https://context7.com/deepseek-ai/deepseek-ocr/llms.txt

This code snippet replaces specific image grounding tokens in a raw output string with markdown image references. It also removes other non-image grounding tokens.

```python
print("Other boxes:", other_boxes)
# → ['<|ref|>title<|ref|><|det|>[[10, 20, 400, 60]]<|/det|>']

# Replace image grounding tokens with markdown image references
for idx, m in enumerate(image_boxes):
    raw_output = raw_output.replace(m, f"![](images/{idx}.jpg)\n")
# Remove non-image grounding tokens from clean output
for m in other_boxes:
    raw_output = raw_output.replace(m, "")
print(raw_output)
```

--------------------------------

### Deepseek OCR Vision Encoder Projection

Source: https://context7.com/deepseek-ai/deepseek-ocr/llms.txt

Illustrates the internal projection of vision features to the language model embedding space using MlpProjector. This is an internal call flow and not directly invoked by users.

```python
import torch
from deepseek_ocr import DeepseekOCRForCausalLM
from vllm.config import VllmConfig

# The model is instantiated by vLLM automatically; the embedding pipeline is:
#
# pixel_values  : [n_images, 3, BASE_SIZE, BASE_SIZE]  — global view
# images_crop   : [n_images, n_patches, 3, IMAGE_SIZE, IMAGE_SIZE]  — local tiles
# images_spatial_crop : [n_images, 2]  — (width_tiles, height_tiles)

# Internally per image:
# 1. local_feat_1  = sam_model(patches)          # spatial features
# 2. local_feat_2  = clip_model(patches, feat_1) # semantic + spatial fusion
# 3. local_features = concat(feat_2[:, 1:], feat_1.flatten(2).T) → projector
# 4. global_feat_1 = sam_model(global_view)
# 5. global_feat_2 = clip_model(global_view, feat_1)
# 6. global_features = concat(feat_2[:, 1:], feat_1.flatten(2).T) → projector
# 7. Reshape local/global to 2-D grids, append image_newline tokens per row
# 8. Final sequence: [local_tiles | global_view | view_separator]

# The MlpProjector maps 2048-dim concatenated features → 1280-dim LM embedding:
from deepencoder.build_linear import MlpProjector
from addict import Dict

projector = MlpProjector(Dict(projector_type="linear", input_dim=2048, n_embed=1280))
dummy = torch.randn(1, 256, 2048)   # [batch, spatial_tokens, in_dim]
out = projector(dummy)
print(out.shape)  # → torch.Size([1, 256, 1280])
```

--------------------------------

### Parse Deepseek OCR Grounding Output

Source: https://context7.com/deepseek-ai/deepseek-ocr/llms.txt

Parses structured grounding output from the model, separating image bounding boxes from other element types. This function is used in inference scripts for post-processing.

```python
import re

def re_match(text):
    pattern = r'(<|ref|>(.*?)<|/ref|><|det|>(.*?)<|/det|>)'
    matches = re.findall(pattern, text, re.DOTALL)
    mathes_image, mathes_other = [], []
    for m in matches:
        if '<|ref|>image<|/ref|>' in m[0]:
            mathes_image.append(m[0])
        else:
            mathes_other.append(m[0])
    return matches, mathes_image, mathes_other

raw_output = (
    "<|ref|>title<|/ref|><|det|>[[10, 20, 400, 60]]<|/det|>\n"
    "# Introduction\n"
    "<|ref|>image<|/ref|><|det|>[[50, 100, 800, 600]]<|/det|>\n"
    "Some paragraph text."
)

matches, image_boxes, other_boxes = re_match(raw_output)
print("All matches:", len(matches))     # → All matches: 2
print("Image boxes:", image_boxes)
```

--------------------------------

### N-gram Repetition Suppression for OCR

Source: https://context7.com/deepseek-ai/deepseek-ocr/llms.txt

Prevents repetitive N-gram sequences in OCR output using `NoRepeatNGramLogitsProcessor`. Configure `ngram_size` and `window_size` based on the use case. A whitelist can exclude specific tokens like table cell delimiters.

```python
from process.ngram_norepeat import NoRepeatNGramLogitsProcessor
from vllm import SamplingParams

# Recommended settings by use-case:
#   PDF pages (fast):   ngram_size=20, window_size=50
#   Single images:      ngram_size=30, window_size=90
#   Benchmarks (strict):ngram_size=40, window_size=90

processor = NoRepeatNGramLogitsProcessor(
    ngram_size=30,
    window_size=90,
    whitelist_token_ids={128821, 128822},  # <td>, </td> — allow table cell repetition
)

sampling_params = SamplingParams(
    temperature=0.0,
    max_tokens=8192,
    logits_processors=[processor],
    skip_special_tokens=False,
)
# Pass sampling_params to llm.generate() or engine.generate()
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.