# Integrating PaddleOCR with Python Applications: From Basic OCR to Multimodal AI

> Integrate PaddleOCR with Python apps for advanced text recognition and document understanding. Leverage powerful OCR and multimodal AI with easy pipeline classes.

- Repository: [PaddlePaddle/PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR)
- Tags: tutorial
- Published: 2026-03-03

---

**PaddleOCR enables developers to embed high-performance text recognition, layout parsing, and document understanding into Python applications through modular pipeline classes that abstract complex deep-learning inference.**

PaddleOCR is an open-source OCR and document-AI toolkit built on the PaddlePaddle framework. Its Python API separates model wrappers, pipeline orchestrators, and CLI utilities, allowing developers to integrate production-ready OCR capabilities with minimal boilerplate code. Whether processing single images or building automated document processing workflows, the library provides consistent interfaces across detection, recognition, and multimodal understanding tasks.

## Architecture Overview

The PaddleOCR codebase follows a strict separation of concerns across four architectural layers, as implemented in the `PaddlePaddle/PaddleOCR` repository.

**Public API Layer** – The entry point in [`paddleocr/__init__.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/__init__.py) re-exports high-level classes like `PaddleOCR`, `PPStructureV3`, `PPChatOCRv4Doc`, and `PaddleOCRVL`, enabling simple `from paddleocr import` statements.

**Model Wrapper Layer** – Defined in [`paddleocr/_models/base.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_models/base.py), the abstract `PaddleXPredictorWrapper` class handles `paddlex` predictor creation via `_create_paddlex_predictor`, parses CLI arguments, and exposes a unified `predict()` method. Concrete implementations such as `TextRecognition` and `TextDetection` in [`paddleocr/_models/text_recognition.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_models/text_recognition.py) and corresponding detection files define `default_model_name` and model-specific initialization arguments.

**Pipeline Orchestrator Layer** – Located in `paddleocr/_pipelines/`, these classes combine multiple model wrappers to deliver end-to-end solutions. The `PaddleOCR` class orchestrates detection and recognition, while `PPStructureV3`, `PPChatOCRv4Doc`, and `PaddleOCRVL` handle layout parsing, conversational AI, and vision-language multimodal tasks respectively.

**CLI and Utilities** – The `PredictorCLISubcommandExecutor` in [`paddleocr/_models/base.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_models/base.py) enables command-line usage, while helper functions for image preprocessing and layout partitioning reside in [`ppstructure/utility.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/utility.py).

## Installation and Setup

Install the base package for standard OCR functionality or the full distribution for document-AI features including layout analysis and table recognition.

```bash

# Basic OCR (detection + recognition)

pip install paddleocr

# Full document-AI suite (includes layout, table, and multimodal models)

pip install "paddleocr[all]"

```

## Core Integration Patterns

### 1. Simple Text Detection and Recognition

For standard OCR tasks, instantiate the `PaddleOCR` pipeline class from [`paddleocr/_pipelines/ocr.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_pipelines/ocr.py). This orchestrates `TextDetection` and `TextRecognition` wrappers internally.

```python
from paddleocr import PaddleOCR

# Initialize with optional flags to disable expensive preprocessing

ocr = PaddleOCR(
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
    use_textline_orientation=False,
)

# Execute inference on a remote URL or local file path

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

# Process results - each item supports serialization and visualization

for line in result:
    line.print()                     # Human-readable console output

    line.save_to_img("outputs")      # Render bounding boxes to image files

    line.save_to_json("outputs")     # Export structured JSON data

```

The `predict()` method accepts `input` as a string path/URL or a NumPy array, returning `Result` objects that encapsulate bounding box coordinates, confidence scores, and recognized text.

### 2. Document Structure Analysis with PP-StructureV3

For complex documents containing tables, figures, and formulas, use the `PPStructureV3` pipeline from [`paddleocr/_pipelines/pp_structurev3.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_pipelines/pp_structurev3.py). This combines layout analysis with region-specific recognition models.

```python
from paddleocr import PPStructureV3

structure = PPStructureV3(
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
)

output = structure.predict(
    input="https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/pp_structure_v3_demo.png"
)

# Export structured elements to multiple formats

for element in output:
    element.print()
    element.save_to_json(save_path="struct_out")
    element.save_to_markdown(save_path="struct_out")

```

This pipeline automatically classifies document regions and applies appropriate models for tables, seals, or mathematical expressions.

### 3. Conversational Document Understanding

The `PPChatOCRv4Doc` class in [`paddleocr/_pipelines/doc_understanding.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_pipelines/doc_understanding.py) integrates visual OCR with large language models (LLMs) for retrieval-augmented generation (RAG) workflows.

```python
from paddleocr import PPChatOCRv4Doc

# Configure LLM and embedding endpoints (Qianfan or OpenAI-compatible)

chat_bot_cfg = {
    "module_name": "chat_bot",
    "model_name": "ernie-3.5-8k",
    "base_url": "https://qianfan.baidubce.com/v2",
    "api_type": "openai",
    "api_key": "YOUR_API_KEY",
}

retriever_cfg = {
    "module_name": "retriever",
    "model_name": "embedding-v1",
    "base_url": "https://qianfan.baidubce.com/v2",
    "api_type": "qianfan",
    "api_key": "YOUR_API_KEY",
}

pipeline = PPChatOCRv4Doc(
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
)

# Phase 1: Visual OCR with optional seal and table recognition

visual_res = pipeline.visual_predict(
    input="https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/vehicle_certificate-1.png",
    use_common_ocr=True,
    use_seal_recognition=True,
    use_table_recognition=True,
)

# Phase 2: Build vector store for semantic retrieval

vector_info = pipeline.build_vector(
    [r["visual_info"] for r in visual_res],
    flag_save_bytes_vector=True,
    retriever_config=retriever_cfg,
)

# Phase 3: Query the document using natural language

answer = pipeline.chat(
    key_list=["驾驶室准乘人数"],
    visual_info=[r["visual_info"] for r in visual_res],
    vector_info=vector_info,
    chat_bot_config=chat_bot_cfg,
    retriever_config=retriever_cfg,
)

print("Answer:", answer)

```

