# PaddlePaddle/PaddleOCR-VL-1.5 — vLLM serving recipe

> PaddleOCR-VL-1.5 (0.9B) — next-gen compact VLM for document parsing; adds text spotting, seal recognition, and Tibetan/Bengali

Configuration: hardware `h200` (8× H200) · strategy `single_node_tp` (Tensor Parallel) · variant `default` (BF16)

- Interactive page: https://vllm-recipes-git-preview-vllm-pr-60762-inferact-inc.vercel.app/PaddlePaddle/PaddleOCR-VL-1.5
- This configuration as JSON: https://vllm-recipes-git-preview-vllm-pr-60762-inferact-inc.vercel.app/PaddlePaddle/PaddleOCR-VL-1.5.json?hardware=h200

The commands below were rendered for exactly this configuration and take precedence over any example in the guide.

## Other configurations

Change the query string (the same parameters as the page URL) and fetch this URL again. Unknown or incompatible values fall back to the recipe default, so check the Configuration line.

- `hardware`: `h100`, `h200`, `b200`, `gb200`, `b300`, `gb300`, `mi300x`, `mi325x`, `mi350x`, `mi355x`
- `variant`: `default`
- `strategy`: `single_node_tp`, `multi_node_tp` (multi-node strategies also need `nodes=<n>`)
- `features`: comma-separated list of `text_only`, `encoder_parallel` (default: none)

## Install

Requires vLLM >= 0.11.1.

```bash
uv venv
source .venv/bin/activate
uv pip install -U vllm --torch-backend auto
```

Docker image: `vllm/vllm-openai:latest`

Extra dependencies:

- PaddlePaddle runtime (install in a separate venv from vllm to avoid conflicts)

```bash
uv pip install paddlepaddle-gpu==3.2.1 --extra-index-url https://www.paddlepaddle.org.cn/packages/stable/cu126/
```

- PaddleOCR document-parsing helpers (1.5 ships under the same paddleocr[doc-parser] extra)

```bash
uv pip install -U "paddleocr[doc-parser]"
```

- Safetensors loader used by the doc-parser path

```bash
uv pip install safetensors
```

## Serve

```bash
vllm serve PaddlePaddle/PaddleOCR-VL-1.5 \
  --trust-remote-code \
  --max-num-batched-tokens 16384 \
  --no-enable-prefix-caching \
  --mm-processor-cache-gb 0 \
  --tensor-parallel-size 1
```

Docker equivalent:

```bash
docker run --gpus all \
  --privileged --ipc=host -p 8000:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  vllm/vllm-openai:latest PaddlePaddle/PaddleOCR-VL-1.5 \
  --trust-remote-code \
  --max-num-batched-tokens 16384 \
  --no-enable-prefix-caching \
  --mm-processor-cache-gb 0 \
  --tensor-parallel-size 1
```

## Guide

> Background reference. Commands in it are examples and may target another configuration — use the Serve section above.

### Overview

[PaddleOCR-VL-1.5](https://huggingface.co/PaddlePaddle/PaddleOCR-VL-1.5) is the next
generation of PaddleOCR-VL — same 0.9B architecture (NaViT-style dynamic-resolution
vision encoder + ERNIE-4.5-0.3B LM), with substantial accuracy gains and new tasks:

- **94.5% on OmniDocBench v1.5** (SOTA)
- **Text spotting** — line-level localization + recognition in one pass
- **Seal recognition** — new task with SOTA results
- **Irregular-shape localization** — polygonal detection under skew/warping
- **Multilingual** — adds Tibetan and Bengali
- Cross-page table merging and paragraph-heading recognition

Architecture is identical to PaddleOCR-VL, so the vLLM launch command and feature
flags are the same.

### Prerequisites

- Hardware: 1x GPU (small VRAM footprint)
- vLLM >= 0.11.1 (nightly if not released yet)
- AMD ROCm wheels require Python 3.12, ROCm 7.2.3, and glibc >= 2.35.

#### Install vLLM (NVIDIA)

```bash
uv venv
source .venv/bin/activate
uv pip install -U vllm --pre \
  --extra-index-url https://wheels.vllm.ai/nightly \
  --extra-index-url https://download.pytorch.org/whl/cu129 \
  --index-strategy unsafe-best-match
```

#### Install vLLM (AMD ROCm)

```bash
uv venv --python 3.12
source .venv/bin/activate
uv pip install vllm --extra-index-url https://wheels.vllm.ai/rocm
```

### Launch command

```bash
vllm serve PaddlePaddle/PaddleOCR-VL-1.5 \
  --trust-remote-code \
  --max-num-batched-tokens 16384 \
  --no-enable-prefix-caching \
  --mm-processor-cache-gb 0
```

AMD MI300X/MI325X/MI355X:

```bash
export SAFETENSORS_FAST_GPU=1

vllm serve PaddlePaddle/PaddleOCR-VL-1.5 \
  --trust-remote-code \
  --max-num-batched-tokens 16384 \
  --mm-processor-cache-gb 0
```

Tip: OCR workloads don't benefit much from prefix caching or image reuse, so disable
those to avoid hashing/caching overhead.

### Client Usage

Task-specific prompts (note the two new tasks `spotting` and `seal`):

```python
from openai import OpenAI

client = OpenAI(api_key="EMPTY", base_url="http://localhost:8000/v1", timeout=3600)

TASKS = {
    "ocr": "OCR:",
    "table": "Table Recognition:",
    "formula": "Formula Recognition:",
    "chart": "Chart Recognition:",
    "spotting": "Spotting:",
    "seal": "Seal Recognition:",
}

response = client.chat.completions.create(
    model="PaddlePaddle/PaddleOCR-VL-1.5",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": "https://.../receipt.png"}},
            {"type": "text", "text": TASKS["spotting"]},
        ],
    }],
    temperature=0.0,
)
print(response.choices[0].message.content)
```

### Offline Inference with PP-DocLayoutV2

Use separate venvs for `vllm` and `paddlepaddle` to avoid conflicts. If you see
"The model PaddleOCR-VL-1.5-0.9B does not exist.", add
`--served-model-name PaddleOCR-VL-1.5-0.9B`.

```bash
uv pip install paddlepaddle-gpu==3.2.1 --extra-index-url https://www.paddlepaddle.org.cn/packages/stable/cu126/
uv pip install -U "paddleocr[doc-parser]"
uv pip install safetensors
```

```python
from paddleocr import PaddleOCRVL

pipeline = PaddleOCRVL(
    vl_rec_model_name="PaddleOCR-VL-1.5-0.9B",
    vl_rec_backend="vllm-server",
    vl_rec_server_url="http://localhost:8000/v1",
    layout_detection_model_name="PP-DocLayoutV2",
    layout_detection_model_dir="/path/to/your/PP-DocLayoutV2/",
)

output = pipeline.predict("https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png")
for i, res in enumerate(output):
    res.save_to_json(save_path=f"output_{i}.json")
    res.save_to_markdown(save_path=f"output_{i}.md")
```

### References

- [PaddleOCR-VL-1.5 on Hugging Face](https://huggingface.co/PaddlePaddle/PaddleOCR-VL-1.5)
- [PaddleOCR GitHub](https://github.com/PaddlePaddle/PaddleOCR)
- [vLLM support tracking issue](https://github.com/vllm-project/vllm/issues/33554)