PaddleOCR

https://www.paddleocr.ai/latest
Admin
PaddleOCR is an open-source OCR framework that provides state-of-the-art models for text detection,...
Tokens:335,389
Snippets:3,186
Trust Score:5.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Run PaddleOCR MCP Server Examples

Source: https://www.paddleocr.ai/latest/version3.x/integrations/mcp_server.html?q=

Various command-line examples for starting the server with different models, inference sources, and transport modes.

```bash
# PP-OCRv5 + 官方 API + stdio
PADDLEOCR_MCP_AISTUDIO_ACCESS_TOKEN=xxxxxx paddleocr_mcp --model PP-OCRv5 --ppocr_source aistudio

# PP-OCRv6 + 官方 API + stdio
paddleocr_mcp --model PP-OCRv6 --ppocr_source aistudio

# PP-StructureV3 + 本地推理 + stdio
paddleocr_mcp --model PP-StructureV3 --ppocr_source local

# OCR + 自建 API + Streamable HTTP
paddleocr_mcp --model PP-OCRv5 --ppocr_source self_hosted --self-hosted-base-url http://127.0.0.1:8080 --http
```

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

### Install FlashAttention Prebuilt Wheel

Source: https://www.paddleocr.ai/latest/version3.x/pipeline_usage/PaddleOCR-VL.html

Example command to install a precompiled FlashAttention wheel for environments lacking CUDA build tools.

```bash
python -m pip install https://github.com/mjun0812/flash-attention-prebuild-wheels/releases/download/v0.3.14/flash_attn-2.8.2+cu128torch2.8-cp310-cp310-linux_x86_64.whl
```

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

### Quick Start with Command Line

Source: https://www.paddleocr.ai/latest/version3.x/module_usage/doc_vlm.html?q=

This command-line example demonstrates how to quickly use the DocVLM module to process an image and query its content.

```APIDOC
## Quick Start

To quickly experience the DocVLM module, you can use the following command-line instruction:

```bash
paddleocr doc_vlm -i "{'image': 'https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/medal_table.png', 'query': '识别这份表格的内容, 以markdown格式输出'}"
```

This command uses the `paddle_dynamic` inference engine by default. Ensure you have PaddlePaddle installed according to the PaddlePaddle installation guide.
```

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

### Docker Compose Startup Output

Source: https://www.paddleocr.ai/latest/version3.x/pipeline_usage/PaddleOCR-VL-AMD-GPU.html

Example output observed after successfully starting the services.

```text
paddleocr-vl-api             | INFO:     Started server process [1]
paddleocr-vl-api             | INFO:     Waiting for application startup.
paddleocr-vl-api             | INFO:     Application startup complete.
paddleocr-vl-api             | INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
```

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

### Install and initialize pre-commit

Source: https://www.paddleocr.ai/latest/community/code_and_doc.html?q=

Setup commands for the pre-commit tool to manage Git hooks and ensure code formatting standards.

```bash
pip install pre-commit
pre-commit install
```

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

### Install SDK and Set Authentication

Source: https://www.paddleocr.ai/latest/version3.x/inference_deployment/serving/paddleocr_official_api/typescript.html

Install the package and set the access token via environment variable.

```bash
npm install @paddleocr/api-sdk
export PADDLEOCR_ACCESS_TOKEN="your-access-token"
```

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

### Install paddleocr-mcp from source

Source: https://www.paddleocr.ai/latest/version3.x/integrations/mcp_server.html

Installation method using the project repository.

```bash
git clone https://github.com/PaddlePaddle/PaddleOCR.git
pip install -e mcp_server
```

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

### Install and Install Pre-commit Hooks

Source: https://www.paddleocr.ai/latest/community/code_and_doc.html

Installs the 'pre-commit' tool and then installs the Git pre-commit hooks for the current repository. This helps in formatting code and performing checks before commits.

```bash
pip install pre-commit
pre-commit install
```

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

### Install OpenAI Client

Source: https://www.paddleocr.ai/latest/version3.x/pipeline_usage/HPD-Parsing.html

Install the required Python client library for API interaction.

```bash
python -m pip install openai
```

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

### Install paddleocr-mcp

Source: https://www.paddleocr.ai/latest/version3.x/integrations/mcp_server.html?q=