### 4. Multimodal Vision-Language OCR

For simultaneous text, layout, and visual understanding using a single vision-language model, use `PaddleOCRVL` from [`paddleocr/_pipelines/paddleocr_vl.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_pipelines/paddleocr_vl.py).

```python
from paddleocr import PaddleOCRVL

vl = PaddleOCRVL()
output = vl.predict(
    "https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/paddleocr_vl_demo.png"
)

for item in output:
    item.print()
    item.save_to_json("vl_out")
    item.save_to_markdown("vl_out")

```

### 5. Custom Model Integration

To integrate custom-trained models directly, subclass `PaddleXPredictorWrapper` from [`paddleocr/_models/base.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_models/base.py). This bypasses high-level pipelines while retaining argument parsing and predictor management.

```python
from paddleocr._models.base import PaddleXPredictorWrapper

class CustomRecognizer(PaddleXPredictorWrapper):
    @property
    def default_model_name(self):
        return "my_custom_rec"  # Model identifier in PaddleX zoo

    def _get_extra_paddlex_predictor_init_args(self):
        # Override default input specifications

        return {"input_shape": (3, 48, 320)}

# Direct instantiation and prediction

model = CustomRecognizer()
res = model.predict(input="my_image.png")
print(res)

```

## Key Source Files for Integration

Understanding these specific file locations helps when debugging or extending functionality:

- **[`paddleocr/__init__.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/__init__.py)** – Public API exports and package initialization.
- **[`paddleocr/_models/base.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_models/base.py)** – Abstract `PaddleXPredictorWrapper` class and CLI executor base; contains `_create_paddlex_predictor` logic.
- **[`paddleocr/_models/text_recognition.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_models/text_recognition.py)** – Concrete implementation for text recognition models.
- **[`paddleocr/_pipelines/ocr.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_pipelines/ocr.py)** – `PaddleOCR` pipeline implementation combining detection and recognition.
- **[`paddleocr/_pipelines/pp_structurev3.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_pipelines/pp_structurev3.py)** – Layout parsing and document structure extraction.
- **[`paddleocr/_pipelines/doc_understanding.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_pipelines/doc_understanding.py)** – Chat-style Q&A implementation (`PPChatOCRv4Doc`).
- **[`paddleocr/_pipelines/paddleocr_vl.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_pipelines/paddleocr_vl.py)** – Vision-language multimodal pipeline.
- **[`ppstructure/utility.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/utility.py)** – Helper functions for layout region sorting and merging.

## Summary

- **Standard OCR** – Use the `PaddleOCR` class for text detection and recognition; configure preprocessing flags like `use_doc_unwarping` to optimize performance.
- **Structured Documents** – Deploy `PPStructureV3` to parse tables, figures, and complex layouts into Markdown or JSON.
- **Intelligent Processing** – Leverage `PPChatOCRv4Doc` to combine OCR with LLMs for natural language querying of document content.
- **Multimodal Analysis** – Implement `PaddleOCRVL` for unified vision-language understanding of visual and textual content.
- **Extensibility** – Subclass `PaddleXPredictorWrapper` to inject custom models while maintaining the library's argument parsing and device management capabilities.

## Frequently Asked Questions

### How do I disable GPU acceleration in PaddleOCR?

Pass `use_gpu=False` when instantiating any pipeline class or model wrapper. For CPU optimization, add `enable_mkldnn=True` to leverage Intel MKL-DNN acceleration. These parameters propagate through `PaddleXPredictorWrapper` to the underlying `paddlex` predictor creation logic in [`paddleocr/_models/base.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_models/base.py).

### What is the difference between `PaddleOCR` and `PPStructureV3`?

`PaddleOCR` (defined in [`paddleocr/_pipelines/ocr.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_pipelines/ocr.py)) performs text detection and recognition only, returning bounding boxes and strings. `PPStructureV3` (in [`paddleocr/_pipelines/pp_structurev3.py`](https://github.com/PaddlePaddle/PaddleOCR/blob/main/paddleocr/_pipelines/pp_structurev3.py)) adds layout analysis, identifying document elements like tables, figures, and titles, then applies specialized models to each region. Use `PaddleOCR` for plain text extraction and `PPStructureV3` when you need to preserve document structure.

### Can I process images already loaded as NumPy arrays?

Yes. All pipeline `predict()` methods accept NumPy arrays via the `input` parameter, not just file paths or URLs. This enables integration with OpenCV preprocessing pipelines or web frameworks that receive image uploads as byte arrays converted to tensors.

### How do I save visualization results programmatically?

Result objects returned by `predict()` calls include `save_to_img()` methods that render bounding boxes and labels onto the source image. Specify a directory path as the argument; the library handles filename generation based on timestamps or input identifiers. For structured data, use `save_to_json()` to export coordinates, confidence scores, and text content.