PaddleOCR 常见报错与解决方法

报错修复助手#

每一条都来自两个地方之一：PaddleOCR、PaddleX 或 PaddlePaddle 的源码（我们注明了文件和行号），或者在我们自己测试机上的实际运行，标记为 paddleocr.dev 已复现。官方文档中在 3.x 已经不再适用的建议，我们也会指出。所有条目都在下方列出，方便你直接链接到任意一条。⁹

ConvertPirAttribute2RuntimeAttribute not support pir::ArrayAttribute（oneDNN 崩溃）#

paddleocr.dev 已复现 如果你在 CPU 机器上按最直观的步骤安装——pip install paddleocr paddlepaddle，然后运行任意 OCR——现在就会遇到这个报错。¹

NotImplementedError: (Unimplemented) ConvertPirAttribute2RuntimeAttribute not support [pir::ArrayAttribute<pir::DoubleAttribute>]  (at /paddle/paddle/fluid/framework/new_executor/instruction/onednn/onednn_instruction.cc:116)

为什么会出现#

三个事实叠加在一起。pip install paddlepaddle 会安装 PyPI 上最新的版本 3.3.1。⁸ PaddleOCR 3.x 在 CPU 上默认开启 oneDNN（MKL-DNN），即 enable_mkldnn=True。⁴ 而在 PaddlePaddle 的 oneDNN 执行器中，ConvertPirAttribute2RuntimeAttribute 函数在已发布的 v3.3.0、v3.3.1 和 v3.4.0 中都没有处理“double 数组”类型属性的分支，于是在第 116 行抛出 Unimplemented。develop 分支补上了这个分支，但我们检查过的已发布版本都还没有包含它。³ PaddleOCR 官方文档从未提到这个报错；文档锁定的是 paddlepaddle==3.2.0，所以照着文档装的人不会遇到。⁶

三种有效的修复方法#

每一种我们都在同一台机器、同一批文档上试过。¹²

python -m pip install paddlepaddle==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
# 然后原样运行你的代码

from paddleocr import PaddleOCR
ocr = PaddleOCR(lang='en', device='cpu', enable_mkldnn=False)
# 命令行：paddleocr ocr -i img.png --enable_mkldnn False

# pip install onnxruntime   （使用这个引擎完全不需要 PaddlePaddle）
from paddleocr import PaddleOCR
ocr = PaddleOCR(lang='en', device='cpu', engine='onnxruntime')

• A 保留 oneDNN，与安装文档锁定的版本一致，不需要改代码。
• B 最慢。它把 CPU 运行模式从 oneDNN 切换为普通的 paddle。在我们的机器上平均每页 11.88 秒，而 PaddlePaddle 3.2.0 上开启 oneDNN 为 4.51 秒：平均慢 2.6 倍，随文档不同在 2.3 到 3.0 倍之间。
• C 最快（默认的 PP-OCRv6 模型）：每页 2.92 秒。只需 pip install paddleocr onnxruntime；首次加载会打印很多无害的 Removing initializer 警告。同一基准测试中的一个注意点：使用 PP-OCRv5_server 模型时，ONNX Runtime 要慢得多（每页 35.70 秒对比 5.25 秒）。

三种配置都把 124 个标注文本项中的 123 个完全识别正确，所以选择只关乎速度，与精度无关。完整的测试方法见 我们的基准测试页（英文），各操作系统锁定版本的安装命令见 安装教程。一旦有 PaddlePaddle 正式版本包含 develop 分支的修复，升级就会成为第四种选择；届时我们会更新本页。

A dependency error occurred during pipeline creation（创建产线时依赖错误）#

paddleocr.dev 已复现 在只执行了 pip install paddleocr 的环境里调用 PPStructureV3()，我们得到了这个报错：¹

RuntimeError: A dependency error occurred during pipeline creation. Please refer to the installation documentation to ensure all required dependencies are installed.

报错没说缺了什么。真正的原因在堆栈里再往上一层，“The above exception was the direct cause of the following exception”之后：

DependencyError: `PP-StructureV3` requires additional dependencies. To install them, run `pip install "paddlex[ocr]==<PADDLEX_VERSION>"` if you're installing `paddlex` from an index, or `pip install -e "/path/to/PaddleX[ocr]"` if you're installing `paddlex` locally.

基础的 pip install paddleocr 只会带上 paddlex[ocr-core]。文档解析需要 doc-parser 这个 extra，它会拉取 paddlex[ocr,genai-client]。⁴ 不必像报错建议的那样手动安装 PaddleX，安装 PaddleOCR 的 extra 即可：

如果某个必需的包被替换或删除，基础 OCR 也会出现同样的报错，因为 PaddleX 用 importlib.metadata 按发行包名称检查已安装的依赖。⁵ 最典型的触发方式就是把 OpenCV 换成 headless 版——见下文的 libGL。

Engine 'paddle_static' is unavailable because dependency 'paddlepaddle' is not installed（未安装 PaddlePaddle）#

RuntimeError: Engine 'paddle_static' is unavailable because dependency 'paddlepaddle' is not installed.

pip install paddleocr 不会安装 PaddlePaddle。它的依赖只有 paddlex[ocr-core]、PyYAML、requests、aiohttp 和 typing-extensions。不设置 engine 时，PaddleX 会选择 PaddlePaddle 引擎并检查 paddle 模块。⁴⁵ 安装一个引擎即可：

python -m pip install paddlepaddle==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
python -c "import paddle; print(paddle.__version__)"

# 驱动 >= 550.54.14
python -m pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/
# 较旧的驱动（Linux >= 450.80.02，Windows >= 452.39）：改用 .../stable/cu118/

python -m pip install onnxruntime
# 然后：PaddleOCR(engine='onnxruntime')

CPU 上请锁定 3.2.0：不锁版本的 pip install paddlepaddle 会装上 3.3.1，进而遇到 oneDNN 崩溃。GPU 版的 3.x wheel 只能从飞桨官方源获取：PyPI 上的 paddlepaddle-gpu 停在 2.6.2，PaddleOCR 3.x 无法使用。⁸⁶ 官方文档说明应按显卡驱动版本选择 wheel，而不是按本机安装的 CUDA Toolkit。一个环境里只装一个引擎。

ImportError: libGL.so.1: cannot open shared object file#

ImportError: libGL.so.1: cannot open shared object file: No such file or directory

这个报错常出现在精简的 Docker 镜像和最小化安装的 Linux 服务器上。PaddleX 的 OCR 依赖包括 opencv-contrib-python==4.10.0.84，这是常规（非 headless）的 OpenCV 版本，会链接系统的 libGL 和 glib。⁵ 安装这两个系统库即可——PaddleOCR 官方的 Dockerfile 也是这么做的：⁷

apt-get update && apt-get install -y libgl1 libglib2.0-0

同样的方法也能解决 libgthread-2.0.so.0 和 libglib-2.0.so.0 报错，它们来自 glib 包。

