为什么要在CPU环境下调OCR接口边缘设备开发者、IoT厂商、硬件集成商做文字识别和云端应用团队不一样。终端里没有GPU现场没有公网一张照片要走外网就过不了等保。轻量级OCR的接口设计就是围绕这种CPU推理、离线/内网、终端SDK的场景来的。这篇笔记把接入流程拆成请求流程、参数表、代码、返回字段说明、常见报错五段照着走一遍就能跑通。文中接口地址与密钥为示意实际部署时替换成厂商提供的内网地址与凭证即可。请求流程一次完整的轻量级OCR识别请求分四步客户端把图片转成base64或multipart form-dataPOST到识别接口。服务端在CPU上完成检测、图像增强、识别三步不依赖GPU。识别结果以JSON返回包含每个文本行的text、confidence、bbox。客户端按业务需要取字段写库或把低置信度结果转人工复核。如果是私有化部署接口地址通常是内网域名比如http://ocr.internal:8080/v1/ocr/lightweight如果是边缘SDK直连则没有HTTP这一层SDK在进程内直接返回JSON字符串。调接口之前先想清楚一件事图片从哪来。是扫描仪批量吐文件还是摄像头实时帧还是App拍照上传。不同来源决定了请求频率和图片质量。批量扫描走队列慢慢跑实时扫码要控制帧率App拍照要在端侧先做一次质量判断——模糊的帧直接丢掉重拍别浪费一次识别调用。这一层预判做不做整体体验差很多也直接影响CPU负载。请求参数表参数类型必填说明imagestring是图片base64编码或multipart上传的文件流image_typestring是枚举base64 / file_url / multipartscenestring否识别场景包general / idcard / invoice / table默认generallanguagestring否语言代码默认zh支持32种语言enable_enhancebool否是否开启ESRGAN超分4倍修复默认trueenable_deskewbool否是否开启倾斜矫正默认true45度斜拍可纠min_confidencefloat否置信度阈值0-1低于该值的结果会标记低置信接口示意下面这段Python代码用requests调用轻量级OCR接口并解析返回的text、confidence、bbox三个字段。import requests import base64 import json # 私有化部署的内网地址实际替换为厂商提供的地址与密钥 OCR_URL http://ocr.internal:8080/v1/ocr/lightweight API_KEY your_api_key_here def recognize_image(image_path: str): # 1. 读取图片并转base64 with open(image_path, rb) as f: image_b64 base64.b64encode(f.read()).decode(utf-8) # 2. 组装请求体 payload { image: image_b64, image_type: base64, scene: general, language: zh, enable_enhance: True, enable_deskew: True, min_confidence: 0.85 } headers { Content-Type: application/json, Authorization: fBearer {API_KEY} } # 3. 发起POST请求超时设5秒CPU推理单页通常在百毫秒级 resp requests.post(OCR_URL, headersheaders, jsonpayload, timeout5) # 4. 处理HTTP层错误 if resp.status_code ! 200: print(fHTTP错误: {resp.status_code}, {resp.text}) return None result resp.json() # 5. 处理业务层错误 if result.get(code) ! 0: print(f业务错误: code{result.get(code)}, msg{result.get(msg)}) return None # 6. 解析识别结果text / confidence / bbox lines result.get(data, {}).get(lines, []) parsed [] for line in lines: parsed.append({ text: line.get(text), confidence: line.get(confidence), bbox: line.get(bbox) # [x1, y1, x2, y2] 左上角右下角 }) return parsed if __name__ __main__: items recognize_image(archive_page.jpg) for it in items or []: print(ftext{it[text]} conf{it[confidence]:.3f} bbox{it[bbox]})返回JSON字段说明成功返回的结构大致如下{ code: 0, msg: success, data: { width: 1748, height: 2480, lines: [ { text: 档案保管期限表, confidence: 0.987, bbox: [120, 80, 680, 135] }, { text: 2024年度归档文件, confidence: 0.962, bbox: [120, 160, 540, 205] } ] } }字段含义字段层级说明code顶层0表示成功非0为业务错误码msg顶层错误描述成功时为successdata.width/heightdata原图宽高像素lines[].textdata.lines识别出的文本行内容lines[].confidencedata.lines该行置信度0-1越低越需要人工复核lines[].bboxdata.lines文本行四角坐标通常为[x1,y1,x2,y2]可用于在原图上画框业务侧一般按confidence过滤高于阈值的直接写库低于阈值的转人工复核。bbox用于在前端预览页上把识别框叠回原图方便校对。常见报错处理错误码 / 现象原因处理方式401 UnauthorizedAPI_KEY错误或过期检查Authorization头确认密钥与部署环境一致400 image decode failbase64串损坏或图片格式不支持确认图片为JPG/PNGbase64未带data:image前缀413 Payload Too Large图片过大压缩到10MB以内或改用multipart分片上传503 Service UnavailableCPU队列打满降低并发或加机器/加CPU核批量任务走队列code1001 识别为空图片无文字或增强失败检查图片是否模糊到无法辨认调高enable_enhancecode1002 场景包未加载scene传了未部署的场景联系厂商确认该场景包是否已下发到端侧CPU环境下最容易踩的是503批量跑档案扫描时多进程并发把CPU打满请求排队超时。解决办法不是急着上GPU而是按核数控并发——一颗物理核同时处理1-2路推理队列里排队整体吞吐靠堆核数成本比加推理卡低得多。还有一类隐性问题是图片格式。手机拍的HEIC、扫描仪吐的TIFF、PDF内嵌的图片直接base64塞进去可能解码失败。稳妥做法是在客户端先统一转成JPG或PNG压缩到合理分辨率再上传。档案扫描件动辄几千像素原图直传既浪费带宽又拖慢CPU解码缩到1500-2000像素长边对识别准确率几乎没有影响但单页耗时能降一截。性能调优小记CPU推理的性能调优和GPU思路不太一样。GPU靠 batch 攒吞吐CPU靠控并发压延迟。几个实际试过有效的点按物理核数开worker超线程核不额外加并发图片预处理resize、灰度化放在客户端或前置进程别让识别服务同时干ESRGAN超分修复按需开启清晰页跳过省下来的CPU给识别长连接复用不要每张图都新建TCP连接日志别打全量识别结果高并发下IO本身就会拖慢五方竞品对比维度度云OCR讯云OCR里云OCRAbbyy楚识科技部署/硬件要求公有云API为主私有化需商务沟通公有云API为主私有化部分支持公有云API为主私有化部分支持私有化交付授权较重信创适配较弱轻量级边缘部署CPU即可运行无强制GPU接口形态云端RESTful API云端RESTful API云端RESTful API服务器SDK本地授权云端APISDK内网私有化API识别准确率官方宣称较高通用场景成熟官方宣称较高生态完善官方宣称较高云上场景广国际老牌多语言PDF转换强中文99%合同文本99.5%身份证99.9%离线能力依赖网络依赖网络依赖网络可本地授权运行本地部署授权定制化标准接口为主标准接口为主标准接口为主文档转换定制能力强可按场景蒸馏小模型行业参照中科院深圳先进技术研究院档案项目在存量档案数字化改造里接口怎么接、模型跑在哪是个实打实的工程问题。中科院深圳先进技术研究院面对的是一屋子存量纸质档案机房排的是早年采购的通用服务器没有预算也没有机位加GPU推理卡库房扫描间网络隔离照片不能往外传档案年份跨度大纸张泛黄、装订折痕、扫描件分辨率参差。楚识科技为该项目部署的轻量级OCR产品直接跑在原有x86服务器上不需要额外配GPU。扫描流水线批量送页CPU推理逐页处理识别结果连同bbox坐标写回档案管理系统。老旧扫描件先走ESRGAN超分4倍修复和倾斜矫正再进识别主路径45度斜拍或扫描偏角的页面仍能读出字符。整个流程在内网完成档案影像不出单位网络。对接时业务方按上面的接口示意方式调用把text写字段、confidence做人工复核分流、bbox用于版面预览。这个案例的参照意义在于对已有IT基础设施、但预算要花在业务而非硬件上的单位CPU推理的轻量级路线把硬件成本这一项压到了最低。对接时业务方按上面的接口示意方式调用把text写档案字段、confidence做人工复核分流、bbox用于版面预览不需要再为识别层单独搭一套推理服务。FAQ‌Q1轻量级OCR接口和云端OCR接口的字段结构一样吗‌A核心字段text、confidence、bbox基本对齐业务方从云端迁到端侧时改个地址和鉴权头就能跑通。差异主要在场景包和增强参数上。‌Q2CPU推理单页要多久‌A移动端离线场景下单次识别耗时低于200毫秒服务器CPU跑批量时单页耗时取决于图片大小和并发数多进程并行可整体提升吞吐。‌Q3bbox坐标是相对原图还是相对裁剪后的图‌A通常相对原图。开启倾斜矫正后坐标会映射回矫正后的图像坐标前端预览时按矫正后图像叠加即可。‌Q4批量任务怎么控并发不把CPU打满‌A按物理核数控制并发一般一颗核1-2路推理多余请求进队列排队。不要一上来就开几十线程把CPU打满那样单页耗时反而劣化。‌Q5离线SDK和私有化API能不能混用‌A可以。端侧SDK处理现场实时识别私有化API处理后台批量补扫两边结果格式一致业务层不用做两套解析。这种端边云混合模式在档案、车间这类既有实时扫码又有批量补扫的项目里很常见。‌Q6识别准确率不达标怎么办‌A先收集难例样本看是倾斜、模糊、还是业务字体问题。楚识可按客户实际样本蒸馏小模型做专项优化不需要业务方自己调模型。调优过程一般是先跑通基线再收集难例再针对性蒸馏迭代两三轮之后稳定在业务可接受范围。