CnOCR - Character Recognition Toolkit

2025.06.26 版本更新：发布 V2.3.2

关键迭代内容：

• 整合了最新的 PPOCRv5 识别引擎
• 新增了对 PP-OCRv5 识别模型的兼容性支持：ch_PP-OCRv5 和 ch_PP-OCRv5_server 模型的引入

[2024.11.30 版本更新]：发布 V2.3.1

主要发布说明：

• 借由 RapidOCR 框架，整合了当下最新的 PPOCRv4 识别引擎，极大地拓宽了模型选择范围
• 引入了对 PP-OCRv4 识别模型的支持，包含标准版与服务器部署版本
• 优化了文件读取逻辑，现已完全兼容 Windows 系统下的中文文件路径访问
• 缺陷修复：解决了多进程环境下 transform_func 无法进行序列化操作的问题
• 缺陷修复：确保了与 albumentations=1.4.* 库版本的良好互操作性

[2023.12.24 版本更新]：发布 V2.3

核心变动摘要：

• 全系列模型均经过重新训练与微调，显著提升了识别精度。
• 根据不同的应用场景对模型进行了系统化的分类（详见 可使用的识别模型 章节）：
• scene：适用于自然场景图像的文本提取，模型名称通常以 scene- 为前缀，例如 scene-densenet_lite_136-gru。
• doc：专为结构化文档截图或高质量扫描件设计，模型名称通常以 doc- 为前缀，例如 doc-densenet_lite_136-gru。
• number：专职数字识别（仅限 0 到 9），适用于银行账号、证件号码等精确数字提取场景。模型名称通常以 number- 为前缀，例如 number-densenet_lite_136-gru。
• general: 对应无明显倾向性的通用场景，模型命名沿袭旧有规范，无特定前缀，例如 densenet_lite_136-gru。

  ⚠️ 特别提示：上述场景划分仅供初步参考，最终模型选择应以在目标图像上的实际识别表现为准。

• 新增了两组更大参数量的模型系列以供选用：
• *-densenet_lite_246-gru_base：初期仅对知识星球 CnOCR/CnSTD私享群 订阅者开放，预计一个月后将公开发布。
• *-densenet_lite_666-gru_large：Pro 等级模型，需付费解锁使用权限。

更多技术细节请查阅：CnOCR V2.3 正式发布：模型优化、品类扩展、性能升级 | Breezedeus.com。

CnOCR 是一个基于 Python 3 环境的先进文本识别（Optical Character Recognition，简称OCR）软件包。它原生支持对简体中文、部分繁体中文、英文字符及阿拉伯数字的常见字符识别，并具备处理垂直排列文本的能力。工具包内置了超过20种 已训练模型，开箱即用，覆盖多种应用需求。此外，CnOCR 也为用户提供了简便的模型训练接口以定制专属模型。欢迎扫描下方二维码添加小助手微信，请备注 ocr，助手将定期集中邀请加入交流社区：

作者同时运营知识星球 CnOCR/CnSTD私享群，在此群组内提问可以获得作者更即时的反馈和支持，诚邀您加入。知识星球会员 专享特权包括：

• 免费获取部分尚未公开的付费模型的下载权限；
• 购买所有其他付费模型的八折优惠；
• 作者对使用中遇到的困难提供快速响应支持；
• 作者每月提供两次针对用户特定数据的免费模型训练服务。
• 群内将持续分享CnOCR/CnSTD相关的独家内部资料；
• 群内将持续发布 OCR/STD/CV 等领域的最新前沿研究资料。

深度技术文档

参阅 CnOCR 在线文档 以获取完整信息。

操作指南

自 V2.2 版本发布以来，CnOCR 内部已无缝集成文本检测引擎 CnSTD 进行字符的定位与检测。因此，CnOCR V2.2 及更高版本不仅能处理版面规整的印刷体图像（如软件截图、清晰扫描件），还能有效识别自然场景图像中的文本。

