PaddleOCR-VL: versions, setup, serving and benchmarks

What PaddleOCR-VL is#

PaddleOCR-VL is a two-stage pipeline, not a single model.¹ The first stage is a layout model that detects every element on the page (paragraphs, titles, tables, formulas, charts, seals), puts them in reading order and crops them. The second stage is a small vision-language model that reads each crop and writes Markdown, an HTML table, LaTeX or a chart table. The pipeline then stitches the pieces back together in reading order.

The VLM component pairs a NaViT-style dynamic-resolution visual encoder with the ERNIE-4.5-0.3B language model.¹ The Hugging Face API reports 958,588,736 parameters (BF16 safetensors) for all three releases — v1, 1.5 and 1.6 share one architecture.⁴ "0.9B" in names like PaddleOCR-VL-1.6-0.9B refers to this VLM component only, not a separate model size.¹

PaddleOCR-VL or PP-StructureV3?#

Both convert documents to Markdown and JSON and both ship in paddleocr[doc-parser]. The README positions PP-StructureV3 as the choice when you need finer-grained coordinates, such as table-cell and text-line boxes, which the VL series doesn't return.⁵ PaddleOCR-VL is the accuracy pick: on the OmniDocBench v1.5 table, PaddleOCR-VL-1.5 scores 94.50 and PP-StructureV3 86.73.⁷ PP-StructureV3 runs comfortably on a CPU; PaddleOCR-VL is designed for a GPU.

Versions: v1, 1.5 and 1.6#

1. Oct 16, 2025PaddleOCR-VL (v1) ships with PaddleOCR 3.3.0. 109 languages; text, tables, formulas and charts; arXiv 2510.14528.⁵⁴
2. Oct 29, 2025Hugging Face Transformers support.⁴
3. Nov 4, 2025Official vLLM support.⁴
4. Jan 29, 2026PaddleOCR-VL-1.5 with PaddleOCR 3.4.0. New PP-DocLayoutV3 layout model with polygon boxes, seal recognition, text spotting, cross-page table merging and heading levels; adds Tibetan and Bengali; arXiv 2601.21957.¹⁵
5. Mar 6, 2026llama.cpp (GGUF) support for 1.5.⁴
6. May 28, 2026PaddleOCR-VL-1.6 with PaddleOCR 3.6.0. Same architecture as 1.5; better ancient-document, rare-character, seal, spotting and chart results per Baidu. Technical report arXiv 2606.03264 followed on June 3.¹⁹
7. Jul 22, 2026HPD-Parsing, a separate high-throughput parser, is announced (see below).⁵

Layout models and component names come from the PaddleX 3.7.2 pipeline configs.³ The VLM understands task prompts: v1 knows OCR:, Table Recognition:, Formula Recognition: and Chart Recognition:; 1.5 and 1.6 add Spotting: and Seal Recognition:.⁴ PP-DocLayoutV2 and V3 share the same 25 labels, including display_formula, inline_formula, vertical_text, seal and chart.¹⁵ V3 predicts polygon boxes and reading order in one forward pass; its own model card says it is also used by GLM-OCR.¹⁵

Benchmarks: where PaddleOCR-VL stands#

The most-cited benchmark for document parsers is OmniDocBench, published by OpenDataLab — the team that also builds MinerU, which appears on the same table. The leaderboard below is the one in OmniDocBench's own README, not Baidu's. We copied the rows as published.⁶ "Overall" there is ((1 − TextEdit) × 100 + TableTEDS + FormulaCDM) / 3 over 1,651 pages.⁶

PaddleOCR-VL-1.6 has the best formula score (CDM 97.53) of the ten, while TeleOCR leads on tables and OvisOCR2 on text edit distance.⁶ For scale, the same table lists Gemini 3 Pro at 92.91, dots.ocr at 90.77, GPT-5.2 at 86.59 and the MinerU pipeline at 86.47. GPT-4o and PP-StructureV3 are not in this table.⁶ Remember that a 1–2 point gap on a 1,651-page benchmark says little about your documents — test on a sample of your own.

How much did each version improve?#

The jump from v1 to 1.5 on Real5-OmniDocBench is driven by the hard cases: skewed pages went from 77.47 to 91.66 and screen photos from 82.54 to 91.76, in line with the switch to polygon layout boxes in PP-DocLayoutV3.⁸ Treat those as vendor numbers. On the independent table the gains are smaller: +0.75 from v1 to 1.5 and +1.41 from 1.5 to 1.6.⁶

