Add deployment docs and enhance CLI (#15117)

* Add serving and hpi docs

* Optimize CLI logging info

* Update interface

* Add on-device deployment and onnx model conversion docs

* Enhance CLI

* _gen->_iter

* Fix CLI help message

* Update table_recognition_v2 and PP-StructureV3 interfaces

* Update installation doc

* Update interface

* Update interface

* Add logging doc

* Update default values

---------

Co-authored-by: cuicheng01 <45199522+cuicheng01@users.noreply.github.com>

Author: Bobholamovic

docs/deployment/high_performance_inference.md

@@ -0,0 +1,91 @@
+# 高性能推理
+
+在实际生产环境中，许多应用对部署策略的性能指标（尤其是响应速度）有着较严苛的标准，以确保系统的高效运行与用户体验的流畅性。PaddleOCR 提供高性能推理能力，让用户无需关注复杂的配置和底层细节，一键提升模型的推理速度。具体而言，PaddleOCR 的高性能推理功能能够：
+
+- 结合先验知识自动选择合适的推理后端（Paddle Inference、OpenVINO、ONNX Runtime、TensorRT等），并配置加速策略（如增大推理线程数、设置 FP16 精度推理）；
+- 根据需要自动将飞桨静态图模型转换为 ONNX 格式，以使用更优的推理后端实现加速。
+
+本文档主要介绍高性能推理功能的安装与使用方法。
+
+## 1. 前置条件
+
+## 1.1 安装高性能推理依赖
+
+通过 PaddleOCR CLI 安装高性能推理所需依赖：
+
+```bash
+paddleocr install_hpi_deps {设备类型}
+```
+
+支持的设备类型包括：
+
+- `cpu`：仅使用 CPU 推理。目前支持 Linux 系统、x86-64 架构处理器、Python 3.8-3.12。
+- `gpu`：使用 CPU 或 NVIDIA GPU 推理。目前支持 Linux 系统、x86-64 架构处理器、Python 3.8-3.12。请查看下一小节的详细说明。
+
+同一环境中只应该存在一种设备类型的依赖。对于 Windows 系统，目前建议在 Docker 容器或者 [WSL](https://learn.microsoft.com/zh-cn/windows/wsl/install) 环境中安装。
+
+**推荐使用飞桨官方 Docker 镜像安装高性能推理依赖。** 各设备类型对应的镜像如下：
+
+- `cpu`：`ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddle:3.0.0`
+- `gpu`：
+    - CUDA 11.8：`ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddle:3.0.0-gpu-cuda11.8-cudnn8.9-trt8.6`
+
+## 1.2 GPU 环境详细说明
+
+首先，需要确保环境中安装有符合要求的 CUDA 与 cuDNN。目前 PaddleOCR 仅支持与 CUDA 11.8 + cuDNN 8.9 兼容的 CUDA 和 cuDNN版本。以下分别是 CUDA 11.8 和 cuDNN 8.9 的安装说明文档：
+
+- [安装 CUDA 11.8](https://developer.nvidia.com/cuda-11-8-0-download-archive)
+- [安装 cuDNN 8.9](https://docs.nvidia.com/deeplearning/cudnn/archives/cudnn-890/install-guide/index.html)
+
+如果使用飞桨官方镜像，则镜像中的 CUDA 和 cuDNN 版本已经是满足要求的，无需额外安装。
+
+如果通过 pip 安装飞桨，通常 CUDA、cuDNN 的相关 Python 包将被自动安装。在这种情况下，**仍需要通过安装非 Python 专用的 CUDA 与 cuDNN**。同时，建议安装的 CUDA 和 cuDNN 版本与环境中存在的 Python 包版本保持一致，以避免不同版本的库共存导致的潜在问题。可以通过如下方式可以查看 CUDA 和 cuDNN 相关 Python 包的版本：
+
+```bash
+# CUDA 相关 Python 包版本
+pip list | grep nvidia-cuda
+# cuDNN 相关 Python 包版本
+pip list | grep nvidia-cudnn
+```
+
+其次，需确保环境中安装有符合要求的 TensorRT。目前 PaddleOCR 仅支持 TensorRT 8.6.1.6。如果使用飞桨官方镜像，可执行如下命令安装 TensorRT wheel 包：
+
+```bash
+python -m pip install /usr/local/TensorRT-*/python/tensorrt-*-cp310-none-linux_x86_64.whl
+```
+
+对于其他环境，请参考 [TensorRT 文档](https://docs.nvidia.com/deeplearning/tensorrt/archives/index.html) 安装 TensorRT。示例如下：
+
+```bash
+# 下载 TensorRT tar 文件
+wget https://developer.nvidia.com/downloads/compute/machine-learning/tensorrt/secure/8.6.1/tars/TensorRT-8.6.1.6.Linux.x86_64-gnu.cuda-11.8.tar.gz
+# 解压 TensorRT tar 文件
+tar xvf TensorRT-8.6.1.6.Linux.x86_64-gnu.cuda-11.8.tar.gz
+# 安装 TensorRT wheel 包
+python -m pip install TensorRT-8.6.1.6/python/tensorrt-8.6.1-cp310-none-linux_x86_64.whl
+# 添加 TensorRT 的 `lib` 目录的绝对路径到 LD_LIBRARY_PATH 中
+export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:TensorRT-8.6.1.6/lib"
+```
+
+## 2. 执行高性能推理
+
+对于 PaddleOCR CLI，指定 `--enable_hpi` 为 `True` 即可执行高性能推理。例如：
+
+```bash
+paddleocr ocr --enable_hpi True ...
+```
+
+对于 PaddleOCR Python API，在初始化产线对象或者模块对象时，设置 `enable_hpi` 为 `True` 即可在调用推理方法时执行高性能推理。例如：
+
+```python
+from paddleocr import PaddleOCR
+pipeline = PaddleOCR(enable_hpi=True)
+result = pipeline.predict(...)
+```
+
+## 3. 说明
+
+1. 对于部分模型，在首次执行高性能推理时，可能需要花费较长时间完成推理引擎的构建。推理引擎相关信息将在第一次构建完成后被缓存在模型目录，后续可复用缓存中的内容以提升初始化速度。
+2. 目前，由于使用的不是静态图格式模型、存在不支持算子等原因，部分模型可能无法获得推理加速。
+3. 在进行高性能推理时，PaddleOCR 会自动处理模型格式的转换，并尽可能选择最优的推理后端。同时，PaddleOCR 也支持用户指定 ONNX 模型。有关如何飞桨静态图模型转换为 ONNX 格式，可参考 [获取 ONNX 模型](./obtaining_onnx_models.md)。
+4. PaddleOCR 的高性能推理能力依托于 PaddleX 及其高性能推理插件。通过传入自定义 PaddleX 产线配置文件，可以对推理后端等进行配置。请参考 [使用 PaddleX 产线配置文件](../paddleocr_and_paddlex.md#3-使用-paddlex-产线配置文件) 和 [PaddleX 高性能推理指南](https://paddlepaddle.github.io/PaddleX/3.0/pipeline_deploy/high_performance_inference.html#22) 了解如何调整高性能推理配置。

docs/deployment/obtaining_onnx_models.md

@@ -0,0 +1,48 @@
+# 获取 ONNX 模型
+
+PaddleOCR 提供了丰富的预训练模型，这些模型均采用飞桨的静态图格式进行存储。若需在部署阶段使用 ONNX 格式的模型，可借助 PaddleX 提供的 Paddle2ONNX 插件进行转换。关于 PaddleX 及其与 PaddleOCR 之间的关系，请参考 [PaddleOCR 与 PaddleX 的区别与联系](../paddleocr_and_paddlex.md#1-paddleocr-与-paddlex-的区别与联系)。
+
+首先，执行如下命令，通过 PaddleX CLI 安装 PaddleX 的 Paddle2ONNX 插件：
+
+```bash
+paddlex --install paddle2onnx
+```
+
+然后，执行如下命令完成模型转换：
+
+```bash
+paddlex \
+    --paddle2onnx \  # 使用paddle2onnx功能
+    --paddle_model_dir /your/paddle_model/dir \  # 指定 Paddle 模型所在的目录
+    --onnx_model_dir /your/onnx_model/output/dir \  # 指定转换后 ONNX 模型的输出目录
+    --opset_version 7  # 指定要使用的 ONNX opset 版本
+```
+
+参数说明如下：
+
+<table>
+    <thead>
+        <tr>
+            <th>参数</th>
+            <th>类型</th>
+            <th>描述</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>paddle_model_dir</td>
+            <td>str</td>
+            <td>包含 Paddle 模型的目录。</td>
+        </tr>
+        <tr>
+            <td>onnx_model_dir</td>
+            <td>str</td>
+            <td>ONNX 模型的输出目录，可以与 Paddle 模型目录相同。默认为 <code>onnx</code>。</td>
+        </tr>
+        <tr>
+            <td>opset_version</td>
+            <td>int</td>
+            <td>使用的 ONNX opset 版本。当使用低版本 opset 无法完成转换时，将自动选择更高版本的 opset 进行转换。默认为 <code>7</code>。</td>
+        </tr>
+    </tbody>
+</table>

docs/deployment/on_device_deployment.md

@@ -0,0 +1,3 @@
+# 端侧部署
+
+PaddleOCR 模型可通过 [PaddleX 端侧部署方案](https://paddlepaddle.github.io/PaddleX/3.0/pipeline_deploy/edge_deploy.html) 实现端侧部署。关于 PaddleX 及其与 PaddleOCR 之间的关系，请参考 [PaddleOCR 与 PaddleX 的区别与联系](../paddleocr_and_paddlex.md#1-paddleocr-与-paddlex-的区别与联系)。

docs/deployment/serving.md

@@ -0,0 +1,93 @@
+# 服务化部署
+
+服务化部署是实际生产环境中常见的一种部署形式。通过将推理功能封装为服务，客户端可以通过网络请求来访问这些服务，以获取推理结果。PaddleOCR 推荐用户使用 [PaddleX](https://github.com/PaddlePaddle/PaddleX) 进行服务化部署。请阅读 [PaddleOCR 与 PaddleX 的区别与联系](../paddleocr_and_paddlex.md#1-paddleocr-与-paddlex-的区别与联系) 了解 PaddleOCR 与 PaddleX 的关系。
+
+PaddleX 提供以下服务化部署方案：
+
+- **基础服务化部署**：简单易用的服务化部署方案，开发成本低。
+- **高稳定性服务化部署**：基于 [NVIDIA Triton Inference Server](https://developer.nvidia.com/triton-inference-server) 打造。与基础服务化部署相比，该方案提供更高的稳定性，并允许用户调整配置以优化性能。
+
+**建议首先使用基础服务化部署方案进行快速验证**，然后根据实际需要，评估是否尝试更复杂的方案。
+
+## 1. 基础服务化部署
+
+### 1.1 安装依赖
+
+执行如下命令，通过 PaddleX CLI 安装 PaddleX 服务化部署插件：
+
+```bash
+paddlex --install serving
+```
+
+### 1.2 运行服务器
+
+通过 PaddleX CLI 运行服务器：
+
+```bash
+paddlex --serve --pipeline {PaddleX 产线注册名或产线配置文件路径} [{其他命令行选项}]
+```
+
+以通用 OCR 产线为例：
+
+```bash
+paddlex --serve --pipeline OCR
+```
+
+可以看到类似以下展示的信息：
+
+```text
+INFO:     Started server process [63108]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
+```
+
+如需调整配置（如模型路径、batch size、部署设备等），可指定 `--pipeline` 为自定义配置文件。请参考 [PaddleOCR 与 PaddleX](../advanced/paddleocr_and_paddlex.md) 了解 PaddleOCR 产线与 PaddleX 产线注册名的对应关系，以及 PaddleX 产线配置文件的获取与修改方式。
+
+与服务化部署相关的命令行选项如下：
+
+<table>
+<thead>
+<tr>
+<th>名称</th>
+<th>说明</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>--pipeline</code></td>
+<td>PaddleX 产线注册名或产线配置文件路径。</td>
+</tr>
+<tr>
+<td><code>--device</code></td>
+<td>产线部署设备。默认为 <code>cpu</code>（如 GPU 不可用）或 <code>gpu</code>（如 GPU 可用）。</td>
+</tr>
+<tr>
+<td><code>--host</code></td>
+<td>服务器绑定的主机名或 IP 地址。默认为 <code>0.0.0.0</code>。</td>
+</tr>
+<tr>
+<td><code>--port</code></td>
+<td>服务器监听的端口号。默认为 <code>8080</code>。</td>
+</tr>
+<tr>
+<td><code>--use_hpip</code></td>
+<td>如果指定，则使用高性能推理。</td>
+</tr>
+<tr>
+<td><code>--hpi_config</code></td>
+<td>高性能推理配置。请参考 <a href="https://paddlepaddle.github.io/PaddleX/3.0/pipeline_deploy/high_performance_inference.html#22">PaddleX 高性能推理指南</a> 了解更多信息。</td>
+</tr>
+</tbody>
+</table>
+</table>
+
+### 1.3 调用服务
+
+PaddleX 产线使用教程中的 <b>“开发集成/部署”</b> 部分提供了服务的 API 参考与多语言调用示例。在 [PaddleX模型产线使用概览](https://paddlepaddle.github.io/PaddleX/3.0/pipeline_usage/pipeline_develop_guide.html) 中可以找到各产线的使用教程。
+
+## 2. 高稳定性服务化部署
+
+请参考 [PaddleX 服务化部署指南](https://paddlepaddle.github.io/PaddleX/3.0/pipeline_deploy/serving.html#2)。在 [使用 PaddleX 产线配置文件](../paddleocr_and_paddlex.md#3-使用-paddlex-产线配置文件) 中，可以了解关于 PaddleX 产线配置文件的更多信息。
+
+需要说明的是，由于缺乏细粒度优化等原因，当前 PaddleOCR 提供的高稳定性服务化部署方案在性能上可能不及 2.x 版本基于 PaddleServing 的方案；但该新方案已对飞桨 3.0 框架提供了全面支持，我们也将持续优化，后续考虑推出性能更优的部署方案。

docs/logging.md

@@ -0,0 +1,22 @@
+# 日志
+
+本文档主要介绍如何配置 PaddleOCR 推理包的日志系统。需要注意的是，PaddleOCR 推理包与训练脚本使用的是不同的日志系统，本文档不涉及训练脚本所使用的日志系统的配置方法。
+
+PaddleOCR 构建了一个基于 Python [`logging` 标准库](https://docs.python.org/zh-cn/3/library/logging.html#module-logging) 的集中式日志系统。换言之，PaddleOCR 使用唯一的日志记录器（logger），可通过 `paddleocr.logger` 访问和配置。
+
+默认情况下，PaddleOCR 的日志级别设为 `ERROR`，这意味着仅当日志级别为 `ERROR` 或更高（如 `CRITICAL`）时，日志信息才会输出。PaddleOCR 同时为该日志记录器配置了一个 `StreamHandler`，将日志输出到标准错误流，并将记录器的 `propagate` 属性设为 `False`，以避免日志信息传递到其父记录器。
+
+若希望禁止 PaddleOCR 对日志系统的自动配置行为，可将环境变量 `DISABLE_AUTO_LOGGING_CONFIG` 设为 `1`。此时，PaddleOCR 将不会对日志记录器进行任何额外配置。
+
+如需更灵活地定制日志行为，可参考 `logging` 标准库的相关文档。以下是一个将日志写入文件的示例：
+
+```python
+import logging
+from paddleocr import logger
+
+# 将日志写入文件 `paddleocr.log`
+fh = logging.FileHandler("paddleocr.log")
+logger.addHandler(fh)
+```
+
+请注意，PaddleOCR 依赖的其他库（如 [PaddleX](./paddleocr_and_paddlex.md)）拥有各自独立的日志系统，以上配置不会影响这些库的日志输出。

docs/paddleocr_and_paddlex.md

@@ -0,0 +1,69 @@
+# PaddleOCR 与 PaddleX
+
+[PaddleX](https://github.com/PaddlePaddle/PaddleX) 是一款基于飞桨框架构建的低代码开发工具，集成了众多开箱即用的预训练模型，支持模型从训练到推理的全流程开发，兼容多款国内外主流硬件，助力 AI 开发者在产业实践中高效落地。
+
+PaddleOCR 在推理部署方面基于 PaddleX 构建，二者在该环节可实现无缝协同。在安装 PaddleOCR 时，PaddleX 也将作为其依赖一并安装。此外，PaddleOCR 与 PaddleX 在产线名称等方面也保持一致。对于快速体验，如果只使用基础配置，用户通常无需了解 PaddleX 的具体概念；但在涉及高级配置、服务化部署等使用场景时，了解 PaddleX 的相关知识将有所帮助。
+
+本文档将介绍 PaddleOCR 与 PaddleX 之间的关系，并说明如何协同使用这两个工具。
+
+## 1. PaddleOCR 与 PaddleX 的区别与联系
+
+PaddleOCR 与 PaddleX 在定位和功能上各有侧重：PaddleOCR 专注于 OCR 相关任务，而 PaddleX 则覆盖了包括时序预测、人脸识别等在内的多种任务类型。此外，PaddleX 提供了丰富的基础设施，具备多模型组合推理的底层能力，能够以统一且灵活的方式接入不同模型，支持构建复杂的模型产线。
+
+PaddleOCR 在推理部署环节充分复用了 PaddleX 的能力，具体包括：
+
+- PaddleOCR 在模型推理、前后处理及多模型组合等底层能力上，主要依赖于 PaddleX。
+- PaddleOCR 的高性能推理能力通过 PaddleX 的 Paddle2ONNX 插件及高性能推理插件实现。
+- PaddleOCR 的服务化部署方案基于 PaddleX 的实现。
+
+## 2. PaddleOCR 产线与 PaddleX 产线注册名的对应关系
+
+| PaddleOCR 产线 | PaddleX 产线注册名 |
+| --- | --- |
+| 通用 OCR | `OCR` |
+| 通用版面解析 v3 | `PP-StructureV3` |
+| 文档场景信息抽取 v4 | `PP-ChatOCRv4-doc` |
+| 通用表格识别 v2 | `table_recognition_v2` |
+| 公式识别 | `formula_recognition` |
+| 印章文本识别 | `seal_recognition` |
+| 文档图像预处理 | `doc_preprocessor` |
+| 文档理解 | `doc_understanding` |
+
+## 3. 使用 PaddleX 产线配置文件
+
+在推理部署阶段，PaddleOCR 支持导出和加载 PaddleX 的产线配置文件。用户可通过编辑配置文件，对推理部署相关参数进行深度配置。
+
+### 3.1 导出产线配置文件
+
+可调用 PaddleOCR 产线对象的 `export_paddlex_config_to_yaml` 方法，将当前产线配置导出为 YAML 文件。示例如下：
+
+```python
+from paddleocr import PaddleOCR
+
+pipeline = PaddleOCR()
+pipeline.export_paddlex_config_to_yaml("ocr_config.yaml")
+```
+
+上述代码会在工作目录下生成名为 `ocr_config.yaml` 的产线配置文件。
+
+### 3.2 编辑产线配置文件
+
+导出的 PaddleX 产线配置文件不仅包含 PaddleOCR CLI 和 Python API 支持的参数，还可进行更多高级配置。请在 [PaddleX模型产线使用概览](https://paddlepaddle.github.io/PaddleX/3.0/pipeline_usage/pipeline_develop_guide.html) 中找到对应的产线使用教程，参考其中的详细说明，根据需求调整各项配置。
+
+### 3.3 在 CLI 中加载产线配置文件
+
+通过 `--paddlex_config` 参数指定 PaddleX 产线配置文件的路径，PaddleOCR 会读取其中的内容作为产线的默认配置。示例如下：
+
+```bash
+paddleocr ocr --paddlex_config ocr_config.yaml ...
+```
+
+### 3.4 在 Python API 中加载产线配置文件
+
+初始化产线对象时，可通过 `paddlex_config` 参数传入 PaddleX 产线配置文件路径或配置字典，PaddleOCR 会将其作为默认配置。示例如下：
+
+```python
+from paddleocr import PaddleOCR
+
+pipeline = PaddleOCR(paddlex_config="ocr_config.yaml")
+```