简介一套基于Flask框架封装PaddleOCR的服务部署项目面向需要快速搭建OCR识别接口的开发者与计算机相关专业学生可应用于健康宝识别、文档自动化处理等场景。项目以轻量Web服务形式对外提供文字识别能力通过简单POST请求即可提交图像数据并获得识别结果。压缩包共19个文件以Python脚本、Markdown/HTML说明文档和JPG效果示例图为主整体约1.25MB目录结构简洁便于本地调试与云端部署。内容不仅包含Flask服务端实现和测试调用脚本还提供本地使用、云端部署及请求参数的详细说明附图展示实际识别效果帮助使用者理解接口调用流程与返回格式。已有288人学习下载适合作为AI/CS相关课程设计、毕业设计或入门OCR服务部署的参考资料。1. 一条 POST 请求拿到图像文字Flask 壳与 PaddleOCR 推理链路的真实落点把一张带文字的图片 POST 到一个 HTTP 接口两三秒后拿回 JSON 格式的识别结果这是 OCR 能力接入业务系统时最常用的交付形态。很多人早就在 notebook 里跑通过 PaddleOCR但真正做项目部署时会被卡住没有 Web 接口、模型初始化慢、文档只写了训练不写服务封装、部署到服务器上不知道从哪个文件开始。这份基于 Flask 的 PaddleOCR 服务部署资源把交付过程打包成了可直接复现的 Flask 工程server.py 统一加载推理模型HTTP 层接收图像templates/index.html 提供浏览器调试入口test-post.py 演示客户端上传图片的完整写法。适合课程设计、毕业设计也适合内部工具快速接入 OCR 能力尤其是健康宝识别、票据录入这类需要提交图片换文字的自动化场景。2. 环境准备与模型资源检查先看懂目录再谈启动2.1 依赖安装顺序与版本坑PaddleOCR 的安装顺序很容易被搞反。常见做法是先安装 PaddlePaddle 基础运行库再安装 paddleocr 工具包最后补 Flask 和 requests。如果直接pip install paddleocr它未必会帮你装好对应版本的 paddlepaddle 运行库启动时大概率报ModuleNotFoundError: No module named paddle或者 protobuf、shapely 等依赖版本冲突。这个项目对应的模型调用方式属于 PaddleOCR 2.x 分支安装时建议把三个核心包绑在相近的版本上避免 3.x 返回结构变化导致解析代码失效。# 先装 PaddlePaddle 基础库CPU 环境用 2.6.x 足够稳定 python -m pip install paddlepaddle2.6.2 -i https://mirror.baidu.com/pypi/simple # 再装 OCR 工具链与 Web 框架 python -m pip install paddleocr2.7.3 flask requests第一行命令把 PaddlePaddle 固定在 2.6.2是因为 2.7 以上对部分旧版 CUDA 环境不友好而 2.6.x 是 CPU 推理和常见 GPU 环境兼容性最稳的一个版本。第二行里的 flash 和 requests 分别对应服务端与测试端requests 在 test-post.py 中承担客户端传图职责。如果服务器在内网环境记得预先下载好 paddlepaddle 和 paddleocr 的 wheel 包离线安装时用pip install --no-index --find-links$PACKAGE_DIR指定本地目录否则会卡在下载阶段。安装后可以执行一次python -c from paddleocr import PaddleOCR; PaddleOCR(use_angle_clsTrue, langch, show_logFalse)来验证依赖是否完整首次执行会自动加载检测、方向分类、识别三个模型文件。2.2 项目目录里哪些文件是服务必需的解压后可以看到 PaddleOCR-Flask-main 目录下除了 server.py 和 README.md还有 templates、images、test-post.py 和 caches 目录。我一般会先把 caches 单独复制出来留作模型备份因为它存放的是模型下载后的缓存数据里面的哈希命名文件就是推理过程中保存的中间图像和特征图这些不是运行必需文件但能反映请求在哪个步骤出了异常排查图片旋转、裁切问题时非常有用。文件/目录作用部署时是否需要server.pyFlask 应用主入口模型初始化和 /ocr 接口必需templates/index.html浏览器可视化调试页面可上传图片预览结果可选保留便于演示test-post.py用 requests 模拟客户端上传图片的测试脚本必需用于自测images/内置测试图片如 1.jpg、2.jpg建议保留caches/PaddleOCR 模型缓存与中间产物备份即可README.md本地启动、云端部署、接口参数说明必需部署前通读templates/index.html 对生产环境不是必需品不过课程答辩或给非技术同事演示时非常方便浏览器打开 Flask 根路径就能看到上传按钮不用每次敲命令行。images 目录里的 demo.jpg 和 5407_corrected.jpg 适合做请求级联测试先用小图验证链路通再用文字密集的图验证识别效果。2.3 PaddleOCR 推理最小闭环一条图片输入路径的完整链路PaddleOCR 的标准推理链路包含三个子模块文本检测 DB、方向分类器、文本识别 CRNN。server.py 初始化时会把这三个模型一起加载进内存后续每个请求只做前向推理不再重复读盘。推理代码的逻辑并不复杂先传入图片路径然后逐层取出文本框坐标、识别文本和置信度。from paddleocr import PaddleOCR # 初始化时一次性加载三件套检测 方向分类 识别 ocr PaddleOCR( use_angle_clsTrue, # 启用方向分类器适合手机拍摄的倾斜图片 langch, # 中文识别也能兼容英文和数字 show_logFalse # 关闭推理日志避免污染服务打印 ) # 对单张图片执行识别 result ocr.ocr(images/1.jpg, clsTrue) # 解析返回结果result 的每个元素对应一张图 for block in result: for line in block: box line[0] # 四个角点坐标用于定位文字在画面中的位置 text line[1][0] # 识别出的文本内容 confidence line[1][1] # 置信度小于 0.6 的通常需要人工确认 print(f坐标: {box}, 文本: {text}, 置信度: {confidence})初始化里的use_angle_clsTrue看似只多了一个参数但它会让方向分类器先判断图片是否旋转了 90 度或 180 度再送入识别模型。像手机拍的证件、翻拍的纸质文档这个开关能明显提升准确率代价是单张图片多出十几毫秒的推理时间。langch指定中英文混合模型如果业务场景全是英文换成langen后模型体积更小首包传输更快。代码里对返回结果的解析按“图块 → 文本框 → 文本与置信度”三层展开项目里 server.py 就是把这段逻辑包进 Flask 路由再把数据转成 JSON 返回给调用方。3. Flask 接口设计路由、参数表与 test-post.py 的第一次调用3.1 server.py 的路由结构与模型加载时机Flask 服务的路由通常是两个根路径/返回 templates/index.html用于浏览器访问/ocr接收 POST 请求并执行推理。模型对象要声明在路由函数外部、模块加载时完成初始化这是接口响应速度的关键。如果把PaddleOCR()写进视图函数每次请求都要重建三个模型第一次调用会被拖到几十秒线上直接触发超时。import io import json from flask import Flask, request, jsonify, render_template from paddleocr import PaddleOCR from PIL import Image app Flask(__name__) # 全局只初始化一次进程生命周期内复用同一份模型 ocr_engine PaddleOCR( use_angle_clsTrue, langch, show_logFalse ) app.route(/) def index(): # 返回调试页面浏览器可以直接上传图片 return render_template(index.html) app.route(/ocr, methods[POST]) def ocr_service(): # 1. 从表单文件字段读取图片 if image in request.files: file_storage request.files[image] image_data file_storage.read() else: image_data request.get_data() # 2. 转成 PIL Image 后再存临时文件兼容内存中直接传入的字节流 image Image.open(io.BytesIO(image_data)).convert(RGB) temp_path /tmp/ocr_input.jpg image.save(temp_path, quality95) # 3. 执行推理并整理结果 result ocr_engine.ocr(temp_path, clsTrue) lines [] for block in result: for line in block: box line[0] text line[1][0] confidence float(line[1][1]) lines.append({ text: text, confidence: confidence, box: box }) return jsonify({code: 0, data: lines})request.files.get(image)是前端表单上传文件时的标准取法用file_storage.read()直接拿到二进制内容。Image.open(io.BytesIO(image_data))让接口既支持 multipart 文件也支持二进制流直接提交convert(RGB)的目的是把带透明度通道的 PNG 图统一转成三通道固定成 JPEG 后写盘避免 PaddleOCR 在处理 RGBA 输入时出现通道数不匹配的报错。返回结构里 box 字段是四角坐标列表前端可以据此画红框标出文字位置。3.2 接口参数表与返回结构说明这个项目的 README 中已经把接口参数写得很清楚部署时可以直接作为接口文档交付。核心参数集中在识别语言、方向分类、是否返回坐标三项文件本身通过表单字段传递。参数名类型必须说明imagefile是表单文件字段支持 jpg、png大小建议不超过 10MBlangstring否识别语言ch 为中英文en 为英文默认 chuse_angle_clsbool否是否启用方向分类器true/false默认 truedetailbool否是否返回每个文本框坐标默认 true返回内容统一封装成 JSON调用方只需要判断code是否为 0再遍历data数组取text字段即可。置信度字段是浮点数取值范围 0 到 1识别模糊图片时建议在业务侧过滤掉置信度低于 0.6 的结果宁可漏识也不要把错误文本直接入库。{ code: 0, data: [ { text: 姓名张XX, confidence: 0.987, box: [[25, 34], [125, 34], [125, 64], [25, 64]] }, { text: 证件号码110101199001011234, confidence: 0.964, box: [[25, 72], [285, 72], [285, 104], [25, 104]] } ] }返回结构里的 box 坐标顺序是“左上、右上、右下、左下”不是随手写的任意四边形顺序。如果前端要画 Polygon必须按这个顺序连线否则会出现文字框交叉。置信度低于 0.6 的结果建议后端主动标记need_review: true让下游人工审核这个逻辑可以在 server.py 的返回组装里加一行判断。3.3 用 test-post.py 发起第一次识别请求项目里的 test-post.py 解决了“服务起来了但不敢确认能不能用”的尴尬。脚本逻辑非常简单构造一个表单文件字段用 requests.post 发给本地服务再把响应打印出来。正式接入时把这套写进你的业务客户端即可。import requests # 服务地址本地测试用 127.0.0.1云端部署换成 ECS 公网 IP url http://127.0.0.1:5000/ocr # 以表单文件字段方式上传图片字段名必须和 server.py 里一致 files {image: open(images/1.jpg, rb)} # 超时时间设 30 秒OCR 推理在 CPU 环境对复杂图片可能超过 10 秒 resp requests.post(url, filesfiles, timeout30) # 服务端返回的是 JSON直接按字典读取 result resp.json() print(状态码:, resp.status_code) print(业务码:, result[code]) for item in result[data]: print(f识别文本: {item[text]}, 置信度: {item[confidence]:.4f})files字典的键名image必须与 server.py 里request.files[image]完全一致拼错任何一个字母都会导致服务端读不到文件返回 400。timeout30是客户端层面的保护防止服务端长时间不响应导致业务线程被拖死。第一次运行如果报连接拒绝先看 Flask 服务是否还在前台运行如果是部署到云服务器还要确认安全组规则里放通了 5000 端口这个坑在阿里云 ECS 上尤其常见。4. 从开发机到服务器gunicorn、Nginx 反向代理与 systemd 守护4.1 为什么 flask run 不能直接用于生产python server.py启动的是 Flask 自带开发服务器底层是 Werkzeug 单进程模型能扛住开发调试的小流量但一旦并发请求上来会出现请求排队、CPU 占用异常、图片上传大文件时连接被重置等问题。常见做法是引入 gunicorn 作为 WSGI 服务器把 Flask 应用对象加载到多个 worker 进程中利用多核 CPU 并行处理请求。gunicorn 本身只负责进程管理和请求分发真正的应用逻辑仍然跑在 server.py 里。4.2 gunicorn 启动命令与 worker 数选择启动命令的写法决定了服务能不能稳定扛住并发。PaddleOCR 推理每个 worker 进程会持有完整模型内存占用大致在 1GB 到 2GB 之间worker 数开多了容易把服务器内存打满。我一般先按 CPU 核心数的一半起步同时预留内存余量。# 2 个 worker绑定 5000 端口超时 120 秒 gunicorn -w 2 -b 0.0.0.0:5000 -t 120 server:app # 如果内存紧张改为单 worker 配合多线程 gunicorn -w 1 --threads 4 -b 0.0.0.0:5000 -t 120 server:app-w 2是 worker 进程数简单理解成同时能并行处理的请求数上限。-t 120是超时时间默认值 30 秒对 PaddleOCR 不够一张高分辨率图片在 CPU 上推理就可能超过 30 秒超时后 gunicorn 会直接 kill 掉 worker导致服务反复重启。第二种写法里--threads 4让单进程内部用线程处理请求线程共享模型内存适合并发低但单请求耗时长、内存又紧张的场景。启动后访问http://服务器IP:5000/如果能看到调试页面说明 gunicorn 已经正常接管 Flask 应用。4.3 Nginx 反向代理、上传限制与静态资源把 Nginx 放在 gunicorn 前面主要是为了处理三件事客户端图片上传体积限制、静态资源访问、外部请求到内部进程的转发。PaddleOCR 服务本身不擅长处理大文件Nginx 可以直接在入口处限制请求体大小超过 10MB 的图片直接拒绝省掉模型推理上的无效消耗。server { listen 80; server_name your_domain_or_ip; # 上传大小限制OCR 图片一般 10MB 以内足够 client_max_body_size 10m; location / { # 转发到 gunicorn 监听端口 proxy_pass http://127.0.0.1:5000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # 推理可能耗时较长关闭 Nginx 层快速超时 proxy_read_timeout 300s; proxy_send_timeout 300s; } }client_max_body_size 10m设的是请求体上限超过 10MB 的业务图片会在 Nginx 层直接返回 413而不是把压力传给后端模型。proxy_read_timeout 300s很关键因为 PaddleOCR 推理是计算密集型任务拿 4MB 图片在纯 CPU 环境跑一次可能耗时几十秒Nginx 默认 60 秒超时对于大图不够调大后能避免误杀慢请求。配置完成后执行nginx -t检查语法再systemctl reload nginx生效这时候服务对外端口从 5000 变成 80访问路径也变成http://IP/ocrtest-post.py 里的地址要同步修改。4.4 systemd 让服务开机自启与崩溃自动拉起在服务器上维护进程最怕登录终端一关服务就挂。用 systemd 写一个服务单元文件能实现开机自动启动、进程崩溃自动拉起、日志集中管理比手动 nohup 可靠得多。文件路径/etc/systemd/system/ocr.service内容可以直接套用下面的模板。[Unit] DescriptionPaddleOCR Flask Service Afternetwork.target [Service] Userwww-data WorkingDirectory/opt/PaddleOCR-Flask-main # 用 gunicorn 启动加载 server 模块里的 app 对象 ExecStart/usr/bin/gunicorn -w 2 -b 127.0.0.1:5000 -t 120 server:app Restartalways RestartSec5 [Install] WantedBymulti-user.targetWorkingDirectory必须指向 server.py 所在目录否则 gunicorn 找不到应用对象。ExecStart指定 gunicorn 全路径这是 systemd 环境里 PATH 精简导致的最常见故障点。Restartalways表示进程无论因为什么原因退出都自动重启RestartSec5控制重启间隔 5 秒避免模型加载失败时陷入快速重启风暴。配置好后执行systemctl daemon-reload、systemctl enable --now ocr再用systemctl status ocr查看运行状态。如果端口被占用先ss -lntp | grep 5000找到旧进程杀掉后重启服务。提示每次更新 server.py 代码后只需要systemctl restart ocr即可不需要重新加载系统服务配置。如果模型或依赖发生变化重启间隔建议拉长到 10 秒以上。5. 线上验证与耗时调优从 curl 自测到模型切换5.1 用 curl 做连通性自测部署完成后先别急着写业务调用用 curl 从命令行直接模拟一次请求快速验证链路是否打通。curl 能同时暴露网络层、HTTP 层和应用层的异常比打开浏览器调试更精准。# 上传 images/1.jpg 到 /ocr 接口打印响应头和响应体 curl -X POST http://127.0.0.1:5000/ocr \ -F imageimages/1.jpg \ -w \nHTTP状态码: %{http_code}\n # 只请求根路径确认 Flask 是否正常返回调试页面 curl -I http://127.0.0.1:5000/参数-F imageimages/1.jpg表示以表单字段形式上传文件前缀告诉 curl 后面的字符串是本地文件路径而不是字面量。-I只发送 HEAD 请求用来确认 Web 服务进程本身没有宕机。如果返回 500多半是 server.py 在解析图片或组装 JSON 时抛了异常查看 gunicorn 日志定位即可如果返回 502则是 Nginx 后端连接超时或 gunicorn worker 全部崩溃。5.2 耗时瓶颈定位与定位策略单张图片接口耗时超过预期时先明确瓶颈在传输还是推理。用 test-post.py 本地调用对比输出时间如果本地小于 100ms 而云端超过 3 秒问题在网络带宽或图片体积如果本地和服务端都超过 2 秒瓶颈在模型推理。PaddleOCR 单个请求的耗时主要由三部分构成检测模型推理、方向分类、识别模型推理。日志里会输出每张图片各阶段的耗时分布观察是检测花了 1.5 秒还是识别花了 1.8 秒再针对性优化。瓶颈阶段现象处理方式文本检测慢图片中文字区域多检测耗时占比高降低输入图片分辨率或换 mobile 检测模型方向分类慢每张图片都启用方向分类业务图片都是正向时在接口里加参数关闭分类器识别模型慢文字行多识别耗时占比高换 ch_PP-OCRv4_mobile_rec 模型识别速度提升明显5.3 轻量模型替换与方向分类器开关技巧项目默认加载的是标准版模型在内存和速度上都不是最优解。如果服务器只有 2 核 4GB 配置建议显式指定轻量模型组合把检测模型换成 mobile 版识别模型换成 mobile 版初始化参数写在 server.py 的 PaddleOCR 调用里即可。from paddleocr import PaddleOCR ocr PaddleOCR( use_angle_clsTrue, langch, show_logFalse, det_model_dir./models/ch_PP-OCRv4_mobile_det_infer, rec_model_dir./models/ch_PP-OCRv4_mobile_rec_infer, cls_model_dir./models/ch_ppocr_mobile_v2.0_cls_infer )det_model_dir和rec_model_dir分别指定检测模型与识别模型的本地路径指定后不会再触发在线下载离线服务器也能直接运行。mobile 系列模型体积比 server 版小大约一半单次推理耗时能减少 30% 到 50%识别精度差异在正常拍摄的文档上几乎感知不到。修改完模型路径后要把原来的模型缓存清理掉否则 PaddleOCR 仍会从缓存目录读取旧权重。这里还留一个可以继续深挖的扩展点用--preload配合 gunicorn 启动在 worker fork 前加载模型让多个 worker 共享同一份模型权重减少 2GB 级的内存重复占用这对 4GB 内存的入门云服务器非常有用。本文还有配套的精品资源点击获取 Flask部署PaddleOCR识别服务：从接口封装到生产上线全流程
简介一套基于Flask框架封装PaddleOCR的服务部署项目面向需要快速搭建OCR识别接口的开发者与计算机相关专业学生可应用于健康宝识别、文档自动化处理等场景。项目以轻量Web服务形式对外提供文字识别能力通过简单POST请求即可提交图像数据并获得识别结果。压缩包共19个文件以Python脚本、Markdown/HTML说明文档和JPG效果示例图为主整体约1.25MB目录结构简洁便于本地调试与云端部署。内容不仅包含Flask服务端实现和测试调用脚本还提供本地使用、云端部署及请求参数的详细说明附图展示实际识别效果帮助使用者理解接口调用流程与返回格式。已有288人学习下载适合作为AI/CS相关课程设计、毕业设计或入门OCR服务部署的参考资料。1. 一条 POST 请求拿到图像文字Flask 壳与 PaddleOCR 推理链路的真实落点把一张带文字的图片 POST 到一个 HTTP 接口两三秒后拿回 JSON 格式的识别结果这是 OCR 能力接入业务系统时最常用的交付形态。很多人早就在 notebook 里跑通过 PaddleOCR但真正做项目部署时会被卡住没有 Web 接口、模型初始化慢、文档只写了训练不写服务封装、部署到服务器上不知道从哪个文件开始。这份基于 Flask 的 PaddleOCR 服务部署资源把交付过程打包成了可直接复现的 Flask 工程server.py 统一加载推理模型HTTP 层接收图像templates/index.html 提供浏览器调试入口test-post.py 演示客户端上传图片的完整写法。适合课程设计、毕业设计也适合内部工具快速接入 OCR 能力尤其是健康宝识别、票据录入这类需要提交图片换文字的自动化场景。2. 环境准备与模型资源检查先看懂目录再谈启动2.1 依赖安装顺序与版本坑PaddleOCR 的安装顺序很容易被搞反。常见做法是先安装 PaddlePaddle 基础运行库再安装 paddleocr 工具包最后补 Flask 和 requests。如果直接pip install paddleocr它未必会帮你装好对应版本的 paddlepaddle 运行库启动时大概率报ModuleNotFoundError: No module named paddle或者 protobuf、shapely 等依赖版本冲突。这个项目对应的模型调用方式属于 PaddleOCR 2.x 分支安装时建议把三个核心包绑在相近的版本上避免 3.x 返回结构变化导致解析代码失效。# 先装 PaddlePaddle 基础库CPU 环境用 2.6.x 足够稳定 python -m pip install paddlepaddle2.6.2 -i https://mirror.baidu.com/pypi/simple # 再装 OCR 工具链与 Web 框架 python -m pip install paddleocr2.7.3 flask requests第一行命令把 PaddlePaddle 固定在 2.6.2是因为 2.7 以上对部分旧版 CUDA 环境不友好而 2.6.x 是 CPU 推理和常见 GPU 环境兼容性最稳的一个版本。第二行里的 flash 和 requests 分别对应服务端与测试端requests 在 test-post.py 中承担客户端传图职责。如果服务器在内网环境记得预先下载好 paddlepaddle 和 paddleocr 的 wheel 包离线安装时用pip install --no-index --find-links$PACKAGE_DIR指定本地目录否则会卡在下载阶段。安装后可以执行一次python -c from paddleocr import PaddleOCR; PaddleOCR(use_angle_clsTrue, langch, show_logFalse)来验证依赖是否完整首次执行会自动加载检测、方向分类、识别三个模型文件。2.2 项目目录里哪些文件是服务必需的解压后可以看到 PaddleOCR-Flask-main 目录下除了 server.py 和 README.md还有 templates、images、test-post.py 和 caches 目录。我一般会先把 caches 单独复制出来留作模型备份因为它存放的是模型下载后的缓存数据里面的哈希命名文件就是推理过程中保存的中间图像和特征图这些不是运行必需文件但能反映请求在哪个步骤出了异常排查图片旋转、裁切问题时非常有用。文件/目录作用部署时是否需要server.pyFlask 应用主入口模型初始化和 /ocr 接口必需templates/index.html浏览器可视化调试页面可上传图片预览结果可选保留便于演示test-post.py用 requests 模拟客户端上传图片的测试脚本必需用于自测images/内置测试图片如 1.jpg、2.jpg建议保留caches/PaddleOCR 模型缓存与中间产物备份即可README.md本地启动、云端部署、接口参数说明必需部署前通读templates/index.html 对生产环境不是必需品不过课程答辩或给非技术同事演示时非常方便浏览器打开 Flask 根路径就能看到上传按钮不用每次敲命令行。images 目录里的 demo.jpg 和 5407_corrected.jpg 适合做请求级联测试先用小图验证链路通再用文字密集的图验证识别效果。2.3 PaddleOCR 推理最小闭环一条图片输入路径的完整链路PaddleOCR 的标准推理链路包含三个子模块文本检测 DB、方向分类器、文本识别 CRNN。server.py 初始化时会把这三个模型一起加载进内存后续每个请求只做前向推理不再重复读盘。推理代码的逻辑并不复杂先传入图片路径然后逐层取出文本框坐标、识别文本和置信度。from paddleocr import PaddleOCR # 初始化时一次性加载三件套检测 方向分类 识别 ocr PaddleOCR( use_angle_clsTrue, # 启用方向分类器适合手机拍摄的倾斜图片 langch, # 中文识别也能兼容英文和数字 show_logFalse # 关闭推理日志避免污染服务打印 ) # 对单张图片执行识别 result ocr.ocr(images/1.jpg, clsTrue) # 解析返回结果result 的每个元素对应一张图 for block in result: for line in block: box line[0] # 四个角点坐标用于定位文字在画面中的位置 text line[1][0] # 识别出的文本内容 confidence line[1][1] # 置信度小于 0.6 的通常需要人工确认 print(f坐标: {box}, 文本: {text}, 置信度: {confidence})初始化里的use_angle_clsTrue看似只多了一个参数但它会让方向分类器先判断图片是否旋转了 90 度或 180 度再送入识别模型。像手机拍的证件、翻拍的纸质文档这个开关能明显提升准确率代价是单张图片多出十几毫秒的推理时间。langch指定中英文混合模型如果业务场景全是英文换成langen后模型体积更小首包传输更快。代码里对返回结果的解析按“图块 → 文本框 → 文本与置信度”三层展开项目里 server.py 就是把这段逻辑包进 Flask 路由再把数据转成 JSON 返回给调用方。3. Flask 接口设计路由、参数表与 test-post.py 的第一次调用3.1 server.py 的路由结构与模型加载时机Flask 服务的路由通常是两个根路径/返回 templates/index.html用于浏览器访问/ocr接收 POST 请求并执行推理。模型对象要声明在路由函数外部、模块加载时完成初始化这是接口响应速度的关键。如果把PaddleOCR()写进视图函数每次请求都要重建三个模型第一次调用会被拖到几十秒线上直接触发超时。import io import json from flask import Flask, request, jsonify, render_template from paddleocr import PaddleOCR from PIL import Image app Flask(__name__) # 全局只初始化一次进程生命周期内复用同一份模型 ocr_engine PaddleOCR( use_angle_clsTrue, langch, show_logFalse ) app.route(/) def index(): # 返回调试页面浏览器可以直接上传图片 return render_template(index.html) app.route(/ocr, methods[POST]) def ocr_service(): # 1. 从表单文件字段读取图片 if image in request.files: file_storage request.files[image] image_data file_storage.read() else: image_data request.get_data() # 2. 转成 PIL Image 后再存临时文件兼容内存中直接传入的字节流 image Image.open(io.BytesIO(image_data)).convert(RGB) temp_path /tmp/ocr_input.jpg image.save(temp_path, quality95) # 3. 执行推理并整理结果 result ocr_engine.ocr(temp_path, clsTrue) lines [] for block in result: for line in block: box line[0] text line[1][0] confidence float(line[1][1]) lines.append({ text: text, confidence: confidence, box: box }) return jsonify({code: 0, data: lines})request.files.get(image)是前端表单上传文件时的标准取法用file_storage.read()直接拿到二进制内容。Image.open(io.BytesIO(image_data))让接口既支持 multipart 文件也支持二进制流直接提交convert(RGB)的目的是把带透明度通道的 PNG 图统一转成三通道固定成 JPEG 后写盘避免 PaddleOCR 在处理 RGBA 输入时出现通道数不匹配的报错。返回结构里 box 字段是四角坐标列表前端可以据此画红框标出文字位置。3.2 接口参数表与返回结构说明这个项目的 README 中已经把接口参数写得很清楚部署时可以直接作为接口文档交付。核心参数集中在识别语言、方向分类、是否返回坐标三项文件本身通过表单字段传递。参数名类型必须说明imagefile是表单文件字段支持 jpg、png大小建议不超过 10MBlangstring否识别语言ch 为中英文en 为英文默认 chuse_angle_clsbool否是否启用方向分类器true/false默认 truedetailbool否是否返回每个文本框坐标默认 true返回内容统一封装成 JSON调用方只需要判断code是否为 0再遍历data数组取text字段即可。置信度字段是浮点数取值范围 0 到 1识别模糊图片时建议在业务侧过滤掉置信度低于 0.6 的结果宁可漏识也不要把错误文本直接入库。{ code: 0, data: [ { text: 姓名张XX, confidence: 0.987, box: [[25, 34], [125, 34], [125, 64], [25, 64]] }, { text: 证件号码110101199001011234, confidence: 0.964, box: [[25, 72], [285, 72], [285, 104], [25, 104]] } ] }返回结构里的 box 坐标顺序是“左上、右上、右下、左下”不是随手写的任意四边形顺序。如果前端要画 Polygon必须按这个顺序连线否则会出现文字框交叉。置信度低于 0.6 的结果建议后端主动标记need_review: true让下游人工审核这个逻辑可以在 server.py 的返回组装里加一行判断。3.3 用 test-post.py 发起第一次识别请求项目里的 test-post.py 解决了“服务起来了但不敢确认能不能用”的尴尬。脚本逻辑非常简单构造一个表单文件字段用 requests.post 发给本地服务再把响应打印出来。正式接入时把这套写进你的业务客户端即可。import requests # 服务地址本地测试用 127.0.0.1云端部署换成 ECS 公网 IP url http://127.0.0.1:5000/ocr # 以表单文件字段方式上传图片字段名必须和 server.py 里一致 files {image: open(images/1.jpg, rb)} # 超时时间设 30 秒OCR 推理在 CPU 环境对复杂图片可能超过 10 秒 resp requests.post(url, filesfiles, timeout30) # 服务端返回的是 JSON直接按字典读取 result resp.json() print(状态码:, resp.status_code) print(业务码:, result[code]) for item in result[data]: print(f识别文本: {item[text]}, 置信度: {item[confidence]:.4f})files字典的键名image必须与 server.py 里request.files[image]完全一致拼错任何一个字母都会导致服务端读不到文件返回 400。timeout30是客户端层面的保护防止服务端长时间不响应导致业务线程被拖死。第一次运行如果报连接拒绝先看 Flask 服务是否还在前台运行如果是部署到云服务器还要确认安全组规则里放通了 5000 端口这个坑在阿里云 ECS 上尤其常见。4. 从开发机到服务器gunicorn、Nginx 反向代理与 systemd 守护4.1 为什么 flask run 不能直接用于生产python server.py启动的是 Flask 自带开发服务器底层是 Werkzeug 单进程模型能扛住开发调试的小流量但一旦并发请求上来会出现请求排队、CPU 占用异常、图片上传大文件时连接被重置等问题。常见做法是引入 gunicorn 作为 WSGI 服务器把 Flask 应用对象加载到多个 worker 进程中利用多核 CPU 并行处理请求。gunicorn 本身只负责进程管理和请求分发真正的应用逻辑仍然跑在 server.py 里。4.2 gunicorn 启动命令与 worker 数选择启动命令的写法决定了服务能不能稳定扛住并发。PaddleOCR 推理每个 worker 进程会持有完整模型内存占用大致在 1GB 到 2GB 之间worker 数开多了容易把服务器内存打满。我一般先按 CPU 核心数的一半起步同时预留内存余量。# 2 个 worker绑定 5000 端口超时 120 秒 gunicorn -w 2 -b 0.0.0.0:5000 -t 120 server:app # 如果内存紧张改为单 worker 配合多线程 gunicorn -w 1 --threads 4 -b 0.0.0.0:5000 -t 120 server:app-w 2是 worker 进程数简单理解成同时能并行处理的请求数上限。-t 120是超时时间默认值 30 秒对 PaddleOCR 不够一张高分辨率图片在 CPU 上推理就可能超过 30 秒超时后 gunicorn 会直接 kill 掉 worker导致服务反复重启。第二种写法里--threads 4让单进程内部用线程处理请求线程共享模型内存适合并发低但单请求耗时长、内存又紧张的场景。启动后访问http://服务器IP:5000/如果能看到调试页面说明 gunicorn 已经正常接管 Flask 应用。4.3 Nginx 反向代理、上传限制与静态资源把 Nginx 放在 gunicorn 前面主要是为了处理三件事客户端图片上传体积限制、静态资源访问、外部请求到内部进程的转发。PaddleOCR 服务本身不擅长处理大文件Nginx 可以直接在入口处限制请求体大小超过 10MB 的图片直接拒绝省掉模型推理上的无效消耗。server { listen 80; server_name your_domain_or_ip; # 上传大小限制OCR 图片一般 10MB 以内足够 client_max_body_size 10m; location / { # 转发到 gunicorn 监听端口 proxy_pass http://127.0.0.1:5000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # 推理可能耗时较长关闭 Nginx 层快速超时 proxy_read_timeout 300s; proxy_send_timeout 300s; } }client_max_body_size 10m设的是请求体上限超过 10MB 的业务图片会在 Nginx 层直接返回 413而不是把压力传给后端模型。proxy_read_timeout 300s很关键因为 PaddleOCR 推理是计算密集型任务拿 4MB 图片在纯 CPU 环境跑一次可能耗时几十秒Nginx 默认 60 秒超时对于大图不够调大后能避免误杀慢请求。配置完成后执行nginx -t检查语法再systemctl reload nginx生效这时候服务对外端口从 5000 变成 80访问路径也变成http://IP/ocrtest-post.py 里的地址要同步修改。4.4 systemd 让服务开机自启与崩溃自动拉起在服务器上维护进程最怕登录终端一关服务就挂。用 systemd 写一个服务单元文件能实现开机自动启动、进程崩溃自动拉起、日志集中管理比手动 nohup 可靠得多。文件路径/etc/systemd/system/ocr.service内容可以直接套用下面的模板。[Unit] DescriptionPaddleOCR Flask Service Afternetwork.target [Service] Userwww-data WorkingDirectory/opt/PaddleOCR-Flask-main # 用 gunicorn 启动加载 server 模块里的 app 对象 ExecStart/usr/bin/gunicorn -w 2 -b 127.0.0.1:5000 -t 120 server:app Restartalways RestartSec5 [Install] WantedBymulti-user.targetWorkingDirectory必须指向 server.py 所在目录否则 gunicorn 找不到应用对象。ExecStart指定 gunicorn 全路径这是 systemd 环境里 PATH 精简导致的最常见故障点。Restartalways表示进程无论因为什么原因退出都自动重启RestartSec5控制重启间隔 5 秒避免模型加载失败时陷入快速重启风暴。配置好后执行systemctl daemon-reload、systemctl enable --now ocr再用systemctl status ocr查看运行状态。如果端口被占用先ss -lntp | grep 5000找到旧进程杀掉后重启服务。提示每次更新 server.py 代码后只需要systemctl restart ocr即可不需要重新加载系统服务配置。如果模型或依赖发生变化重启间隔建议拉长到 10 秒以上。5. 线上验证与耗时调优从 curl 自测到模型切换5.1 用 curl 做连通性自测部署完成后先别急着写业务调用用 curl 从命令行直接模拟一次请求快速验证链路是否打通。curl 能同时暴露网络层、HTTP 层和应用层的异常比打开浏览器调试更精准。# 上传 images/1.jpg 到 /ocr 接口打印响应头和响应体 curl -X POST http://127.0.0.1:5000/ocr \ -F imageimages/1.jpg \ -w \nHTTP状态码: %{http_code}\n # 只请求根路径确认 Flask 是否正常返回调试页面 curl -I http://127.0.0.1:5000/参数-F imageimages/1.jpg表示以表单字段形式上传文件前缀告诉 curl 后面的字符串是本地文件路径而不是字面量。-I只发送 HEAD 请求用来确认 Web 服务进程本身没有宕机。如果返回 500多半是 server.py 在解析图片或组装 JSON 时抛了异常查看 gunicorn 日志定位即可如果返回 502则是 Nginx 后端连接超时或 gunicorn worker 全部崩溃。5.2 耗时瓶颈定位与定位策略单张图片接口耗时超过预期时先明确瓶颈在传输还是推理。用 test-post.py 本地调用对比输出时间如果本地小于 100ms 而云端超过 3 秒问题在网络带宽或图片体积如果本地和服务端都超过 2 秒瓶颈在模型推理。PaddleOCR 单个请求的耗时主要由三部分构成检测模型推理、方向分类、识别模型推理。日志里会输出每张图片各阶段的耗时分布观察是检测花了 1.5 秒还是识别花了 1.8 秒再针对性优化。瓶颈阶段现象处理方式文本检测慢图片中文字区域多检测耗时占比高降低输入图片分辨率或换 mobile 检测模型方向分类慢每张图片都启用方向分类业务图片都是正向时在接口里加参数关闭分类器识别模型慢文字行多识别耗时占比高换 ch_PP-OCRv4_mobile_rec 模型识别速度提升明显5.3 轻量模型替换与方向分类器开关技巧项目默认加载的是标准版模型在内存和速度上都不是最优解。如果服务器只有 2 核 4GB 配置建议显式指定轻量模型组合把检测模型换成 mobile 版识别模型换成 mobile 版初始化参数写在 server.py 的 PaddleOCR 调用里即可。from paddleocr import PaddleOCR ocr PaddleOCR( use_angle_clsTrue, langch, show_logFalse, det_model_dir./models/ch_PP-OCRv4_mobile_det_infer, rec_model_dir./models/ch_PP-OCRv4_mobile_rec_infer, cls_model_dir./models/ch_ppocr_mobile_v2.0_cls_infer )det_model_dir和rec_model_dir分别指定检测模型与识别模型的本地路径指定后不会再触发在线下载离线服务器也能直接运行。mobile 系列模型体积比 server 版小大约一半单次推理耗时能减少 30% 到 50%识别精度差异在正常拍摄的文档上几乎感知不到。修改完模型路径后要把原来的模型缓存清理掉否则 PaddleOCR 仍会从缓存目录读取旧权重。这里还留一个可以继续深挖的扩展点用--preload配合 gunicorn 启动在 worker fork 前加载模型让多个 worker 共享同一份模型权重减少 2GB 级的内存重复占用这对 4GB 内存的入门云服务器非常有用。本文还有配套的精品资源点击获取