Hardware requirements#

On NVIDIA GPUs, the requirement depends on which engine runs the VLM:¹

• T4 and V100 (CC 7.x) can start vLLM but the docs say it is "prone to timeouts or OOM" and not recommended. Use the PaddlePaddle engine on those cards.¹
• RTX 30/40/50 and A10/A100 are CC 8+ and qualify for every backend except that RTX 50 (Blackwell, CC 12) is outside the SGLang and FastDeploy range. Blackwell has its own guide: a driver supporting CUDA 12.9+ and -sm120 images.¹¹
• VRAM: no minimum is documented anywhere in the repo. The only memory guidance is a tuning tip for the NVIDIA RTX 3060: set gpu-memory-utilization: 0.7 for vLLM or FastDeploy.¹
• x64 CPU: the support matrix marks local PaddlePaddle inference on x64 CPU as supported, but the MCP server docs say "CPU inference is not recommended" for the VL series.¹¹⁶ We haven't timed it.

Which inference method works on which device#

The "+ server" rows run layout with PaddlePaddle on the client and the VLM on the named server. "Pending" means the docs mark it as in progress or not yet verified. The official matrix also covers Kunlunxin, Hygon, MetaX, Iluvatar and Intel Arc (see below). vLLM, SGLang and FastDeploy don't run natively on Windows, so use Docker there.¹

Install#

The VL guide asks for PaddlePaddle 3.2.1 or later and Python 3.9–3.13, and recommends a virtual environment. Don't install the CPU and GPU builds of PaddlePaddle side by side.¹

python -m venv .venv_paddleocr && source .venv_paddleocr/bin/activate
python -m pip install paddlepaddle-gpu==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/
python -m pip install -U "paddleocr[doc-parser]"

python -m venv .venv_paddleocr && source .venv_paddleocr/bin/activate
python -m pip install paddlepaddle==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
python -m pip install -U "paddleocr[doc-parser]"

# ~8 GB image with PaddlePaddle preinstalled; needs a driver for CUDA 12.6+
docker run -it --gpus all --network host --user root \
  ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-nvidia-gpu \
  /bin/bash
# then run the paddleocr CLI or Python inside the container
# offline variant (~10 GB): ...:latest-nvidia-gpu-offline

Two version notes from our own testing. With the plain PyPI paddlepaddle (3.3.1 at the time of writing), PP-OCRv6 inference on CPU crashed for us with a ConvertPirAttribute2RuntimeAttribute error — that's why we pin the exact version the guide names. And if you see A dependency error occurred during pipeline creation, you installed paddleocr without the [doc-parser] extra. Both are in our error fixer; the full matrix of OS and CUDA options is on the install page.

Python and CLI usage#

from paddleocr import PaddleOCRVL

pipeline = PaddleOCRVL()          # loads v1.6 by default
# pipeline = PaddleOCRVL(pipeline_version="v1.5")
# pipeline = PaddleOCRVL(engine="transformers")
# pipeline = PaddleOCRVL(device="cpu")   # Apple Silicon

for res in pipeline.predict("paper.png"):
    res.print()
    res.save_to_json(save_path="output")
    res.save_to_markdown(save_path="output")
    res.save_to_word(save_path="output")   # .docx

paddleocr doc_parser -i paper.png --save_path ./output

# pick a release, or switch engine
paddleocr doc_parser -i paper.png --pipeline_version v1.5 --save_path ./output
paddleocr doc_parser -i paper.png --engine transformers --save_path ./output

# fix rotated or curved pages first
paddleocr doc_parser -i photo.jpg --use_doc_orientation_classify True --use_doc_unwarping True

pipeline_version accepts exactly "v1", "v1.5" and "v1.6", which map to the PaddleX pipelines PaddleOCR-VL, PaddleOCR-VL-1.5 and PaddleOCR-VL-1.6.² Each result has the same parsing_res_list shape as PP-StructureV3 — block_label, block_content, block_bbox, block_order — and the save methods save_to_json, save_to_markdown, save_to_html, save_to_xlsx, save_to_word and save_to_img.¹

Multi-page PDFs: restructure_pages()#

A PDF gives you one result per page. To merge tables that continue across pages, rebuild heading levels across the whole document, or join everything into one result, pass the page list to restructure_pages():¹

from paddleocr import PaddleOCRVL

pipeline = PaddleOCRVL()
pages = list(pipeline.predict("report.pdf"))

