企业官网建设流程全解析

OCR 这东西，听起来简单，做起来全是细节。很多开发者一开始会图省事直接调云端 API，但真到了要处理敏感数据、要离线部署、要控制长期成本的时候，还是得落到本地方案上。我之前在一个模拟项目里需要处理大量中文票据识别，试过一圈开源工具，最后是 PaddleOCR 配合 Flask 打包成 Web 服务跑通的。整个过程从安装、测试到部署，踩了不少坑，也沉淀了一些比较实用的经验。这篇就完整捋一遍，给同样想快速把 OCR 能力做成 Web 接口的朋友做个参考。

1. 为什么是 PaddleOCR：本地中文识别的最优解分析

先聊一个很现实的问题：OCR 方案那么多，为什么我最终选了 PaddleOCR，而不是 Tesseract、EasyOCR 或者直接上云端 API？这个选择背后其实有几个关键考量。

Tesseract 是老牌开源方案，纯 C++ 实现，部署简单，社区也大。但它的中文识别准确率放在真实业务场景里真的不够看，稍微遇到倾斜、模糊、复杂背景的图片，识别结果就是灾难级。我早期在某个实验环境里拿 300 张不同质量的中文票据测过，Tesseract 的字级准确率大概只有六成到七成，这个水平很难交付给业务方。EasyOCR 在学术圈口碑不错，模型也比较新，但它的依赖太重，而且 PaddleOCR 在中文场景的优化明显更激进，两者的识别效果差距在真实数据上很直观。

云端 API 的方案我一开始也考虑过。好处是省心，不用管模型和推理资源，按调用量付费就行。但问题也很明显：数据要传到外部服务，很多内部项目直接卡在合规这关；长期高频调用下来，成本并不低。我之前了解过几个类似项目的账单，每天几千次调用，月费很快就突破四位数了，这还不算网络延迟带来的体验损耗。

PaddleOCR 的优势在于三点：一是中文识别准确率确实能打，尤其是针对印刷体、表格、票据这类结构化文本，整体效果好于同级别的开源方案；二是它内置了文本检测（detection）、方向分类（classification）、文本识别（recognition）三段式流水线，每一段都可以单独替换模型，非常灵活；三是支持 CPU 和 GPU 两种推理模式，部署时可以根据服务器实际情况选，不用一上来就堆显卡。

还有一个让我很舒服的点：它是纯离线运行的。模型下载到本地之后，整个识别过程不依赖外部网络。这对于内网环境、对数据敏感的场景几乎是必须的能力。后续就算服务部署在无外网的机器上，也不影响使用。

2. 环境安装的完整步骤与依赖冲突处理

确认选型之后，第一件事就是搭环境。这一步看着简单，实际里面坑不少，尤其是依赖冲突问题，我见过太多人卡在这里。

2.1 Python 环境准备

先明确一个基本要求：Python 版本最好选 3.8 到 3.10 之间。太新的版本（比如 Python 3.12+）在部分依赖上可能没有预编译的 wheel 包，装起来会比较麻烦。

我个人的习惯是用 conda 先建一个独立环境，避免把系统 Python 环境搞乱：

conda create -n ocr_service python=3.9 conda activate ocr_service

如果你不用 conda，用 Python 自带的虚拟环境也是一样的，关键是隔离。

2.2 安装飞桨框架

PaddleOCR 的底层推理依赖飞桨（PaddlePaddle）框架。这一步要特别注意 CPU 和 GPU 版本的选择，两者不能混装。

CPU 版本直接装：

pip install paddlepaddle

GPU 版本需要先看下自己的 CUDA 版本，然后装对应的版本。比如 CUDA 11.8 的环境，要指定装这个版本：

pip install paddlepaddle-gpu==2.5.2.post118

