PaddleOCR 3.5：使用 Transformers 后端运行 OCR 与文档解析任务

文章背景与核心概要

本文介绍了 PaddleOCR 3.5 版本的重大更新，该版本通过引入 Hugging Face Transformers 作为推理后端，成功将 OCR 和文档解析任务深度融入了 Hugging Face 生态系统。开发人员现在只需配置 engine="transformers"，即可利用熟悉的 Transformers 基础设施来运行 PP-OCRv5 和 PaddleOCR-VL 1.5 等领先模型，从而有效弥合了沉重的文档提取管道与以 PyTorch 为中心的架构之间的鸿沟。

文章详细阐述了新版本在推理引擎架构上的演进、支持 Transformers 后端的重要意义（特别是在优化 RAG 和 Agent 工作流的文档摄取瓶颈方面），并提供了详尽的快速上手指南。内容涵盖了环境安装、命令行与 Python API 的使用示例、针对特定硬件环境的性能微调参数配置，以及选择不同推理后端的适用场景指导。

PaddleOCR 3.5: Running OCR and Document Parsing Tasks with a Transformers Backend

Published: May 18, 2026
Authors: AlexZhang, cuicheng, Jun Zhang, Manhui Lin, Yue Zhang (PaddlePaddle)
Live Demo: Hugging Face Space

Executive Summary

PaddleOCR 3.5 integrates OCR and document parsing tasks with the Hugging Face ecosystem by introducing Hugging Face Transformers as an inference backend. Developers can now leverage models like PP-OCRv5 and PaddleOCR-VL 1.5 using familiar Transformers infrastructure simply by configuring engine="transformers", bridging the gap between heavy document ingestion pipelines and PyTorch-centric architectures.

PaddleOCR 3.5 通过引入 Hugging Face Transformers 作为推理后端，将 OCR 和文档解析任务与 Hugging Face 生态系统进行了深度集成。开发者现在只需配置 engine="transformers"，便可借助熟悉的 Transformers 基础设施来调用 PP-OCRv5 和 PaddleOCR-VL 1.5 等模型，从而消除了笨重的文档摄取管道与以 PyTorch 为中心的架构之间的隔阂。

What Changed?

PaddleOCR 3.5 introduces a flexible inference-engine interface. Developers can choose their runtime environment using the engine parameter while passing custom configurations via engine_config.

Pipeline Management: PaddleOCR continues to manage underlying OCR and document parsing logic internally, eliminating the need to manually invoke discrete components.
Backend Flexibility: Transformers joins the existing Paddle static and dynamic graph runtimes as a supported inference backend.
Granular Control: Configure parameters like dtype, hardware device placement, and attention implementations directly through engine_config.

有哪些改变？

PaddleOCR 3.5 引入了一个灵活的推理引擎接口。开发者可以通过 engine 参数选择运行时环境，同时通过 engine_config 传递自定义配置。

管道管理： PaddleOCR 继续在内部管理底层的 OCR 和文档解析逻辑，省去了手动调用各个独立组件的麻烦。

后端灵活性： Transformers 作为受支持的推理后端，加入了现有的 Paddle 静态图和动态图运行时行列。

精细化控制： 直接通过 engine_config 配置 dtype、硬件设备分配以及注意力机制（Attention）实现等参数。

Architecture Stack

Layer	Function	Examples
Application Layer	Consumes structured OCR and document outputs	RAG, AI Agents, Document AI
Model Layer	Provides OCR and document parsing capabilities	PP-OCRv5, PaddleOCR-VL 1.5
Inference Backend Layer	Executes underlying model operations	Paddle Static Graph, Paddle Dynamic Graph, Transformers

架构栈

层级功能示例

应用层 (Application Layer) 消费结构化的 OCR 和文档输出 RAG、AI Agent、文档 AI

模型层 (Model Layer) 提供 OCR 和文档解析能力 PP-OCRv5、PaddleOCR-VL 1.5

推理后端层 (Inference Backend Layer) 执行底层模型运算 Paddle 静态图、Paddle 动态图、Transformers

Why This Matters

For RAG, document parsing, and agent-based workflows, ingestion is often the biggest bottleneck. Turning complex layouts, tables, formulas, and scanned PDFs into accurate structured data is critical; failures here directly degrade downstream LLM accuracy.

By supporting Transformers as a backend, PaddleOCR 3.5 makes it easier to embed top-tier document ingestion tools directly into Hugging Face-native pipelines. This drastically reduces integration friction for teams building applications relying on PyTorch and Transformers ecosystems.

为什么这很重要

对于 RAG、文档解析以及基于 Agent 的工作流而言，数据摄取通常是最大的瓶颈。将复杂的版面、表格、公式和扫描版 PDF 转换为准确的结构化数据至关重要，此环节的失败会直接降低下游大语言模型（LLM）的准确性。

