把 PaddleOCR 2.x 代码迁移到 3.x

2.x → 3.x 代码转换工具#

转换工具基于规则，而不是靠猜。它只改写自己能识别的模式，为每处改动注明 PaddleOCR 源码中的依据行，并在需要人来决定的地方留下 # TODO(paddleocr 3.x) 注释。我们在 PaddleOCR 3.7.0 上运行了前两个示例的转换结果：两者都没有报错，都正确读出了测试小票的全部 27 行，第一个还写出了 result.jpg。⁷

3.x 改了什么，为什么改#

PaddleOCR 2.x 从 2021 年到 2025 年初，一直是在同一套轻量代码上不断叠加功能。维护者在升级说明中写道，这种方式走到了尽头：代码重复、接口不一致，旧依赖也无法再配合新版 PaddlePaddle。他们的答案是“一次重大的、不向后兼容的升级”。² 在 3.x 中，paddleocr 包是 PaddleX 产线之上的一层薄封装；PaddleOCR 封装的是 PaddleX 的 OCR 产线，并返回结果对象。¹

1. 2023 年 9 月 15 日paddleocr 2.7.0.3——至今仍常见于老项目的 requirements.txt。
2. 2025 年 3 月 7 日paddleocr 2.10.0——最后一个 2.x 版本。
3. 2025 年 5 月 20 日paddleocr 3.0.0——基于 PaddleX 的全新 API。
4. 2026 年 6 月 11 日paddleocr 3.7.0——当前版本，默认使用 PP-OCRv6 模型。

以上日期均为 PyPI 上的首次上传日期。⁶ 现在不指定版本安装 paddleocr 会得到 3.7.0，所以只要新建环境，2.x 代码就会立刻出错。导致出错的改动如下：

还有两处改动不会报错，但会改变输出：新的默认模型和预处理（见 悄悄变化的默认值），以及推理引擎的安装方式。在 3.x 中 pip install paddleocr 不会安装 PaddlePaddle，而 PyPI 上的 paddlepaddle-gpu 停在 2.6.2——见 安装教程。

use_angle_cls 以及仍然可用的 11 个旧参数名#

3.x 为 PaddleOCR 的旧关键字参数保留了一张小小的映射表。下面是完整列表，直接摘自源码：¹

_DEPRECATED_PARAM_NAME_MAPPING = {
    "det_model_dir": "text_detection_model_dir",
    "det_limit_side_len": "text_det_limit_side_len",
    "det_limit_type": "text_det_limit_type",
    "det_db_thresh": "text_det_thresh",
    "det_db_box_thresh": "text_det_box_thresh",
    "det_db_unclip_ratio": "text_det_unclip_ratio",
    "rec_model_dir": "text_recognition_model_dir",
    "rec_batch_num": "text_recognition_batch_size",
    "use_angle_cls": "use_textline_orientation",
    "cls_model_dir": "textline_orientation_model_dir",
    "cls_batch_num": "textline_orientation_batch_size",
}

传入其中任意一个，3.x 都会替你改成新名称并给出警告。我们在 3.7.0 上运行 PaddleOCR(lang='en', use_angle_cls=True)，得到的正是：⁷

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

除非由 __main__ 触发，Python 默认会隐藏 DeprecationWarning，所以很多人根本看不到这条警告。从这张表周围的代码可以得出三条规则：¹

• 新旧名称同时传入会报错。PaddleOCR(use_angle_cls=True, use_textline_orientation=True) 会抛出 ValueError: `use_angle_cls` and `use_textline_orientation` are mutually exclusive.（我们复现过）。
• 只有 PaddleOCR 有这张表。PPStructureV3(det_model_dir=...) 和 PPStructureV3(use_angle_cls=True) 会抛出 ValueError: Unknown argument: det_model_dir / use_angle_cls。两者我们都复现过。
• “还能用”不等于“行为不变”。2.x 中 use_angle_cls 默认为 False。3.x 中不设置 use_textline_orientation 时采用产线默认值，也就是 True。⁵