这里有个容易踩的坑：如果你只是做原型验证，先装 CPU 版本就好。不是所有机器都值得为了 OCR 单独配 GPU，CPU 跑 PaddleOCR 对单张图片的推理时间大约在 1-3 秒（取决于图片大小和内容复杂度），原型阶段完全够用。我的建议是：先把整个流程跑通，再根据实际性能瓶颈决定要不要换 GPU。

2.3 安装 PaddleOCR 本体

pip install paddleocr

安装过程一般比较顺利，主要依赖包括 opencv-python、numpy、shapely、pyclipper 等。真正容易出问题的是后面这些依赖和你现有环境里其他包的版本冲突。

2.4 最常遇到的依赖冲突

我实际过程中踩过几个具体的冲突：

• opencv-python 和 opencv-contrib-python 不能共存，如果你的环境里之前装过后者，建议先卸载干净再装。
• numpy 版本太新（比如 2.x）可能和旧版 PaddleOCR 不兼容，会出现_ARRAY_API not found之类的报错。解决办法是固定 numpy 版本：

pip install "numpy<2.0"

• shapely 库在 macOS 上有时会报 Geos 相关错误，需要单独升级：

pip install --upgrade shapely

遇到这类问题，先看完整报错堆栈，再逐个处理，不要盲目卸载重装整套环境。我的习惯是边装边记录，每装一个关键依赖就跑一下pip list看版本号，这样出了问题能快速定位是哪一层的原因。

3. 模型下载机制与命令行测试实操

环境装好之后，先不急着写代码，用 PaddleOCR 自带的命令行工具做一轮功能测试。这一步能快速发现环境问题，也能确认模型能不能正常下载和推理。

3.1 首次运行会自动下载模型

PaddleOCR 的模型不在安装包里，而是首次运行时自动下载到本机缓存目录。Linux 和 macOS 下默认在~/.paddlex或~/.paddleocr，Windows 下在用户目录下的同名隐藏目录中。

这个机制很方便，但也有个痛点：国内网络环境下下载速度不太稳定。实测下来，如果不幸遇到下载卡住，可以先手动去官网把模型文件下下来，再放到指定目录。这里给一下手动放置的参考路径结构：

~/.paddlex/ 官方提供的模型压缩包解压后： det_model/ rec_model/ cls_model/

确保目录结构和官方压缩包内一致就行。PaddleOCR 识别时会自动按默认配置加载这些模型，不用手动指定路径。

3.2 命令行测试命令

用一个有文字的图片跑一轮基础测试：

paddleocr --image_dir ./test.jpg --lang ch --use_angle_cls True

命令含义拆开解释一下：

• --image_dir：指定要识别的图片路径。
• --lang ch：指定中文识别。
• --use_angle_cls True：开启方向分类器，自动检测图片中的文字是否旋转了 90 度、180 度之类的，有则纠正。默认是开启的，这里显式写出来是为了确认行为符合预期。

跑完会在终端输出一个列表，里面包含了识别出的每个文本框的坐标、置信度和文本内容。输出格式类似下面这样：

[ { "box": [[12, 34], [120, 34], [120, 68], [12, 68]], "rec_text": "收款人", "rec_score": 0.9824 } ]

这个输出结构非常关键，后面打包 Web 服务返回给前端时就是基于这个结构来设计的。

3.3 可视化测试与定位问题

命令行模式下可以在参数里加上可视化输出，把检测框画在原图上保存下来，直观确认检测效果：

paddleocr --image_dir ./test.jpg --lang ch --visualize --output_dir ./ocr_result

生成的图片会保存在./ocr_result目录下。我习惯把测试样本分成几类：印刷体截图、手机拍的纸质文档、倾斜角比较大的文本、行间距很小的表格。分别跑一轮，能很快看出模型在哪种场景下表现稳定，哪种场景下容易翻车，方便后面针对性优化。

3.4 测试阶段必须验证的三种场景

根据我的经验，至少要测以下三种典型输入：

第一，纯文字截图。这种是最理想的输入，背景干净，文字清晰。应该达到几乎 100% 的准确率，如果这里有问题，基本是环境或模型加载有问题，先排查环境。