Commands to install the library from PyPI or source code.

```bash
pip install -U paddleocr-mcp
```

```bash
git clone https://github.com/PaddlePaddle/PaddleOCR.git
pip install -e mcp_server
```

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

### Install Skills from Local Repository

Source: https://www.paddleocr.ai/latest/version3.x/integrations/skills.html

Clone the repository and install skills from a local path if network issues occur.

```bash
git clone https://github.com/PaddlePaddle/PaddleOCR.git
npx skills add ./PaddleOCR/skills/paddleocr-text-recognition
npx skills add ./PaddleOCR/skills/paddleocr-doc-parsing
```

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

### Check CUDA Version and Install PaddlePaddle

Source: https://www.paddleocr.ai/latest/FAQ.html

Verify your CUDA version using `nvidia-smi` and install the corresponding PaddlePaddle GPU version. This is crucial for GPU environment setup.

```bash
nvidia-smi
```

```bash
pip install paddlepaddle-gpu==3.0.0 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html
```

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

### C++ Service Client Example

Source: https://www.paddleocr.ai/latest/version3.x/pipeline_usage/table_recognition_v2.html?q=

Initializes a client connection and prepares a file for transmission to the service.

```cpp
#include <iostream>
#include <fstream>
#include <vector>
#include <string>
#include "cpp-httplib/httplib.h" // https://github.com/Huiyicc/cpp-httplib
#include "nlohmann/json.hpp" // https://github.com/nlohmann/json
#include "base64.hpp" // https://github.com/tobiaslocker/base64

int main() {
    httplib::Client client("localhost", 8080);
    const std::string filePath = "./demo.jpg";
    std::ifstream file(filePath, std::ios::binary | std::ios::ate);
    if (!file) {
        std::cerr << "Error opening file." << std::endl;
        return 1;
    }
```

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

### Model Fine-tuning on Hardware

Source: https://www.paddleocr.ai/latest/version3.x/other_devices_support/multi_devices_use_guide.html

Configure environment variables and launch training scripts for Ascend NPU or Kunlun XPU.

```bash
export FLAGS_npu_storage_format=0
export FLAGS_npu_jit_compile=0
export FLAGS_use_stride_kernel=0
export FLAGS_allocator_strategy=auto_growth
export FLAGS_npu_split_aclnn=True
export FLAGS_npu_scale_aclnn=True
export CUSTOM_DEVICE_BLACK_LIST=pad3d,pad3d_grad
python3 -m paddle.distributed.launch --devices '0,1,2,3' \
        tools/train.py -c configs/rec/PP-OCRv5/PP-OCRv5_mobile_rec.yml \
        -o Global.use_gpu=False Global.use_npu=True
```

```bash
export FLAGS_use_stride_kernel=0
export BKCL_FORCE_SYNC=1
export BKCL_TIMEOUT=1800
export XPU_BLACK_LIST=pad3d,pad3d_grad
python3 -m paddle.distributed.launch --devices '0,1,2,3' \
        tools/train.py -c configs/rec/PP-OCRv5/PP-OCRv5_mobile_rec.yml \
        -o Global.use_gpu=False Global.use_xpu=True
```

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

### Prepare Dataset and Pretrained Model

Source: https://www.paddleocr.ai/latest/version3.x/module_usage/formula_recognition.html?q=

Download and extract the example dataset and the PP-FormulaNet_plus-M pretrained model.

```bash
# 下载示例数据集
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/ocr_rec_latexocr_dataset_example.tar
tar -xf ocr_rec_latexocr_dataset_example.tar
```

```bash
# 下载 PP-FormulaNet_plus-M 预训练模型
wget https://paddleocr.bj.bcebos.com/contribution/rec_ppformulanet_plus_m_train.tar 
tar -xf rec_ppformulanet_plus_m_train.tar
```

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

### Prepare Dataset and Pretrained Model

Source: https://www.paddleocr.ai/latest/version3.x/module_usage/table_structure_recognition.html

Commands to download the example dataset and the SLANet_plus pretrained model weights.

```bash
# 下载示例数据集
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/table_rec_dataset_examples.tar
tar -xf table_rec_dataset_examples.tar
```