同样这 11 个名称在 paddleocr ocr 中也以命令行参数的形式存在：--use_angle_cls 仍然可用，并会打印 CLIDeprecationWarning: The option `--use_angle_cls` has been deprecated and will be removed in the future. Please refer to the documentation for more details.

use_gpu、show_log、use_onnx、drop_score：是报错，不是警告#

其余所有遗留的关键字参数都会撞上这个循环，它只接受 3.x 的引擎选项：¹

unknown_names = kwargs.keys() - default_vals.keys()
for name in unknown_names:
    raise ValueError(f"Unknown argument: {name}")

因为它遇到第一个未知名称就抛出异常，而 unknown_names 又是集合，所以带着三个过时参数的构造函数每次运行只会报出其中一个。用下面的表格或转换工具一次性全部改掉。我们在 3.7.0 上的复现结果：⁷

use_gpu=True      -> ValueError: Unknown argument: use_gpu
show_log=False    -> ValueError: Unknown argument: show_log
use_onnx=True     -> ValueError: Unknown argument: use_onnx
drop_score=0.5    -> ValueError: Unknown argument: drop_score

反方向的常见错误：device='cuda'。PaddleX 会用一个裸 AssertionError 拒绝它；GPU 的设备类型叫 gpu。

ocr(img, cls=True) 与新的结果格式#

3.x 仍然有 ocr() 方法，但它只是一个已弃用的别名，会把关键字参数转发给 predict()：¹

@deprecated("Please use `predict` instead.")
def ocr(self, img, **kwargs):
    return self.predict(img, **kwargs)

predict() 没有 cls 参数，所以几乎每篇 2.x 教程里都有的那一行会直接失败。在 3.7.0 上我们得到：⁷

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

文本行方向分类现在在创建对象时决定（use_textline_orientation=True），或在单次调用时用 predict(img, use_textline_orientation=False) 指定。PaddleX 源码里有个坑：你可以在单次调用时关闭它，但如果创建对象时没开，单次调用时再打开只会记录一条错误日志，而不会执行。

更大的变化是返回值。在 2.x 中，ocr() 为每张图片返回一个列表，每行是 [box, (text, score)]，没识别到文字时返回 None。³ 在 3.x 中，predict() 为每张图片或每个 PDF 页面返回一个 OCRResult。它是一个包含若干并列列表的字典：⁵

值得了解旧循环遇到这个对象时会发生什么，因为报错里完全不提 PaddleOCR。for line in result[0] 现在遍历的是字典的键，所以第一个 line 是字符串 'input_path'，box, (text, score) = line 会报 ValueError: too many values to unpack (expected 2)。result[0][0][1][0] 这类下标会报 KeyError: 0。两者我们都复现过。⁷

result = ocr.ocr(img_path, cls=True)
for line in result[0]:
    box, (text, score) = line
    print(text, score, box)

result = ocr.predict(img_path)
for res in result:  # 每张图片 / 每个 PDF 页面一个 OCRResult
    for box, text, score in zip(res['rec_polys'], res['rec_texts'], res['rec_scores']):
        print(text, score, box.tolist())

转换之后有三个细节容易出错。多边形是 NumPy 数组，所以 json.dumps 之前要先调用 .tolist()（或者直接用 res.json）。没有文字的页面得到的是空列表而不是 None，所以 if result[0] is None 永远不会成立——改为判断 if not res['rec_texts']。另外，在默认的 use_doc_unwarping=True 下，坐标对应的是展平后的图片：在我们的小票上，开启弯曲矫正时第一行是 [[119,11],[507,8],[507,46],[120,49]]，关闭时是 [[128,55],[489,55],[489,82],[128,82]]。⁷ 详见 检测框与原图对不上。

ocr(img, det=False) 和 ocr(img, rec=False) 在产线中没有对应写法，请使用单模型类：TextRecognition(model_name="PP-OCRv6_medium_rec").predict(crop) 返回 rec_text 和 rec_score；TextDetection(model_name="PP-OCRv6_medium_det").predict(img) 返回 dt_polys 和 dt_scores。转换工具不会去猜你的裁剪图是怎么来的，而是给这些调用标上 TODO。

cannot import name 'draw_ocr' from 'paddleocr'#