第二，手机拍摄的纸质文档。有透视变形、光照不均、轻微模糊。这种情况主要看检测阶段能否把文字区域正确框出来，识别阶段能否抵抗边缘噪声。

第三，带复杂背景的图片。比如海报、包装盒照片。这种情况下检测模型可能会误把纹理识别成文字，需要我们后续在服务层加入置信度过滤、最小文本框过滤等策略。

命令行测试通过之后，才算真正具备了进入编码阶段的条件。

4. 封装识别核心服务：从命令行到函数调用

命令行工具适合测试，但不适合做服务。真正的识别逻辑需要封装成 Python 模块，这样才能被 Web 框架调用。这一节我讲一下封装思路和过程中容易忽略的细节。

4.1 核心封装代码

先看代码：

from paddleocr import PaddleOCR class OcrEngine: def __init__(self, use_gpu: bool = False, lang: str = "ch"): # use_gpu 传 False 时走 CPU 推理 # 实测 CPU 推理单张图片延迟在 1-3 秒左右 self.engine = PaddleOCR( use_angle_cls=True, lang=lang, show_log=False, use_gpu=use_gpu, ) # 方向分类器开关 self.use_angle_cls = True def predict(self, image_path: str) -> list: result = self.engine.ocr(image_path, cls=self.use_angle_cls) parsed = [] if not result: return parsed # 旧版 PaddleOCR 返回结构可能是 [line1, line2, ...] # 新版返回可能是 [[line1, line2, ...]] # 这里做一层兼容处理 lines = result[0] if result and isinstance(result[0], list) else result for line in lines: if line is None: continue box_info, text_info = line parsed.append({ "box": box_info, "text": text_info[0], "confidence": round(float(text_info[1]), 4), }) return parsed

这里有几个关键点要展开说。

4.2 核心参数选择与配置逻辑

参数方面，use_angle_cls默认可以开，但如果你处理的图片基本都是正向文字（比如截图、表格扫描件），方向分类器会增加额外推理耗时。我实测下来，开启方向分类器会让单张图片的推理时间增加 200-500 毫秒，这个开销在批量场景下不可忽视。所以如果业务场景中图片方向固定，建议把use_angle_cls关掉，明显提速。

lang参数不只是中文和英文的区别，PaddleOCR 还支持ch、en、japan、korean等多语言模型。如果业务里明确只要中文，就不用担心英文识别率，因为ch模型本身包含中英混排的识别能力。

4.3 结果解析的结构兼容问题

我在实际开发中发现一个问题：PaddleOCR 不同小版本之间返回的结果结构是有差异的。早期的版本直接返回一个列表，列表的每个元素是一个二元组(box, (text, confidence))；后期部分版本返回的是嵌套一层[result]的结构。

上面代码里那段isinstance(result[0], list)的兼容处理，就是为这个差异兜底的。建议在实际项目中写一个这样的容错逻辑，否则升级版本后接口很容易静默崩掉。

4.4 单例模式与重复加载问题

PaddleOCR 的初始化过程比较慢，因为需要加载三个模型（检测、分类、识别），CPU 环境下首次初始化可能需要 5-10 秒。这个时间不能省，但如果每次请求都重新初始化一次，服务几乎没法用。

解决办法是让 OcrEngine 实例全局复用，在 Flask 初始化时只创建一次。后面如果你的服务要支持多进程并发，每个进程都要有自己的实例，不能跨进程共享同一个模型对象。

4.5 图片预处理与识别率的隐藏关联

写接口时经常忽略图片预处理。实测下来有两个点对识别率影响最大：

一是图片尺寸。PaddleOCR 本身会做缩放处理，但超大图片（比如 5000px 以上的长图）在检测阶段耗时很长，而且小字区域容易被压缩丢失。我实践中的做法是限制最长边不超过 2000px，超过就等比缩放，识别率反而更稳定。