以下是针对不同应用场景的调用示例。

场景化调用示例

常见图像文本提取

初始阶段，所有配置参数均采用默认值即可。若识别精度不尽人意，建议尝试调整各项参数，通常能找到提升精度的理想配置。

python from cnocr import CnOcr

img_fp = './docs/examples/huochepiao.jpeg' oc = CnOcr() # 实例化时使用所有默认参数 out = oc.ocr(img_fp)

print(out)

识别输出示例：

针对版面简单的印刷体截图图像识别

若处理的图像是版面结构简单的印刷体文字（例如软件截图、文档扫描件），可以通过设置参数 det_model_name='naive_det' 来禁用深度文本检测模型，转而采用简化的基于规则的行分割策略。

注意

det_model_name='naive_det' 的运行效果等同于 V2.2 之前的 CnOCR 版本（即 V2.0.*, V2.1.*）。

使用 det_model_name='naive_det' 的主要优势在于执行速度极快，但缺点是对输入图像的适应性较差。判断是否应采用此检测模式的最简单方法是：用目标图像进行测试，若效果满意则采用，否则应切换回更强大的检测模型。

python from cnocr import CnOcr

img_fp = './docs/examples/multi-line_cn1.png' oc = CnOcr(det_model_name='naive_det') out = oc.ocr(img_fp)

print(out)

识别结果展示：

垂直文本识别

建议采用源自 PaddleOCR（后续简称 ppocr）的中文识别模型 rec_model_name='ch_PP-OCRv3' 来处理竖排文本。

python from cnocr import CnOcr

img_fp = './docs/examples/shupai.png' oc = CnOcr(rec_model_name='ch_PP-OCRv3') out = oc.ocr(img_fp)

print(out)

识别结果：

纯英文内容识别

尽管中文字符的检测与识别模型也能处理英文内容，但专门为英文文本训练的检测器和识别器通常能达到更高的精度。对于纯英文的应用场景，推荐选用 ppocr 提供的英文检测模型 det_model_name='en_PP-OCRv3_det' 和英文识别模型 rec_model_name='en_PP-OCRv3'。

python from cnocr import CnOcr

img_fp = './docs/examples/en_book1.jpeg' oc = CnOcr(det_model_name='en_PP-OCRv3_det', rec_model_name='en_PP-OCRv3') out = oc.ocr(img_fp)

print(out)

识别结果概览：

传统繁体中文识别

请选用源自 ppocr 的繁体中文识别模型 rec_model_name='chinese_cht_PP-OCRv3' 进行处理。

python from cnocr import CnOcr

img_fp = './docs/examples/fanti.jpg' oc = CnOcr(rec_model_name='chinese_cht_PP-OCRv3') # 选用繁体识别专用模型 out = oc.ocr(img_fp)

print(out)

使用该繁体模型时需留意以下限制：

• 其识别的总体准确率相对有限，表现中等；

• 除了繁体汉字外，对标点符号、英文字母和数字的识别效果均不理想；

• 此特定模型不支持竖向文本的识别。

识别结果图示：

针对单行文本图像的快速识别

当您确定待处理的图像仅包含单行文字（参考下图），可以使用类方法 CnOcr.ocr_for_single_line()。此方法会直接跳过耗时的文字检测步骤，识别速度可提升一倍以上。

调用代码如下所示：

python from cnocr import CnOcr

img_fp = './docs/examples/helloworld.jpg' oc = CnOcr() out = oc.ocr_for_single_line(img_fp) print(out)

更多应用场景演示

• 核酸检测/疫苗接种凭证截图识别

• 身份证件信息提取

• 餐饮小票/收据识别

安装部署

理想情况下，基础安装仅需执行一条命令行指令即可完成。

bash $ pip install cnocr[ort-cpu]

如果您使用的是 GPU 环境并计划利用 ONNX 模型进行加速，请采用以下命令进行安装：

