简介这份压缩包提供了一套基于Flask的PaddleOCR服务部署项目面向需要快速搭建OCR服务能力的开发者与计算机相关专业学生解决将PaddleOCR模型封装为HTTP接口并稳定调用的需求。项目提供了完整代码、README说明文档、POST请求测试脚本及若干验证图片均通过严格测试验证可帮助用户理解从本地到云端的完整部署流程。压缩包内共19个文件包含Python核心脚本、Markdown指南、HTML前端页面、文本说明与多张演示图像整体仅1.25MB轻量紧凑便于下载后直接对照学习。目前已有288人浏览学习适合人工智能、计算机科学与技术等专业用于毕业设计、课程作业或技术实践。通过阅读项目内的部署指南与参数说明读者可以掌握利用Flask搭建OCR服务接口、提交图像数据并获得文字识别结果的具体方法相关思路也能迁移到健康宝识别、文档自动化处理等实际场景中。1. 把 PaddleOCR 包成 Flask 服务难点不在 OCR 本身做过 OCR 服务端接入的人都有个体会模型在 Notebook 里跑通一张图和能扛住线上请求的 HTTP 服务中间隔着的不是一两步代码而是模型生命周期管理、并发安全、部署路径这三道坎。拿 PaddleOCR 来说模型本身成熟、识别效果也稳但直接用原生 API 暴露出去很快就会发现两个问题一是每次请求都重新加载模型显存和响应时间双双失控二是 Flask 默认的多线程模型下PaddleOCR 实例的 predict 调用并不安全并发稍高就报错或结果错乱。这篇把两者结合起来写一套能直接参考的部署方案用 Flask 做 Web 层PaddleOCR 做推理引擎从模型初始化、接口封装、并发控制一直讲到服务器上的进程管理与压测。适合已经跑通过 OCR 示例、准备把识别能力做成内部服务或对外接口的开发者。2. 先理清 PaddleOCR 的模型加载与推理边界2.1 检测模型和识别模型为什么要分开看待PaddleOCR 的 PP-OCR 系列是典型的“检测 识别”两段式结构检测模型定位文本行识别模型把每一行转为字符串。最新版还支持方向分类器cls来处理横竖排混排的场景。很多第一次接触的人把PaddleOCR()这个类当成一个黑盒predict()一调就完事这种做法在脚本里没有任何问题但一旦要做服务化就需要把这两个阶段的时间占比、显存占用和错误来源拆开看。检测阶段耗时通常在几十到一百毫秒级别取决于图片分辨率和文本密度识别阶段则是逐行串行推理行数越多耗时线性增加。如果业务场景是身份证、营业执照这类固定版式检测模型几乎每张图都在做重复劳动这时候可以先把检测结果缓存或裁剪只把文本行区域送进识别模型。而自然场景随手拍的照片检测反而是准确率瓶颈。# 最小推理脚本先跑通再谈服务化 from paddleocr import PaddleOCR import json ocr PaddleOCR( use_angle_clsTrue, # 启用方向分类器处理横竖排混排 langch, # 中文模型模型文件会自动下载 show_logFalse # 关闭推理日志服务端日志由框架统一管 ) result ocr.ocr(sample.jpg, clsTrue) for page in result: for line in page: # 每个 line 结构[box坐标, (文本, 置信度)] print(json.dumps(line[1], ensure_asciiFalse))提示ocr.ocr()在高版本 PaddleOCR 中会返回嵌套列表第一层是图片列表第二层是每一行的检测结果。做服务化时建议直接在服务初始化阶段调一次ocr.ocr()做预热把模型加载、显存分配、算子编译都触发掉避免第一个线上请求慢到几十秒。2.2 推理模型的存储位置与加载策略模型文件在首次运行时下载到~/.paddleocr/目录下部署到服务器时最稳妥的做法是提前在本地把模型下载好连同代码一起打包再通过环境变量或配置文件指定模型路径。原因很简单生产服务器的外网下载不一定可靠而且官方模型地址一旦变更服务起来时再拉取就会直接失败。mkdir -p /opt/paddleocr-svc/models cp -r ~/.paddleocr/whl/det/det_db_mv5 /opt/paddleocr-svc/models/ cp -r ~/.paddleocr/whl/rec/rec_ch_ppocr_v4 /opt/paddleocr-svc/models/ cp -r ~/.paddleocr/whl/cls/cls_mv3 /opt/paddleocr-svc/models/PaddleOCR类支持通过det_model_dir、rec_model_dir、cls_model_dir三个参数直接将模型指向本地目录这意味着在服务器上可以不依赖自动下载逻辑全部用离线文件初始化。参数里还有一个容易忽略的device选项默认是 CPU。服务器带 NVIDIA GPU 时把它设为gpu:0并且把use_tensorrtTrue打开识别吞吐通常能提升三到五倍GPU 显存小于 4G 就别折腾 TensorRT 了算子编译容易把显存撑爆。模型加载策略上服务进程启动时只创建一个 PaddleOCR 实例而不是每次请求都新建。Python 的 GIL 和 Paddle 推理引擎的并发模型都决定了“一个进程内共享一个实例加锁串行推理”是稳定性和内存占用之间的最优解。多进程部署时每个 worker 进程各自持有一份模型副本这一点后续部署章节会重点展开。3. Flask 服务的核心封装接口设计、并发锁与参数透传3.1 路由设计与超时控制服务封装的第一步把 Flask 应用和 PaddleOCR 的生命周期解耦。模型在模块导入时全局初始化Flask 的每个 worker 进程都会持有这个实例而不是每次请求都要等到模型加载完。# app.py import base64 import uuid import time from flask import Flask, request, jsonify from paddleocr import PaddleOCR from PIL import Image import io, threading app Flask(__name__) # 全局唯一实例进程启动时完成模型加载 ocr PaddleOCR( use_angle_clsTrue, langch, det_model_dir/opt/paddleocr-svc/models/det_db_mv5, rec_model_dir/opt/paddleocr-svc/models/rec_ch_ppocr_v4, cls_model_dir/opt/paddleocr-svc/models/cls_mv3, show_logFalse, ) # 推理锁避免多线程同时调用 predict 导致崩溃 ocr_lock threading.Lock() def ocr_predict(image_bytes: bytes): image Image.open(io.BytesIO(image_bytes)).convert(RGB) with ocr_lock: result ocr.ocr(image, clsTrue) return result app.post(/ocr) def ocr_endpoint(): t0 time.time() file request.files.get(image) if file is None: return jsonify({code: 400, msg: image file is required}), 400 data file.read() try: result ocr_predict(data) except Exception as e: return jsonify({code: 500, msg: str(e)}), 500 # 整理成适合前端消费的扁平结构 lines [] page result[0] if result else [] for line in page: box, (text, score) line lines.append({box: box, text: text, score: round(score, 4)}) return jsonify({ code: 0, data: {lines: lines}, cost_ms: int((time.time() - t0) * 1000), request_id: uuid.uuid4().hex }) if __name__ __main__: app.run(host0.0.0.0, port9000, threadedTrue)代码逻辑拆开看PaddleOCR的三个模型路径参数把上一章的离线模型目录接进来ocr_lock保证同一进程内任意时刻只有一个线程在调用 predict这是 FlaskthreadedTrue模式下不翻车的底线返回结构里带上cost_ms和request_id前者方便自查性能后者方便对接方排障。图片接收方式同时兼容表单上传和后续要讲的 Base64 传递先用request.files做到最简再做扩展。提示Image.open之后要convert(RGB)。用户上传的图片可能是 PNG 带透明通道也可能是灰度图Paddle 内部对 RGB 三通道输入最稳妥提前转换能避开“输入尺寸不一致”这类晦涩报错。3.2 支持 Base64 与 URL 拉图的输入扩展表单上传适合内部服务间调用但很多业务方前端页面、小程序云函数更习惯直接传一张图片 Base64 字符串。Base64 会增加约 33% 的传输体积可好在避免了 multipart 解析的兼容性问题。另一个常见场景是对方只给一个图片 URL服务端自己去拉取这就需要requests.get并且限时——外部 URL 的响应时间不可控没有超时上限的拉图会让 Flask worker 被慢请求拖死。def load_image_from_base64(raw: str) - bytes: # 去除 data URL 前缀如果有 if raw.startswith(data:): raw raw.split(,, 1)[1] return base64.b64decode(raw) app.post(/ocr/base64) def ocr_base64(): payload request.get_json(forceTrue) raw payload.get(image, ) if not raw: return jsonify({code: 400, msg: image field required}), 400 try: image_bytes load_image_from_base64(raw) result ocr_predict(image_bytes) except Exception as e: return jsonify({code: 500, msg: finvalid image: {str(e)}}), 500 # 后续整理结构同 /ocr return jsonify({code: 0, data: {accepted: True}})URL 拉图的方式我一般单独做一个接口不带入主 OCR 接口避免外部超时影响本地调用方。requests.get(url, timeout(3.05, 10))这里的元组格式分别表示连接超时和读取超时读取超时设到 10 秒是给慢图床留缓冲再大就没有意义会让线程池堆积。3.3 识别参数如何做成可控维度PaddleOCR.ocr()的参数里clsTrue其实不是简单开关它决定了方向分类模型是否参与推理。如果你们的图片全部来自扫描件且方向固定关掉cls能省掉约 20-40 毫秒如果手机随手拍占比高则必须开着。这两个场景差异很大因此接口层应该把参数透传出来而不是写死在服务内部。比较简洁的做法是允许请求体传入一个use_cls字段默认None表示用服务端预设值传了true/false则覆盖。此外还有两个高频需求导出识别框位置box 坐标和过滤低置信度结果。有些调用方只关心全文不关心每一行的坐标那就在响应里加一个detail字段false时丢弃 box 只拼接文本。置信度过滤阈值建议在服务端做而不是抛给调用方因为调用方在业务代码里逐个判断 score 并不直观。# 3.3 关键逻辑示意 app.post(/ocr/v2) def ocr_v2(): payload request.get_json(forceTrue) image_bytes load_image_from_base64(payload.get(image, )) use_cls payload.get(use_cls, True) min_score float(payload.get(min_score, 0.0)) detail payload.get(detail, True) with ocr_lock: result ocr.ocr(image_bytes, clsuse_cls) lines [] full_text [] page result[0] if result else [] for line in page: box, (text, score) line if score min_score: continue lines.append({box: box, text: text, score: round(score, 4)}) full_text.append(text) return jsonify({ code: 0, full_text: \n.join(full_text) if not detail else None, lines: lines if detail else None, })这段代码把三个决策权交给调用方但每个都有合理默认值兼容旧的简单调用。min_score的类型是浮点数很多人传整数80想表达“80%”这里一定要在文档里写清楚传0.8。接口设计层面多一个v2路由而不是直接改原路由这样老调用方不感知变更也方便做灰度切流量。PaddleOCR 的返回格式在不同小版本里有差异有的结果第一层是空列表而第二层为空解析时page result[0] if result else []这种防御性写法很有必要避免拿None去迭代。4. 部署到服务器从解压到进程管理的完整链路4.1 用 Gunicorn 替代 Flask 内置服务器Flask 自带的开发服务器app.run()有一个饼它支持多线程但每个请求的线程管理、超时回收、进程守护都不可控直接暴露公网很容易被慢请求和异常连接拖垮。生产环境的选择基本是 Gunicorn 加 gevent 或 gthread worker这一套组合在 Linux 上最省心。进程模型上--workers建议设为 CPU 核数的两倍以内每个 worker 是独立进程也意味着独立持有一份 PaddleOCR 模型副本。pip install gunicorn gevent gunicorn -w 4 -b 0.0.0.0:9000 \ -k gevent \ --timeout 60 \ --max-requests 5000 \ --max-requests-jitter 500 \ app:app拆解参数-w 4表示 4 个 worker 进程-k gevent指定 worker 类型为协程比默认的同步 worker 更擅长处理 I/O 密集型的 Flask 请求--timeout 60是说 worker 处理单个请求超过 60 秒就被 Master 进程杀掉重启。这里有个非常隐蔽的坑--timeout默认是 30 秒而 PaddleOCR 在 CPU 机器上识别一张大图耗时可能超过 30 秒如果不调大强杀重启就成了常态日志里全是Worker timed out。# 模型显存是按 worker 数翻倍的 # 2个worker GPU 2份模型显存 # 4G显存显卡建议-w 2 # 纯CPU服务器建议-w 4 以上推理时拿到GIL的代价可以接受--max-requests是一个常被忽略的参数Paddle 推理引擎长时间运行后内部缓存和内存碎片会缓慢增长即使没有内存泄漏也会让 RSS 居高不下。设一个上限让 worker 处理满 5000 个请求后自动重启内存回到初始状态。这个参数对长期运行的 OCR 服务性价比极高代价只是偶尔有一个请求慢几百毫秒。4.2 文件解压、目录结构与运行用户隔离拿到打包好的项目压缩包后服务器上的目录规划应该遵循“代码、模型、日志、虚拟环境”四分离的原则。解压到固定目录不要用 root 直接跑服务这是底线OCR 服务要处理用户上传的图片如果代码里有任何文件操作漏洞root 权限意味着整个服务器沦陷。useradd -r -s /sbin/nologin ocruser mkdir -p /opt/paddleocr-svc/{app,models,logs} cd /opt/paddleocr-svc unzip 基于Flask的PaddleOCR服务部署.zip -d app/ chown -R ocruser:ocruser /opt/paddleocr-svcPython 虚拟环境也放在项目目录内方便整体备份和迁移python3 -m venv /opt/paddleocr-svc/venv source /opt/paddleocr-svc/venv/bin/activate pip install flask paddleocr gunicorn gevent pillow requests部署到服务器上最常翻车的一步是paddleocr安装时依赖的paddlepaddle版本不对。GPU 服务器必须安装paddlepaddle-gpu且 CUDA 版本要匹配这个必须在虚拟环境内提前验证而不是等启动时报libcudart.so not found再回头。验证命令很简单python -c from paddleocr import PaddleOCR; PaddleOCR(show_logFalse); print(ok)4.3 systemd 守护与开机自启进程守护交给 systemdnohup那套方案在服务器重启、进程崩溃后都得人工干预不是长期运行的做法。写一个 unit 文件管理启动、停止、崩溃自动拉起和日志轮转。# /etc/systemd/system/paddleocr.service [Unit] DescriptionPaddleOCR Flask Service Afternetwork.target [Service] Userocruser Groupocruser WorkingDirectory/opt/paddleocr-svc EnvironmentPATH/opt/paddleocr-svc/venv/bin ExecStart/opt/paddleocr-svc/venv/bin/gunicorn \ -w 4 -b 0.0.0.0:9000 -k gevent \ --timeout 60 --max-requests 5000 \ --max-requests-jitter 500 \ --access-logfile /opt/paddleocr-svc/logs/access.log \ --error-logfile /opt/paddleocr-svc/logs/error.log \ app:app Restartalways RestartSec5 [Install] WantedBymulti-user.targetRestartalways加上RestartSec5的组合意味着进程异常退出后 5 秒拉起一次这一组参数对 OCR 服务尤其重要模型文件损坏、显存被其他任务占满都可能导致进程崩溃自动拉起能保证服务可用性。如果日志里反复出现拉起又崩溃那就说明模型初始化有问题这种场景靠 systemd 是不解决问题的必须看 error log。提示--access-logfile一定要开。OCR 服务的请求体是图片Access Log 里至少要有来源 IP、响应状态、耗时出问题时排查的第一步就是从 log 找请求样本。5. 生产化部署的额外几件事压测、连接数与鉴权5.1 用 wrk 压测摸清服务上限部署完成后第一件事不是宣布完成而是压测。wrk是 Linux 上顺手且输出清晰的压测工具模拟固定并发、持续时间的请求负载。压测结果里的“Requests/sec”就是你服务的处理上限“Latency”分布要重点看 P99。wrk -t 4 -c 20 -d 30s \ -s post.lua \ http://127.0.0.1:9000/ocrpost.lua是 wrk 的请求构造脚本post.lua内容可以这样写读取本地一张测试图片打成表单结构 POST 给服务。压测前先单发一个请求确认图片能识别再上并发压测过程中监控nvidia-smi的显存占用和 CPU 负载。如果压测发现 P99 延迟是平均延迟的 3 倍以上通常说明锁竞争激烈或 worker 数量不足。CPU 机器上把-w 4提到-w 8的收益有时远超预期——但显存足够时 GPU 推理服务加 worker 会稀释显存4G 显存的卡保持 2 个 worker 即可。5.2 防火墙、反向代理与内网隔离另外一个常被忽略的点是在阿里云 ECS 这类云服务器上服务启动后还要检查两个层级的网络策略。firewall-cmd --permanent --add-port9000/tcp firewall-cmd --reload安全组也要同步放行。如果你的服务只给内部系统调用就不要把 9000 端口暴露到公网改用 Nginx 反代后只放行 80/443并且限定来源 IP。镜像部署场景里云服务器上部署前后端项目时还要注意 Docker 容器的--network host模式而不是默认桥接模式否则127.0.0.1:9000从宿主机访问不到容器内的监听地址。两个方案对比下来生产环境的本质是“谁接收用户请求、谁持有模型、谁管理进程”三个角色分开。直接对公网暴露 OCR 服务是最危险的做法图片内容不可控、请求体积无上限、无鉴权任何一个问题都能被恶意利用。5.3 鉴权与长文本识别优化最后做一道简单的鉴权围墙。内部服务之间的调用也建议至少用一个静态 Token避免扫描器直接命中。在 Flask 里做一个before_request钩子校验 Header 里的X-Token。from functools import wraps from flask import request, jsonify VALID_TOKEN your-secret-token def require_token(f): wraps(f) def wrapper(*args, **kwargs): token request.headers.get(X-Token) if token ! VALID_TOKEN: return jsonify({code: 401, msg: unauthorized}), 401 return f(*args, **kwargs) return wrapper app.post(/ocr) require_token def ocr_endpoint(): # 业务逻辑见前文 pass长文本识别优化则属于“响应快慢直接决定调用方体验”的进阶项超过 4000px 的长图识别耗时极长且容易让模型漏检。常规做法是对图片做等比例缩放限制长边 2000px 内缩放后再送进 PaddleOCR检测精度不下降而耗时大幅缩短。还可以在 Flask 层加max_content_length限制请求体不超过 5MB防止超大图片拖垮 worker——这些边界定得越早后期线上告警就越少。本文还有配套的精品资源点击获取