二是图片格式。很多用户上传的图片其实是带旋转信息的手机照片（EXIF 方向），直接喂给 OCR 引擎可能出现识别结果旋转 90 度或倒置的情况。更稳妥的做法是先统一转成 RGB 数组，并重置 EXIF 信息。可以用 Pillow 处理，这块在下一章的接口层会具体展示。

5. Flask Web 接口设计：文件上传、JSON 响应与错误码约定

封装好识别引擎之后，这一节就正式进入 Flask 服务搭建环节。Flask 本身很轻，但做 Web 接口时如果不提前约定好输入输出格式，后面联调会很痛苦。我把自己设计的接口规范完整列出来。

5.1 基础路由与启动入口

项目目录结构我建议这样组织，简单清晰：

ocr_service/ app.py ocr_engine.py requirements.txt uploads/

ocr_engine.py放上一章的识别引擎，app.py放 Flask 接口逻辑。下面是app.py的核心代码：

import os import uuid import logging from flask import Flask, request, jsonify from ocr_engine import OcrEngine app = Flask(__name__) # 限制上传最大 10MB，超过直接拒绝 app.config["MAX_CONTENT_LENGTH"] = 10 * 1024 * 1024 # 全局初始化 OCR 引擎，进程内复用 ocr_engine = OcrEngine(use_gpu=False, lang="ch") # 临时上传目录 UPLOAD_DIR = "./uploads" os.makedirs(UPLOAD_DIR, exist_ok=True) logger = logging.getLogger(__name__) @app.route("/health", methods=["GET"]) def health(): return jsonify({"code": 0, "message": "ok"}) @app.route("/api/ocr", methods=["POST"]) def ocr_api(): # 1. 检查是否有文件 if "file" not in request.files: return jsonify({"code": 1001, "message": "缺少 file 字段"}), 400 file = request.files["file"] if file.filename == "": return jsonify({"code": 1001, "message": "文件名为空"}), 400 # 2. 保存临时文件 ext = os.path.splitext(file.filename)[1].lower() if ext not in [".jpg", ".jpeg", ".png", ".bmp", ".webp"]: return jsonify({"code": 1002, "message": "不支持的图片格式"}), 400 tmp_path = os.path.join(UPLOAD_DIR, f"{uuid.uuid4().hex}{ext}") file.save(tmp_path) try: # 3. 调用 OCR 引擎 try: # 先做图像预处理，统一转换为 RGB 并重置 EXIF from PIL import Image, ImageOps img = Image.open(tmp_path) img = ImageOps.exif_transpose(img).convert("RGB") # 限制最长边 max_side = 2000 if max(img.size) > max_side: ratio = max_side / max(img.size) img = img.resize( (int(img.size[0] * ratio), int(img.size[1] * ratio)) ) processed_path = tmp_path + ".processed.png" img.save(processed_path) results = ocr_engine.predict(processed_path) except Exception as e: logger.exception("OCR 识别异常") return jsonify({"code": 1003, "message": f"识别失败: {str(e)}"}), 500 # 4. 组装结果，过滤低置信度 filtered = [r for r in results if r["confidence"] >= 0.5] return jsonify({ "code": 0, "message": "ok", "data": { "total": len(filtered), "items": filtered, } }), 200 finally: # 5. 清理临时文件 if os.path.exists(tmp_path): os.remove(tmp_path) if os.path.exists(processed_path): os.remove(processed_path) if __name__ == "__main__": # 开发环境专用，生产环境要用 waitress/gunicorn app.run(host="0.0.0.0", port=5000, debug=False)

5.2 接口设计规范说明

对接口这部分，我解释下每个设计决策背后的思路。

为什么用 POST 而非 GET？OCR 请求需要携带图片文件，属于典型的数据提交型操作，POST 是标准做法。GET 适合幂等查询，比如健康检查接口。

为什么用 multipart/form-data 而不是 base64 JSON？两点考虑：一是 multipart 上传是 Web 标准，前端和测试工具支持最广泛；二是 base64 会让请求体膨胀约 33%，大图片场景下性能和内存都不占优。

