RapidOCR 3.10 上手：PaddleOCR 模型的离线部署与调参

RapidOCR 是一个把 PaddleOCR 系列模型转成 ONNX、再用轻量运行时离线推理的 OCR 工具包。它不训练模型，做的是“算法已经够用、部署依旧麻烦”这一段工程活：不必安装飞桨框架，Python、C++、Java、C# 都能直接调用。当前版本 3.10.0 发布于 2026 年 10 月 8 日。

仓库采用 Apache-2.0 许可证，2026 年 11 月 6 日查看时约 8.5k Star。这里有个容易混淆的边界：模型权重来自 PaddleOCR，版权归百度及相关权利人，RapidOCR 负责的是权重转换与推理封装，并不主张模型的所有权。

它补的是工程层：检测、方向分类、识别三段流水线

PaddleOCR 的模型精度已经能满足多数票据、证件、截图场景，但要用起来得先背上整套飞桨运行时。端侧设备跑不动，C++、Java、C# 项目还要各自重写一遍前后处理；政务、医疗这类不能外传的图片，又不适合直接调商用接口。

RapidOCR 的做法是把文本检测、文本行方向分类、文本识别三个模型的权重统一转成 ONNX，各语言 SDK 里对齐前后处理逻辑。调用方只需要关心一件事：丢一张图进去，拿回文本框坐标、文本内容和置信度。

主仓库的 README列出了六种推理引擎，同一套模型可以在它们之间切换，实验性的 CoreML 与 MPS 后端也在其中。语言侧提供 Python、C++、Java、C# 四种 SDK，Android 另有独立示例。

时间线上也有个节点：2026 年 11 月 1 日，官方博客发布公告，称项目在开源中国举办的 2026 上海开源软件应用创新大赛中获开源 AI 工具赛道三等奖。奖项不改变用法，但能说明项目仍在维护。

安装：一条命令，加三个自检命令

基础安装就一条：pip install rapidocr onnxruntime。从 2.0.6 起，onnxruntime 不再作为依赖自动安装，所以两个包要一起写，只装 rapidocr 会在初始化时报找不到引擎。Python 版本要求 3.8 以上、4 以下，Linux、Windows、macOS 都支持。

装完的 wheel 约 27.2MB，内置了 small 尺寸的检测、方向分类、识别三个模型，开箱即可离线识别中英文。想确认环境是否正常，执行 rapidocr check，它会用 ONNX Runtime 跑一张内置图，成功时输出 Success! rapidocr is installed correctly!。

另外两个命令值得先记住。rapidocr config 会在当前目录生成 default_rapidocr.yaml，参数都在这份文件里，改完用 config_path 指回去即可；rapidocr download_models 把默认模型预先下到安装目录的 models 下，断网机器就靠它提前备料。

3.10.0 还新增了语言查询，命令行用 rapidocr --list-langs --task rec --ocr_version PP-OCRv6 --model_type medium，Python 里对应 RapidOCR.list_supported_langs()。选语种前先查一遍，比翻文档猜模型名快。

还有一处旧教程容易误导人：rapidocr_onnxruntime、rapidocr_openvino、rapidocr_paddle 这三个旧包名将逐步停止维护，统一收敛到 rapidocr。安装文档里写得很直白，照老文章复制 import 语句，大概率开头就报错。

三行代码跑通，先动三个参数

最小用法只有三步：from rapidocr import RapidOCR 导入类，engine = RapidOCR() 创建引擎，result = engine("invoice.png") 传入图片。输入不限于本地路径，URL、bytes、NumPy 数组、Pillow 对象都可以；3.10.0 起还支持直接解码内存地址与带 stride 的原始内存缓冲。

返回对象里，txts 是识别出的文本列表，scores 是对应的置信度，boxes 是每个文本框的四个角点坐标。默认情况下 word_results 为 None，只有把 return_word_box 设为 True，才会返回单字或单词级坐标。

需要可视化就调 result.vis("vis_result.jpg")，它会把框和文本画到图上存成文件。需要排版文本可以用 result.to_markdown()，这个能力从 3.2.0 起提供，文档里明确写着“粗略支持”，并且要同时打开 return_word_box 与 return_single_char_box 才有足够的位置信息。

默认模型组合在 3.9.0 换过一次：检测与识别改用 PP-OCRv6 的 small 模型，方向分类仍是 PP-OCRv4 mobile。CSDN 上有一篇升级说明记录了这次变化，wheel 因此从 15MB 涨到 29MB 左右。升级后如果结果和旧版本对不上，先怀疑这里，而不是以为代码写错了。

参数写在 yaml 里，也支持在构造时用 params 字典覆盖，键名带阶段前缀，例如 {"Det.box_thresh": 0.3}。图片是白底黑字、框漏检时调低 box_thresh；文字挤在一起被切成两段时调小 unclip_ratio。