# merge_tables and relevel_titles already default to True in the code
merged = pipeline.restructure_pages(pages, concatenate_pages=True)

for res in merged:        # one result with concatenate_pages=True
    res.save_to_markdown(save_path="output")

The signature in PaddleOCR 3.7.0 is restructure_pages(res_list, merge_tables=True, relevel_titles=True, concatenate_pages=False) and it returns a list.² The official example passes merge_tables=True, relevel_titles=True explicitly, which suggests they are off by default; they aren't. Only concatenate_pages needs turning on. A simpler concatenate_markdown_pages(markdown_list) helper, the one PP-StructureV3 has, also exists.

Parameters you'll actually use#

vl_rec_* settings go to the constructor; the rest can be set there or per call in predict(), except prompt_label, layout_shape_mode and the sampling controls, which are predict()-only. Defaults are from the usage doc and the 3.7.0 source; prompt_label values are from the PaddleX 3.7.2 code, which accepts six labels although its error message lists four.¹²³ One conflict: the docs give layout_threshold a default of 0.5, while the PaddleX configs use 0.3 for 1.5 and 1.6 and per-class 0.4–0.5 for v1.³ To see exactly what your pipeline will use, call pipeline.export_paddlex_config_to_yaml("vl.yaml"); after editing, pass the file back with PaddleOCRVL(paddlex_config="vl.yaml").²

Serving: vLLM, SGLang, FastDeploy, llama.cpp#

The quick-start path above runs everything in one Python process. The docs call that suitable for "rapid validation" and recommend a dedicated VLM inference server for production.¹ The split is: a VLM server runs only the 0.9B model; your client — still the PaddleOCRVL pipeline — runs layout analysis locally and sends crops to the server. Because the client still runs a layout model, the docs recommend running it on a GPU too.¹

Start the VLM server#

docker run -it --rm --gpus all --network host \
  ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest-nvidia-gpu \
  paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --host 0.0.0.0 --port 8118 --backend vllm

docker run -it --rm --gpus all --network host \
  ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-fastdeploy-server:latest-nvidia-gpu \
  paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --host 0.0.0.0 --port 8118 --backend fastdeploy

python -m venv .venv_vlm && source .venv_vlm/bin/activate
python -m pip install "paddleocr[doc-parser]"
paddleocr install_genai_server_deps vllm      # or: sglang, fastdeploy
paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --backend vllm --port 8118

# GGUF files: huggingface.co/PaddlePaddle/PaddleOCR-VL-1.6-GGUF
./build/bin/llama-server \
  -m /path/to/PaddleOCR-VL-1.6-GGUF.gguf \
  --mmproj /path/to/PaddleOCR-VL-1.6-GGUF-mmproj.gguf \
  --port 8111 --host 0.0.0.0 --temp 0

Commands are verbatim from the usage tutorial.¹ The vLLM and SGLang builds installed by install_genai_server_deps target CUDA 12.6, and vLLM/SGLang need FlashAttention 2.8.2. The Transformers engine can't share an environment with vLLM or SGLang because they need different transformers versions.¹ Server tuning goes in a YAML file passed with --backend_config (for example gpu-memory-utilization and max-num-seqs for vLLM).

Point the pipeline at it#

from paddleocr import PaddleOCRVL

pipeline = PaddleOCRVL(
    vl_rec_backend="vllm-server",      # or sglang-server, fastdeploy-server
    vl_rec_server_url="http://localhost:8118/v1",
    vl_rec_max_concurrency=16,         # tune for your GPU
)
for res in pipeline.predict("report.pdf"):
    res.save_to_markdown(save_path="output")

paddleocr doc_parser --input report.pdf \
  --vl_rec_backend vllm-server \
  --vl_rec_server_url http://localhost:8118/v1

# server started with plain `vllm serve` (port 8000): pass the HF repo id
paddleocr doc_parser --input report.pdf \
  --vl_rec_backend vllm-server \
  --vl_rec_server_url http://localhost:8000/v1 \
  --vl_rec_api_model_name 'PaddlePaddle/PaddleOCR-VL-1.6'

Managed VLM endpoints work the same way with --vl_rec_api_key. Per the docs, SiliconFlow serves only v1 and 1.5 (use pipeline_version="v1.5") and Novita AI only v1.¹

A full HTTP API#