bash $ pip install cnocr[ort-gpu]

如果您计划自行训练或微调模型，可使用以下命令安装开发依赖：

bash $ pip install cnocr[dev]

若标准安装源下载速度较慢，建议切换至国内镜像源，例如阿里云的加速源：

bash $ pip install cnocr[ort-cpu] -i https://mirrors.aliyun.com/pypi/simple

环境提示

请务必使用 Python3 环境（版本范围 3.7. 至 3.10. 通常兼容良好），Python 2 环境未进行兼容性测试。

更多详细的安装说明请参考 安装文档。

重要警告

如果您的系统尚未安装 PyTorch 或 OpenCV-python 库，首次安装可能会遇到依赖冲突或编译问题。这些通常是常见的环境配置问题，建议通过搜索引擎（百度/Google）查找对应解决方案。

Docker 容器化部署

您可直接从 Docker Hub 拉取预先配置好 CnOCR 环境的官方镜像，实现快速启动。

bash $ docker pull breezedeus/cnocr:latest

更多关于 Docker 的部署细节请参考 安装文档。

部署为 HTTP 服务

CnOCR 在 V2.2.1 版本中加入了基于 FastAPI 框架构建的 Web 服务接口。启用该服务需要安装额外的依赖包，请使用以下命令安装：

bash pip install cnocr[serve]

安装完毕后，可通过如下命令启动 HTTP 监听服务（-p 后面的数字是服务端口号，可根据实际需求修改）：

bash cnocr serve -p 8501

服务启动后，您可以使用以下方式通过网络请求调用该服务。

命令行调用（cURL）

假设待识别文件路径为 docs/examples/huochepiao.jpeg，可使用 curl 命令进行 POST 请求：

bash

curl -F image=@docs/examples/huochepiao.jpeg http://0.0.0.0:8501/ocr

Python 客户端调用

使用 Python 的 requests 库进行服务调用的示例代码如下：

python import requests

image_fp = 'docs/examples/huochepiao.jpeg' r = requests.post( 'http://0.0.0.0:8501/ocr', files={'image': (image_fp, open(image_fp, 'rb'), 'image/png')}, ) ocr_out = r.json()['results'] print(ocr_out)

更详细的集成示例可参考项目内的文件 scripts/screenshot_daemon_with_server.py 。

其他编程语言

其他语言的客户端实现应参考上述 curl 请求的方式自行构建。

可用模型资源列表

可选用的文本检测模型

详细的检测模型信息请参阅 CnSTD 项目的下载说明。

可选用的文本识别模型

与 CnOCR V2.2. 版本对比，V2.3* 版本中大多数模型都经过了重新训练和精调过程，从而带来了更高的识别精度。同时，我们新增了两组参数规模更大的模型系列供高级用户选择：

• *-densenet_lite_246-gru_base：初期专供 知识星球 CnOCR/CnSTD私享群 订阅者优先使用，随后将免费开源。
• *-densenet_lite_666-gru_large：付费 Pro 模型，需通过指定链接购买后方可启用。

V2.3 版本中的模型根据其优化的应用场景，可被划分为以下主要类别：

• scene：面向场景图像，适用于自然拍摄照片中的文本提取。这类模型名称前缀为 scene-，例如模型 scene-densenet_lite_136-gru。
• doc：面向文档图像，适用于识别排版工整的截图或扫描件等。这类模型名称前缀为 doc-，例如模型 doc-densenet_lite_136-gru。
• number：仅支持数字识别（仅限 0 到 9 十个阿拉伯数字），专为银行卡号、证件号码等场景优化。这类模型名称前缀为 number-，例如模型 number-densenet_lite_136-gru。
• general: 适用于无明显风格倾向的通用图像。这类模型沿用旧版命名规则，无特定前缀，例如模型 densenet_lite_136-gru。