```bash
# 下载 SLANet_plus 预训练模型
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/official_pretrained_model/SLANet_plus_pretrained.pdparams
```

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

### Install PaddleX

Source: https://www.paddleocr.ai/latest/version3.x/paddlex/quick_start.html?q=

Install PaddleX with OCR support. This command installs the core PaddleX library and OCR-specific components.

```bash
pip install "paddlex[ocr]"
```

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

### Install PaddleOCR.js

Source: https://www.paddleocr.ai/latest/version3.x/inference_deployment/cross_platform/browser.html

Install the package via npm.

```bash
npm install @paddleocr/paddleocr-js
```

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

### Set up Virtual Environment

Source: https://www.paddleocr.ai/latest/version3.x/pipeline_usage/PaddleOCR-VL.html

Commands to create and activate a Python virtual environment for the project.

```bash
python -m venv .venv_vlm
source .venv_vlm/bin/activate
```

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

### Install PaddlePaddle for CUDA 11.8

Source: https://www.paddleocr.ai/latest/FAQ.html?q=

Install the PaddlePaddle GPU version specifically for CUDA 11.8. Ensure your system has CUDA 11.8 installed and compatible drivers.

```bash
pip install paddlepaddle-gpu==3.0.0 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html
```

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

### Install PaddlePaddle with Specific CUDA Version

Source: https://www.paddleocr.ai/latest/FAQ.html?q=

Install the correct PaddlePaddle version that matches your CUDA version to avoid compatibility issues. Verify GPU availability after installation.

```bash
nvidia-smi
```

```bash
pip install paddlepaddle-gpu==3.0.0 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html
```

```python
python -c "import paddle; print(paddle.is_compiled_with_cuda())"
```

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

### 编译预测 demo

Source: https://www.paddleocr.ai/latest/version3.x/inference_deployment/local_inference/cpp/OCR.html

在配置好 tools/build.sh 后，执行此命令编译预测 demo。

```bash
sh tools/build.sh
```

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

### Start Inference Server with Configuration

Source: https://www.paddleocr.ai/latest/version3.x/pipeline_usage/PaddleOCR-VL.html

Launches the genai_server using a specific model and backend configuration file.

```bash
paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --backend vllm --backend_config vllm_config.yaml
```

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

### Start Inference Server with Inline Configuration

Source: https://www.paddleocr.ai/latest/version3.x/pipeline_usage/PaddleOCR-VL.html

Launches the genai_server using process substitution to pass configuration parameters directly without a file.

```bash
paddleocr genai_server --model_name PaddleOCR-VL-1.6-0.9B --backend vllm --backend_config <(echo -e 'gpu-memory-utilization: 0.3\nmax-num-seqs: 128')
```

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

### Verify Installation

Source: https://www.paddleocr.ai/latest/version3.x/integrations/mcp_server.html?q=

Command to verify that the paddleocr-mcp CLI is installed correctly.

```bash
paddleocr_mcp --help
```

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

### Install PaddleOCR

Source: https://www.paddleocr.ai/latest/version3.x/module_usage/text_detection.html

Commands to install the base or full version of the PaddleOCR package.

```bash
# 安装基础版本（仅包含文本检测功能）
pip install paddleocr

# 安装完整版本（包含所有功能）
pip install "paddleocr[all]"
```

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

### Prepare Dataset for Text Detection

Source: https://www.paddleocr.ai/latest/version3.x/module_usage/text_detection.html

Download and extract the example dataset required for training.

```bash
# 下载示例数据集
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/ocr_det_dataset_examples.tar
tar -xf ocr_det_dataset_examples.tar
```

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

### Install PaddleOCR Dependencies

Source: https://www.paddleocr.ai/latest/version3.x/integrations/skills.html

Install the required PaddleOCR package via pip.

```bash
pip install "paddleocr>=3.7.0"
```

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

### Successful Installation Output

Source: https://www.paddleocr.ai/latest/version3.x/other_devices_support/paddlepaddle_install_XPU.html

This is the expected output message confirming a successful PaddlePaddle installation.

```text
PaddlePaddle is installed successfully! Let's start deep learning with PaddlePaddle now.

```

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

### Start Server via PaddleX CLI

Source: https://www.paddleocr.ai/latest/version3.x/pipeline_usage/PaddleOCR-VL.html?q=