For an HTTP endpoint that runs the entire pipeline, the docs offer a Docker Compose setup (listens on port 8080) or paddlex --serve --pipeline PaddleOCR-VL. Both process one request at a time; for concurrency the docs point to a separate high-performance serving (HPS) solution.¹ Our serving and API guide covers request formats and clients.

Published throughput (Baidu's numbers)#

Baidu reports end-to-end throughput for PaddleOCR-VL-1.5 on OmniDocBench v1.5 with one A100 and batches of 512: 1.4335 pages/s with FastDeploy 2.3, 1.1433 with vLLM 0.10.2 and 1.0091 with SGLang 0.5.2. In the same table MinerU2.5 on vLLM does 0.9984 pages/s.¹⁰ These tables exist only as images in the repo; we transcribed them. The 1.6 doc says inference speed is identical to 1.5.⁹ We have no GPU numbers of our own.

Apple Silicon, AMD, Ascend and other hardware#

Each accelerator has its own official guide, and each names one device it was verified on:¹¹

Hugging Face and Transformers#

The weights are on Hugging Face as PaddlePaddle/PaddleOCR-VL, -1.5 and -1.6, plus a GGUF build and the standalone PP-DocLayoutV3 layout model. The model cards include a raw Transformers example that sends one image with a task prompt such as OCR: or Table Recognition:; for 1.5 and 1.6 it needs transformers>=5.0.0.⁴ That's element-level recognition — useful for a cropped table or formula, but not a full-page parser. For whole documents through Transformers, keep the pipeline and switch its engine: PaddleOCRVL(engine="transformers").¹

The hosted API (no GPU needed)#

PaddleOCR 3.7.0 ships a client for the official hosted service, and its document-parsing default is PaddleOCR-VL-1.6.¹³ You need an access token from AI Studio. We checked the code against the 3.7.0 source but haven't called the service.

# export PADDLEOCR_ACCESS_TOKEN="..."
from paddleocr import PaddleOCRClient, Model

client = PaddleOCRClient()
result = client.parse_document(
    file_path="report.pdf",
    model=Model.PADDLE_OCR_VL_16,   # the default
)
for page in result.pages:
    print(page.markdown_text)
client.close()

export PADDLEOCR_ACCESS_TOKEN="..."
paddleocr api --model_type doc_parsing --file_path report.pdf

The AI Studio quota page says each user can parse up to 3,000 pages per model per day and that only the first 100 pages of a file are parsed; the async API guide says one request supports up to 1,000 PDF pages. The two official pages disagree, so test with your own files.¹⁴ No price is published on any page we could read. Details, SDKs for TypeScript and Go, and error codes are on our API page.

HPD-Parsing: the throughput-first sibling#

HPD-Parsing, announced July 22, 2026, is a separate ~1B document VLM built on InternVL3.5-1B for high-volume parsing. Instead of decoding a page as one long token stream, a main layout branch spawns content branches that decode in parallel, and Progressive Multi-Token Prediction (P-MTP) cuts decoding steps further.¹²

• Accuracy (self-reported): 94.91 overall on OmniDocBench v1.6. HPD-Parsing is not in the OmniDocBench README table, so there is no independent number; for comparison, PaddleOCR-VL-1.6 is 96.34 on that table.¹²⁶
• Speed (self-reported): 2.68 pages/s and 4,752.1 tokens/s on an A800 80GB with vLLM and batch 512, against 1.02 pages/s for an autoregressive baseline.¹²
• Requirements: NVIDIA GPU (verified on H100, H800, H20, A100, A800, A30, L20, RTX Pro 6000), driver for CUDA 12.8+, Linux x86-64, Python 3.10–3.13, and a custom vLLM build based on v0.17.1. It does not use the paddleocr package at all.¹²

docker run -it --rm --gpus all --network host \
  ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/hpd-parsing-vllm:latest-nvidia-gpu

The server listens on port 8118 and speaks the OpenAI API; clients send the fixed prompt document parsing with fork. with each page.¹² Pick HPD-Parsing when pages per GPU-hour matter more than the last point of accuracy and you're on a supported data-centre GPU; pick PaddleOCR-VL for accuracy, broader hardware support and the paddleocr tooling.

Fine-tuning#

The VLM can be fine-tuned with supervised fine-tuning through ERNIEKit; the layout and reading-order models can't.¹ One inconsistency: the v1 algorithm FAQ says fine-tuning is "not supported" in one answer and recommends ERNIEKit SFT in another. The usage tutorial's ERNIEKit section is the current guidance.

FAQ#