错误码怎么约定？我设计了三个层次：HTTP 状态码表示大类别（400 参数错、500 服务错），业务码（code 字段）表示具体原因，message 字段给出可读描述。200 和业务码 0 才是真正的成功。前端统一先看 code，再看 HTTP 状态码。

MAX_CONTENT_LENGTH 为什么设 10MB？不同业务的图片大小差异很大，10MB 算一个比较宽松的上限。实际经验中，超过 10MB 的图片在 OCR 之前大概率也需要压缩，直接拒绝能省掉大量无效计算。

临时文件的清理为什么放在 finally 里？识别过程中一旦抛异常，临时文件容易残留，时间久了会堆积大量垃圾文件。放 finally 里哪怕 OCR 异常也能保证清理。这个习惯帮我少运维了不少麻烦。

5.3 健康检查接口的重要性

/health接口看着多余，实际是服务部署后的必备项。不管是 Nginx 负载均衡的健康探测，还是容器编排系统的存活探针，都依赖这样一个不依赖外部资源、能快速响应的接口。它不查数据库、不调模型，只确认进程活着。

6. 服务部署的完整流程：本地跑通到后台常驻

本地 Flask 跑通只是第一步。真实部署环境要考虑三件事：怎么让服务进程常驻、怎么让外部能访问、怎么保证重启后自动拉起。

6.1 用 waitress 替代 Flask 自带的开发服务器

Flask 自带的app.run()启动的是开发服务器，单进程、单线程，性能有限，而且在并发请求下容易出现排队阻塞。生产环境下我用 waitress，它是一个纯 Python 的 WSGI 服务器，Windows 和 Linux 都能跑，安装简单。

pip install waitress

启动命令：

waitress-serve --host=0.0.0.0 --port=5000 --threads=4 app:app

几个参数的用意：

• --host=0.0.0.0：监听所有网络接口，这样外部才能访问。
• --port=5000：服务端口，按实际需求调整。
• --threads=4：线程数，我一般设为 CPU 核数的 2 倍左右。

如果只有 CPU 运算，waitress 的线程模式完全可以支撑中等规模的并发。我的模拟项目里，4 线程下 QPS 大约稳定在 1-2（每张图耗时 1-3 秒），对内部工具类服务够了。

6.2 模型离线迁移到服务器的正确姿势

开发机上模型已经下载好了，部署到生产服务器时，一个常见的坑是服务器要联网重新下载模型。如果你的服务器在内网环境，这个过程会直接卡死。

正确做法是：找到开发机上的模型缓存目录（一开始提到过的~/.paddlex或~/.paddleocr），把整个目录打包，上传到服务器对应位置解压。这样 PaddleOCR 在首次运行时检测到本地已有模型，就会直接加载，不再发起远程下载。

实测迁移过程中要注意目录权限问题。以 Linux 为例，如果服务运行在非 root 用户下，需要确保模型目录归属该用户或至少对进程用户有读取权限：

chmod -R 755 ~/.paddlex

6.3 用 systemd 实现进程常驻

个人项目或小团队内部服务，用一个 systemd 服务文件就能解决常驻、开机自启、崩溃自动重启的问题。下面是一个参考配置：

[Unit] Description=OCR Web Service After=network.target [Service] User=www-data WorkingDirectory=/path/to/ocr_service ExecStart=/path/to/venv/bin/waitress-serve --host=0.0.0.0 --port=5000 --threads=4 app:app Restart=always [Install] WantedBy=multi-user.target

需要注意的只有一点：ExecStart里的可执行文件一定要写虚拟环境里的绝对路径，不能只写waitress-serve，否则 systemd 启动时用的 PATH 可能找不到这个命令。

配置好后：

sudo systemctl daemon-reload sudo systemctl start ocr_service sudo systemctl enable ocr_service

6.4 Nginx 反向代理与端口访问