通过支持 Transformers 作为后端，PaddleOCR 3.5 使得将顶级文档摄取工具直接嵌入 Hugging Face 原生管道变得更加容易。这大大降低了依赖 PyTorch 和 Transformers 生态系统的团队在构建应用程序时的集成阻力。

Quick Start

1. Installation

Install PaddleOCR 3.5, PaddleX, Transformers, and a hardware-compatible PyTorch build (e.g., CUDA 12.6):

python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126
python -m pip install "paddleocr==3.5.0" "paddlex==3.5.2" "transformers>=5.4.0"

快速上手

1. 安装

安装 PaddleOCR 3.5、PaddleX、Transformers 以及与硬件兼容的 PyTorch 构建版本（例如 CUDA 12.6）：
python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126
python -m pip install "paddleocr==3.5.0" "paddlex==3.5.2" "transformers>=5.4.0"

2. Command Line Interface (CLI)

Run OCR via the terminal using the Transformers backend:

paddleocr ocr \
  -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_002.png \
  --device gpu:0 \
  --engine transformers

2. 命令行接口 (CLI)

使用 Transformers 后端通过终端运行 OCR：

paddleocr ocr \
  -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_002.png \
  --device gpu:0 \
  --engine transformers

3. Python API

Integrate the pipeline directly into your Python code:

from paddleocr import PaddleOCR

pipeline = PaddleOCR(
    device="gpu:0",
    engine="transformers",
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
    use_textline_orientation=False,
    engine_config={
        "dtype": "float32",
    },
)

results = pipeline.predict(
    "https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_002.png"
)

for result in results:
    print(result)

3. Python API

将流水线直接集成到您的 Python 代码中：

from paddleocr import PaddleOCR

pipeline = PaddleOCR(
    device="gpu:0",
    engine="transformers",
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
    use_textline_orientation=False,
    engine_config={
        "dtype": "float32",
    },
)

results = pipeline.predict(
    "https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_002.png"
)

for result in results:
    print(result)

Fine-Tuning Performance

To optimize performance for your specific hardware environment, adjust the parameters within engine_config:

engine_config = {
    "dtype": "bfloat16",
    "device_type": "gpu",
    "device_id": 0,
    "attn_implementation": "sdpa",
}

性能微调

为了针对您的特定硬件环境优化性能，请调整 engine_config 中的参数：
engine_config = {
    "dtype": "bfloat16",
    "device_type": "gpu",
    "device_id": 0,
    "attn_implementation": "sdpa",
}

When Should You Use the Transformers Backend?

Choose Transformers if: Your infrastructure heavily relies on Hugging Face ecosystems, PyTorch-native model distribution, Hub-compatible model discovery, and integrated MLOps workflows.
Choose Default paddle_static if: Maximizing high-throughput production OCR or document parsing performance is your primary objective.

什么时候应该使用 Transformers 后端？

如果您的基础设施严重依赖 Hugging Face 生态系统、PyTorch 原生模型分发、兼容 Hub 的模型发现以及集成的 MLOps 工作流，请选择 Transformers。

如果您的主要目标是 最大化高吞吐量的生产环境 OCR 或文档解析性能，请选择默认的 paddle_static。

Resources & Links

Live Demo: Hugging Face Space
Model Hub: PaddlePaddle Models on Hugging Face
Documentation: Official PaddleOCR Website
Source Code: PaddleOCR GitHub Repository

资源与链接

在线演示： Hugging Face Space

模型中心： Hugging Face 上的 PaddlePaddle 模型

官方文档： PaddleOCR 官方网站

源码： PaddleOCR GitHub 仓库

Acknowledgements

Special thanks to the Hugging Face engineering team for their invaluable support with the PaddleOCR 3.5 Transformers integration—particularly Anton Vlasjuk for end-to-end pull request reviews and merging, alongside Raushan Turganbay and Yoni Gozlan for invaluable technical feedback.

致谢

特别感谢 Hugging Face 工程团队对 PaddleOCR 3.5 Transformers 集成给予的大力支持——特别是 Anton Vlasjuk 负责端到端的 Pull Request 审查与合并，以及 Raushan Turganbay 和 Yoni Gozlan 提供的宝贵技术反馈。

层级	功能	示例
应用层 (Application Layer)	消费结构化的 OCR 和文档输出	RAG、AI Agent、文档 AI
模型层 (Model Layer)	提供 OCR 和文档解析能力	PP-OCRv5、PaddleOCR-VL 1.5
推理后端层 (Inference Backend Layer)	执行底层模型运算	Paddle 静态图、Paddle 动态图、Transformers