draw_ocr 由 paddleocr 2.10.0 导出，而 3.x 包里没有它，所以导入会失败：⁷

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

现在结果对象可以自己绘图。升级说明用一行调用替换了整段可视化代码：²

from PIL import Image
from paddleocr import draw_ocr
result = result[0]
image = Image.open(img_path).convert('RGB')
boxes = [line[0] for line in result]
txts = [line[1][0] for line in result]
scores = [line[1][1] for line in result]
im_show = draw_ocr(image, boxes, txts, scores, font_path='simfang.ttf')
im_show = Image.fromarray(im_show)
im_show.save('result.jpg')

for res in result:
    res.save_to_img('output')            # 写出 <name>_ocr_res_img.png（以及预处理后的图片）
    pil_image = res.img['ocr_res_img']   # 或者以 PIL 图片的形式留在内存中

在我们的小票上，save_to_img('output') 写出了 receipt_ocr_res_img.png 和 receipt_preprocessed_img.png；res.img 里也是这两个键。⁷ 要使用自己的字体，请设置环境变量 PADDLE_PDX_LOCAL_FONT_FILE_PATH，而不是传 font_path。其他被移除的辅助函数也同样对应：save_structure_res → res.save_to_json()、save_to_xlsx()、save_to_html() 或 save_all()；convert_info_docx → res.save_to_word()；to_excel → res.save_to_xlsx()。⁵

det_model_dir 和 rec_model_dir：自定义模型#

det_model_dir、rec_model_dir 和 cls_model_dir 属于那 11 个别名，所以在 PaddleOCR 上仍然可用。但底层有两点变化：

• 还要给出模型名称。如果只设置了 text_detection_model_dir，产线会沿用默认名称（PP-OCRv6_medium_det），PaddleX 再拿它与文件夹中 inference.yml 里的名称比对：ValueError: Model name mismatch: expected 'PP-OCRv6_medium_det' but config has 'PP-OCRv5_server_det'. Please input the correct model dir.⁵
• 文件夹必须是 3.x 格式的导出。3.x 会查找 inference.json 或 inference.pdmodel，以及 inference.pdiparams 和 inference.yml。没有有效文件的文件夹会报 No valid model files were found for engine 'paddle_static'。
• 训练相关的选项没了。rec_char_dict_path、rec_algorithm、det_algorithm、use_space_char 和 max_text_length 会报 Unknown argument。模型按名称选择，各模块的设置放在导出的 PaddleX 配置中（先 export_paddlex_config_to_yaml，再传 paddlex_config=...）。

from paddleocr import PaddleOCR

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',
)

给出模型名称或文件夹后，lang 和 ocr_version 会被忽略，并给出 UserWarning。另外注意，2.x 的文字体系取值 lang='latin'、'arabic'、'cyrillic' 和 'devanagari' 在 3.x 中不是语言代码：它们会报 No models are available for lang='latin' and ocr_version=None. 请从 语言列表 中选择真正的语言代码。

悄悄变化的默认值#

迁移后能跑通的代码，文字、检测框和速度仍可能与以前不同，因为默认值变了：⁵³

转换工具的“保持 2.x 的行为”选项会加上报错数据库推荐的四个开关，使输出接近 2.x：use_doc_orientation_classify=False、use_doc_unwarping=False、use_textline_orientation=False 和 text_rec_score_thresh=0.5。关闭预处理模型还能让 3.x 跑得更快。它保留新模型——新模型在我们的五份测试文档上 124 项中 123 项完全正确（我们的基准测试（英文））。

PPStructure → PPStructureV3#

在 3.x 中，from paddleocr import PPStructure 会报 ImportError: cannot import name 'PPStructure' from 'paddleocr'。升级说明指向 PPStructureV3，它需要额外安装：²⁸

没有安装它时，PPStructureV3() 会报 RuntimeError: A dependency error occurred during pipeline creation（解决方法）。它的构造函数有自己的一套参数，而且没有别名映射表，所以连在 PaddleOCR 上能用的旧名称在这里也会报错。我们在 3.7.0 上从 PPStructureV3 得到了 use_gpu、det_model_dir、use_angle_cls 和 show_log 的 Unknown argument 报错。⁷