PaddleOCR 没有使用 GPU#

PaddleOCR 3.x 在用不了 GPU 时不会报错。如果你指定了 device='gpu'，而安装的 PaddlePaddle 不带 CUDA，PaddleX 只会打印一行日志，然后继续用 CPU 运行：⁵

The specified device (GPU) is not available! Switching to CPU instead.

设置 PADDLE_PDX_DISABLE_DEVICE_FALLBACK 可以把它变成 RuntimeError。常见原因是装了 CPU 版的 PaddlePaddle：单独执行 pip install paddlepaddle 或 pip install paddleocr 都不会获得 GPU 支持，而从 PyPI pip install paddlepaddle-gpu 得到的是 2.6.2。检查一下你装的是什么：

python -c "import paddle; print(paddle.__version__, paddle.is_compiled_with_cuda(), paddle.device.cuda.device_count())"
nvidia-smi

1. 如果输出 False：先 pip uninstall paddlepaddle paddlepaddle-gpu，再按显卡驱动版本从上面的 cu126 或 cu118 源安装 paddlepaddle-gpu==3.2.0。
2. 如果输出 True 但设备数为 0，说明 PaddlePaddle 看不到 GPU：检查 nvidia-smi 是否列出了显卡。
3. 使用 device='gpu' 或 'gpu:0'；'cuda' 会因 AssertionError 被拒绝。
4. 2.x 的写法 use_gpu=True 在 3.x 中会报 ValueError: Unknown argument: use_gpu（见 下文）。

使用 engine='onnxruntime' 时，GPU 需要 onnxruntime-gpu（CUDA 12）及其 CUDAExecutionProvider。动态库加载错误（libcudnn、libcublas）和 Windows 上的 RTX 50 系列见下方 GPU 一节。

官方在线 API 任务失败：如何用 jobId 查询状态#

如果你用的不是本地的 PaddleOCR，而是官方托管服务（www.paddleocr.com，会跳转到飞桨星河社区 AI Studio），处理流程是异步的：提交文件后返回一个 jobId，再用它轮询任务状态。¹⁰

1. 提交：POST https://paddleocr.aistudio-app.com/api/v2/ocr/jobs，请求头 Authorization: Bearer <token>，返回 {"code": 0, "data": {"jobId": "..."}}。
2. 查询：GET https://paddleocr.aistudio-app.com/api/v2/ocr/jobs/<jobId>，看 data.state：pending → running → done 或 failed。
3. 成功后下载 data.resultUrl.jsonUrl：一个 JSONL 文件，每页一行。

curl -s "https://paddleocr.aistudio-app.com/api/v2/ocr/jobs/<jobId>" \
  -H "Authorization: Bearer $PADDLEOCR_ACCESS_TOKEN"

官方 Python SDK 中结果对象带有 result.job_id，异常都继承自 PaddleOCRAPIError（如 AuthError、RateLimitError、PollTimeoutError）。AI Studio 配额文档列出的错误码：403 token 无效，413 文件过大，422 参数错误，429 超出每日页数上限，503 请求过多，504 网关超时。限额方面：每个模型每天 3,000 页；单文件建议不超过 100 页（配额文档称超出部分只解析前 100 页，而异步指南写的是每次请求最多 1000 页，两份官方文档不一致）；URL 文件不超过 200 MB，本地上传不超过 50 MB。我们没有用 token 实际调用过这个服务，以上是协议说明，不是实测结果；完整内容见 服务化部署与 API（英文）。¹⁰

从 2.x 升级#

Unknown argument: use_gpu#

paddleocr.dev 已复现 paddleocr.dev 于 2026-10-27 复现：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

ValueError: Unknown argument: use_gpu

原因：2.x 的引擎选项 use_gpu / gpu_id / gpu_mem 在 3.x 中已不存在。类本身没有消费掉的关键字参数，都会拿去和 device、engine、engine_config、enable_hpi、use_tensorrt、precision、enable_mkldnn、mkldnn_cache_capacity、cpu_threads、enable_cinn 逐一比对。

1. 删掉 use_gpu / gpu_id / gpu_mem。
2. 用 device='gpu'、device='gpu:1' 或 device='cpu' 选择硬件。
3. 不写 device 时，只要 Paddle 能识别到 CUDA GPU 就使用 GPU 0，否则使用 CPU。

# 2.x
ocr = PaddleOCR(use_gpu=True, lang='en')
# 3.x
ocr = PaddleOCR(device='gpu', lang='en')

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：PaddleOCR/paddleocr/_common_args.py:52-54; PaddleOCR/paddleocr/_common_args.py:38-50; paddlex-3.7.2/paddlex/utils/device.py:55-75; PaddleOCR/docs/version3.x/pipeline_usage/OCR.en.md:1094-1111

Unknown argument: show_log#

paddleocr.dev 已复现 paddleocr.dev 于 2026-10-27 复现：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

ValueError: Unknown argument: show_log

原因：show_log 已被移除；3.x 统一使用名为 'paddleocr' 的 logger（默认级别 ERROR）。

1. 删掉 show_log=...。
2. 要调整日志详细程度：import logging; from paddleocr import logger; logger.setLevel(logging.INFO)

import logging
from paddleocr import PaddleOCR, logger
logger.setLevel(logging.ERROR)  # replaces show_log=False
ocr = PaddleOCR(lang='en')

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：PaddleOCR/paddleocr/_common_args.py:52-54; PaddleOCR/docs/update/upgrade_notes.en.md:69; PaddleOCR/docs/version3.x/logging.en.md:9-24; PaddleOCR/paddleocr/_utils/logging.py:24-36

Unknown argument: use_onnx#

paddleocr.dev 已复现 paddleocr.dev 于 2026-10-27 复现：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

ValueError: Unknown argument: use_onnx

原因：use_onnx 先是被高性能推理（enable_hpi）取代，从 3.5 起又改为 engine / engine_config 机制。

1. 删掉 use_onnx。
2. 二选一：传入 enable_hpi=True（高性能推理插件），或者先 pip install onnxruntime（CPU）/ onnxruntime-gpu（CUDA 12）再用 engine='onnxruntime'。
3. ONNX Runtime 的选项放进 engine_config，例如 engine_config={'providers': ['CUDAExecutionProvider']}。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：PaddleOCR/paddleocr/_common_args.py:52-54; PaddleOCR/docs/update/upgrade_notes.en.md:71; PaddleOCR/docs/version3.x/inference_deployment/local_inference/inference_engine.en.md:20-30,50-58,118-132

Unknown argument: drop_score#

paddleocr.dev 已复现 paddleocr.dev 于 2026-10-27 复现：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

ValueError: Unknown argument: drop_score

原因：drop_score 不在 3.x 的弃用参数映射表里；对应的参数是 text_rec_score_thresh（3.x 默认 0.0，2.x 为 0.5）。