注意 ⚠️：上述场景描述仅供参考，用户在实际部署时，务必以模型在目标数据上的实测性能为最终选择依据。

更多模型细节请参考：可用模型资源。

前进路线图

• [x] 实现对多行文本图像的准确识别 (已完成)
• [x] CRNN 模型支持变长序列预测，增强处理灵活性 (自 V1.0.0 起)
• [x] 完善单元测试用例 (进行中)
• [x] 修复已知软件缺陷（当前代码结构相对复杂。。） (进行中)
• [x] 支持识别文本中的空格字符 (自 V1.1.0 起)
• [x] 探索并集成新型模型，如 DenseNet 架构，以期提升识别精度 (自 V1.1.0 起)
• [x] 数据集清洗与优化，去除低质量样本；在此基础上，对所有模型进行重训练
• [x] 技术栈迁移：从 MXNet 架构切换至 PyTorch 框架 (自 V2.0.0 起)
• [x] 基于 PyTorch 平台训练出更高性能的模型
• [x] 支持对列式（垂直）布局文本的识别能力
• [x] 实现与 CnSTD 文本检测模块的零摩擦集成 (自 V2.2 起)
• [ ] 持续推进模型识别精度的边界突破
• [ ] 扩展对更多特定应用场景的优化支持

鼓励作者（请喝杯咖啡）

开源维护不易，若本工具包对您的工作有所助益，恳请您考虑 为作者添砖加瓦🥤，给予精神支持💪🏻 。

官方代码仓库地址：https://github.com/breezedeus/cnocr。 WIKIPEDIA 引用：A text-to-image model (T2I or TTI model) is a machine learning model which takes an input natural language prompt and produces an image matching that description. Text-to-image models began to be developed in the mid-2010s during the beginnings of the AI boom, as a result of advances in deep neural networks. In 2022, the output of state-of-the-art text-to-image models—such as OpenAI's DALL-E 2, Google Brain's Imagen, Recraft, Stability AI's Stable Diffusion, Midjourney, and Runway's Gen-4—began to be considered to approach the quality of real photographs and human-drawn art. Text-to-image models are generally latent diffusion models, which combine a language model, which transforms the input text into a latent representation, and a generative image model, which produces an image conditioned on that representation. The most effective models have generally been trained on massive amounts of image and text data scraped from the web.

== History == Before the rise of deep learning, attempts to build text-to-image models were limited to collages by arranging existing component images, such as from a database of clip art. The inverse task, image captioning, was more tractable, and a number of image captioning deep learning models came prior to the first text-to-image models.

The first modern text-to-image model, alignDRAW, was introduced in 2015 by researchers from the University of Toronto. alignDRAW extended the previously-introduced DRAW architecture (which used a recurrent variational autoencoder with an attention mechanism) to be conditioned on text sequences. Images generated by alignDRAW were in small resolution (32×32 pixels, attained from resizing) and were considered to be 'low in diversity'. The model was able to generalize to objects not represented in the training data (such as a red school bus) and appropriately handled novel prompts such as "a stop sign is flying in blue skies", exhibiting output that it was not merely "memorizing" data from the training set. In 2016, Reed, Akata, Yan et al. became the first to use generative adversarial networks for the text-to-image task. With models trained on narrow, domain-specific datasets, they were able to generate "visually plausible" images of birds and flowers from text captions like "an all black bird with a distinct thick, rounded bill". A model trained on the more diverse COCO (Common Objects in Context) dataset produced images which were "from a distance... encouraging", but which lacked coherence in their details. Later systems include VQGAN-CLIP, XMC-GAN, and GauGAN2. One of the first text-to-image models to capture widespread public attention was OpenAI's DALL-E, a transformer system announced in January 2021. A successor capable of generating more complex and realistic images, DALL-E 2, was unveiled in April 2022, followed by Stable Diffusion that was publicly released in August 2022. In August 2022, text-to-image personalization allows to teach the model a new concept using a