离线 OCR · 涉密场景文字识别
适用场景
云端 OCR（各家 API）进不去的地方：涉密会议、课堂教学、工厂内网、律师/医疗材料。
数据不出本机是硬要求时，这是唯一路线。
技术选型（已实战验证的组合）
| 层 | 选择 | 理由 |
|---|---|---|
| 推理引擎 | RapidOCR 3.9.0（ONNXRuntime） | 纯 ONNX 链路，打包最干净；不拖 Paddle 重型框架 |
| 模型 | PP-OCRv5 起步，PP-OCRv6 已可升级 | v6 检测/识别精度较 v5 分别 +4.6% / +5.1%，统一模型覆盖 50 种语言；升级 = 换模型文件，推理与打包链路零改动 |
| 模型档位 | tiny（1.5M 参数）/ medium（34.5M 参数） | tiny 控体积，medium 保精度；建议默认 medium，双档做成配置项 |
| 模型来源 | modelscope（paddle/PP-OCRv6/rec/PP-OCRv6_rec_medium 等） |
国内直接拉取，不用翻墙 |
| 打包 | PyInstaller --onefile |
产出单个 exe，客户机零 Python 依赖 |
标准流程（照 scripts/build_offline_ocr.py 执行）
- 建隔离环境：
python -m venv .venv——不要在全局环境装包。 - 装依赖：
pip install rapidocr_onnxruntime pyinstaller（脚本会自动做）。 - 写最小 OCR 应用：脚本生成
ocr_app.py（命令行：ocr_app.exe <图片路径>输出识别文本）。 - 跑通再打包：先在开发机
python ocr_app.py test.png验证识别效果，确认满意后再进 PyInstaller——打包后调试成本翻倍。 - 打包：
pyinstaller --onefile --collect-all rapidocr_onnxruntime ocr_app.py（--collect-all是关键，把 ONNX 模型文件一起收进 exe）。 - 净机验证：拷到一台没装 Python 的 Windows 上跑——这是"免依赖"的唯一真实验证。
⚠️ 踩坑记录（已趟完）
| 坑 | 现象 | 解法 |
|---|---|---|
| 模型没打进 exe | 开发机能跑，净机报模型文件缺失 | pyinstaller --collect-all rapidocr_onnxruntime；或在 spec 文件 datas 里显式加模型目录 |
| 中文路径 | 图片路径含中文/空格时识别失败或闪退 | 读图用 np.fromfile(path, dtype=np.uint8) + cv2.imdecode，不用 cv2.imread（它走 ANSI） |
| 体积爆炸 | onefile 动辄几百 MB | 别装 paddlepaddle 全家桶；只用 rapidocr_onnxruntime；模型选 tiny/medium 档 |
| 首次启动慢 | onefile 解压到临时目录，首启 5-15s | 告知用户正常现象；或改 --onedir 分发目录 |
| 精度争议 | 用户说"识别不准" | 先确认是检测漏框还是识别错字；升级 PP-OCRv6（+5%）；截图类建议放大 2x 再识别 |
| 杀毒误报 | PyInstaller exe 被 360/ Defender 拦 | 加白名单说明文档；企业分发可做代码签名 |
精度/体积权衡建议
- 文档截图、扫描件：medium 档（默认）
- 嵌入式/分发体积敏感：tiny 档
- 拿不准：双档都打包，让用户自选——配置面只多一个参数