1. 把 drop_score=0.5 改名为 text_rec_score_thresh=0.5（构造函数或 predict() 中均可）。

ocr = PaddleOCR(text_rec_score_thresh=0.5)

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：PaddleOCR/paddleocr/_common_args.py:52-54; PaddleOCR/paddleocr/_pipelines/ocr.py:44-56,90,191; paddleocr-2.10.0/paddleocr/tools/infer/utility.py:107; paddlex-3.7.2/paddlex/configs/pipelines/OCR.yaml:45

Unknown argument：其他 2.x 参数#

ValueError: Unknown argument: {name}

原因：只有 11 个旧参数名会被自动映射（use_angle_cls、det_model_dir、det_limit_side_len、det_limit_type、det_db_thresh、det_db_box_thresh、det_db_unclip_ratio、rec_model_dir、rec_batch_num、cls_model_dir、cls_batch_num），而且只在 PaddleOCR 上有效。其余 2.x 关键字参数一律报错。

1. 在迁移对照表（migration.json）中查找该参数名。
2. rec_image_shape -> text_rec_input_shape；use_xpu/use_npu -> device='xpu'/'npu'；page_num/image_dir -> 把文件直接传给 predict()。
3. 在 3.x 中没有对应项的选项必须删除；高级设置可以在导出的 PaddleX 配置中修改（先 export_paddlex_config_to_yaml，再传 paddlex_config=...）。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：PaddleOCR/paddleocr/_common_args.py:52-54; PaddleOCR/paddleocr/_pipelines/ocr.py:44-56,155-169; PaddleOCR/paddleocr/_pipelines/base.py:74-100

PPStructureV3 报 Unknown argument（layout / table / ocr / structure_version / det_model_dir ...）#

paddleocr.dev 已复现 paddleocr.dev 于 2026-10-27 复现：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。PPStructureV3(det_model_dir=...)、(use_angle_cls=...) 和 (use_gpu=...) 都报了 Unknown argument。

ValueError: Unknown argument: table

原因：PPStructureV3 有一套独立的参数，也没有旧参数名映射（连 det_model_dir / use_angle_cls 在这里都会报错）。

1. table -> use_table_recognition；formula -> use_formula_recognition（现在默认 True）；image_orientation -> use_doc_orientation_classify；layout_model_dir -> layout_detection_model_dir；table_model_dir -> wired_/wireless_table_structure_recognition_model_dir；det_model_dir -> text_detection_model_dir。
2. layout=False / ocr=False 没有对应项：纯文字识别用 PaddleOCR，表格用 TableRecognitionPipelineV2。
3. recovery=True -> 对每个结果调用 res.save_to_word() / res.save_to_markdown()。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：PaddleOCR/paddleocr/_common_args.py:52-54; PaddleOCR/paddleocr/_pipelines/pp_structurev3.py:32-101,129-143

DeprecationWarning: The parameter `use_angle_cls` has been deprecated#

paddleocr.dev 已复现 paddleocr.dev 于 2026-10-27 复现：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

DeprecationWarning: The parameter `use_angle_cls` has been deprecated and will be removed in the future. Please use `use_textline_orientation` instead.

原因：2.x 的参数名在 PaddleOCR 上仍然可用，但会被映射到 3.x 的新名称，并给出警告。

1. 改成警告里给出的新名称（例如 use_angle_cls -> use_textline_orientation，det_model_dir -> text_detection_model_dir，rec_batch_num -> text_recognition_batch_size）。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：PaddleOCR/paddleocr/_utils/deprecation.py:36-42; PaddleOCR/paddleocr/_pipelines/ocr.py:44-56,156-159

`use_angle_cls` and `use_textline_orientation` are mutually exclusive#

paddleocr.dev 已复现 paddleocr.dev 于 2026-10-27 复现：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

ValueError: `use_angle_cls` and `use_textline_orientation` are mutually exclusive.

原因：同时传入了已弃用的旧名称和它的新名称（命令行会打印相同的文字，只是带 -- 前缀，并以状态码 2 退出）。

1. 只保留新名称。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：PaddleOCR/paddleocr/_pipelines/ocr.py:163-166,595-600

The option `--use_angle_cls` has been deprecated#

paddleocr.dev 已复现 paddleocr.dev 于 2026-10-27 复现：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

CLIDeprecationWarning: The option `--use_angle_cls` has been deprecated and will be removed in the future. Please refer to the documentation for more details.

原因：在 paddleocr ocr 中使用了 2.x 的旧命令行参数。

1. 改用新参数：--use_textline_orientation、--text_detection_model_dir、--text_recognition_model_dir、--text_det_thresh、--text_det_box_thresh、--text_det_unclip_ratio、--text_det_limit_side_len、--text_det_limit_type、--text_recognition_batch_size、--textline_orientation_model_dir、--textline_orientation_batch_size。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：PaddleOCR/paddleocr/_utils/deprecation.py:26-33; PaddleOCR/paddleocr/_pipelines/ocr.py:567-588

predict() got an unexpected keyword argument 'cls'#

paddleocr.dev 已复现 paddleocr.dev 于 2026-10-27 复现：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

TypeError: PaddleOCR.predict() got an unexpected keyword argument 'cls'

原因：在 3.x 中，ocr() 是已弃用的别名，会把 **kwargs 原样转发给 predict()，而 predict() 的仅限关键字参数签名里没有 cls/det/rec/bin/inv/alpha_color/slice。（具体措辞由 Python 生成；Python 3.10 以下不显示类名。）

1. ocr.ocr(img, cls=True) -> ocr.predict(img)，配合 PaddleOCR(use_textline_orientation=True) 或 predict(img, use_textline_orientation=True)。
2. det=False -> TextRecognition().predict(crops)；rec=False -> TextDetection().predict(img)。
3. bin/inv/alpha_color/slice 在 predict() 中没有对应项。

ocr = PaddleOCR(use_textline_orientation=True)
result = ocr.predict('img.png')

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：PaddleOCR/paddleocr/_pipelines/ocr.py:208-241; PaddleOCR/docs/update/upgrade_notes.en.md:69; paddleocr-2.10.0/paddleocr/paddleocr.py:696-706

DeprecationWarning: Please use `predict` instead.#

DeprecationWarning: Please use `predict` instead.

原因：3.x 中 PaddleOCR.ocr() 被 typing_extensions.deprecated 装饰，已标记为弃用。

1. 把 .ocr(img) 换成 .predict(img)。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：PaddleOCR/paddleocr/_pipelines/ocr.py:239-241; PaddleOCR/paddleocr/_utils/deprecation.py:19

cannot import name 'draw_ocr' from 'paddleocr'#

paddleocr.dev 已复现 paddleocr.dev 于 2026-10-27 复现：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

ImportError: cannot import name 'draw_ocr' from 'paddleocr'

原因：draw_ocr 是 2.x 导出的函数；3.x 的结果对象可以自己绘图。

