简介这份OCR图片识别源码是一个可直接运行的Python项目面向需要将图片内容快速转为可交互HTML的开发者或自动化办公场景核心基于RapidOCR改造优化了接口调用与结果展示方式。内置/engine/ocr统一接口支持HTTP链接、本地文件、文件流等多种图片输入返回带标记的HTML结构方便直接嵌入页面或二次复制使用。资源共46个文件主要包括23个Python源码、17个编译后的pyc文件、3个ONNX推理模型、1个YAML配置、1个HTML模板及依赖说明txt压缩包大小约14.26MB。目录划分清晰web_service负责启动服务common封装通用逻辑rapid_ocr子目录存放检测、识别、分类等核心模块便于定位与学习。该项目适合有一定Python基础、希望理解OCR服务化封装或需要快速集成图片转文字功能的开发者。通过阅读源码可以掌握RapidOCR的调用流程、接口参数设计、HTML结果生成方法以及一个轻量级Web服务的组织方式。目前已有1734人学习下载可作为OCR入门与改造借鉴的实用参考。1. 为什么我用rapidOCR替换掉了PaddleOCR和Tesseract做OCR识别项目的人应该都有同感模型选型是最折磨人的一步。我在做这个“图片识别并返回HTML结构”的源码项目之前先后在Tesseract和PaddleOCR上折腾了近两个星期最后才确定用rapidOCR作为核心引擎。换掉它们不是因为它们不好而是因为它们跟我的目标场景不够匹配。我的需求其实很明确第一识别结果里必须带坐标信息我要靠坐标还原排版结构第二部署要简单不能一上来就要求装CUDA、配GPU环境第三引擎要适合二次改造我需要把底层输出的文本串加工成HTML结构这就要求源码足够清爽、依赖足够轻。Tesseract的问题在于中文识别精度一般尤其遇到竖排文本、带角度的文字或者低分辨率截图错误率会明显上升。PaddleOCR的精度确实高但它的部署依赖太重了——PaddlePaddle框架本身就几百MB加上各种模型文件在Docker里一包装体积直接让人崩溃。而且它的源码层次比较复杂想改它的内部逻辑去输出自定义结构成本不低。rapidOCR刚好卡在两者之间的最佳平衡点上精度接近PaddleOCR部署体量小得多而且是基于ONNX Runtime的那一套推理速度和跨平台能力都很让人放心。先说明一下我做的这套源码并不是把rapidOCR拉下来换个皮就完事而是在它的基础上做了几处实质性改造把底层的OCR输出统一封装成结构化的数据对象然后在识别完成后新增了一个排版分析和HTML渲染层最后输出一段带坐标注释、带排版层级、能被浏览器直接渲染的HTML片段。下面我逐步拆解整个实现过程和踩过的坑。2. rapidOCR的源码核心机制与改造前必懂的三个关键点2.1 三段式流水线检测、方向分类、识别要改一个开源项目的代码首先得知道它的数据流是怎么走的。rapidOCR的内部结构是典型的三段式OCR流水线对应三个依次执行的模型文本检测模型Det负责从图片中定位出所有文字区域输出每个文本区域的四边形坐标。方向分类模型Cls负责判断每个检测到的文本区域是否需要旋转矫正主要解决倒置文本的问题。文本识别模型Rec负责把矫正后的文本区域“翻译”成字符串输出识别文字和对应的置信度。这三个环节是瀑布式串起来的。我之前看到很多人在自己的项目里直接用rapidocr_onnxruntime提供的__call__接口传一张图片进去就拿到全部结果。这确实省事但如果你打算二次改造比如要自定义输出HTML结构就必须真正理解这三个阶段分别产出了什么。因为HTML结构不仅仅是文字还涉及位置、层级、阅读顺序这些信息只靠最终的字符串结果是不够的。2.2 改造入口先拿到结构化中间结果在rapidOCR的源码里核心入口通常长这样from rapidocr_onnxruntime import RapidOCR engine RapidOCR() result, elapse engine(img_path)result里每条记录的结构大致是[ [ [左上角x, 左上角y], [右上角x, 右上角y], [右下角x, 右下角y], [左下角x, 左下角y] ], 识别出来的文字, 置信度 ]这个结构看起来朴实无华但它是整篇HTML结构产出的“地基”。我做的第一件事就是把它封装成一个更语义化的内部对象class OcrBlock: def __init__(self, box: list, text: str, confidence: float): self.box box # 四个顶点坐标 self.text text self.confidence confidence property def top(self): return min(point[1] for point in self.box) property def left(self): return min(point[0] for point in self.box) property def bottom(self): return max(point[1] for point in self.box) property def right(self): return max(point[0] for point in self.box) property def center_x(self): return (self.left self.right) / 2 property def center_y(self): return (self.top self.bottom) / 2从这一步开始我就完全绕开了rapidOCR默认的纯文本输出逻辑所有后续的排版判断、HTML渲染都建立在这套坐标对象之上。这种改造方式的优点在于我不需要动rapidOCR训练层面的代码只替换输出解析层风险最小、可维护性最高。2.3 置信度过滤不能一刀切改造过程中比较坑的一个点是置信度阈值。rapidOCR的默认阈值通常是0.6左右但在实际场景里截图类图片和自然场景照片的置信度分布差异非常大。截图里的文字通常清晰、边缘锐利置信度能到0.9以上而自然场景里被遮挡的文字、艺术字体置信度可能只有0.4-0.5。如果你在设计改造方案时直接设一个全局阈值很容易误杀或者漏放。我的做法是把置信度过滤放到HTML渲染之前的最后一个环节并且分场景单独配置。比如处理干净截图时阈值设0.5就能拿到很好的效果处理商品实拍图时阈值提高到0.7宁可漏检也不能满屏都是错别字。3. HTML结构怎么设计才能让OCR结果真正可用3.1 为什么返回HTML而不是JSON做OCR的人可能都会有一个疑惑前端要数据给JSON不就行了吗为什么非要做成HTML我在做这个项目的时候也纠结过。后来真正落地才发现很多非技术用户根本不会去看JSON里的坐标数组他们想要的是“一眼就能看到的识别结果”——一段能在浏览器里直接渲染的文字一段能反馈到富文本编辑器里的排版。HTML恰好就是这样一个“自带渲染能力”的载体。我把每个OCR文本块映射成HTML里的块级元素保留它的绝对定位信息这样不仅能看到识别出来的文字还能从视觉上直接对照原图的排版结构。这对做文档比对、票据识别、截图信息抽取的需求来说非常直观。另外一个重要的场景是知识库检索。现在很多人拿OCR去做RAG检索增强生成知识库的预处理流程识别结果往往需要保留段落顺序和阅读逻辑。如果只有JSON坐标数据下游还得自己写一套合并逻辑如果直接给HTML很多解析器天然就能提取标题、段落、列表层级接入成本几乎为零。3.2 坐标到HTML文档流的映射逻辑这一步是整个源码改造的核心也是我写了最多测试用例的部分。OCR输出的坐标是绝对定位而HTML的渲染天然是文档流两者之间必须做一次“翻译”。我的映射策略分成几个层次行合并把高度中心接近、垂直方向重叠的文本块合并成一行。块合并把行与行之间水平方向有重叠、垂直距离接近的行合并成段落块。标题判定通过字号文本块高度、加粗程度、位置特征把可能的标题识别出来用h1到h3的标签输出。段落分割块与块之间垂直距离明显大于行距时切成独立的p段落。图片区域处理如果检测到模型置信度极低但面积很大的区域可能不是文字而是图片用figure占位。核心代码思路大致是这样def blocks_to_html(blocks: list[OcrBlock]) - str: lines merge_into_lines(blocks) paragraphs merge_lines_into_paragraphs(lines) html_parts [] for para in paragraphs: tag judge_tag(para) html_parts.append(f{tag}{escape(para.text)}/{tag}) return \n.join(html_parts)实际输出效果大概是h2项目概述/h2 p本项目基于rapidOCR进行了二次改造/p div>import threading class RapidOCREnginePool: def __init__(self, max_engines4): self.max_engines max_engines self.local threading.local() def get_engine(self): if not hasattr(self.local, engine): self.local.engine RapidOCR() return self.local.engine这样既保证了线程安全又避免了每次识别都重新加载模型的开销。4.2 HTML定位精度和图片缩放强相关另一个特别容易被忽略的细节是图片缩放。OCR识别通常会把图片做内部resizerapidOCR的默认检测模型也对不同分辨率的输入有不同的表现。但坐标输出是相对于原始图片尺寸的如果你的流程里有“图片缩放后识别”的环节一定要记录缩放比在生成HTML时把坐标映射回原始尺寸。这个问题的坑还藏在另一个地方输入图片的DPI。用pillow打开图片时如果不显式处理DPI信息某些场景下坐标偏移能达到几十个像素。我在源码里写死了这样一个逻辑from PIL import Image img Image.open(image_path) dpi img.info.get(dpi, (96, 96)) scale_x dpi[0] / 96.0 scale_y dpi[1] / 96.0把所有坐标统一折算到96DPI的基准上这样HTML输出后不管在哪台设备上打开位置的相对关系都是准的。4.3 CPU推理的速度瓶颈与规避方式我一开始对CPU推理速度是有心理准备的但实际项目跑起来还是被惊到了——一张1920x1080的截图在CPU上跑完整流程平均要1.2秒左右。如果做批量处理比如100张截图那就要等两分钟。这在本地工具场景还能接受但如果是给Web API提供接口这个时延会直接劝退用户。实测下来几个有效的优化手段把输入图片先做一次等比缩放最长边不超过960px识别精度下降很小但推理速度提升约40%。对纯色背景的截图先做图像预处理用OpenCV去除大面积纯色块后再送入OCR减少检测阶段的干扰候选框。如果部署机器的CPU支持检查ONNX Runtime是否启用了AVX-512指令集开启后推理时延能再降一些。批量图片识别时不要每次识别都从文件系统重新读图用内存缓存机制保存解码后的numpy数组。5. 这套源码的完整工作流程与实测数据还原效果我把整体架构的流程图直接说清楚输入图片 → OpenCV图像预处理 → 缩放与DPI校正 → RapidOCR检测识别 → 坐标对象化 → 行/段落合并 → 标题层级判定 → 标准HTML渲染 → 附带data-box坐标输出。实测数据集我用了三组第一组是干净截图包括网页长截图、聊天记录截图第二组是扫描件带轻微的倾斜和噪点第三组是自然场景照片商品图、路牌随手拍。干净截图组的字准确率基本在98%以上段落还原准确率在95%左右扫描件准确率略低但段落还原仍然能到90%自然场景照片的字准确率会降到85%左右主要损失来自艺术字体和复杂背景干扰。实际输出的HTML片段效果大致如下article h3 style="width:16px;margin-left:4px;vertical-align:text-bottom;cursor:text;" />