如果服务器上已经有 Nginx，我建议在前面加一层反向代理，把http://ocr.example.com/api/ocr代理到本地的 5000 端口。这样有几个好处：80/443 端口对外、可以统一加 SSL、可以更容易地做访问日志统计。

参考配置：

location /api/ocr { proxy_pass http://127.0.0.1:5000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_read_timeout 60s; client_max_body_size 20m; }

proxy_read_timeout之所以要设置 60s，是因为 OCR 对复杂图片的推理可能超过默认的 30s。如果超时时间太短，就会出现前端收到了请求但迟迟没等到响应的现象。client_max_body_size要覆盖到 Flask 层的文件大小限制。

7. 生产环境踩坑实录：三条最典型的错误排查链路

这个部分单独拎出来写，是因为这些坑严重到我一度以为代码写错了，最后发现全是环境或兼容性问题。完整记录排查思路，比直接给答案更有价值。

7.1 Windows 下缺 MSVC DLL 导致推理崩溃

现象：OCR 引擎初始化正常，但一跑推理程序就闪退，没有任何 Python 报错。

排查过程：刚开始以为是代码问题，单步调试发现崩在飞桨内部 C++ 调用处。搜索了半天，确定是 Windows 上缺了微软 Visual C++ 运行库。飞桨的底层二进制依赖这些 DLL，但安装时不会主动帮你装系统组件。

解决方案：去官方下载最新版 Visual C++ Redistributable 安装包，装完重启服务，问题消失。

经验：Windows 部署 Python 深度学习项目时，第一步先确认系统运行库，能少走很多弯路。

7.2 中文路径导致模型加载失败

现象：代码在 Linux 上一切正常，换到另一台机器后，PaddleOCR 初始化一直报找不到模型。

排查过程：新机器的系统语言设置为中文，用户目录变成了/home/用户/这种含中文的路径。模型实际下载到了这个目录，但我检查时发现路径打印出来的中文变成了乱码，模型加载逻辑无法匹配到正确的文件。

解决方案：把模型目录改到纯英文路径，比如/opt/ocr_models，并在代码中显式设置：

PaddleOCR(det_model_dir="/opt/ocr_models/det", rec_model_dir="/opt/ocr_models/rec", cls_model_dir="/opt/ocr_models/cls", lang="ch")

经验：在代码里显式指定模型路径，比依赖默认的缓存目录更可控。尤其是部署环境复杂的时候，显式配置永远比隐式约定更可靠。

7.3 并发请求下识别结果串台

现象：服务单独测试没问题，用并发工具一压，偶尔会出现识别结果和上传图片对不上，甚至返回空结果。

排查过程：开始以为是上传文件命名冲突。检查代码后发现，问题出在OcrEngine.engine这个全局对象上。PaddleOCR 的预测方法在内部有状态，不是线程安全的。Flask 用多线程处理请求时，两个线程同时调用同一个实例的predict方法，内部状态互相污染，结果就乱了。

解决方案：最简单的方案是给识别流程加一个全局锁，串行化识别调用。因为 CPU 推理本身就是瓶颈，加锁对整体吞吐影响不大：

import threading ocr_lock = threading.Lock() # 在调用 predict 处： with ocr_lock: results = ocr_engine.predict(processed_path)

经验：任何加载了深度学习模型的全局实例，在 Web 框架的多线程模型下使用前，都先确认底层是否线程安全。这个检查成本很低，但能避免一个非常隐蔽的生产事故。

8. 识别性能优化：从耗时分解到服务吞吐提升

部署稳定之后，接下来就是优化识别速度的问题。同样是 CPU 环境，同样的图片，不同配置下延迟能差出一倍多。这一章分享我做过的几项有效优化。

8.1 耗时结构分析

PaddleOCR 的三段式流水线每一步都有开销，实测下来一张 1500px 宽的普通文档图片在纯 CPU 上的耗时分布大概是：

了解耗时结构后，优化就有了重点。

8.2 关闭方向分类器的收益

如果业务场景中上传的图片基本都是正向文档，关闭方向分类器是最直接有效的减负手段：

PaddleOCR(use_angle_cls=False, lang="ch")

实测收益：单张图片耗时减少约 20%，识别准确率在正向文本场景下没有明显下降。这算是我做过性价比最高的一项优化。

8.3 限制图片大小与比例

限制最长边和分辨率是我反复强调的点。PaddleOCR 内部虽然会做缩放，但过大的原始图像在第一步图像缩放、归一化时就会有额外开销。我的做法是：对于 4000px 以上的超长截图，统一等比缩放到最长边 2000px，识别率几乎不受影响，耗时却能下降 50% 以上。

同时，对极窄长的图片（比如宽度不足 400px 的横幅文字图），先不缩放直接识别，效果可能更好，因为这类图片本身的文字信息就很少，缩放反而会让字形细节丢失。

8.4 结果缓存方案

如果服务里有大量重复图片请求（比如同一张发票被多次查询），在 OCR 上层加一层内容哈希缓存非常有用。以图片内容的 MD5 为 key，把识别结果缓存起来，二次请求直接命中缓存返回：

import hashlib cache_dict = {} def image_md5(image_bytes): return hashlib.md5(image_bytes).hexdigest() # 请求逻辑中： key = image_md5(file.read()) if key in cache_dict: return jsonify(cache_dict[key])

注意缓存要设定过期时间，避免长期占用内存。我这里用简单字典只是为了演示思路，生产环境建议换成带 TTL 的缓存方案。

8.5 其他一些零散但有用的优化点

批量识别场景下，PaddleOCR 本身支持传入批量图片路径，可以共享模型推理的初始化开销，比单张循环调用快很多。如果你的业务是一次请求传多张图，建议在接口层设计为批量模式，而不是多次调用 OCR 接口。

另外，如果服务器内存够大，加载模型后不要随意释放。模型常驻内存是让推理稳定的关键。

9. 上线后的持续运维与接口观测

服务上线不代表结束。这一章讲一下我在实际运维中建立的基础观测手段，对个人项目和小团队足够用，不用上重型监控系统。

9.1 日志规范：不仅仅记录异常

Flask 默认日志信息太少，我加了结构化日志，至少记录每次请求的处理耗时、识别图片大小、识别返回的文本条数、置信度分布。这些数据对评估模型效果和定位性能问题都有直接帮助。

import time # 在 ocr_api 中： start = time.time() results = ... elapsed = round(time.time() - start, 2) logger.info("ocr_finished elapsed=%ss lines=%d", elapsed, len(filtered))

线上跑一段时间后，统计这些日志就能得出服务耗时分布，判断是否需要优化。

9.2 识别失败与低置信度结果监控

只记录 500 错误是不够的。我在日志里额外记录了所有置信度低于阈值的结果，这类结果很可能就是模型识别错了但接口还返回了 200。定期检查这些低置信度样例，能比用户反馈更早地发现识别质量下降的问题。

9.3 模型文件完整性校验

某次维护中我意外发现模型目录里有个文件被误删，导致识别接口大面积报错。从那以后我加了一个启动自检脚本，在服务启动前校验模型文件是否存在、大小是否正常。这个检查虽然简单，但能避免一场"不知道为什么服务挂了"的长时间排查。

#!/bin/bash MODEL_DIR=/opt/ocr_models for f in det/inference.pdmodel rec/inference.pdmodel cls/inference.pdmodel; do if [ ! -f "$MODEL_DIR/$f" ]; then echo "缺少模型文件: $f" exit 1 fi done

我个人在做了这些基础的观测和维护工作之后，服务在很长一段时间内都没有再出现过让人措手不及的问题。OCR 的 Web 化部署本质上不难，核心是把每个环节的预期想清楚，把环境问题、模型问题、并发问题在编码阶段就消化掉，而不是留到线上再头痛。希望这篇完整记录能帮你减少一些盲目试错的时间。