1. 删掉这个 import。
2. 改用 res.save_to_img('output_dir') 或 res.img['ocr_res_img']（一个 PIL Image）。
3. 自定义字体：设置环境变量 PADDLE_PDX_LOCAL_FONT_FILE_PATH=/path/to/font.ttf。

from paddleocr import PaddleOCR
ocr = PaddleOCR(lang='en')
for res in ocr.predict('img.png'):
    res.save_to_img('output')
    img = res.img['ocr_res_img']  # PIL.Image

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：paddleocr-2.10.0/paddleocr/__init__.py:14-24; PaddleOCR/paddleocr/__init__.py:84-131; PaddleOCR/docs/update/upgrade_notes.en.md:38-48,65-66; PaddleOCR/docs/FAQ.en.md:195-197

cannot import name 'PPStructure' from 'paddleocr'#

paddleocr.dev 已复现 paddleocr.dev 于 2026-10-27 复现：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

ImportError: cannot import name 'PPStructure' from 'paddleocr'

原因：PPStructure 在 3.x 中已被移除。

1. pip install "paddleocr[doc-parser]"
2. from paddleocr import PPStructureV3
3. pipeline = PPStructureV3(); output = pipeline.predict('doc.png'); for res in output: res.save_to_markdown('out'); res.save_to_json('out')

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：PaddleOCR/docs/update/upgrade_notes.en.md:73; PaddleOCR/paddleocr/__init__.py:32-43; PaddleOCR/docs/version3.x/pipeline_usage/PP-StructureV3.en.md:963,1686-1700

cannot import name 'save_structure_res' / 'sorted_layout_boxes' / 'convert_info_docx'#

ImportError: cannot import name 'save_structure_res' from 'paddleocr'

原因：2.x PP-Structure 的辅助函数不在 3.x 包中。

1. save_structure_res -> res.save_to_json / save_to_xlsx / save_to_html / save_to_img（或 res.save_all）。
2. convert_info_docx -> res.save_to_word(path)。
3. convert_info_markdown / sorted_layout_boxes -> res.save_to_markdown(path)、pipeline.concatenate_markdown_pages(...)。
4. to_excel -> res.save_to_xlsx(path)。
5. download_with_progressbar -> 不再需要，模型会自动下载。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：paddleocr-2.10.0/paddleocr/__init__.py:14-24; PaddleOCR/paddleocr/__init__.py:84-131; paddlex-3.7.2/paddlex/inference/common/result/mixin.py:69,216,400,526,590,797

No module named 'paddleocr.tools' / 'paddleocr.ppocr' / 'paddleocr.ppstructure'#

ModuleNotFoundError: No module named 'paddleocr.tools'

原因：2.x 的 wheel 包里带有 tools/、ppocr/、ppstructure/ 和 paddleocr.py；3.x 包只包含 paddleocr/，并提供一套精简的公开 API。

1. 只从顶层包导入：from paddleocr import PaddleOCR, PPStructureV3, TextDetection, ...
2. 如果必须使用 2.x 的内部模块，请在单独的环境中锁定 paddleocr==2.10.0。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：PaddleOCR/pyproject.toml:61-64; PaddleOCR/paddleocr/__init__.py:84-131

用 2.x 代码读取 3.x 结果时报 KeyError: 0 / string indices#

paddleocr.dev 已复现 paddleocr.dev 于 2026-10-27 复现：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。result[0][0][1][0] 报 KeyError: 0；2.x 的循环 for line in result[0]: box, (text, score) = line 遍历的是字典的键，报 ValueError: too many values to unpack (expected 2)。

KeyError: 0

原因：3.x 的 predict()/ocr() 返回的是 OCRResult 对象列表（dict 子类，包含 rec_texts、rec_scores、rec_polys 等键），而不是 [[box, (text, score)], ...]。result[0][0] 是在查找字典的键 0。（NoneType 那种报错是 2.x 的行为：2.x 在图片中没有文字时返回 None。）

1. 遍历结果并读取具名字段：res['rec_texts']、res['rec_scores']、res['rec_polys']（4x2 int16 数组）、res['rec_boxes']（[x_min, y_min, x_max, y_max]）。
2. 需要可直接序列化为 JSON 的字典时用 res.json（{'res': {...}}）。

for res in ocr.predict('img.png'):
    for text, score, poly in zip(res['rec_texts'], res['rec_scores'], res['rec_polys']):
        print(text, score, poly.tolist())

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：paddlex-3.7.2/paddlex/inference/common/result/base_result.py:75; paddlex-3.7.2/paddlex/inference/pipelines/ocr/result.py:31; paddlex-3.7.2/paddlex/inference/common/result/mixin.py:197-207; PaddleOCR/docs/version3.x/pipeline_usage/OCR.en.md:1836-1853; paddleocr-2.10.0/paddleocr/paddleocr.py:762-772

Invalid OCR version#

ValueError: Invalid OCR version: PP-OCRv2. Supported values are ['PP-OCRv3', 'PP-OCRv4', 'PP-OCRv5', 'PP-OCRv6'].

原因：2.x 接受 PP-OCR 和 PP-OCRv2。3.x 的 PaddleOCR 接受 PP-OCRv3 到 PP-OCRv6；PPStructureV3 只接受 PP-OCRv3 到 PP-OCRv5。

1. 使用 ocr_version='PP-OCRv5' 或 'PP-OCRv6'（或者干脆不传）。
2. 在 PPStructureV3 中不要传 'PP-OCRv6'。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：PaddleOCR/paddleocr/_pipelines/ocr.py:58,97-100; PaddleOCR/paddleocr/_pipelines/pp_structurev3.py:28,103-106; paddleocr-2.10.0/paddleocr/paddleocr.py:91

paddleocr: error: argument COMMAND: invalid choice#

paddleocr.dev 已复现 paddleocr.dev 于 2026-10-27 复现：paddleocr 3.7.0、paddlex 3.7.2、Python 3.13、Linux x86-64。

paddleocr: error: argument COMMAND: invalid choice: 'img.png' (choose from ...)

原因：用 2.x 的命令行写法（paddleocr --image_dir x --use_angle_cls true）调用 3.x 命令行，而 3.x 要求子命令并使用 -i/--input。报错由 Python argparse 生成（我们在 Python 3.13 上用结构相同的解析器在本地复现过）。

1. paddleocr ocr -i img.png --use_textline_orientation True
2. 文档解析：paddleocr pp_structurev3 -i doc.pdf --save_path out
3. 只做检测：paddleocr text_detection -i img.png；只做识别：paddleocr text_recognition -i crop.png
4. GPU/CPU：--device gpu:0 | --device cpu

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：PaddleOCR/paddleocr/_cli.py:281-309; PaddleOCR/paddleocr/_utils/cli.py:31-45; PaddleOCR/paddleocr/_common_args.py:129-188

同一张图片，3.x 的结果/速度与 2.x 不同（无报错）#

(behaviour change, no error)