Launch the PaddleOCR-VL pipeline server.

```bash
paddlex --serve --pipeline PaddleOCR-VL
```

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

### Quick Start via Command Line

Source: https://www.paddleocr.ai/latest/version3.x/module_usage/doc_vlm.html

Execute a document visual language task directly from the terminal using the paddleocr command.

```bash
paddleocr doc_vlm -i "{'image': 'https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/medal_table.png', 'query': '识别这份表格的内容, 以markdown格式输出'}"
```

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

### Install Skills via Clawhub

Source: https://www.paddleocr.ai/latest/version3.x/integrations/skills.html

Install skills using the clawhub package manager.

```bash
clawhub install paddleocr-text-recognition
clawhub install paddleocr-doc-parsing
```

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

### Start Server with Transformers Engine

Source: https://www.paddleocr.ai/latest/version3.x/pipeline_usage/PaddleOCR-VL.html?q=

Launch the server using the transformers engine instead of the default.

```bash
paddlex --serve --pipeline PaddleOCR-VL --engine transformers
```

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

### Install FreeType Dependencies

Source: https://www.paddleocr.ai/latest/version3.x/inference_deployment/local_inference/cpp/OCR.html

Install the required system libraries for FreeType and HarfBuzz support.

```bash
sudo apt-get update
sudo apt-get install libfreetype6-dev libharfbuzz-dev
```

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

### Chart Parsing Output Example

Source: https://www.paddleocr.ai/latest/version3.x/module_usage/chart_parsing.html?q=

Example of the JSON output structure returned by the model.

```json
{'res': {'image': 'chart_parsing_02.png', 'result': '年份 | 单家五星级旅游饭店年平均营收 (百万元) | 单家五星级旅游饭店年平均利润 (百万元)\n2018 | 104.22 | 9.87\n2019 | 99.11 | 7.47\n2020 | 57.87 | -3.87\n2021 | 68.99 | -2.9\n2022 | 56.29 | -9.48\n2023 | 87.99 | 5.96'}}
```

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

### Table Recognition Service Client Examples

Source: https://www.paddleocr.ai/latest/version3.x/pipeline_usage/table_recognition_v2.html

Examples demonstrating how to send a file to the table recognition service and process the returned JSON results.

```python
import base64
import requests

API_URL = "http://localhost:8080/table-recognition"
file_path = "./demo.jpg"

with open(file_path, "rb") as file:
    file_bytes = file.read()
    file_data = base64.b64encode(file_bytes).decode("ascii")

payload = {"file": file_data, "fileType": 1}

response = requests.post(API_URL, json=payload)

assert response.status_code == 200
result = response.json()["result"]
for i, res in enumerate(result["tableRecResults"]):
    print(res["prunedResult"])
    for img_name, img in res["outputImages"].items():
        img_path = f"{img_name}_{i}.jpg"
        with open(img_path, "wb") as f:
            f.write(base64.b64decode(img))
        print(f"Output image saved at {img_path}")
```

```cpp
#include <iostream>
#include <fstream>
#include <vector>
#include <string>
#include "cpp-httplib/httplib.h" // https://github.com/Huiyicc/cpp-httplib
#include "nlohmann/json.hpp" // https://github.com/nlohmann/json
#include "base64.hpp" // https://github.com/tobiaslocker/base64

int main() {
    httplib::Client client("localhost", 8080);
    const std::string filePath = "./demo.jpg";
    std::ifstream file(filePath, std::ios::binary | std::ios::ate);
    if (!file) {
        std::cerr << "Error opening file." << std::endl;
        return 1;
    }
```

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

### Install PaddleOCR-VL Base Packages

Source: https://www.paddleocr.ai/latest/version3.x/pipeline_usage/PaddleOCR-VL.html?q=

Installs the core PaddleOCR-VL package after the inference engine is configured.

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

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

### Initialize Project Dependencies and Models

Source: https://www.paddleocr.ai/latest/version3.x/inference_deployment/cross_platform/ios_deployment.html?q=

Install CocoaPods dependencies and download the required ONNX models for the iOS demo.

```bash
pod install
./scripts/fetch_ios_demo_models.sh
```
Tokens:
Raw