# https://github.com/PaddlePaddle/PaddleOCR 项目说明书 生成时间：2026-06-22 10:31:53 UTC ## 目录 - [项目概览与系统架构](#page-1) - [核心模型与算法体系](#page-2) - [部署与多平台集成](#page-3) - [配置、自定义与社区生态](#page-4) ## 项目概览与系统架构 ### 相关页面 相关主题：[核心模型与算法体系](#page-2), [部署与多平台集成](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/README.md) - [ppstructure/layout/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/layout/README.md) - [ppstructure/kie/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/kie/README.md) - [ppstructure/recovery/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/recovery/README.md) - [deploy/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/README.md) - [api_sdk/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/api_sdk/README.md) - [api_sdk/typescript/package.json](https://github.com/PaddlePaddle/PaddleOCR/blob/main/api_sdk/typescript/package.json) - [deploy/cpp_infer/src/configs/OCR.yaml](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/cpp_infer/src/configs/OCR.yaml) - [deploy/lite/readme.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/lite/readme.md) - [ppocr/utils/dict/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppocr/utils/dict/README.md)
# 项目概览与系统架构 ## 一、项目定位与核心能力 PaddleOCR 是由百度飞桨（PaddlePaddle）团队推出的开源 OCR 与文档智能工具集，目标是"将图片与 PDF 文档转换为结构化、LLM 可直接消费的数据（JSON / Markdown）" [README.md:1-20](README.md)。项目累计 70k+ Star，已被 Dify、RAGFlow、Cherry Studio 等知名 RAG / Agent 框架集成 [README.md:1-30](README.md)。 在能力维度上，PaddleOCR 形成了"两大主线 + 一套结构化能力"的格局： - **智能文档解析（LLM-Ready）**：以 PaddleOCR-VL-1.6（0.9B 参数的视觉语言模型）和 PP-StructureV3 为代表，支持文本、公式、表格、图表、古籍、印章等复杂元素识别，并输出 Markdown / JSON [README.md:1-50](README.md)。 - **通用场景文字识别（Scene OCR）**：以 PP-OCRv6 为代表的轻量化检测 + 识别流水线，单一模型支持 50 种语言（含中日英及 46 种拉丁语系），模型仅 34.5M 参数 [README.md:1-40](README.md)。 - **结构化下游任务**：在 `ppstructure/` 目录下提供版面分析（layout）、关键信息抽取（KIE）、版式恢复（recovery）、表格识别（table）等子模块 [ppstructure/layout/README.md:1-30](README.md) [ppstructure/kie/README.md:1-40](README.md) [ppstructure/recovery/README.md:1-20](README.md)。 最新发布版本 v3.7.0（2026.6.11）重点提升了 PP-OCRv6 的精度与多语言能力 [README.md:版本说明](README.md)。 ## 二、系统架构与流水线 PaddleOCR 采用"模块可拼装、流水线可配置"的架构设计。在 C++ 推理侧的默认配置文件 [deploy/cpp_infer/src/configs/OCR.yaml](deploy/cpp_infer/src/configs/OCR.yaml) 中可以看到完整流水线的标准形态： ```mermaid flowchart LR A[输入图片/PDF] --> B[DocPreprocessor] B --> B1[DocOrientationClassify
PP-LCNet_x1_0_doc_ori] B --> B2[DocUnwarping
UVDoc] B1 --> C[TextDetection
PP-OCRv6_medium_det] B2 --> C C --> D[TextLineOrientation
PP-LCNet_x1_0_textline_ori] D --> E[TextRecognition
PP-OCRv6_medium_rec] E --> F[结构化输出
Markdown/JSON] ``` 整体流水线由 `pipeline_name: OCR` 统筹，内部按 `SubPipelines` 与 `SubModules` 嵌套 [deploy/cpp_infer/src/configs/OCR.yaml:1-50](deploy/cpp_infer/src/configs/OCR.yaml)。每个子模块都声明了 `module_name` 与 `model_name`，既可独立替换，也可在 `model_dir` 中接入自训练权重。 在学术算法侧，PP-OCRv6 流水线则由三大经典环节组成 [README.md:特性说明](README.md)： 1. 文本检测（DB / EAST 等算法） 2. 文本行方向分类（可选） 3. 文本识别（CRNN / SVTR 等算法） 需要注意的是，PP-OCRv6 与 PP-StructureV3 是"并列但功能互补"的两条路线：前者输出纯文本结构，后者额外提供表格单元格坐标、文本框坐标等细粒度空间信息 [README.md:1-30](README.md)。 ## 三、子系统与组件构成 仓库的目录组织清晰对应上述能力： | 子目录 | 职责 | 代表模型/工具 | | --- | --- | --- | | `ppstructure/layout/` | 文档版面区域划分与关键区域定位 | PP-PicoDet（基于 PaddleDetection）[ppstructure/layout/README.md:1-20](README.md) | | `ppstructure/kie/` | 关键信息抽取（SER + RE） | VI-LayoutXLM、PP-OCR 推理引擎 [ppstructure/kie/README.md:1-50](README.md) | | `ppstructure/recovery/` | PDF/图片恢复为可编辑 Word | pdf2docx、版面+表格联合重建 [ppstructure/recovery/README.md:1-30](README.md) | | `ppocr/utils/dict/` | 字符级字典与语料管理 | 各语种字典文件 [ppocr/utils/dict/README.md:1-10](README.md) | | `deploy/` | 跨平台部署方案集合 | Python / C++ / Serving / Lite / ONNX [deploy/README.md:1-15](README.md) | | `api_sdk/` | 官方多语言 API 客户端 | Python、TypeScript、Go [api_sdk/README.md:1-15](README.md) | 版面分析模块支持 PubLayNet、TableBank、CDLA、DocBank 等多个公开数据集 [ppstructure/layout/README.md:数据集表格](README.md)；KIE 模块则基于 XFUND 等多语种数据集进行评估 [ppstructure/kie/README.md:2. Performance](README.md)。社区中关于"文本检测后切块留白对识别精度影响显著"的讨论（Issue #1663）也正反映了检测-切分-识别链条中各环节的紧密耦合。 ## 四、部署生态与多语言 SDK 为满足不同生产环境需求，PaddleOCR 提供了多层次的部署路径 [deploy/README.md:1-15](README.md)： - **Python 推理**：最常用入口，适合快速验证与服务端集成。 - **C++ 推理（`deploy/cpp_infer/`）**：通过 YAML 配置流水线，已在 `OCR.yaml` 中默认组装了 PP-OCRv6 medium 系列的检测 / 识别 / 方向分类模型 [deploy/cpp_infer/src/configs/OCR.yaml:1-50](deploy/cpp_infer/src/configs/OCR.yaml)。 - **Paddle Serving（Python/C++）**：面向高并发在线服务。 - **Paddle-Lite 移动端部署**：通过模型优化后在 ARM CPU / OpenCL ARM GPU 上推理 [deploy/lite/readme.md:1-20](README.md)。 - **Paddle2ONNX**：导出为 ONNX 格式，便于跨框架集成。 官方同时在 `api_sdk/` 下提供三种语言的官方 API 客户端 [api_sdk/README.md:1-20](README.md)： - **Python SDK**：源码位于仓库 `paddleocr/` 包。 - **TypeScript SDK**：基于 `tsup` 打包，依赖 Node ≥ 18，使用 `vitest` 进行测试 [api_sdk/typescript/package.json:1-30](package.json)。 - **Go SDK**：使用 `go test ./...` 执行单元测试。 各 SDK 共享同一套官方 REST API，文档分别维护在 `docs/version3.x/inference_deployment/serving/paddleocr_official_api/` 目录下 [api_sdk/README.md:1-20](README.md)。 ## 五、典型工作流总结 一个典型的 PaddleOCR 使用流程可概括为： 1. **环境准备**：通过 pip 安装 PaddlePaddle（GPU 或 CPU 版）[ppstructure/layout/README.md:3.1](README.md)； 2. **任务选择**：根据场景选择 PP-OCRv6（轻量场景文字）、PP-StructureV3（结构化文档）或 PaddleOCR-VL（复杂文档理解）； 3. **流水线组装**：以 YAML 或 Python API 声明检测、识别、方向分类、版式分析等模块 [deploy/cpp_infer/src/configs/OCR.yaml:1-50](deploy/cpp_infer/src/configs/OCR.yaml)； 4. **推理与导出**：通过 Python / C++ / Lite / ONNX 等不同方式执行，必要时导出为 ONNX 或蒸馏版 [ppstructure/layout/README.md:5-7](README.md)； 5. **服务化**：借助官方 SDK（Python/TS/Go）调用在线 API，或自建 Paddle Serving 服务 [api_sdk/README.md:1-20](README.md)。 ## 六、See Also - [PP-OCRv6 场景文字识别流水线](PP-OCRv6场景文字识别流水线.md) - [PP-Structure 文档结构化解析](PP-Structure文档结构化解析.md) - [PaddleOCR-VL 视觉语言模型](PaddleOCR-VL视觉语言模型.md) - [多语言 SDK 集成指南](多语言SDK集成指南.md) --- ## 核心模型与算法体系 ### 相关页面 相关主题：[项目概览与系统架构](#page-1), [部署与多平台集成](#page-3), [配置、自定义与社区生态](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/README.md) - [ppstructure/kie/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/kie/README.md) - [ppstructure/layout/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/layout/README.md) - [ppstructure/recovery/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/recovery/README.md) - [deploy/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/README.md) - [deploy/cpp_infer/src/configs/OCR.yaml](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/cpp_infer/src/configs/OCR.yaml) - [api_sdk/typescript/package.json](https://github.com/PaddlePaddle/PaddleOCR/blob/main/api_sdk/typescript/package.json) - [ppocr/utils/dict/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppocr/utils/dict/README.md)
# 核心模型与算法体系 ## 1. 模型体系总览 PaddleOCR 构建了一套由「轻量 OCR 引擎」与「多模态文档大模型」双轨驱动的算法体系。顶层定位为「将视觉内容转化为 LLM 就绪的结构化数据（JSON / Markdown）」，同时提供面向复杂版式文档的 PP-StructureV3 流水线 资料来源：[README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/README.md)。在 v3.7.0 版本中，PP-OCRv6 进一步以 34.5M 的极小参数量在中等规模档位实现了对主流 VLM（Qwen3-VL-235B、GPT-5.5）的精度超越，并单一模型统一支持中文、英文、日文及 46 种拉丁语系语言 资料来源：[README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/README.md)。 整个算法体系按照「场景 OCR」与「文档解析」两条主线进行组织，整体架构如下： ```mermaid flowchart TB A[输入: 图像 / PDF] --> B{任务类型} B -- 场景文本 --> C[PP-OCRv6
检测 + 识别 + 方向分类] B -- 文档解析 --> D[PP-StructureV3] B -- 复杂版式 --> E[PaddleOCR-VL
VLM-0.9B] C --> F[结构化输出] D --> G[布局分析
表格识别
KIE
版面恢复] E --> F G --> F F --> H[JSON / Markdown / docx] ``` ## 2. PP-OCRv6 文本识别套件 PP-OCRv6 是面向场景文字的端到端识别系统，采用经典的「文本检测 + 文本识别」两阶段管线，辅以文本行方向分类与版面预处理。在部署配置中，其默认子模块组合如下 资料来源：[deploy/cpp_infer/src/configs/OCR.yaml](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/cpp_infer/src/configs/OCR.yaml)： - `DocPreprocessor`：使用 `PP-LCNet_x1_0_doc_ori` 进行文档方向分类，配合 `UVDoc` 模型完成扭曲矫正。 - `TextDetection`：默认采用 `PP-OCRv6_medium_det`，关键超参包括 `thresh=0.3`、`box_thresh=0.6`、`unclip_ratio=1.5`。 - `TextLineOrientation`：使用 `PP-LCNet_x1_0_textline_ori`，`batch_size=6`。 - `TextRecognition`：使用 `PP-OCRv6_medium_rec`，`score_thresh=0.0`。 整套管线通过 `pipeline_name: OCR` 进行声明式编排，并支持子流水线嵌套（`SubPipelines` 与 `SubModules`） 资料来源：[deploy/cpp_infer/src/configs/OCR.yaml](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/cpp_infer/src/configs/OCR.yaml)。 多语言字典文件统一托管在 `ppocr/utils/dict/` 目录，社区可通过该目录贡献词表（如缅甸语字符集） 资料来源：[ppocr/utils/dict/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppocr/utils/dict/README.md)。 ## 3. PaddleOCR-VL 多模态文档解析 PaddleOCR-VL 是一款面向资源高效推理的文档解析 VLM，核心参数规模为 0.9B，结合了 NaViT 风格的动态高分辨率视觉编码器与 ERNIE-4.5 语言模型 资料来源：[README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/README.md)。其关键特性包括： - 单一模型支持 109 种语言，在公开基准（OmniDocBench v1.6）上达到 96.3% 准确率 资料来源：[README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/README.md)。 - 支持文本、表格、公式、图表等复杂元素的识别，并输出结构化 Markdown / JSON。 - 1.5 版本引入了 **PP-DocLayoutV3** 算法，专门处理倾斜、扭曲、扫描、光照变化、屏幕拍摄等 5 类困难场景，并将语言支持扩展到 111 种 资料来源：[README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/README.md)。 需要注意的是，社区已报告在 PaddleX 3.6 SDK 默认配置下 `returnMarkdownImages=false` 参数失效的问题（#18194），这是 VLM 在客户端集成时需要重点验证的兼容性点。 ## 4. PP-StructureV3 结构化理解 PP-StructureV3 在 PP-OCRv6 之上串联了布局分析、表格识别、关键信息抽取（KIE）与版面恢复四大模块： ### 4.1 布局分析 布局分析基于 PaddleDetection 的轻量级 PP-PicoDet，提供英文、英文表格、中文 CDLA 三套预训练模型，类别涵盖 Text、Title、Table、Figure、Header、Footer、Reference、Equation 等 资料来源：[ppstructure/layout/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/layout/README.md)。可使用 PubLayNet 预训练模型进行快速验证 资料来源：[ppstructure/layout/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/layout/README.md)。 ### 4.2 关键信息抽取（KIE） KIE 模块基于多模态预训练模型，在 LayoutXLM 基础上提出 VI-LayoutXLM，去除下游微调时的视觉特征依赖，并通过 UDML 知识蒸馏提升精度 资料来源：[ppstructure/kie/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/kie/README.md)。该模块支持两类子任务： | 子任务 | 功能描述 | XFUND 中文 Hmean | | --- | --- | --- | | SER（语义实体识别） | 识别图像中文本的语义类别 | 93.19% | | RE（关系抽取） | 抽取文本之间的关系（如问句对） | 74.83% | 资料来源：[ppstructure/kie/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/kie/README.md)。 ### 4.3 版面恢复 版面恢复支持两种 PDF 解析策略：标准 PDF 通过 `pdf2docx` 抽取并基于规则重建；图像型 PDF 则串联布局分析与表格识别来恢复复杂版式 资料来源：[ppstructure/recovery/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/recovery/README.md)。 ## 5. 部署与 SDK 生态 PaddleOCR 提供多语言官方 SDK（Python、TypeScript、Go）以及多种推理后端 资料来源：[api_sdk/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/api_sdk/README.md)。其中 TypeScript SDK 锁定 `node>=18`，使用 `tsup` 打包、`vitest` 测试，并通过 `prepublishOnly` 钩子强制执行 lint → build → test 流程 资料来源：[api_sdk/typescript/package.json](https://github.com/PaddlePaddle/PaddleOCR/blob/main/api_sdk/typescript/package.json)。推理侧涵盖 Python、C++、PaddleServing、Paddle-Lite（ARM CPU / OpenCL ARM GPU）、Paddle2ONNX 等多种方案 资料来源：[deploy/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/README.md)。 ## 6. 常见失败模式与社区关注点 - **检测后文本行留白影响识别**：社区实践表明，文本检测裁剪出的长条图片若边缘留白 5 像素左右，识别效果显著下降，建议通过最大外接矩形裁剪将留白压缩到 1–2 像素（参考 Issue #1663）。 - **多语言扩展**：长期社区诉求聚焦多语种统一模型，PP-OCRv6 已通过单一模型支持 50 种语言回应此需求（Issue #1048）。 - **SDK 兼容性**：Windows 下与 torch 共存时可能触发 `OSError [WinError 127]`，需注意 Python 与 torch 轮子的匹配（Issue #14979）。 ## See Also - [PaddleOCR 主仓库 README](../README.md) - [PP-OCR 部署指南](../deploy/README.md) - [布局分析模块](../ppstructure/layout/README.md) - [关键信息抽取（KIE）模块](../ppstructure/kie/README.md) - [版面恢复模块](../ppstructure/recovery/README.md) --- ## 部署与多平台集成 ### 相关页面 相关主题：[项目概览与系统架构](#page-1), [核心模型与算法体系](#page-2), [配置、自定义与社区生态](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [deploy/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/README.md) - [README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/README.md) - [api_sdk/typescript/package.json](https://github.com/PaddlePaddle/PaddleOCR/blob/main/api_sdk/typescript/package.json) - [deploy/android_demo/app/src/main/cpp/ocr_clipper.hpp](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/android_demo/app/src/main/cpp/ocr_clipper.hpp) - [deploy/android_demo/app/src/main/cpp/ocr_clipper.cpp](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/android_demo/app/src/main/cpp/ocr_clipper.cpp) - [ppstructure/layout/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/layout/README.md) - [ppstructure/recovery/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/recovery/README.md) - [ppstructure/kie/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/kie/README.md)
# 部署与多平台集成 ## 1. 概述 PaddleOCR 提供了从服务端到端侧、从原生 C++ 到浏览器与移动端的多种部署形态,以满足不同业务场景对算力、延迟与吞吐的要求。在 `deploy/README.md` 中明确列出,PP-OCR 已支持五种主要部署方案:Python 推理、C++ 推理、Python/C++ Serving 服务化部署、Paddle-Lite(ARM CPU / OpenCL ARM GPU)以及 Paddle2ONNX。资料来源:[deploy/README.md:1-30]() 围绕文档解析主线,`ppstructure/layout/README.md`、`ppstructure/recovery/README.md` 与 `ppstructure/kie/README.md` 等子模块同时给出可在 CPU/GPU 上运行的 Python 推理流程,并通过 `paddle2onnx` 与 PaddleInference 导出图,使其可以接入上述任意部署通道。 ```mermaid flowchart LR subgraph Train["训练 / 模型产出"] A[PP-OCR / PP-Structure / PaddleOCR-VL] end subgraph Deploy["部署形态"] B1[Python Inference] B2["C++ Inference (Linux/Windows)"] B3[Serving Python/C++] B4[Paddle-Lite ARM CPU/ GPU] B5[Paddle2ONNX] B6[Android Demo + JNI] B7[TypeScript SDK] end subgraph Runtime["运行时环境"] C1[Server GPU/CPU] C2[ARM 端侧设备] C3[Android APK] C4[Web/Node.js 应用] end A --> B1 --> C1 A --> B2 --> C1 A --> B3 --> C1 A --> B4 --> C2 A --> B5 --> C1 A --> B6 --> C3 A --> B7 --> C4 ``` ## 2. 服务端部署方案 PaddleOCR 官方部署文档入口位于 `deploy/README.md`,提供了 Paddle 框架层面的部署全景图。核心选项如下: | 部署方式 | 主要场景 | 入口文档 | | --- | --- | --- | | Python 推理 | 服务端 GPU/CPU 快速验证 | [Python Inference 文档](../doc/doc_en/inference_ppocr_en.md) | | C++ 推理 | 性能敏感的生产服务,Linux/Windows 本地部署 | [deploy/cpp_infer/readme.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/cpp_infer/readme.md) | | Serving (Python/C++) | 客户端远程调用、网关化部署 | [deploy/pdserving/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/pdserving/README.md) | | Paddle-Lite | ARM CPU / OpenCL ARM GPU 嵌入式端侧推理 | [deploy/lite/readme.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/lite/readme.md) | | Paddle2ONNX | 将动态图模型导出为 ONNX,便于跨框架部署 | [deploy/paddle2onnx/readme.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/paddle2onnx/readme.md) | 资料来源:[deploy/README.md:18-28]() PP-Structure 子模块同样遵循统一部署约定: - 布局分析(layout)导出模型基于 PP-PicoDet,可使用 PaddleInference 在服务端或边缘端推理。资料来源:[ppstructure/layout/README.md:18-28]() - 版面恢复(recovery)同时支持标准 PDF 解析(`pdf2docx` 路径)与图像型 PDF 解析(组合版面/表格识别)。资料来源:[ppstructure/recovery/README.md:13-22]() - KIE 模块支持 SER 模型导出与 PaddleInference 推理,文档明确写出"支持 SER 模型导出和推理使用 PaddleInference"。资料来源:[ppstructure/kie/README.md:23-30]() ## 3. C++ 跨平台与服务端部署 从 v3.2.0 起,PaddleOCR 对 C++ 本地部署做了重大升级,主要特性包括: - 同时支持 Linux 与 Windows 操作系统。 - 与 Python 实现在精度与功能上保持一致(feature parity)。 - 高性能推理后端开启 CUDA 加速。 资料来源:[README.md:releases-3.2.0]() C++ 推理入口与示例位于 `deploy/cpp_infer` 目录,其 README 详细描述了模型转换、依赖编译以及如何通过 PaddleInference C++ API 调用 OCR、版面与表格流水线。结合 Paddle2ONNX 导出,开发者可在不支持 PaddlePaddle 的容器镜像中,通过 ONNX Runtime 或 TensorRT 加载同一份模型,从而进一步扩展部署面。 ## 4. 移动端与多语言 SDK 集成 ### 4.1 Android 端侧 Demo `deploy/android_demo` 提供了端侧 OCR 的完整工程骨架。其中 `app/src/main/cpp/ocr_clipper.cpp` 与 `ocr_clipper.hpp` 引入了 Clipper 多边形裁剪库(版本 `CLIPPER_VERSION "6.4.2"`),负责对文本检测结果做几何后处理。资料来源:[deploy/android_demo/app/src/main/cpp/ocr_clipper.hpp:1-39]()、[deploy/android_demo/app/src/main/cpp/ocr_clipper.cpp:1-45]() 通过 JNI 把 C++ 推理引擎桥接到 Kotlin/Java 层,可避免对服务端网络的依赖,适合票据扫描、表单识别等离线场景。 ### 4.2 TypeScript / Node.js SDK 仓库根目录下提供 `api_sdk/typescript` 包,目标是让 Web 应用与 Node.js 后端可以调用官方 PaddleOCR API。该 SDK 的关键约束记录在 `package.json` 中: - 运行依赖 Node.js ≥ 18。 - 使用 `tsup` 打包,使用 `vitest` 运行单元测试。 - 关键词:`paddleocr`、`ocr`、`document-parsing`、`api-sdk`、`typescript`、`official-api`,表明该包定位为官方维护的 API 客户端。 资料来源:[api_sdk/typescript/package.json:1-29]() ## 5. 常见问题与注意事项 - **Windows 环境下 torch 兼容性问题**:社区用户在安装 `torch` 时遇到过 `OSError [WinError 127]`,影响在 Windows 平台上独立使用某些 PyTorch 路径的部署脚本。建议在 Windows 上优先使用 PaddlePaddle 原生部署或 C++ 推理,而非混合 PyTorch 运行时。资料来源:[社区 Issue #14979]() - **C++ 与 Python 部署对齐**:升级到 v3.2.0 及之后版本时,应重新导出并替换线上 C++ 模型,以保证与 Python 推理一致的能力。资料来源:[README.md:releases-3.2.0]() - **第三方封装库审计**:社区曾出现对 PaddleOCRSharp 等第三方封装包含可疑系统调用的讨论,建议在生产部署前审查依赖源码并锁定版本。资料来源:[社区 Issue #17479]() - **链接失效与文档健康度**:仓库 Issue 中持续有大量 Link Checker 报告,涉及 `docs/datasets`、`docs/community` 等文档链接需要定期刷新,以确保多平台部署指南中的引用有效。资料来源:[社区 Issue #18131 / #18157]() ## 6. See Also - [PP-OCR 部署入口](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/README.md) - [PP-Structure 版面分析](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/layout/README.md) - [PP-Structure 版面恢复](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/recovery/README.md) - [PP-Structure KIE](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/kie/README.md) - [PaddleOCR 主 README 与版本说明](https://github.com/PaddlePaddle/PaddleOCR/blob/main/README.md) - [官方 TypeScript SDK](https://github.com/PaddlePaddle/PaddleOCR/blob/main/api_sdk/typescript/package.json) --- ## 配置、自定义与社区生态 ### 相关页面 相关主题：[项目概览与系统架构](#page-1), [核心模型与算法体系](#page-2), [部署与多平台集成](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/README.md) - [ppstructure/kie/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/kie/README.md) - [ppstructure/layout/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/layout/README.md) - [ppstructure/recovery/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/recovery/README.md) - [api_sdk/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/api_sdk/README.md) - [api_sdk/typescript/package.json](https://github.com/PaddlePaddle/PaddleOCR/blob/main/api_sdk/typescript/package.json) - [deploy/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/README.md) - [deploy/lite/readme.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/lite/readme.md) - [ppocr/utils/dict/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppocr/utils/dict/README.md)
# 配置、自定义与社区生态 ## 1. 概述与生态全景 PaddleOCR 并不只是一个固定的 OCR 模型仓库，而是一套围绕"配置—自定义—部署—社区"展开的工程化生态。仓库顶层 `README.md` 将其定位为"PDF 与图像到结构化数据"的转换引擎，并明确区分了三类产品线：用于文档解析的 PaddleOCR-VL 系列、用于场景文字识别的 PP-OCRv6（v3.7.0 起统一支持 50 种语言）以及用于结构化版面恢复的 PP-StructureV3 资料来源：[README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/README.md)。 围绕这三条主线，PaddleOCR 提供了多层级的"配置入口"与"扩展点"：模型结构由 `configs/` 下的 YAML 驱动；PP-Structure 子模块（KIE、版面分析、版面恢复）各自拥有独立训练与推理流程；`api_sdk/` 同时维护 Python、TypeScript、Go 三种官方客户端，便于在不同语言栈中嵌入相同能力 资料来源：[api_sdk/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/api_sdk/README.md)。社区用户在使用过程中提出的典型问题（如图文识别无输出、文本检测 padding 过大导致识别下降、多语言覆盖）也直接影响官方配置字典与文档的演进方向 资料来源：[README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/README.md)。 ## 2. 模块级配置与自定义训练 PP-Structure 下的 KIE 模块使用 LayoutXLM/VI-LayoutXLM 多模态模型，通过 SER 与 RE 两类子任务完成关键信息抽取。仓库在 `ppstructure/kie/README.md` 中提供了完整的任务清单与 XFUND 中文基准结果，例如 `ser_vi_layoutxlm_xfund_udml.yml` 在 Hmean 93.19% 的水平上支持语义实体识别，并允许替换为自定义数据集进行再训练 资料来源：[ppstructure/kie/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/kie/README.md)。 版面分析模块以 PaddleDetection 的 PP-Picodet 为骨干，提供中、英、表格三种预训练权重，并允许通过 FGD 蒸馏进一步压缩；`ppstructure/layout/README.md` 详细给出了 PubLayNet、TableBank、DocBank 等数据集接入方式与训练命令 资料来源：[ppstructure/layout/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/layout/README.md)。版面恢复模块则根据 PDF 输入形态提供两种恢复策略——基于 `pdf2docx` 的标准 PDF 解析与结合版面分析 + 表格识别的图像 PDF 解析，使自定义结果可输出为 docx 资料来源：[ppstructure/recovery/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/recovery/README.md)。 ```mermaid flowchart LR A[YAML 配置] --> B[训练 Pipeline] B --> C[导出推理模型] C --> D{Python 推理} C --> E{Paddle Lite / ONNX} C --> F{TypeScript / Go SDK} D --> G[文档结构化输出] E --> G F --> G ``` ## 3. 部署形态与多语言 SDK 仓库在 `deploy/README.md` 中将 PP-OCR 的部署方案划分为五条路径：Python 推理、C++ 推理、PaddleServing、Paddle-Lite 移动端、Paddle2ONNX 跨框架导出，覆盖从服务器到 ARM 端侧的全场景 资料来源：[deploy/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/README.md)。其中 `deploy/lite/readme.md` 描述了基于 Paddle-Lite 在 ARM7/ARM8 手机上部署轻量检测模型的标准流程：先准备交叉编译环境，再使用 `optimize_tool` 将模型转为 nb 格式，最后在 App 中加载运行 资料来源：[deploy/lite/readme.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/lite/readme.md)。 API 客户端层面对社区尤为友好：`api_sdk/` 同时托管 Python、TypeScript、Go 三种官方 SDK，并各自维护测试套件（如 `npm test`、`pytest tests/api_client/`、`go test ./...`），可作为项目集成与 CI 校验的统一基线 资料来源：[api_sdk/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/api_sdk/README.md)。TypeScript 包在 `api_sdk/typescript/package.json` 中显式声明 `engines.node >=18` 与 `tsup` 构建流程，保证发布到 npm 的产物一致性 资料来源：[api_sdk/typescript/package.json](https://github.com/PaddlePaddle/PaddleOCR/blob/main/api_sdk/typescript/package.json)。 ## 4. 社区贡献与字典语料 字符字典是 OCR 自定义扩展的核心切入点。`ppocr/utils/dict/README.md` 集中托管各语种的字符级词表，并要求第三方语料（如 Burmese 语料）在引用时注明版权来源 资料来源：[ppocr/utils/dict/README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppocr/utils/dict/README.md)。在顶层 `README.md` 中，PP-OCRv6 已实现"50 语言统一模型"，意味着新增语言通常以字典 + 合成数据的形式接入，而无需切换主模型 资料来源：[README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/README.md)。 社区治理方面，仓库通过 Issue 自动化的 Link Checker 持续扫描文档失效链接，并公开报告统计（错误、重定向、超时分类），例如 `docs/community/community_contribution.md` 中的失效 CSDN 链接被多次扫描记录 资料来源：[README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/README.md)。同时，多语言 OCR 路线图（#1048）等高互动议题直接影响官方字典扩容策略，使社区需求能够反向驱动配置生态的演进 资料来源：[README.md](https://github.com/PaddlePaddle/PaddleOCR/blob/main/README.md)。 ## See Also - [PP-OCR 部署总览](https://github.com/PaddlePaddle/PaddleOCR/blob/main/deploy/README.md) - [KIE 关键信息抽取](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/kie/README.md) - [版面分析](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/layout/README.md) - [版面恢复](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppstructure/recovery/README.md) - [API SDK 总览](https://github.com/PaddlePaddle/PaddleOCR/blob/main/api_sdk/README.md) - [字典与语料](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppocr/utils/dict/README.md) --- --- ## Doramagic 踩坑日志 项目：PaddlePaddle/PaddleOCR 摘要：发现 14 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: Link Checker Report。 ## 1. 安装坑 · 失败模式：installation: Link Checker Report - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Link Checker Report - 对用户的影响：Developers may fail before the first successful local run: Link Checker Report - 证据：failure_mode_cluster:github_issue | https://github.com/PaddlePaddle/PaddleOCR/issues/18134 | Link Checker Report, failure_mode_cluster:github_issue | https://github.com/PaddlePaddle/PaddleOCR/issues/18131 | Link Checker Report, failure_mode_cluster:github_issue | https://github.com/PaddlePaddle/PaddleOCR/issues/18126 | Link Checker Report, failure_mode_cluster:github_issue | https://github.com/PaddlePaddle/PaddleOCR/issues/18122 | Link Checker Report, failure_mode_cluster:github_issue | https://github.com/PaddlePaddle/PaddleOCR/issues/18103 | Link Checker Report ## 2. 安装坑 · 失败模式：installation: 图片识别没有文字输出。 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: 图片识别没有文字输出。 - 对用户的影响：Developers may fail before the first successful local run: 图片识别没有文字输出。 - 证据：failure_mode_cluster:github_issue | https://github.com/PaddlePaddle/PaddleOCR/issues/17974 | 图片识别没有文字输出。 ## 3. 安装坑 · 来源证据：Link Checker Report - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Link Checker Report - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/PaddlePaddle/PaddleOCR/issues/18157 | 来源类型 github_issue 暴露的待验证使用条件。 ## 4. 安装坑 · 来源证据：PaddleOCR-VL HPS: returnMarkdownImages=false is ineffective with default PaddleX 3.6 SDK - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：PaddleOCR-VL HPS: returnMarkdownImages=false is ineffective with default PaddleX 3.6 SDK - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/PaddlePaddle/PaddleOCR/issues/18194 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 5. 安装坑 · 来源证据：图片识别没有文字输出。 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：图片识别没有文字输出。 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/PaddlePaddle/PaddleOCR/issues/17974 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 6. 配置坑 · 失败模式：configuration: Link Checker Report - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: Link Checker Report - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Link Checker Report - 证据：failure_mode_cluster:github_issue | https://github.com/PaddlePaddle/PaddleOCR/issues/18157 | Link Checker Report ## 7. 配置坑 · 失败模式：configuration: PaddleOCR-VL HPS: returnMarkdownImages=false is ineffective with default PaddleX 3.6 SDK - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: PaddleOCR-VL HPS: returnMarkdownImages=false is ineffective with default PaddleX 3.6 SDK - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: PaddleOCR-VL HPS: returnMarkdownImages=false is ineffective with default PaddleX 3.6 SDK - 证据：failure_mode_cluster:github_issue | https://github.com/PaddlePaddle/PaddleOCR/issues/18194 | PaddleOCR-VL HPS: returnMarkdownImages=false is ineffective with default PaddleX 3.6 SDK ## 8. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/PaddlePaddle/PaddleOCR | README/documentation is current enough for a first validation pass. ## 9. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/PaddlePaddle/PaddleOCR | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/PaddlePaddle/PaddleOCR | no_demo; severity=medium ## 11. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/PaddlePaddle/PaddleOCR | no_demo; severity=medium ## 12. 运行坑 · 失败模式：performance: v3.7.0 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this performance risk before relying on the project: v3.7.0 - 对用户的影响：Upgrade or migration may change expected behavior: v3.7.0 - 证据：failure_mode_cluster:github_release | https://github.com/PaddlePaddle/PaddleOCR/releases/tag/v3.7.0 | v3.7.0 ## 13. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/PaddlePaddle/PaddleOCR | issue_or_pr_quality=unknown ## 14. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/PaddlePaddle/PaddleOCR | release_recency=unknown