原因：默认值变了：默认模型为 PP-OCRv6_medium（2.x 为 PP-OCRv4）；OCR 产线 YAML 中整页方向分类 + UVDoc 弯曲矫正 + 文本行方向分类默认开启；检测 limit_side_len 为 64/min，max_side_limit 为 4000（2.x 为 960/max）；text_rec_score_thresh 为 0.0（2.x 的 drop_score 为 0.5）；enable_mkldnn 为 True（2.x 为 False）。

1. 要接近 2.x 的行为：PaddleOCR(use_doc_orientation_classify=False, use_doc_unwarping=False, use_textline_orientation=False, text_rec_score_thresh=0.5)。
2. 用 ocr_version='PP-OCRv4'（仅 ch/en）或明确的 *_model_name 锁定模型。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：paddlex-3.7.2/paddlex/configs/pipelines/OCR.yaml:6-45; PaddleOCR/paddleocr/_pipelines/ocr.py:330-331; paddleocr-2.10.0/paddleocr/tools/infer/utility.py:62-63,107,124,131; paddleocr-2.10.0/paddleocr/paddleocr.py:90; PaddleOCR/paddleocr/_constants.py:18; PaddleOCR/docs/version3.x/pipeline_usage/OCR.en.md:1293-1298

安装与依赖#

Engine 'onnxruntime' is unavailable because dependency 'onnxruntime' is not installed.#

RuntimeError: Engine 'onnxruntime' is unavailable because dependency 'onnxruntime' is not installed.

原因：选择了 engine='onnxruntime' / 'transformers' 或 enable_hpi，却没有安装对应的运行时；GPU 上的 ONNX 还需要有 CUDAExecutionProvider（onnxruntime 引擎只支持 cpu 和 gpu）。

1. pip install onnxruntime（CPU）或 onnxruntime-gpu（NVIDIA，CUDA 12.x）。
2. Transformers 引擎：pip install "transformers>=5.10.0"，再装好它的后端。
3. 高性能推理：paddleocr install_hpi_deps cpu|gpu|npu。
4. 一个环境里只装一个推理引擎。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：paddlex-3.7.2/paddlex/inference/models/engines/onnxruntime.py:59-82; paddlex-3.7.2/paddlex/inference/models/engines/transformers.py:73-77; paddlex-3.7.2/paddlex/inference/models/engines/hpi.py:66-70; PaddleOCR/docs/version3.x/inference_deployment/local_inference/inference_engine.en.md:32-58; PaddleOCR/paddleocr/_cli.py:96-107

pip 找不到 paddlepaddle-gpu 3.x（No matching distribution found）#

ERROR: No matching distribution found for paddlepaddle-gpu==3.2.0

原因：PyPI 上的 paddlepaddle-gpu 停在 2.6.2（已查 pypi.org JSON）；3.x 的 GPU 版 wheel 由飞桨自己的 pip 源提供。直接从 PyPI pip install paddlepaddle-gpu 会装上 2.6.2，不满足 PaddleOCR 3.x 对 PaddlePaddle >= 3.0.0 的要求。PyPI 上 CPU 版 paddlepaddle 3.3.1 的 wheel 只覆盖 CPython 3.9-3.13 的 manylinux x86_64、Windows amd64 和 macOS arm64。

1. 使用官方源地址：python -m pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/（驱动较旧时用 cu118）。
2. 使用 Python 3.9-3.13。
3. 按显卡驱动版本选择 wheel，而不是按本机安装的 CUDA Toolkit 版本。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：https://pypi.org/pypi/paddlepaddle-gpu/json (latest 2.6.2, fetched 2026-10-27); https://pypi.org/pypi/paddlepaddle/3.3.1/json; PaddleOCR/docs/version3.x/paddlepaddle_installation.en.md:54-65; PaddleOCR/docs/version3.x/paddleocr_and_paddlex.en.md:27-39

No module named 'pyclipper' / 'shapely' / 'cv2'#

ModuleNotFoundError: No module named 'pyclipper'

原因：pyclipper、shapely、opencv-contrib-python、pypdfium2 和 python-bidi 都来自 paddleocr 所依赖的 paddlex[ocr-core]。用 --no-deps 安装（仓库 FAQ 为解决冲突给出的建议）或手动卸载后，它们就会缺失。

1. pip install --force-reinstall "paddleocr"（不要加 --no-deps），或 pip install "paddlex[ocr-core]>=3.7.0,<3.8.0"。
2. 使用全新的虚拟环境。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：paddlex-3.7.2.dist-info/METADATA:101-106; PaddleOCR/pyproject.toml:49-55; PaddleOCR/docs/FAQ.en.md:15-20

NumPy 2 / numpy 版本冲突#

A module that was compiled using NumPy 1.x cannot be run in
NumPy 2.x.x as it may crash. To support both 1.x and 2.x
versions of NumPy, modules must be compiled with NumPy 2.0.

原因：paddlex 3.7.2 要求 numpy>=1.24,<2.4（paddlepaddle 3.3.1 要求 numpy>=1.21），所以 3.x 支持 NumPy 2.0-2.3。报错的来源有两种：(a) 环境里被强行装了 numpy >= 2.4；(b) 某个针对 NumPy 1.x 编译的扩展（例如在旧的 2.x 时代环境中）运行在 NumPy 2 上。报错文字来自 NumPy 本身。

1. pip install "numpy>=1.24,<2.4"
2. 升级报错堆栈中点名的那个包（如果继续使用旧的 2.x 技术栈，则把 numpy 降到 <2）。
3. 从 paddleocr 2.x 迁移到 3.x 时，最好使用全新的环境。

适用范围：paddleocr 3.x 环境；升级到 NumPy 2 的旧 paddleocr 2.x 环境。来源：paddlex-3.7.2.dist-info/METADATA:35; https://pypi.org/pypi/paddlepaddle/3.3.1/json (requires_dist); numpy v2.0.0 numpy/core/_multiarray_umath.py:23-29 and numpy/__init__.py:395-399 (raw.githubusercontent.com/numpy/numpy/v2.0.0)

import paddle 时报 protobuf 错误#

(varies; e.g. 'TypeError: Descriptors cannot be created directly.')

原因：paddlepaddle 3.2.2 和 3.3.1 声明依赖 protobuf>=3.20.2；其他包锁定的旧版 protobuf 会与之冲突。

1. pip install --upgrade "protobuf>=3.20.2"
2. 把 PaddleOCR 装在单独的虚拟环境里。

适用范围：paddlepaddle 3.x。来源：https://pypi.org/pypi/paddlepaddle/3.3.1/json (requires_dist: protobuf>=3.20.2); https://pypi.org/pypi/paddlepaddle/3.2.2/json

Apple Silicon（M1-M4）：怎样安装才能用#

(no single error string)

