# ocrv2 **Repository Path**: csxlin/ocrv2 ## Basic Information - **Project Name**: ocrv2 - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-07 - **Last Updated**: 2026-11-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 手写检验单识别系统 把手写检验单的照片/扫描件转成结构化数据:自动找到表格、逐行读出 **序号 + 缺陷等级 + 输入值**, 按规则过滤后输出 JSON 或 Excel;同时提供接口返回**整页泛用文字识别**(含坐标)。 全程本地推理,不联网、不调用云端 API、不需要 GPU。 > **一句话**:上传一张检验单照片,拿回「第几项、什么等级、填了什么」的 JSON,外加整页文字与坐标。 - 输入:手机拍摄或扫描仪扫描的整页检验单(jpg / png / bmp / webp) - 输出:JSON(HTTP 接口)、Excel(xlsx 下载) - 适合:固定版式的有线表格,手写内容是数字、勾、叉、简单汉字 - 不适合:复杂版式、无表格线、手写大段文字、需要 100% 免复核的场景 --- ## 目录 - [1. 效果示例](#1-效果示例) - [2. 环境要求](#2-环境要求) - [3. 安装](#3-安装) - [4. Windows 服务化部署](#4-windows-服务化部署) - [5. 启动与验证](#5-启动与验证) - [6. 接口一览](#6-接口一览) - [7. 表格解析接口 /ocrcsr](#7-表格解析接口-ocrcsr) - [8. 输出字段](#8-输出字段) - [9. 筛选规则](#9-筛选规则) - [10. 置信度怎么用](#10-置信度怎么用) - [11. 线程与并发自适应](#11-线程与并发自适应) - [12. 项目结构](#12-项目结构) - [13. 工作原理](#13-工作原理) - [14. 性能实测](#14-性能实测) - [15. 调参](#15-调参) - [16. 已知限制](#16-已知限制) - [17. 常见问题](#17-常见问题) - [18. 开发与测试](#18-开发与测试) --- ## 1. 效果示例 输入 `imgs/5.jpg`(双栏检验单,手机拍摄): ``` ┌────┬──────────┬──────────┬──────────┬────────┐ │序号│ 检验项目 │ 技术要求 │ 缺陷等级 │ 输入值 │ ├────┼──────────┼──────────┼──────────┼────────┤ │ 1 │ 外观检查 │ 无损伤 │ 合否 │ ✓ │ │ 2 │ 电流 │ ≤ 6mA │ 数值 │ 5.1 │ │ 3 │ 电压 │ 220V │ 数值 │ 3.8 │ └────┴──────────┴──────────┴──────────┴────────┘ ``` 输出(节选): ```json { "文件名": "12972.jpg", "识别行数": 16, "保留行数": 16, "结果": [ {"序号": 1, "缺陷等级": "合否", "输入值": "✓", "区域": "左", "置信度": 0.944, "来源": "ocr", "等级置信度": 0.785}, {"序号": 3, "缺陷等级": "数值", "输入值": "3.8", "区域": "左", "置信度": 0.959, "来源": "ocr", "等级置信度": 0.974} ] } ``` 同一张图多次运行的结果可能不完全一致(行定位对横线完整度敏感),示例文件仅用于说明**数据格式**, 不代表该图的逐项标准答案。实际使用请按 [第 10 节](#10-置信度怎么用) 设置复核策略。 --- ## 2. 环境要求 | 项目 | 要求 | 说明 | |------|------|------| | Python | 3.10 ~ 3.12,实测 3.12.7 | Windows / Linux 均验证 | | 操作系统 | Windows 10+、Linux | macOS 未验证 | | 内存 | ≥ 2 GB,建议 4 GB+ | 常驻约 700 MB ~ 1 GB,识别峰值更高 | | 磁盘 | ≥ 3 GB | 依赖约 1.5 GB,模型约 200 MB | | GPU | 不需要,也**不支持** | 纯 CPU 推理;PaddlePaddle GPU 版只支持 NVIDIA CUDA,AMD/Intel 核显不可用 | | 网络 | 仅首次安装需要 | 下载模型;之后可完全离线 | **不要用 `uvicorn --workers N`**:每个 worker 都会独立加载全套模型(约 1 GB),Windows 上还会报 `WinError 10022`。并发由 `OCR_CONCURRENCY` 控制,见 [第 11 节](#11-线程与并发自适应)。 --- ## 3. 安装 ### 3.1 Windows(推荐一键脚本) ```bat powershell -ExecutionPolicy Bypass -File .\setup.ps1 ``` 做三件事:建 `venv`、装依赖(默认清华源)、把模型预载到 `models\`(已有 `%USERPROFILE%\.paddlex` 会直接复用)。 可选参数: | 参数 | 说明 | |------|------| | `-PythonExe "C:\Python312\python.exe"` | 指定解释器 | | `-WheelsDir .\wheels` | 离线安装(`pip --no-index --find-links`) | | `-Mirror ` | 换 pip 源 | | `-SkipTest` | 跳过依赖自检 | 手动安装: ```bat python -m venv venv venv\Scripts\activate python -m pip install -U pip pip install -r requirements.txt ``` `paddlepaddle` 安装失败时,改用官方 CPU 源单独安装: ```bat pip install paddlepaddle -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ pip install paddleocr rapidocr onnxruntime fastapi uvicorn python-multipart opencv-python-headless numpy openpyxl ``` 若报 `DLL load failed while importing ...`,安装 [Microsoft Visual C++ 2015-2022 Redistributable (x64)](https://aka.ms/vs/17/release/vc_redist.x64.exe)。 ### 3.2 Linux ```bash python3 -m venv venv source venv/bin/activate python -m pip install -U pip pip install -r requirements.txt ``` 缺少系统库时(`libGL.so.1` 报错): ```bash sudo apt update && sudo apt install -y libgl1 libglib2.0-0 ``` ### 3.3 验证依赖 ```bash python -c "import cv2, numpy, paddle, paddleocr, rapidocr, fastapi; print('ok')" ``` --- ## 4. Windows 服务化部署 与旧版服务保持一致(WinSW 封装,服务名 `OCRService`,端口 8000),**全部脚本需管理员权限运行**: | 脚本 | 作用 | |------|------| | `setup.ps1` | 首次部署:venv + 依赖 + 模型预载 | | `install.bat` | 渲染 `OCRService.xml` → 停/卸旧服务 → 安装 → 启动 → 健康检查 | | `status.bat` | 服务状态、可执行路径、进程 PID、`/health` 响应 | | `uninstall.bat` | 停止并移除服务 | | `cleanup.ps1` | 清理 `venv` / `models` / `Logs` / `__pycache__`,`-Purge` 连产物一起删,`-Force` 免确认 | | `start-server.bat` | 前台运行(不注册服务) | 要点: - `OCRService.xml` 由 `OCRService.xml.tpl` + `render-config.ps1` 在安装时按当前目录生成,**换机器无需改路径**。 - 模型缓存固定在 `<项目>\models`(xml 中设置 `PADDLE_PDX_CACHE_HOME`),避免服务以 SYSTEM 身份运行时重复下载。 - 服务异常退出会自动重启(`onfailure action="restart" delay="10 sec"`),日志写到 `Logs\`。 - 迁移目录后重新执行 `install.bat` 即可,它会先卸旧服务再装新路径。 --- ## 5. 启动与验证 ### 5.1 启动 ```bat :: Windows,前台运行 start-server.bat :: 等价于 venv\Scripts\python.exe -m uvicorn main:app --host 0.0.0.0 --port 8000 ``` 首次启动日志会依次出现: ``` Creating model: ('UVDoc', None, None) Creating model: ('PP-OCRv5_server_rec', None, None) Creating model: ('PP-OCRv6_medium_det', None, None) Uvicorn running on http://0.0.0.0:8000 ``` 模型缓存位置: - Windows 服务 / `start-server.bat`:`<项目>\models\official_models` - 直接 `python main.py`:`~/.paddlex/official_models`(或 `%USERPROFILE%\.paddlex`) ### 5.2 验证 ```bash curl http://127.0.0.1:8000/health ``` ```json {"code":"0","msg":"","status":"ok","version":"1.3.0","engine":"PaddleOCR + OpenCV", "recognizer":"fast","lang":"ch","gpu":false, "cpus":8,"threads":4,"concurrency":1,"plate_models":true} ``` | 字段 | 含义 | |------|------| | `recognizer` | 表格引擎:`fast`(默认,`recognizer_fast.py`)/ `v2`(`recognizer.py`)/ `legacy`(前两者导入失败,回退到 `pipeline.FormRecognizer`) | | `cpus` / `threads` / `concurrency` | 逻辑核数 / 每实例线程数 / 同时处理的请求数 | | `plate_models` | 车牌模型文件是否就绪(`false` 时首次调 `/plate` 会尝试下载) | 浏览器打开 可直接点「Try it out」上传图片,不用写代码。 --- ## 6. 接口一览 分三组:通用文字识别(原服务能力)、车牌识别、检验单表格解析。 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/health` | 健康检查(引擎、核数/线程、车牌模型是否就绪) | | POST | `/ocr` | 通用文字识别,返回 `text` / `score` | | POST | `/ocr_box` | 通用文字识别,额外返回 `x` / `y` / `w` / `h` | | POST | `/plate` | 车牌识别 | | POST | `/ocrcsr` | 检验单表格解析(序号 / 缺陷等级 / 输入值),`uvdoc` 默认 true | | POST | `/ocrcsr/filtered` | 同上,只返回筛选后的 `结果` | | POST | `/ocrcsr/excel` | 同上,导出 xlsx(识别结果 / 全部行 两个 sheet) | 所有 POST 接口的图片字段名都是 `file`(form-data),大小上限 `OCR_MAX_MB`(默认 15 MB)。 车牌识别 < 1 秒;通用文字识别 12 ~ 27 秒;表格解析 20 ~ 26 秒。客户端超时建议:文字/车牌 30 秒,`/ocrcsr*` ≥ 600 秒。 ```powershell # 通用文字识别 curl.exe -X POST "http://127.0.0.1:8000/ocr" -F "file=@imgs/5.jpg" # 通用文字识别(含坐标) curl.exe -X POST "http://127.0.0.1:8000/ocr_box" -F "file=@imgs/5.jpg" # 车牌识别 curl.exe -X POST "http://127.0.0.1:8000/plate" -F "file=@car.jpg" # 表格解析(默认开启 UVDoc) curl.exe -X POST "http://127.0.0.1:8000/ocrcsr" -F "file=@imgs/5.jpg" --max-time 600 # 表格解析:关闭 UVDoc + 切标准引擎 curl.exe -X POST "http://127.0.0.1:8000/ocrcsr?uvdoc=false&engine=v2" -F "file=@imgs/5.jpg" --max-time 900 # 只返回筛选后的结果 / 导出 Excel curl.exe -X POST "http://127.0.0.1:8000/ocrcsr/filtered" -F "file=@imgs/5.jpg" --max-time 600 curl.exe -X POST "http://127.0.0.1:8000/ocrcsr/excel" -F "file=@imgs/5.jpg" --max-time 600 -o ocr_result.xlsx ``` > PowerShell 里必须写 `curl.exe`,裸 `curl` 是 `Invoke-WebRequest` 的别名,不认 `-X` / `-F`。 Python 调用: ```python import requests with open("test.jpg", "rb") as f: r = requests.post("http://127.0.0.1:8000/ocrcsr", files={"file": f}, timeout=600) r.raise_for_status() for row in r.json()["结果"]: print(row["序号"], row["缺陷等级"], row["输入值"], row["置信度"]) ``` C#(.NET 6+): ```csharp using System.Net.Http.Headers; using System.Text.Json; using var http = new HttpClient { Timeout = TimeSpan.FromMinutes(10) }; using var form = new MultipartFormDataContent(); await using var fs = File.OpenRead(@"C:\img\test.jpg"); var file = new StreamContent(fs); file.Headers.ContentType = new MediaTypeHeaderValue("image/jpeg"); form.Add(file, "file", "test.jpg"); var resp = await http.PostAsync("http://127.0.0.1:8000/ocrcsr", form); resp.EnsureSuccessStatusCode(); using var doc = JsonDocument.Parse(await resp.Content.ReadAsStringAsync()); foreach (var row in doc.RootElement.GetProperty("结果").EnumerateArray()) { Console.WriteLine($"{row.GetProperty("序号")} " + $"{row.GetProperty("缺陷等级")} " + $"{row.GetProperty("输入值")} " + $"{row.GetProperty("置信度")}"); } ``` > `MultipartFormDataContent` 和 `StreamContent` 只能用一次。若先调 `/ocrcsr` 再调 `/ocrcsr/excel`, > 必须重新打开文件、重新构造 form。 接口细节见 [docs/API.md](docs/API.md);`/ocrcsr` 的完整字段见[第 7 节](#7-表格解析接口-ocrcsr)。 --- ## 7. 表格解析接口 /ocrcsr 把检验单照片转成「序号 + 缺陷等级 + 输入值」的结构化结果。`/ocrcsr/filtered`、`/ocrcsr/excel` 是同一套参数的精简版与导出形态。 参数(三个接口通用): | 名称 | 位置 | 类型 | 默认 | 说明 | |------|------|------|------|------| | `file` | form-data | file | 必填 | 图片,大小上限 `OCR_MAX_MB`(默认 15 MB) | | `uvdoc` | query | bool | `true` | 是否先做 UVDoc 文档去扭曲(约 2 秒);弯折、卷曲、斜拍的件必开,平整扫描件可用 `false` 省时间;失败时自动按原图继续,结果里 `uvdoc=false` | | `engine` | query | string | `fast` | 表格引擎:`fast`(快速实现)/ `v2`(PaddleOCR 全流程) | 返回示例(节选,默认开启去扭曲的一次真实返回): ```json { "code": "0", "msg": "", "文件名": "12972.jpg", "uvdoc": true, "图像尺寸": [1919, 1080], "识别行数": 15, "保留行数": 15, "筛选规则": "序号(数字)+缺陷等级名称+输入值 三者齐全才保留", "置信度说明": "0~1;置信度为输入值判定置信度(来源=ocr 文字识别 / shape 形状判定),等级置信度为缺陷等级文字识别置信度", "结果": [ {"序号": 1, "缺陷等级": "合否", "输入值": "✓", "区域": "左", "置信度": 0.948, "来源": "ocr", "等级置信度": 0.78} ], "全部行": [ {"序号": 1, "缺陷等级": "合否", "输入值": "✓", "原文": "下1合否", "来源": "ocr", "y": [1457, 1497], "置信度": 0.948, "等级置信度": 0.78} ], "engine": {"table": "fast", "threads": 4, "concurrency": 1, "cpus": 8}, "表格耗时ms": 32415, "耗时ms": 47099, "elapsed_ms": 47099 } ``` `全部行` 的 `y` / `原文` 仅在该次运行有效,用于对回调试图。关闭去扭曲时 `uvdoc` 为 `false`,行数可能相差 1~2 行。 `/ocrcsr/filtered` 只回 `code`/`msg`/`文件名`/`uvdoc`/`筛选规则`/`置信度说明`/`保留行数`/`结果`/`耗时ms`。 错误返回(`code` 为字符串 `-1`,与旧服务一致): | HTTP | 场景 | |------|------| | 400 | 空文件 / 图片无法解码 | | 413 | 超过 `OCR_MAX_MB` | 说明: - 表格解析用 `recognizer_fast`(Paddle,进程内串行,共用常驻模型);`engine=v2` 时改用 `recognizer.py` 的 PaddleOCR 全流程。 - `/ocr`、`/ocr_box`、`/plate` 是纯文字/车牌识别,不做表格结构解析,通常 1 秒内返回。 --- ## 8. 输出字段 ### 8.1 `/ocr`、`/ocr_box`、`/plate` | 字段 | 类型 | 说明 | |------|------|------| | `code` | string | `"0"` 成功,`"-1"` 失败 | | `msg` | string | 错误信息,成功时为空 | | `count` | int | 行数 | | `elapsed_ms` | int | 识别耗时 | | `lines` | array | 每行 `text` + `score`;`/ocr_box` 额外有 `x` / `y` / `w` / `h`(外接矩形,像素) | ### 8.2 `/ocrcsr` | 字段 | 类型 | 说明 | |------|------|------| | `文件名` | string | 上传时的文件名 | | `图像尺寸` | [int, int] | 矫正后的 `[高, 宽]`,像素 | | `识别行数` | int | 入表行数(当前与 `保留行数` 相同,保留兼容字段) | | `保留行数` | int | 同上 | | `筛选规则` | string | 规则文字说明 | | `置信度说明` | string | 置信度含义说明 | | `结果` | array | 识别结果,见下表 | | `全部行` | array | 与 `结果` 同源,额外带 `原文` 与 `y`(行边界),用于追溯 | | `耗时ms` | int | 服务端处理耗时 | `结果` 每一行: | 字段 | 类型 | 取值 | 说明 | |------|------|------|------| | `序号` | int | 正整数 | 表格序号;纵向合并单元格会沿用上一行 | | `缺陷等级` | string | `合否` / `数值` / `外观` / `等级` | 印刷体等级名称 | | `输入值` | string | `✓` / `✗` / 数字 | 手写内容 | | `区域` | string | `左` / `右` | 双栏表格中的栏位 | | `置信度` | float | 0 ~ 1 | 输入值判定的置信度 | | `来源` | string | `ocr` / `shape` | 数值/勾叉来自文字识别,还是墨迹形状判定 | | `等级置信度` | float | 0 ~ 1 | 缺陷等级文字的 OCR 置信度 | `全部行` 额外字段: | 字段 | 说明 | |------|------| | `原文` | 该行「缺陷等级格」的原始 OCR 文本,如 `1合否`、`55合` | | `y` | `[上边界, 下边界]`,在原图(矫正后)中的像素坐标 | --- ## 9. 筛选规则 只保留 **`数字 + 缺陷等级名称 : 输入值`** 三要素齐全的行: | 原始行 | 是否保留 | 原因 | |--------|----------|------| | `1合否:✓` | ✅ | 三要素齐全 | | `2数值:5.1` | ✅ | 三要素齐全 | | `合否:✓` | ❌ | 缺序号(可能是表头或合并单元格) | | `数值:` | ❌ | 缺输入值 | | `完成情况:正常` | ❌ | 缺陷等级不在词表 `{合否, 数值, 外观, 等级}` 内 | 实现上就是三个条件全部成立: ```python 序号 is not None and 缺陷等级 in ("合否", "数值", "外观", "等级") and 输入值 != "" ``` > 若你的表格还有「判定」「结果」等其它等级名称,需要同步修改 `recognizer.py` / `recognizer_fast.py` > 顶部的 `VOCAB`,否则这些行会被丢弃。 --- ## 10. 置信度怎么用 `置信度` 是输入值的可信程度,`等级置信度` 是等级文字的可信程度。建议: | 区间 | 建议处理 | |------|----------| | `≥ 0.85` | 可直接采用,抽查即可 | | `0.60 ~ 0.85` | 人工核对后再入库 | | `< 0.60` | 必须人工核对 | 另外:`来源 = shape` 表示该值是靠墨迹形状判出来的(OCR 没读出文字), 勾/叉方向(✓ 还是 ✗)在连笔、涂改时容易判反,**建议全部复核**。 一个简单的入库策略: ```python for row in result["结果"]: if row["置信度"] < 0.85 or row["来源"] == "shape": row["需复核"] = True ``` --- ## 11. 线程与并发自适应 不同机器核数差别很大(本机 4 核 8 线程,生产 2×Xeon Gold 6330 = 56 核 112 线程),参数自动推导: | 变量 | 默认公式 | 4C8T | 56C112T | |------|----------|------|---------| | `OCR_THREADS` | `clamp(逻辑核 / 2, 2, 8)` | 4 | 8 | | `OCR_CONCURRENCY` | `clamp(逻辑核 / (线程 × 2), 1, 4)` | 1 | 4 | | `OCR_MAX_MB` | 15 | 15 | 15 | - `OCR_THREADS`:每个 Paddle 识别实例的线程数;快速实现左右两栏各一个实例,故实际占用约 `2 × OCR_THREADS`。 - `OCR_CONCURRENCY`:同时处理的 `/ocrcsr` 请求数;RapidOCR 每线程一个引擎,可并行;表格识别共用常驻模型,进程内串行(避免内存叠加)。 - 想手动固定,启动前设置环境变量即可: ```bat set OCR_THREADS=8 set OCR_CONCURRENCY=4 start-server.bat ``` Windows 服务要固定线程数:在 `OCRService.xml.tpl` 里加一行 ``,再执行一次 `install.bat`(会重新渲染配置并重启服务)。 --- ## 12. 项目结构 ``` ocrv2/ ├── main.py # FastAPI 服务:路由(/ocr、/ocr_box、/plate、/ocrcsr*)、Excel 导出 ├── combo.py # 通用文字识别(rapidocr)+ 表格解析 + UVDoc、线程自适应 ├── recognizer_fast.py # 快速实现(默认引擎):只跑识别模型 + 整列 batch ├── recognizer.py # 标准实现:PaddleOCR 全流程(列定位 → 行定位 → 逐格识别) ├── pipeline.py # 底层工具:预处理、OCR 封装、勾叉分类;含旧版 FormRecognizer ├── test_client.py # 命令行测试(HTTP / 离线) ├── requirements.txt # 依赖 ├── setup.ps1 # Windows 一键部署 ├── install.bat # 安装/更新 Windows 服务 ├── uninstall.bat # 卸载 Windows 服务 ├── status.bat # 服务状态 ├── start-server.bat # 前台运行 ├── cleanup.ps1 # 清理部署产物 ├── render-config.ps1 # 渲染 OCRService.xml ├── OCRService.exe # WinSW 服务封装 ├── OCRService.xml.tpl # 服务配置模板 ├── command.txt # 部署/调用速查 ├── docs/ # API.md / ALGORITHM.md / DEPLOY.md / 流程图 ├── imgs/ # 测试图片(5.jpg 为表格测试图) ├── venv/ # 虚拟环境(不入库) ├── models/ # 模型缓存(不入库) └── Logs/ # 服务日志(不入库) ``` 三个识别器: | 实现 | 入口 | 说明 | |------|------|------| | 快速(默认) | `recognizer_fast.recognize()` | 只调 TextRecognition 模型,整列拼 batch,不再逐格跑 UVDoc,明显快于标准实现 | | 标准 | `recognizer.recognize()` | PaddleOCR 全流程,含 UVDoc 去扭曲,逐格识别,更慢 | | 旧版兜底 | `pipeline.FormRecognizer.run()` | 前两者导入失败时自动启用 | --- ## 13. 工作原理 ![处理流程](docs/pipeline.png) 上图六个阶段里,只有 ⑤ 会调用 OCR 模型,前面全是几何运算: 1. **预处理**:找纸张四角 → 透视矫正 → 小角度纠偏 → 光照归一化二值化 2. **列定位**:多带采样做竖线检测并聚类,用「缺陷等级列 28~48px + 输入值列 40~64px」定位目标两列 3. **行定位**:在窄列带里投影找横线 → 吸附成等距网格 → 补上被手写盖住的线 4. **裁格**:行列交叉,只取「缺陷等级」和「输入值」两列 5. **逐格 OCR**:等级格向左多扩 38px 顺带读出序号;值格判数字或勾/叉 6. **筛选输出**:三要素齐全才保留 快速实现(`recognizer_fast.py`)把 ⑤ 换成「TextRecognition 单模型 + 整列 batch」, 并用横线定位后做 ±6px 局部对齐消除等距网格误差;不再每格跑 UVDoc,速度提升明显。 另有两条与本流程无关的通用通道:`/ocr`、`/ocr_box` 用 RapidOCR 做整页文字识别(ONNX,含坐标), `/plate` 用 hyperlpr3 做车牌识别,二者都不经过表格定位。 为什么不用 OCR 的文本框定位行列:PaddleOCR 3.x 的检测框存在系统性偏移(实测约 20~45px, 随版本变化),会把输入值列裁掉一半。表格线是本图里最稳定的几何特征。 详细设计、参数含义、踩过的坑见 [docs/ALGORITHM.md](docs/ALGORITHM.md)。 --- ## 14. 性能实测 测试机:AMD Ryzen 7 3700U(4 核 8 线程),`imgs/5.jpg`(双栏,整页约 60 个单元格)。 | 场景 | 耗时 | 说明 | |------|------|------| | `/ocr`(通用文字识别) | 12 ~ 27 s | 整页 312 行;首请求含引擎初始化 | | `/ocr_box`(含坐标) | 12 ~ 27 s | 同一引擎,仅多取外接矩形 | | `/plate`(无车牌图片) | < 1 s | 模型加载约 0.7 s,之后常驻 | | `/ocrcsr`(表格,默认 uvdoc=true) | 22 ~ 26 s | 15 结构化行;UVDoc 本身约 2 s | | `/ocrcsr?uvdoc=false` | 22 ~ 26 s | 16 结构化行;差异来自行定位波动,不是去扭曲更慢 | | `/ocrcsr?engine=v2`(标准实现) | 分钟级 | 含 UVDoc + 逐格重试 | | 表格模型默认 2 线程(离线跑) | 约 79 s | 线程不足,别用 | | 模型加载(首次请求) | 1 ~ 3 s | 之后常驻复用 | 耗时主要在逐格/整列 OCR,行数越少越快,不是固定值。多核服务器上主要靠 `OCR_THREADS` 与 `OCR_CONCURRENCY` 提升吞吐,单页耗时会明显下降,但**单页不可能做到秒级**。 快速实现的优化思路与测量数据见 [docs/SPEEDUP.md](docs/SPEEDUP.md)。 --- ## 15. 调参 改 `recognizer.py` / `recognizer_fast.py`,改完重启服务: | 想要的效果 | 改哪里 | 说明 | |------------|--------|------| | 适配新的列宽 | `find_columns()` 里的 `28~48`、`40~64` | 先用调试模式量出实际列宽再改 | | 横线检测更灵敏 | `hlines_of(..., thr=0.62)` 调低到 `0.50` | 斜拍、线条浅时用 | | 减少把文字当横线 | `thr` 调高到 `0.75` | 行数异常翻倍时用 | | 行网格更严格 | `fit_grid(..., tol=0.28)` 调低 | 漏行 / 错行时试 | | 序号读不出 | `recognize()` 里左扩 `dx0 - 38` 调大 | 序号列离等级列较远时 | | 数值识别率低 | `read_value()` 里 `up` 加到 `(8, 10)` | 代价是更慢 | | 支持新等级名称 | 顶部 `VOCAB` | 如加「判定」 | | 提升吞吐 | `OCR_THREADS` / `OCR_CONCURRENCY` | 见第 11 节 | --- ## 16. 已知限制 请务必了解以下边界,它们直接影响能不能上生产: 1. **行定位依赖表格横线**。手写笔画压住横线、拍摄倾斜大时,可能漏行、把两行并成一行, 或者同一张图两次运行结果不同。**关键数据必须保留人工复核。** 2. **序号列在快速实现下更容易读错**(出现过 `55`、`70` 这类值)。序号准确性优先时给 `/ocrcsr` 加 `?engine=v2`。 3. **带小数的手写数字可能丢位**(如 `5.1` 读成 `5`、`1`),数值行建议二次核对。 4. **勾/叉靠形状判定时可能判反**,尤其是连笔、涂改、打点式的勾。 5. **版式固定**:左右双栏、每栏 5 列。换版式要调整 `find_columns` 的宽度启发式, 不是改个参数就能通用。 6. **图像质量决定上限**:建议 ≥ 150 dpi、光线均匀、纸张平铺;手写字高 < 12px 时准确率明显下降。 7. **没有鉴权**:服务本身不校验身份,不要直接暴露在公网(见部署文档的安全章节)。 8. **独占端口 8000**,且表格识别进程内串行:并发高时排队,不会并行加速单页。 --- ## 17. 常见问题 **Q:启动报 `No module named 'paddle'`** 装到了系统 Python 而不是 venv。确认 `where python`(Linux `which python`)指向 `venv` 目录。 **Q:`pip install` 报 `SHFileOperationW failed` 或覆盖 `opencv`** `rapidocr`、`hyperlpr3` 都声明依赖 `opencv-python`,与已装的 `opencv-contrib-python` / `opencv-python-headless` 冲突。 改用:`pip install --no-deps rapidocr onnxruntime omegaconf hyperlpr3`,其余依赖已由 paddleocr 带入(`setup.ps1` 已自动这样处理)。 **Q:`/plate` 返回 503 车牌模型不可用** 确认 `pip install --no-deps hyperlpr3==0.1.3 loguru` 已装,且模型目录存在:`C:\Users\<用户>\.hyperlpr3\20230229\onnx`。 没有就把该目录从有网机器拷过来,或用 `HPLR_HOME` 指向模型所在位置;以服务(SYSTEM)身份运行时尤其要注意这一点。 **Q:本机装了代理,请求本地服务走代理报 `ProxyError`** 给客户端加白名单:`set NO_PROXY=127.0.0.1,localhost`(Linux `export no_proxy=...`)。 **Q:控制台打印 `✓` 报 `UnicodeEncodeError: 'gbk' codec ...`** Windows 控制台默认 GBK。加 `-X utf8` 或设置 `PYTHONIOENCODING=utf-8`;接口返回的 JSON 本身是 UTF-8。 **Q:首次启动卡住 / 下载很慢** 模型从官方源下载。内网机器按 [docs/DEPLOY.md](docs/DEPLOY.md) 的「离线部署」拷贝 `models\official_models`, 或直接把 `%USERPROFILE%\.paddlex\official_models` 复制到项目 `models\` 下。 **Q:请求 60 秒就断了** 客户端或反向代理超时。客户端 timeout 设 600~900 秒,Nginx `proxy_read_timeout` 设 900 秒。 **Q:返回 422** form-data 字段名不是 `file`,或者没带文件。 **Q:返回 400 无法解析图片** 文件损坏或不是图片;也可能是 HEIC 格式(需先转 jpg)。 **Q:Windows 服务启动失败 / 端口占用** 先 `status.bat` 看状态与路径,再查 `netstat -ano | findstr :8000`。若手工开过服务, 先结束占用进程或用 `uninstall.bat` 卸掉旧服务再 `install.bat`。 **Q:识别结果行数比实际多/少** 先看 `/ocr?debug=1` 的调试图,再按[第 15 节](#15-调参)调 `thr` 和 `tol`。 行数正好翻倍通常是横线阈值过低,把文字笔画当成了行线。 **Q:能不能识别其它表格** 可以,但要改列宽特征和等级词表。当前实现只认「窄等级列 + 输入值列」这一种组合。 **Q:能不能用 GPU** 不能。PaddlePaddle GPU 版只支持 NVIDIA CUDA;AMD/Intel 核显(含笔记本 APU)在 Windows 上无可用后端。 **Q:能不能批量** 接口一次一张。批量请在调用方循环/排队,不要加 `--workers`:每个进程都会独立加载整套模型。 --- ## 18. 开发与测试 ```bash # 命令行调用(服务已启动) python test_client.py imgs/5.jpg --out out.json # 不起服务,直接跑算法 python test_client.py imgs/5.jpg --offline # 表格解析直接跑(不含 HTTP) python -c "import cv2, combo; r = combo.table(cv2.imread('imgs/5.jpg'), 'a.jpg', uvdoc=True); print(r['保留行数'])" # 通用文字识别直接跑 python -c "import cv2, combo; print(len(combo.text_lines(cv2.imread('imgs/5.jpg'), boxes=False)))" ``` 环境变量: | 变量 | 默认 | 说明 | |------|------|------| | `OCR_LANG` | `ch` | 识别语言 | | `OCR_ENGINE` | `fast` | `/ocrcsr` 默认表格引擎(`fast` / `v2`) | | `OCR_THREADS` | 自动 | 每实例线程数 | | `OCR_CONCURRENCY` | 自动 | 并发请求数 | | `OCR_MAX_MB` | `15` | 所有接口的单图大小上限 | | `OCR_UVDOC_MODEL` | `UVDoc` | 去扭曲模型名 | | `PADDLE_PDX_CACHE_HOME` | `models/`(脚本内设置) | Paddle 模型缓存目录 | | `HPLR_HOME` | 用户目录或 `models/hyperlpr3` | 车牌模型目录(服务以 SYSTEM 运行时建议显式指定) | | `PORT` | `8000` | 端口(`python main.py` 时生效) | | `OCR_DEBUG_DIR` | 临时目录 | `?debug=1` 时调试图输出目录 | 生产部署见 [docs/DEPLOY.md](docs/DEPLOY.md),算法细节见 [docs/ALGORITHM.md](docs/ALGORITHM.md)。