长截图、扫描件这类极端比例要留意缩放参数。limit_side_len 默认 736，limit_type 默认 min，意思是把短边对齐到 736；改成 max 则按长边限制。

模型尺寸有三个档：tiny、small、medium，默认 small。tiny 适合对延迟敏感的截图识别，medium 在复杂版面上更稳，代价是模型更大、单图更慢。具体差多少要在自己的样本上测，文档给的指标不一定对应你的票据或表格。

还有个提速开关：use_cls 控制方向分类，关掉能省一次推理，前提是输入图像的文字都是正的。手机翻拍、扫描歪斜的图不要关，否则整段文字可能识别成乱码。

3.10 的变化与几个会踩的坑

3.10.0 把模型路由集中到 YAML，并对外暴露支持语言列表，多语种调用比以前清楚。同版本还处理了几处工程细节：模型改为懒加载，修复 limit_side_len 在 limit_type 为 max 时被忽略的问题，PyTorch 引擎改用 weights_only=True 加载权重。版本发布页有完整清单。

懒加载会带来一个直观错觉：从 3.10.0 起，RapidOCR() 初始化很快，第一次调用却明显变慢。那不是性能退化，是模型在首次使用时才加载。常驻服务建议启动后先跑一张占位图预热，别让真实用户请求先撞上这段延迟。

另一个坑更隐蔽。3.10.0 起默认依赖改成 opencv-python-headless，不再带图形界面。代码里只要出现 cv2.imshow 就会报错；需要弹窗调试，得卸载 headless 再装 opencv-python，两者不能同时存在。

阿拉伯语等从右向左书写的语言，要额外装 rapidocr[rtl]，它会带上 python-bidi。3.10.0 起初始化时会校验这个依赖，缺了直接拦下，不会给你一堆顺序颠倒的识别结果。

最后是版本锁定。不锁版本时，不同机器装到的默认模型可能不一样，同一批图片跑出不同结果，排查起来很费时间。生产环境把 rapidocr 与推理引擎的版本都写进依赖文件，再用 参数文档核对默认值，比事后对账省事。

边界：不做版面分析，也不保证阅读顺序

它输出的是文本框加文本，没有段落、没有表格结构、也没有阅读顺序。双栏 PDF 转出来的文本可能是左右交错的一串，票据里的金额和抬头也会混在一起。这类需求得再叠一层版面分析或表格识别。

想把 PDF 里的表格和双栏正文还原成结构化 Markdown，Docling 的处理路径更对口，它把版面与表格一起建模，RapidOCR 反而常被当成它的识别后端之一。分工是清楚的：一个管“字是什么”，一个管“字在哪一块”。

识别精度取决于模型与图像质量。手写体、低分辨率截图、弯曲书页都容易掉分；方向分类只处理 0 度和 180 度，横躺 90 度的整页图不在它的职责里。遇到这类素材，先做旋转与去噪，比反复调阈值有效。

它也不解析 PDF，扫描件要先转成图片再送入。如果目标是给一堆纸质档案做全文检索，更适合用带 OCR 流程的归档系统，比如Paperless-ngx 的 OCR 检索方案，RapidOCR 在这里是可替换的零件，不是整套方案。

和视觉大模型比，它没有“理解”能力，读不出图表含义，但也不会编造不存在的字段，批量处理按本地算力计费。大模型能处理复杂版面和手写连笔，代价是幻觉与成本，两者是互补关系。

适合谁用，以及一条上手路径

三类人比较对口：要把 OCR 嵌进 C++、Java、C# 客户端的开发者；需要批量处理票据、证照且数据不能出内网的单位；在搭 RAG 文档解析、想要一个便宜前置环节的团队。

• 先把 rapidocr check 跑通，确认引擎装对，别在依赖上耗时间。
• 用三五张真实图片试默认参数，记录漏检和错行的情况，再动阈值。
• 换 tiny 与 medium 各跑一遍，比较速度与准确率，选出自己的默认档。
• 离线机器提前执行 download_models，并把模型目录一起打包进镜像。
• 上线前锁版本，把 yaml 配置纳入版本管理，升级时对比默认值变化。

如果只是偶尔识别几张截图，装个带界面的 OCR 工具更省事；如果需要把识别能力做成服务、嵌进流水线，或者必须完全离线，RapidOCR 的工程封装才体现出价值。它不解决精度上限问题，但把部署门槛降到了 pip 安装这一级。

相关地址

以下为文中项目的官方入口，版本号、文档与下载以这些页面为准。

• RapidOCR（GitHub 仓库）：https://github.com/RapidAI/RapidOCR
• RapidOCR（版本发布页）：https://github.com/RapidAI/RapidOCR/releases
• RapidOCR（文档站）：https://rapidai.github.io/RapidOCRDocs/main/
• Docling（站内实测文章）：https://www.1fdh.com/4971.html
• Paperless-ngx（站内上手文章）：https://www.1fdh.com/4679.html