原因：paddlepaddle 在 PyPI 上发布了 macOS arm64 的 CPU 版 wheel（cp39-cp313）。官方的 PaddleOCR-VL Apple Silicon 指南从 CPU 源安装 paddlepaddle==3.2.1，并要求 >= 3.2.1；那里不支持 Docker；在这类硬件上 PaddlePaddle 是唯一的本地推理引擎。没有 CUDA，所以使用 device='cpu'。

1. python -m pip install paddlepaddle==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
2. python -m pip install -U "paddleocr[doc-parser]"（只做文字识别的话装普通的 paddleocr 即可）
3. 运行时使用 device='cpu'。

适用范围：Apple Silicon 上的 macOS。来源：PaddleOCR/docs/version3.x/pipeline_usage/PaddleOCR-VL-Apple-Silicon.en.md:31-60; https://pypi.org/pypi/paddlepaddle/3.3.1/json (macosx_11_0_arm64 wheels)

[W:onnxruntime ... Removing initializer ...] 警告#

paddleocr.dev 已复现 paddleocr.dev 于 2026-10-27 实测：paddleocr 3.7.0 + onnxruntime 1.31.1，未安装 PaddlePaddle。

[W:onnxruntime:...] ... Removing initializer ...

原因：使用 engine='onnxruntime' 时，ONNX Runtime 在加载模型时会打印大量 'Removing initializer' 警告。在我们的测试中它们是无害的：只装了 onnxruntime 1.31.1（没有 PaddlePaddle）的 paddleocr 3.7.0 返回了正确结果。

1. 忽略即可。它们出现在首次加载时，不影响输出。
2. 完全不用 PaddlePaddle 运行：pip install paddleocr onnxruntime，然后 PaddleOCR(engine='onnxruntime')。

# pip install paddleocr onnxruntime
from paddleocr import PaddleOCR
ocr = PaddleOCR(lang='en', engine='onnxruntime')

适用范围：使用 engine='onnxruntime' 的 paddleocr 3.5+。来源：tested by paddleocr.dev 2026-10-27 (paddleocr 3.7.0, onnxruntime 1.31.1); PaddleOCR/docs/version3.x/inference_deployment/local_inference/inference_engine.en.md:50-58

CPU、速度与推理引擎#

Invalid precision / Invalid engine#

ValueError: Invalid precision: int8. Supported values are: ['fp32', 'fp16'].

原因：precision 只接受 fp32/fp16；engine 只接受 None、paddle、paddle_static、paddle_dynamic、transformers、onnxruntime。

1. precision='fp16' 需配合 use_tensorrt=True 使用，否则不要传。
2. engine 使用上面列出的取值之一。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：PaddleOCR/paddleocr/_common_args.py:29-35,58-69; PaddleOCR/paddleocr/_constants.py:21

MKL-DNN is not available#

ValueError: MKL-DNN is not available

原因：在不支持 MKL-DNN 的 Paddle 版本或 CPU 上显式要求了 run_mode 'mkldnn'（例如 engine_config={'run_mode': 'mkldnn'}）。相关警告 "The model(X) is not supported to run in MKLDNN mode! Using paddle instead!" 只是提示信息（该模型在 PaddleX 的 MKLDNN 屏蔽列表中，例如 SLANet、UVDoc、PP-FormulaNet）。

1. 使用 run_mode 'paddle' 或不指定 run_mode；在 enable_mkldnn（默认 True）下，PaddleX 只会在可用时才选择 mkldnn。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：paddlex-3.7.2/paddlex/inference/models/runners/paddle_static/config/pp_option.py:31-43,161-170; paddlex-3.7.2/paddlex/inference/models/runners/paddle_static/runner.py:317-327; paddlex-3.7.2/paddlex/inference/models/runners/paddle_static/config/blocklists.py:46

engine_config cannot mix per-engine bucket keys with flat config keys#

ValueError: engine_config cannot mix per-engine bucket keys with flat config keys. Use either a flat dict for the resolved engine only, or a dict whose top-level keys are exclusively inference engine names. Flat-like keys: [...]; bucket-like keys: [...].

原因：engine_config 中混用了 {'paddle_static': {...}} 这种按引擎分桶的键和 'run_mode' 这类扁平键。

1. 为所选引擎使用扁平字典（engine='paddle_static', engine_config={'run_mode': 'paddle', 'cpu_threads': 4}），或者只使用按引擎名分桶的写法。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：paddlex-3.7.2/paddlex/inference/models/__init__.py:176-213; PaddleOCR/docs/version3.x/inference_deployment/local_inference/inference_engine.en.md:134-141

PaddleOCR 在 CPU 上很慢#

paddleocr.dev 已复现 paddleocr.dev 于 2026-10-27 实测（4 vCPU Intel Xeon @ 2.10 GHz，无 GPU）。

(no error: each page takes several seconds)

原因：3.x 默认的 OCR 产线除了 PP-OCRv6_medium，还会运行三个默认开启的辅助模型：整页方向分类、UVDoc 弯曲矫正和文本行方向分类。在 CPU 上，PaddlePaddle 通过 oneDNN（enable_mkldnn=True，默认值）运行最快。在我们的基准测试中（辅助模型关闭），PP-OCRv6_medium 在 PaddlePaddle 3.2.0 上平均每页 4.51 秒，在 ONNX Runtime 上 2.92 秒；PP-OCRv6_small 为 1.23 秒 / 0.90 秒；PP-OCRv6_tiny 为 0.39 秒 / 0.26 秒。使用 enable_mkldnn=False（PaddlePaddle 3.3.1）时，medium 需要 11.88 秒。

1. 对方向正确、平整的扫描件，关闭辅助模型：PaddleOCR(use_doc_orientation_classify=False, use_doc_unwarping=False, use_textline_orientation=False)。
2. pip install onnxruntime 后试试 engine='onnxruntime'：在我们的测试中它跑 PP-OCRv6 最快。例外：PP-OCRv5_server 在 ONNX Runtime 上慢得多（每页 35.70 秒对比 5.25 秒）。
3. 使用更小的模型：text_detection_model_name='PP-OCRv6_small_det'、text_recognition_model_name='PP-OCRv6_small_rec'（或 _tiny 这一对）。
4. 保持 enable_mkldnn=True 并锁定 paddlepaddle==3.2.0，而不是靠关闭 oneDNN 来规避 3.3.x 的崩溃。
5. PaddleOCR 对象只创建一次并重复使用。第一次 predict() 会更慢（在我们的测试中，小票首次运行 4.88 秒，三次运行的中位数 3.23 秒）。

from paddleocr import PaddleOCR

ocr = PaddleOCR(
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
    use_textline_orientation=False,
    text_detection_model_name='PP-OCRv6_small_det',
    text_recognition_model_name='PP-OCRv6_small_rec',
    engine='onnxruntime',  # pip install onnxruntime
)

适用范围：CPU 上的 paddleocr 3.x。来源：paddleocr.dev benchmark: _src/data/bench/summary.json, results.jsonl (2026-10-27); paddlex-3.7.2/paddlex/configs/pipelines/OCR.yaml:6-13; PaddleOCR/paddleocr/_constants.py:18