from paddleocr import PPStructure, save_structure_res

table_engine = PPStructure(show_log=True, image_orientation=True, use_gpu=True)
img = cv2.imread(img_path)
result = table_engine(img)
save_structure_res(result, './output', os.path.basename(img_path).split('.')[0])
for line in result:
    line.pop('img')
    print(line)

from paddleocr import PPStructureV3

pipeline = PPStructureV3(use_doc_orientation_classify=True, device='gpu')
output = pipeline.predict(img_path)       # 每页一个结果；PDF 可以直接传入
for res in output:
    res.print()
    res.save_to_json('output')
    res.save_to_markdown('output')        # 另有：save_to_word、save_to_html、save_to_xlsx、save_to_img

2.x 的版面结果是单张图片的区域字典列表；3.x 的结果是每页一个对象。我们的 PP-StructureV3 指南 详细介绍了输出内容，包括它默认使用哪些 OCR 模型。

命令行：paddleocr --image_dir → paddleocr ocr -i#

3.x 的命令行需要子命令，并用 -i 传入输入。2.x 的写法会以一种让人摸不着头脑的方式失败：argparse 把你的文件名当成了子命令。我们在 3.7.0 上的运行结果：⁷

usage: paddleocr [-h] [-v] COMMAND ...
paddleocr: error: argument COMMAND: invalid choice: 'receipt.png' (choose from 'doc_preprocessor', 'doc_understanding', 'formula_recognition_pipeline', 'ocr', 'doc_parser', 'pp_chatocrv4_doc', 'pp_doctranslation', 'pp_structurev3', ...)

布尔参数接受 true/True/1，其他值都视为 false。我们用 --save_path 在小票上运行了 paddleocr ocr：它打印了结果，并写出了 JSON 和两张图片。可以把整个 shell 脚本粘贴进转换工具，它只改写 paddleocr 和 pip install 这两类行，其余保持不变。

完整的 2.x → 3.x 对照表#

下面是我们核实过的全部 123 条对照，与转换工具使用同一份数据生成。“别名，有警告”表示旧名称仍可使用；“需改名”表示必须修改；“已替换”和“已移除”如果保留不改就会报错。每一行都链接到我们阅读过的文件和行号。各行的说明目前为英文原文。¹³⁵

导入 13#

PaddleOCR 构造参数 47#

PPStructure → PPStructureV3 参数 18#

方法与结果格式 12#

辅助函数 9#

命令行 24#

继续使用 2.x：把 paddleocr 锁定在 3 以下#

如果暂时无法迁移，请在单独的虚拟环境中锁定最后一个 2.x 版本：

这会解析到 2.10.0。和 3.x 一样，它的 wheel 也没有把 PaddlePaddle 列为依赖，需要你自己安装框架。³ 我们没有测试过哪些 PaddlePaddle 3.x 版本能运行 paddleocr 2.x，所以如果你已经有一个能用的 2.x 环境，请把它冻结下来（pip freeze > requirements.txt），而不是重建。导入了 2.x 内部模块（paddleocr.tools、paddleocr.ppocr、paddleocr.ppstructure）的代码只能在 2.x 上运行：3.x 包里没有这些模块。

等待的代价会越来越大：2.x 不会再有新模型，而 3.x 已经从 PP-OCRv5 升级到 PP-OCRv6，还新增了 PaddleOCR-VL。

迁移检查清单#

1. 新环境，新引擎#

   新建一个 venv。pip install paddleocr，再从飞桨源安装 paddlepaddle==3.2.0，或者安装 onnxruntime。安装命令生成器 会给出适合你机器的准确命令。

2. 转换代码#

   把每个文件都过一遍 转换工具，处理掉每一个 # TODO(paddleocr 3.x)。

3. 把警告当成错误跑一次#

   用 python -W error::DeprecationWarning 运行测试，找出残留的别名和 ocr() 调用。

4. 对比输出#

   在几份真实文档上比较识别文字。如果有差异，先试试“保持 2.x 的行为”那几个开关，再怀疑模型。

5. 查一查遇到的报错#

   把任何意外的报错粘贴到 报错修复助手。

常见问题#