PPPOCRLabel安装步骤+报错解决

PPPOCRLabel安装步骤

原有环境运行PPOCRLabel，报错ValueError: too many values to unpack (expected 2)

由于当前安装的 PaddleOCR 库版本与 PPOCRLabel 自带的推理代码（tools/infer/predict_system.py）不匹配导致的。新版 PaddleOCR（如 3.x）中检测器的 __call__ 方法返回 3 个值（dt_boxes, elapse, _），而 PPOCRLabel 里的旧代码只期望 2 个值，因此报错。

(paddleocr_env) PS E:\AI\PaddleOCR-release-2.7.1\PPOCRLabel> & C:/Users/admin/.conda/envs/paddleocr_env/python.exe e:/AI/PaddleOCR-release-2.7.1/PPOCRLabel/PPOCRLabel.py
download https://paddleocr.bj.bcebos.com/PP-OCRv3/english/en_PP-OCRv3_det_infer.tar to C:\Users\admin/.paddleocr/whl\det\en\en_PP-OCRv3_det_infer\en_PP-OCRv3_det_infer.tar
100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 4.00M/4.00M [00:01<00:00, 3.42MiB/s]
download https://paddleocr.bj.bcebos.com/PP-OCRv3/english/en_PP-OCRv3_rec_infer.tar to C:\Users\admin/.paddleocr/whl\rec\en\en_PP-OCRv3_rec_infer\en_PP-OCRv3_rec_infer.tar
100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 9.96M/9.96M [00:01<00:00, 9.06MiB/s]
download https://paddleocr.bj.bcebos.com/ppstructure/models/slanet/en_ppstructure_mobile_v2.0_SLANet_infer.tar to C:\Users\admin/.paddleocr/whl\table\en_ppstructure_mobile_v2.0_SLANet_infer\en_ppstructure_mobile_v2.0_SLANet_infer.tar
100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 10.2M/10.2M [00:02<00:00, 3.63MiB/s]
download https://paddleocr.bj.bcebos.com/ppstructure/models/layout/picodet_lcnet_x1_0_fgd_layout_infer.tar to C:\Users\admin/.paddleocr/whl\layout\picodet_lcnet_x1_0_fgd_layout_infer\picodet_lcnet_x1_0_fgd_layout_infer.tar
100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 10.1M/10.1M [00:01<00:00, 8.78MiB/s]
[2026/09/09 10:30:46] ppocr WARNING: When args.layout is false, args.ocr is automatically set to false
Traceback (most recent call last):
  File "e:/AI/PaddleOCR-release-2.7.1/PPOCRLabel/PPOCRLabel.py", line 2840, in <module>
    sys.exit(main())
  File "e:/AI/PaddleOCR-release-2.7.1/PPOCRLabel/PPOCRLabel.py", line 2828, in main
    app, _win = get_main_app(sys.argv)
  File "e:/AI/PaddleOCR-release-2.7.1/PPOCRLabel/PPOCRLabel.py", line 2818, in get_main_app
    win = MainWindow(lang=args.lang,
  File "e:/AI/PaddleOCR-release-2.7.1/PPOCRLabel/PPOCRLabel.py", line 111, in __init__
    result = self.ocr.ocr('./data/paddle.png', cls=True, det=True)
  File "C:\Users\admin\.conda\envs\paddleocr_env\lib\site-packages\paddleocr\paddleocr.py", line 555, in ocr
    dt_boxes, rec_res, _ = self.__call__(img, cls)
  File "E:\AI\PaddleOCR-release-2.7.1\PPOCRLabel\..\tools\infer\predict_system.py", line 76, in __call__
    dt_boxes, elapse = self.text_detector(img)
ValueError: too many values to unpack (expected 2)

新建conda环境运行PPOCRLabel

1、创建虚拟环境

conda create -n ppocr python=3.8 -y

2、激活环境

conda activate ppocr

3、安装paddlepaddle（GPU版）

#最通用的安装命令如下，但需要注意，使用清华源等PyPI镜像可能无法获取到最新的2.6.2版本。
pip install paddlepaddle-gpu==2.6.2 -i https://pypi.tuna.tsinghua.edu.cn/simple

#为确保能成功安装 2.6.2 版本，更可靠的方式是从 PaddlePaddle 官方源指定 CUDA 版本进行安装，CUDA 版本是 11.8：
pip install paddlepaddle-gpu==2.6.2 -f https://www.paddlepaddle.org.cn/whl/windows/mkl/cu118.html

[!NOTE]

1. 确认CUDA版本：如果不确定，可以在命令行运行 nvcc --version 来查看。

2. 卸载旧版本：在安装新版本前，建议先卸载已有的 PaddlePaddle 相关包，避免冲突：

   pip uninstall paddlepaddle paddlepaddle-gpu

4、安装lmdb（指定 1.4.1，避免编译错）

pip install lmdb==1.4.1 -i https://pypi.tuna.tsinghua.edu.cn/simple

5、装 paddleocr==2.7.0.3（最后一个带 PPStructure 的版本）

pip install paddleocr==2.7.0.3 -i https://pypi.tuna.tsinghua.edu.cn/simple

[!NOTE]

在安装 paddleocr 时，其依赖包 crc32c 需要从源代码编译， Windows 系统缺少必要的 C++ 编译环境会报错。

6、安装PPOCRLabel

pip install PPOCRLabel -i https://pypi.tuna.tsinghua.edu.cn/simple

7、验证

python -c "from paddleocr import PaddleOCR, PPStructure; print('导入成功')"

输出 导入成功 表示安装成功

8、启动

以中文的方式启动。PPOCRLabel 启动默认英文

#先进入PPOCRLabel文件下
PPOCRLabel --lang ch 

问题报错与解决

切换环境运行报错1

问题原因

PPOCRLabel 在初始化时调用了 PPStructure 类，并尝试访问 args.return_word_box 属性。但你当前安装的 PaddleOCR 库版本（可能是 3.x）中，这个参数可能已被移除或改名，因此引发了 AttributeError。

操作步骤：

1. 打开文件 E:\AI\PaddleOCR-release-2.7.1\ppstructure\predict_system.py

2. 找到第 82 行附近（报错所在行）：

   self.return_word_box = args.return_word_box
   

3. 在这行上面插入一行，手动设置默认值：

   if not hasattr(args, 'return_word_box'):
       args.return_word_box = False
   self.return_word_box = args.return_word_box
   

切换环境运行报错2

问题原因

这次是图像通道数问题：你的图片 ./data/paddle.png 可能是 PNG 格式，带有透明度（4通道 RGBA），而模型预处理只接受 3通道 RGB，导致形状不匹配。

操作步骤：

1. 打开文件 E:\AI\PaddleOCR-release-2.7.1\ppstructure\table\predict_structure.py
2. 找到 __call__ 方法（大约第 120 行附近），其中调用了 transform(data, self.preprocess_op)。
3. 在调用 transform 之前，添加判断，如果图像是 4 通道，则去掉透明度通道。

修改后的代码片段应类似于：

def __call__(self, img):
    # 检查通道数，如果是4通道(RGBA)则转为3通道(RGB)
    if img.shape[2] == 4:
        img = img[:, :, :3]  # 直接丢弃alpha通道
    
    data = {'image': img}
    data = transform(data, self.preprocess_op)
    # ... 后续代码

如果没有 img.shape[2] 的检查，可能图像是灰度图（单通道），但这里出错明确是 (213,488,4)，所以安全处理。

切换环境运行报错2

问题原因

新的错误仍然是通道数问题，这次是在文本检测阶段（predict_det.py）。之前的修改只覆盖了表格结构预测，没有涉及文本检测。

文件路径：E:\AI\PaddleOCR-release-2.7.1\ppstructure\table\predict_table.py

方法1操作

1. 找到 _ocr 方法（大约第 114 行附近），它在 predict_table.py 中。
2. 在该方法开头，添加通道检查与转换代码。

修改后的代码示例（找到类似下面的函数定义）：

def _ocr(self, img, ...):
    # 添加以下两行
    if img.shape[2] == 4:
        img = img[:, :, :3]   # 去掉透明通道
    # ... 原有代码继续

如果 _ocr 方法没有直接接收 img 参数，而是从 __call__ 传入，可以在 __call__ 中处理。但根据报错栈，_ocr 接收了 img，所以在此添加即可。

方法2 如果还想更彻底——采取

也可以在 predict_det.py（site-packages 中）的 __call__ 开头添加同样的转换，这样任何进入文本检测器的图片都会被统一处理，一劳永逸。

文件路径：C:\Users\admin\.conda\envs\ppocr\lib\site-packages\paddleocr\tools\infer\predict_det.py

找到 def __call__(self, img):，在开头加入：

python

if img.shape[2] == 4:
    img = img[:, :, :3]

但注意，这个文件是库文件，升级 paddleocr 可能会覆盖，推荐优先修改项目内的 predict_table.py。

切换环境运行报错3

问题原因

问题出在文本识别阶段：裁剪出的图像仍然是 4 通道（RGBA），而识别模型只接受 3 通道（RGB），导致断言失败。

直接修改 predict_rec.py 中的 resize_norm_img 方法，在通道检查前强制转换。

文件路径：
C:\Users\admin\.conda\envs\ppocr\lib\site-packages\paddleocr\tools\infer\predict_rec.py

操作步骤：

1. 打开该文件，找到 resize_norm_img 方法（大约第 179 行）。

2. 在 def resize_norm_img(self, img, max_wh_ratio): 的第一行（方法体开始处）插入：

   # 强制将 4 通道 RGBA 转为 3 通道 RGB
   if img.shape[2] == 4:
       img = img[:, :, :3]