GPU#

device='cuda'（或其他无效设备字符串）时报 AssertionError#

AssertionError (from paddlex/utils/device.py parse_device)

原因：PaddleX 接受的设备类型为 cpu、gpu、xpu、npu、mlu、gcu、dcu、iluvatar_gpu、metax_gpu。'cuda'、'cuda:0' 或 'mps' 会被一个裸 assert 拒绝；'cpu:0' 则报 'No Device ID should be specified for CPUs'。

1. 使用 device='gpu' 或 'gpu:0'（不是 'cuda'）。
2. 使用 device='cpu'（不带序号）。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：paddlex-3.7.2/paddlex/utils/device.py:31-41,78-100

The third-party dynamic library (libcudnn.so) that Paddle depends on is not configured correctly#

The third-party dynamic library (libcudnn.so) that Paddle depends on is not configured correctly. (error code is ...)
  Suggestions:
  1. Check if the third-party dynamic library (e.g. CUDA, CUDNN) is installed correctly and its version is matched with paddlepaddle you installed.
  2. Configure third-party dynamic library environment variables as follows:
  - Linux: set LD_LIBRARY_PATH by `export LD_LIBRARY_PATH=...`

原因：paddlepaddle-gpu 无法 dlopen 它编译时所对应版本的 CUDA/cuDNN 库。

1. 安装与你的显卡驱动匹配的 paddlepaddle-gpu 版本（cu118 需要驱动 >= 450.80.02；cu126 需要 >= 550.54.14）。
2. 或者使用官方 Docker 镜像 paddle:3.0.0-gpu-cuda11.8-cudnn8.9-trt8.6 / paddle:3.0.0-gpu-cuda12.6-cudnn9.5-trt10.5。
3. 如果库文件存在但找不到，把所在目录加入 LD_LIBRARY_PATH（Linux）/ PATH（Windows）。

适用范围：paddlepaddle-gpu 3.x（任意 paddleocr 3.x）。来源：Paddle v3.3.1 paddle/phi/backends/dynload/dynamic_loader.cc:386-400; PaddleOCR/docs/version3.x/paddlepaddle_installation.en.md:16-28,58-65

GPU 0 显存不足（ResourceExhaustedError）#

ResourceExhaustedError: 

Out of memory error on GPU 0. Cannot allocate ... memory on GPU 0, ... memory has been allocated(actual using allocated memory ...) and available memory is only ....

Please check whether there is any other process using GPU 0.
1. If yes, please stop them, or start PaddlePaddle on another GPU.
2. If no, please decrease the batch size of your model.

原因：GPU 显存耗尽（图片太大、批量太大、使用服务端大模型，或 GPU 上还有其他进程）。

1. 释放 GPU 或换一张卡：device='gpu:1'。
2. 调小批量：text_recognition_batch_size=1、textline_orientation_batch_size=1。
3. 降低检测分辨率：调整 text_det_limit_side_len / text_det_limit_type，或在导出的配置中减小 max_side_limit。
4. 使用 mobile 模型，例如 text_detection_model_name='PP-OCRv5_mobile_det'、text_recognition_model_name='PP-OCRv5_mobile_rec'。
5. 关闭不需要的子模型（use_doc_orientation_classify=False、use_doc_unwarping=False）。
6. 注意：仓库 FAQ 还列出了 gpu_mem / batch_size / enable_memory_optim / det_limit_side_len；在 3.x 中它们都不是 PaddleOCR 的构造参数（gpu_mem 等会报 'Unknown argument'）。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：Paddle v3.3.1 paddle/phi/core/memory/allocation/cuda_allocator.cc:75-83; PaddleOCR/docs/FAQ.en.md:85-92; PaddleOCR/paddleocr/_pipelines/ocr.py:73-92; PaddleOCR/docs/version3.x/pipeline_usage/OCR.en.md:796

Windows 上的 NVIDIA RTX 50 系列显卡无法使用标准版 paddlepaddle-gpu#

(no single error string documented)

原因：官方文档：在 Windows 上以标准方式安装的 PaddlePaddle 不能很好地支持 NVIDIA 50 系列显卡；官方提供了专用的 CUDA 12.9 wheel（文字识别模型的训练仍有已知问题）。

1. 安装 paddlepaddle_installation 文档中列出的、与你的 Python 版本对应的专用 wheel（paddlepaddle_gpu-3.0.0.dev20250717-cp3XX-cp3XX-win_amd64.whl）。

适用范围：Windows + NVIDIA RTX 50 系列。来源：PaddleOCR/docs/version3.x/paddlepaddle_installation.en.md:79-97

模型与语言#

No models are available for lang=... and ocr_version=...#

ValueError: No models are available for lang='latin' and ocr_version=None.

原因：该 lang / ocr_version 组合没有可用模型。迁移时的常见情况：2.x 的文字体系代码（'latin'、'arabic'、'cyrillic'、'devanagari'、'ch_doc'、'structure'）在 3.x 中不再是有效的 lang；另外 PP-OCRv4 只支持 'ch' 和 'en'，PP-OCRv6 只支持 ch/chinese_cht/en/japan 以及拉丁字母语言。PPStructureV3 的报错措辞是："No models are available for the language 'xx' and OCR version 'yy'."

1. 使用真正的语言代码（例如 'fr'、'de'、'es'、'ru'、'ar'、'hi'、'korean'、'japan'）。
2. 去掉 ocr_version，让 PaddleOCR 自动选择支持该语言的最新版本。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：PaddleOCR/paddleocr/_pipelines/ocr.py:58-62,113-119,318-422; PaddleOCR/paddleocr/_utils/langs.py; PaddleOCR/paddleocr/_pipelines/pp_structurev3.py:119-125; paddleocr-2.10.0/paddleocr/paddleocr.py:506-527

`lang` and `ocr_version` will be ignored when model names or model directories are not `None`.#

UserWarning: `lang` and `ocr_version` will be ignored when model names or model directories are not `None`.

原因：你同时传入了 lang/ocr_version 和 text_detection_model_*/text_recognition_model_*（或已弃用的 det_model_dir/rec_model_dir）。

1. 选择模型时，要么用 lang/ocr_version，要么用明确的模型名称/目录，不要两者同时使用。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：PaddleOCR/paddleocr/_pipelines/ocr.py:122-127

Model name mismatch: expected 'PP-OCRv6_medium_det' but config has ...#

ValueError: Model name mismatch: expected 'PP-OCRv6_medium_det' but config has 'PP-OCRv5_server_det'. Please input the correct model dir.

原因：只给了 *_model_dir 而没有给对应的 *_model_name，于是产线沿用默认模型名（OCR YAML 中的 PP-OCRv6_medium_det / PP-OCRv6_medium_rec），PaddleX 再拿它与目录中 inference.yml 的 Global.model_name 比对。

1. 传入与目录匹配的模型名，例如 text_detection_model_name='PP-OCRv5_server_det', text_detection_model_dir='./PP-OCRv5_server_det_infer'。
2. 使用 3.x 格式的推理模型目录（其中包含 inference.yml）。

ocr = PaddleOCR(
    text_detection_model_name='PP-OCRv5_server_det',
    text_detection_model_dir='./models/PP-OCRv5_server_det_infer',
    text_recognition_model_name='PP-OCRv5_server_rec',
    text_recognition_model_dir='./models/PP-OCRv5_server_rec_infer',
)

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：paddlex-3.7.2/paddlex/inference/models/utils/model_resolver.py:25-44; paddlex-3.7.2/paddlex/inference/models/utils/model_config.py:24-31; paddlex-3.7.2/paddlex/configs/pipelines/OCR.yaml:27,42; PaddleOCR/paddleocr/_pipelines/utils.py:14-27

模型下载失败：No model hoster is available / No available model hosting platforms detected#

Exception: No available model hosting platforms detected. Please check your network connection.

原因：PaddleX 在首次使用时，会先做连通性检查，再从 HuggingFace（默认）、AIStudio、ModelScope 或 BOS 下载官方模型。防火墙、代理或离线主机会让所有模型源都失败。

1. 在导入 paddleocr 之前设置首选模型源：os.environ['PADDLE_PDX_MODEL_SOURCE'] = 'bos'（可选值：huggingface、modelscope、aistudio、bos；不区分大小写）。在国内访问 Hugging Face 困难时，这通常是第一步。
2. 跳过较慢的连通性检查：PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK=True。
3. 自定义 HF 镜像：PADDLE_PDX_HUGGING_FACE_ENDPOINT=https://...
4. 离线使用：把模型复制到 ~/.paddlex/official_models/<model_name>（缓存根目录由 PADDLE_PDX_CACHE_HOME 指定），或者传入 *_model_dir 并配上匹配的 *_model_name。

import os
os.environ['PADDLE_PDX_MODEL_SOURCE'] = 'bos'
os.environ['PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK'] = 'True'
from paddleocr import PaddleOCR

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：paddlex-3.7.2/paddlex/inference/utils/official_models.py:878-921,962-967,1015-1041; paddlex-3.7.2/paddlex/utils/flags.py:72-79; paddlex-3.7.2/paddlex/utils/cache.py:28-29; PaddleOCR/docs/FAQ.en.md:29-34,55-60

No valid model files were found for engine 'paddle_static' / No valid PaddlePaddle model found#

ValueError: No valid model files were found for engine 'paddle_static'.

原因：模型目录中缺少 inference.json 或 inference.pdmodel，以及与之配套的 inference.pdiparams（或所选引擎需要的格式，例如 onnxruntime 需要 inference.onnx）。

1. 把 *_model_dir 指向导出的推理模型文件夹（inference.json/.pdmodel + inference.pdiparams + inference.yml）。
2. 删除 ~/.paddlex/official_models/ 下下载不完整的文件夹，强制重新下载。

适用范围：paddleocr 3.x（已对照仓库 commit dab3fe3 / paddleocr 3.7.x + paddlex 3.7.2 核实）。来源：paddlex-3.7.2/paddlex/inference/models/engines/_base.py:107-115; paddlex-3.7.2/paddlex/inference/models/utils/model_paths.py:50-76; paddlex-3.7.2/paddlex/inference/models/runners/paddle_static/runner.py:345-347; paddlex-3.7.2/paddlex/inference/utils/official_models.py:944-946

识别结果#

结果为空：rec_texts 是 []#

{'rec_texts': [], 'rec_scores': [], ...}   (2.x returned [None])

原因：3.x 从不返回 None。没有可接受文字的图片会得到一个 rec_texts、rec_scores 和 rec_polys 都是空列表的 OCRResult（2.x 则会追加一个 None）。文字可能在检测阶段丢失（默认 text_det_thresh 0.3、text_det_box_thresh 0.6），也可能被得分过滤 text_rec_score_thresh 去掉：rec_* 只保留得分不低于该阈值的行，而 dt_polys 保留所有检测到的框。

1. 打印 res['dt_polys']。为空说明检测阶段什么都没找到；有框但 rec_texts 为空，说明得分过滤把它们全去掉了。
2. 检测阶段：对较淡或对比度低的文字，调低 text_det_box_thresh（例如 0.4）和/或 text_det_thresh。
3. 得分过滤：3.x 默认为 0.0。从 2.x 的 drop_score 沿用过来的值（0.5）会隐藏低置信度的行。
4. 把 lang 设为文档的语言。默认的 PP-OCRv6 模型覆盖中文、英文、日文和拉丁字母语言。
5. 把 2.x 中 if result[0] is None 这类判断换成 if not result[0]['rec_texts']。

res = ocr.predict('page.png')[0]
print(len(res['dt_polys']), 'boxes detected')
print(res['rec_texts'])
# faint text:
res = ocr.predict('page.png', text_det_box_thresh=0.4, text_rec_score_thresh=0.0)[0]

适用范围：paddleocr 3.x。来源：paddleocr-2.10.0/paddleocr/paddleocr.py:762-772; paddlex-3.7.2/paddlex/inference/pipelines/ocr/pipeline.py:480-498; paddlex-3.7.2/paddlex/configs/pipelines/OCR.yaml:32-45; PaddleOCR/paddleocr/_pipelines/ocr.py:58-62

检测框与原图对不上#

paddleocr.dev 已复现 paddleocr.dev 于 2026-10-27 实测：paddleocr 3.7.0 + paddlepaddle 3.2.0。

(no error: rec_polys / rec_boxes look shifted when drawn on your own copy of the image)

原因：默认的 PaddleOCR() 中 use_doc_unwarping=True。UVDoc 会先把页面展平，检测框的坐标对应的是处理后的图片，而不是你的原图。在我们的小票上，开启弯曲矫正时第一行是 [[119,11],[507,8],[507,46],[120,49]]，关闭时是 [[128,55],[489,55],[489,82],[128,82]]。整页方向校正（同样默认开启）也可能旋转页面。

1. 想要原图上的坐标：PaddleOCR(use_doc_unwarping=False, use_doc_orientation_classify=False)。
2. 或者直接使用 PaddleOCR 自己画的图：res.save_to_img('out') 会同时写出 ocr_res_img 和 preprocessed_img（res.img 里也是这两个键）。

ocr = PaddleOCR(use_doc_unwarping=False, use_doc_orientation_classify=False)
res = ocr.predict('receipt.png')[0]
print(res['rec_polys'][0])

适用范围：默认设置下的 paddleocr 3.x 通用 OCR 产线。来源：tested by paddleocr.dev 2026-10-27 (paddleocr 3.7.0 + paddlepaddle 3.2.0); paddlex-3.7.2/paddlex/configs/pipelines/OCR.yaml:6-13

常见问题#