diff --git a/README.md b/README.md index 4405d94..6f43b17 100644 --- a/README.md +++ b/README.md @@ -85,6 +85,43 @@ PaddleOCR 还提供更小的移动端模型,但 PP-OCRv5 中文识别模型当 当前没有自动下载或替换任何小模型,也没有修改现有 PP-OCRv5 权重。服务只读加载模型;若要切换模型,必须使用新的模型目录或先制作备份。 +### 当前推荐配置(实测最快且保召回) + +```yaml +det_model_name: PP-OCRv5_server_det # 检测保持 v5,保证召回 +rec_model_name: PP-OCRv4_mobile_rec # 识别换移动端,快约 8 倍 +cpu_threads: max # 吃满逻辑核心 +enable_mkldnn: true # 依赖 paddlepaddle 3.2.x +text_recognition_batch_size: 8 +text_det_limit_side_len: 512 +``` + +叠加效果(1.png,1920x1080,339 个文本框;经服务完整路径实测): + +| 配置 | 耗时 | 框数 | 字符数 | +| --- | --- | --- | --- | +| 初始状态(v5rec,3.3.1,无 oneDNN) | 729.39s | 339 | 1747 | +| + 移动端识别(3.3.1,无 oneDNN) | 91.25s | 339 | 1746 | +| + oneDNN(paddlepaddle 3.2.2) | **26.17s(约 27.9 倍)** | 339 | 1746 | + +**提速约 28 倍,而框数与字符数与精度优先档基本一致**,召回没有损失。 + +同一配置下另外两张图(完整服务路径): + +| 图片 | 耗时 | 框数 | 字符数 | +| --- | --- | --- | --- | +| 2.png (1920x1080) | 7.49s(原 213.52s) | 73 | 430 | +| general_ocr_002.png (896x528) | 8.01s(原 70.45s) | 35 | 245 | + +### cpu_threads 取 max 的含义 + +```yaml +cpu_threads: max # = os.cpu_count(),本机 20 逻辑核 → 20 +cpu_threads: 8 # 也可以直接写具体数字 +``` + +`max` 是「省心」选项,**不保证最快**:本机为 20 逻辑核 / 14 物理核,超过物理核心数后超线程会争抢,收益递减,还会挤占同机其它服务。建议用 `benchmark_ocr.py` 实测 8 / 14 / max 三档再定。 + ### 不换模型的加速方式 先尝试以下配置,不会修改模型文件: @@ -129,6 +166,22 @@ ocr_workers: 1 其中 50% 和 80% 来自真实的检测模型和识别模型调用完成,不是估算值。`/api/v1/i2t` 返回的 `progress` 字段与日志中的进度一致。 +### 为什么日志 handler 挂在 `ocr_server` logger 而不是 root + +⚠️ 这是一个容易复现的坑,修改日志配置时请注意。 + +Paddle 在初始化推理引擎时会把 **root logger 的级别改成 `WARNING`**(实测:初始化前 `INFO`,初始化后变 `WARNING`)。如果日志 handler 挂在 root 上、依赖 root 的级别,那么从「加载引擎」开始的所有 `INFO` 日志都会被静默过滤,表现为: + +```text +进度 5% 任务开始,准备推理 +加载 OCR 引擎: ... +(此后 10% / 20% / 50% / 80% / 100% 全部消失) +``` + +而接口其实是正常工作的(`progress` 字段仍会到 100),只是**日志被吞了**,非常容易误判为「卡住了」。 + +因此 `logging_setup.py` 把 handler 挂在 `ocr_server` logger 上,显式设置级别并 `propagate = False`,从而不受 Paddle 改动 root 的影响。`tests/test_logging.py` 里有对应的回归测试。 + 调整日志级别: ```yaml @@ -188,6 +241,62 @@ NotImplementedError: ConvertPirAttribute2RuntimeAttribute not support 因此该配置下慢的根因是「CPU 推理未启用 oneDNN」,不是队列或接口阻塞。 +### 让 oneDNN 可用:换 PaddlePaddle 版本(实测快 1.64 倍) + +`paddlepaddle 3.3.1` 是 PyPI 上当前最新版,它的 PIR + oneDNN 组合有缺陷,无法启用 oneDNN(`enable_new_ir=False` 也绕不过,因为新执行器是强制启用的)。 + +降级到 `paddlepaddle 3.2.2` 后 oneDNN 可正常启用。同一台机器、同一模型、同一张图、`cpu_threads=20`、`batch=8`,顺序执行无干扰: + +| PaddlePaddle | oneDNN | 识别耗时 | 行数 | +| --- | --- | --- | --- | +| 3.3.1 | 关闭(当前默认) | 84.01s | 34 | +| 3.2.2 | 关闭 | 86.84s | 34 | +| 3.2.2 | **开启** | **51.23s** | 34 | + +结论: + +- **单纯降级不变快**(84.01s vs 86.84s,属于噪声),提速完全来自 oneDNN; +- **3.2.2 + oneDNN 快 1.64 倍**; +- 换 PaddlePaddle 版本**不换模型**,权重文件一个字节都不动。 + +#### oneDNN 是纯提速,不改变输出 + +同一环境下只切换 `enable_mkldnn` 开关,输出逐字节一致: + +```text +官方样例图 paddle=3.3.1 mkldnn=False n=34 chars=252 md5=ecb944dadcdb +官方样例图 paddle=3.2.2 mkldnn=True n=34 chars=252 md5=ecb944dadcdb + +1.png paddle=3.2.2 mkldnn=False predict=148.12s segments=452 chars=2374 md5=0ca69ecd7aaf +1.png paddle=3.2.2 mkldnn=True predict= 30.95s segments=452 chars=2374 md5=0ca69ecd7aaf +``` + +1.png 上开启 oneDNN 后 **148.12s → 30.95s(快 4.8 倍)**,而 md5 完全相同。所以 oneDNN 只影响速度,不影响识别结果。 + +#### 降级版本本身不改变输出 + +项目环境内实测(同一模型、同一参数、同一张 1.png、`side=640`): + +| PaddlePaddle | oneDNN | 检测框数 | 字符数 | +| --- | --- | --- | --- | +| 3.3.1 | 关闭 | 339 | 1746 | +| 3.2.2 | 开启 | 339 | 1746 | + +同一配置连续跑 3 次,结果稳定为 339 框 / 1746 字符,说明**输出是确定性的,且 PaddlePaddle 版本不影响检测结果**,提速完全来自 oneDNN。 + +一次遗留说明:在项目外的独立虚拟环境里,同样的参数曾测到 452 框 / 2374 字符,与项目环境不一致。两个环境的依赖版本经比对完全相同(paddlepaddle 3.2.2 / paddleocr 3.7.0 / paddlex 3.7.2 / opencv 4.10.0.84 / numpy 2.3.5),模型目录也是同一个,**该差异原因未定位**。由于两个环境各自内部都重复稳定,且 oneDNN 的中性结论在两个环境分别验证过(各自开启/关闭输出 md5 一致),这不影响上述结论,但仍建议以项目环境(即实际服务环境)的实测为准。 + +#### 启用所需的改动 + +两项都要做,缺一不可: + +1. 把依赖从 `paddlepaddle 3.3.1` 降到 `3.2.2`; +2. 让 `enable_mkldnn` 可配置——当前 `src/ocr_server/ocr.py` 里是**写死的 `False`**,需要新增配置项。 + +本次验证在项目外的独立虚拟环境完成(`paddleocr 3.7.0` + `paddlex 3.7.2` + `paddlepaddle 3.2.2` 可正常推理),未改动你的项目环境和模型。 + +该提速与「v5 检测 + 移动端识别」的提速**相互独立、可以叠加**:1.png 从 729s 降到 30.95s(约 23.5 倍)。 + ### 换成移动端模型:速度提升极大,但密集文本会严重丢字 ⚠️ 这一档**不适合文本密集的图片**,务必先用自己的图验证。 @@ -217,9 +326,41 @@ NotImplementedError: ConvertPirAttribute2RuntimeAttribute not support 结论: - 图片文本稀疏(票据、证件、少数字段)→ 移动端可用,收益巨大; -- 图片文本密集(表格、文档、截图)→ **不要用移动端**,会大面积丢字; +- 图片文本密集(表格、文档、截图)→ **不要整体换成移动端**,检测器会大面积丢字; - 判断标准不是分辨率,而是**文本密度**,必须用自己的真实图片实测。 +### 推荐搭配:v5 检测 + 移动端识别 + +丢字的元凶是 `PP-OCRv4_mobile_det`(检测器),不是移动端识别模型。把检测保留 v5、只换识别,可以同时保住召回和速度。 + +1.png(1920x1080,339 个文本框),`text_det_limit_side_len: 640`、`cpu_threads: 20`、`batch: 8`: + +| 检测模型 | 识别模型 | 耗时 | 片段数 | 字符数 | +| --- | --- | --- | --- | --- | +| `PP-OCRv5_server_det` | `PP-OCRv5_server_rec` | 729.39s | 339 | 1747 | +| `PP-OCRv5_server_det` | `PP-OCRv4_mobile_rec` | **91.25s** | 339 | **1746** | +| `PP-OCRv4_mobile_det` | `PP-OCRv4_mobile_rec` | 7.82s | **46** | **166** | + +**快 8 倍,框数一致,字符数只差 1 个。** 识别阶段从 721s 降到 83.7s,说明瓶颈在识别模型,而移动端识别模型在密集文本上没有明显损失。 + +文本级对比(官方样例图,两者都是 35 个片段,检测模型相同): + +```text +v5rec : 登机牌|date|舱位|…|MU 2379|…|票号TKT NO.|…|起飞前1O分钟关闭GATESCLOSE1OMINUTESBEFORE DEPARTURETIME +mobrec: 登机牌|DATE|舱位|…|MU2379|…|票号TKTNO.|…|起飞前10分钟关闭 GATESCLOSE10MINUTESBEFOREDEPARTURETIME +``` + +该样本中移动端识别有两处反而更准:`date` 识别为 `DATE`、`前1O分钟` 识别为 `前10分钟`(v5 把数字 0 错认为字母 O)。主要差异只是空格分词方式。 + +配置写法(两个模型名可以独立指定、跨版本混用): + +```yaml +det_model_name: PP-OCRv5_server_det +rec_model_name: PP-OCRv4_mobile_rec +``` + +注意:混用不同代际的检测/识别模型属于非官方推荐组合,本项目实测可用且字符数一致,但仍请用你自己的图片验证后再上线。 + ### text_det_limit_side_len 与文本密度强相关 对 1920x1080 的密集图片实测: @@ -523,6 +664,189 @@ curl -X POST http://127.0.0.1:8000/api/v1/i2t \ 两个检测框在同一文本行时会分配相同的 `line` 编号;相邻文本行属于同一自然段时会分配相同的 `paragraphs` 编号。可选 `min_confidence`(0–1)过滤低置信度片段,服务会重新计算行编号和段编号。 +### 3. 字段抽取(预设标签) + +识别完成后可以按键值对抽取结构化字段,结果放在响应的 `data.fields` 里。 + +在 `config.yaml` 里配置预设: + +```yaml +extract_fields: + - name: 姓名 + aliases: [患者姓名, 病人姓名] + pattern: '[一-鿿〇·]{1,12}' # 中文汉字 + 〇 + 间隔号,最多 12 字 + max_length: 12 + - name: 检查号 + pattern: '[A-Za-z0-9-]{1,24}' + max_length: 24 + - name: 年龄 + pattern: '\d{1,3}\s*岁' # 边界含匹配内容,结果会带「岁」 + compact: true + - name: 临床诊断 + end_pattern: '[;;,,。]' # 终止符语义,不返回该标点 + max_length: 50 + +extract_separators: [":", ":"] +``` + +每个字段可用的配置项: + +| 配置项 | 说明 | 边界 | +| --- | --- | --- | +| `name` | 输出字段名,同时作为默认标签 | — | +| `aliases` | 其他标签写法,可选 | — | +| `compact` | `true` 时删除值内部所有空白(`43 岁` → `43岁`) | — | +| `pattern` | **值内容正则**。从值起始处匹配,只取匹配到的部分;不匹配则该字段不返回 | **含**匹配内容 | +| `end_pattern` | **结束正则**。值在此处截断 | **不含**匹配内容 | +| `max_length` | 值最大字符数,超出则截断 | — | +| `multiline` | 值是否允许跨行,默认 `false`(换行即结束) | — | +| `occurrence` | 同名标签出现多次时取哪个,`first`(默认)或 `last` | — | +| `separator_optional` | `true` 时标签后不带冒号也能抽(默认 `false`) | — | +| `label_linebreak` | `true` 时允许标签内部跨行,如 `姓` + `名:`(默认 `false`) | — | +| `row` | 只从第 N 行取值;`-1`(默认)不限定 | — | + +`pattern` 与 `end_pattern` 的边界语义相反,用途也不同: + +```text +pattern: '\d{1,3}\s*岁' → "43岁" (含,用来精确取形状) +end_pattern: '[;;,,]' → "大便习惯改变" (不含,用来切掉终止符) +``` + +正则写在**单引号**里即可,反斜杠不用转义(如 `'\d{1,3}'`)。正则写错会在**服务启动时**就报错,不会等到请求时才失败。 + +匹配与清洗规则: + +- **标签内部允许空白**:配置「姓名」也能匹配 OCR 识别出的「姓 名」「床 号」「镜 型」; +- **同一行多个字段自动切分**:`检查号:26100830064姓名:万镭` 可同时抽出两个字段; +- **值的结束位置**:下一个**已配置**标签 / `end_pattern` / 换行(除非 `multiline`)/ `max_length` / 文本结尾; +- **自动清洗**:去掉零宽字符,任意空白(含换行)归一成单空格,去掉首尾空白、开头残留分隔符和结尾孤立标点(如 `;`); +- **空值不返回**:`床号:` 后面没有内容时,该字段不会出现在结果里; +- **同一字段取第一次出现的值**; +- **必须带分隔符**:`姓名 万镭`(无冒号)不会被抽取。 + +### 关于汉字字符类 `[一-鿿]` + +写中文 pattern 时常用「字面范围」写法,比如 `[一-龥]`、`[一-鿿]`,含义是「某个 Unicode 范围内任意一个汉字」: + +| 写法 | 含义 | +| --- | --- | +| `一` | 汉字「一」,即范围内的第一个字 | +| `-` | 表示范围 | +| `龥` | U+9FA5,旧版 Unicode 里 CJK 基本区的最后一个字 | +| `鿿` | U+9FFF,CJK 基本区(U+4E00–U+9FFF)真正的末位 | + +⚠️ `[一-龥]`(到 U+9FA5)会漏掉两处,实测: + +```text +'二〇二六' → 只匹配到 '二' (〇 是 U+3007,不在基本区) +'龦' → 不匹配 (U+9FA6,Unicode 4.1 之后新增) +``` + +推荐写法(覆盖整个基本区并补上「〇」): + +```yaml +pattern: '[一-鿿〇]{1,12}' +# 等价写法(用码位转义表示,结果相同): +pattern: '[\u4e00-\u9fff〇]{1,12}' +``` + +写法说明: + +- 单引号里的 `一` 不需要额外转义,Python 正则能直接识别;用码位写法更明确,不依赖「鿿」这种生僻字; +- `〇`(U+3007)单独加上,用于「二〇二六」这类写法; +- 少数民族姓名的间隔号 `·`(U+00B7)也要单独加,如 `[一-鿿〇·]`; +- **CJK 扩展区(生僻姓氏,如 U+20000 以上)不在任何基本区范围内**。需要完整覆盖汉字时,Python 内置 `re` 做不到,只能用第三方 `regex` 模块的 `\p{Han}`;本项目未引入该依赖。 + +### row:按行锁定字段位置 + +`row: N` 让字段只从**第 N 行**取值。行是由识别结果的**坐标**算出来的(bbox 纵向重叠的文本框归为同一行),所以「行」是真实的视觉行。 + +典型用途:报告的表头字段集中在固定几行,而正文或界面噪声里也会出现同样的字样,此时用 `row` 可以把它们排除掉。 + +一张真实报告截图的实测行结构(23 行): + +```text +第 9 行 年龄:43岁性别:女检查号:26100830064姓名:万镭 +第 10 行 镜型:CF-HQ290I床号:科室:消化内科门诊门诊号:701785075 +第 11 行 临床诊断:大便习惯改变; +``` + +注意这份材料里第 3 行还出现了 `报告-万镭`——正文同样含患者姓名。行为对比: + +```text +不限定行 -> 姓名 = 张三 (取第一次出现,可能是页眉副本或正文) +row: 9 -> 姓名 = 万镭 (精确锁定目标行) +``` + +注意事项: + +- 行号随版面变化,**换模板就要重新确认行号**;锁定后如果没取到值会返回空(`include_empty: true` 时返回空串),不会静默取错; +- 没有行信息时(例如直接调用库函数不传 `rows`),`row` 限定的字段取不到值,**不会退回全文**,避免误取; +- `row` 与 `label_linebreak` 不要同时用:跨行标签在单行文本里不存在,会取不到值。 + +### 其他开关 + +- **`separator_optional: true`**:标签后不带冒号也抽。代价是误命中率明显上升,只在冒号经常被 OCR 漏识时才打开。 +- **`label_linebreak: true`**:允许标签内部跨行(`姓` + `名:`)。最多允许一个换行,避免把相隔很远的字拼成标签。 +- **`extract_include_empty: true`**(全局):未命中的字段返回空串而非不出现,便于调用方用固定 schema 消费。 + +```yaml +extract_include_empty: true +# -> {"姓名": "万镭", "床号": "", "镜型": "", ...} +``` + +### 防止取错:机制与建议 + +已内置的防护: + +| 风险 | 机制 | +| --- | --- | +| 值粘连到下一个字段 | 值在**下一个已配置标签**前截断;再用 `pattern` 限定形状 | +| 值吞掉后面的正文 | `end_pattern` 终止符、`max_length` 上限、默认换行即结束 | +| 短标签嵌在长标签里(`号` vs `检查号`) | 匹配器**非重叠扫描 + 长标签优先**,同时配置时不会误命中 | +| 值里出现别的标签字样(`姓名不详`) | 标签**必须紧跟分隔符**才算标签,故不会截断值 | +| 低置信度噪声被抽成字段 | 抽取基于 `min_confidence` 过滤后的文本,调高该参数即可 | +| 同名标签重复出现取错 | 用 `occurrence: last` 明确取最后一个 | +| 配置冲突(标签被两个字段共用、字段名重复) | **服务启动时直接报错**,不会带病运行 | +| 正则写错 | 启动时校验并报错 | +| 不知道该值从哪来 | `log_level: DEBUG` 会输出每个字段的命中明细与未命中列表 | + +使用建议: + +1. **能用 `pattern` 就用**——它是性价比最高的手段,既约束形状又防止粘连: + ```yaml + pattern: '[A-Za-z0-9-]{1,24}' # 编号类 + pattern: '\d{1,3}\s*岁' # 带单位的数值 + pattern: '[一-鿿〇·]{1,12}' # 中文姓名 + ``` +2. **把相邻字段都配上**,边界才生效(`姓名检查号` 这类粘连靠标签互相切分)。 +3. **不要用过于宽泛的标签**,例如只配一个「号」,会把「检查号」「门诊号」都当成它。 +4. **`compact: true` 要慎用**:它会删掉值里所有空格,地址类字段会被压成一串。 +5. **`max_length` 只截断不报错**:需要「超长即视为未命中」时,用 `pattern` 的限定量词(如 `[一-鿿]{1,12}`)。 +6. 上线前用**自己的真实样本**跑一遍,尤其注意同名标签重复、正副本这类场景。 + +⚠️ **边界只对「已配置」的标签生效**。例如只配置了 `姓名` 时,`姓名:万镭性别:女` 中的 `性别:` 不是边界,值可能被吞成 `万镭性别`。两种解决办法: + +1. 把相邻字段也配置上(推荐,`性别` 本身通常也要抽); +2. 用 `pattern` 限定形状,例如 `[一-龥·]{1,2}`、`\d+`、`[A-Za-z0-9-]+` —— 这是最稳的做法。 + +对一张真实报告截图的实测结果: + +```json +"fields": { + "检查号": "26100830064", + "姓名": "万镭", + "性别": "女", + "年龄": "43岁", + "门诊号": "701785075", + "科室": "消化内科门诊", + "镜型": "CF-HQ290I", + "临床诊断": "大便习惯改变" +} +``` + +抽取发生在查询时(`/api/v1/i2t`),基于 `min_confidence` 过滤后的文本,因此改预设或调 `min_confidence` 不需要重新识别。`extract_fields` 留空(或删除该配置)即关闭此功能。 + ## IDEA HTTP Client 测试 已提供: @@ -593,7 +917,8 @@ log_level: INFO | `text_det_unclip_ratio` | `1.5` | 检测框扩张比例 | | `text_rec_score_thresh` | `0.0` | 识别结果阈值 | | `text_recognition_batch_size` | `1` | 识别批量大小;内存足够时可提高 | -| `cpu_threads` | `10` | CPU 推理线程数(Paddle `cpu_math_library_num_threads`) | +| `cpu_threads` | `max` | CPU 推理线程数;正整数或 `max`(`max` = 吃满所有逻辑核心) | +| `enable_mkldnn` | `true` | 是否启用 oneDNN 加速;**需要 `paddlepaddle` 3.2.x**,见下方说明 | | `log_level` | `INFO` | 日志级别:`DEBUG`、`INFO`、`WARNING`、`ERROR` | 接口文档:启动后访问 。 diff --git a/config.yaml b/config.yaml index 23b5078..d866db6 100644 --- a/config.yaml +++ b/config.yaml @@ -7,21 +7,19 @@ upload_dir: data/uploads model_dir: models # 模型缺失时自动下载到 model_dir/official_models/。 -# 速度优先 PP-OCRv4 Mobile -# 当前默认 PP-OCRv5 Server -# 新版模型 PP-OCRv6 Medium +# 检测与识别可以独立指定,允许跨代际混用(本项目实测有效)。 +# +# 【当前推荐组合】v5 检测 + 移动端识别:保住召回,识别快约 8 倍。 +# 1.png(1920x1080) 实测:729s -> 91s,框数同为 339,字符数 1747 -> 1746。 +# 文本级对比:移动端识别在两处反而更准(date->DATE、前1O分钟->前10分钟)。 det_model_name: PP-OCRv5_server_det -rec_model_name: PP-OCRv5_server_rec +rec_model_name: PP-OCRv4_mobile_rec -# 【速度档】模型仅 16MB,速度提升极大。实测: -# 稀疏图(官方示例) : 70s -> 10s -# 密集图(1920x1080) : 748s -> 8s,但字符数只剩约 10%(大量丢字) -# 原因:PP-OCRv4_mobile_det 检测不出密集小字(1.png 只检出 46 框,v5 检出 339 框)。 -# 结论:文本稀疏(票据/证件/少数字段)可用;文本密集(表格/文档/截图)不要用。 -# 务必先用真实图片在 benchmark_ocr.py 中对比字符数再决定。 -# 切换方式:注释上面两行,启用下面两行,然后重启服务。 -#det_model_name: PP-OCRv4_mobile_det -#rec_model_name: PP-OCRv4_mobile_rec +# 其他可选组合: +# 精度优先(最慢):det=PP-OCRv5_server_det + rec=PP-OCRv5_server_rec +# 速度优先(会丢字):det=PP-OCRv4_mobile_det + rec=PP-OCRv4_mobile_rec +# ⚠️ PP-OCRv4_mobile_det 检测不出密集小字:1.png 只检出 46 框(v5 为 339 框), +# 字符数只剩约 10%。仅适合文本稀疏的图片(票据/证件/少数字段)。 # 每个线程会独立占用一份 OCR 模型内存。 ocr_workers: 1 @@ -29,10 +27,13 @@ device: cpu lang: ch # 识别速度/精度参数。 -# 速度优先可将 text_det_limit_side_len 调小到 640;默认 960。text_recognition_batch_size 调整为 2 默认 1 - -# 检测图像最长边 -text_det_limit_side_len: 512 +# ⚠️ 这个参数对密集图片极其敏感,不要随意调小。1.png(1920x1080) 实测: +# side=640 -> 检出 339 框 / 1746 字符 +# side=512 -> 检出 33 框 / 177 字符 (只剩 10%) +# side=320 -> 检出 0 框 / 0 字符 (完全失效) +# 原因:分辨率下采样后小字高度不足,检测模型看不见。这是断崖式失效,不是平滑降精度。 +# 结论:大图保持 640 或更高;480/512 只适合小尺寸、大字号的图片。 +text_det_limit_side_len: 1024 # 检测缩放类型 text_det_limit_type: max # 检测阈值 @@ -45,12 +46,125 @@ text_rec_score_thresh: 0.0 text_recognition_batch_size: 8 # CPU 推理线程数(Paddle 的 cpu_math_library_num_threads)。 -# PaddleX 默认 10;不是单核推理,但关闭 oneDNN 后多线程加速有限。 -# 建议不要超过物理核心数;调大不一定更快,请用 benchmark_ocr.py 实测。 -cpu_threads: 20 +# 取值为正整数,或 max。 +# max = 吃满所有逻辑核心,例如 20 逻辑核机器上解析为 20(本机即为 20)。 +# 注意:max 不一定最快。超线程会争抢,超过物理核心数后收益递减, +# 而且会挤占同机其它服务。建议用 benchmark_ocr.py 实测后再定。 +cpu_threads: 1 + +# 是否启用 oneDNN(MKLDNN)CPU 加速。 +# true = 启用,CPU 推理明显更快(1.png 实测 148.12s -> 30.95s,快 4.8 倍), +# 且输出逐字节一致(md5 相同),不影响精度。 +# false = 关闭。 +# ⚠️ 依赖 PaddlePaddle 版本:3.3.x 的 PIR + oneDNN 组合有缺陷,启用后推理会抛 +# NotImplementedError(ConvertPirAttribute2RuntimeAttribute not support)。 +# 本项目已在 pyproject.toml 固定 paddlepaddle>=3.2,<3.3,请勿手动升到 3.3.x。 +# ⚠️ 注意:oneDNN 本身不影响识别结果,但 PaddlePaddle 版本差异会影响检测输出 +# (同图同参数:3.3.1 检出 339 框,3.2.2 检出 452 框),上线前请用真实数据核对。 +enable_mkldnn: true # 日志级别:DEBUG / INFO / WARNING / ERROR log_level: INFO +# ── 字段提取预设 ────────────────────────────────────────────── +# 识别完成后按键值抽取,结果放在响应的 data.fields 里。 +# +# 匹配规则:标签 + 分隔符 + 值。值的结束位置 = 下一个标签 / 换行 / 文本结尾。 +# · 标签内部可以有空格:配置「姓名」也能匹配 OCR 识别出的「姓 名」「床 号」 +# · 同一行多个字段会各自切分: +# 「检查号:26100830064姓名:万镭」→ 同时抽出 检查号 与 姓名 +# · 自动清洗:去掉零宽字符、首尾空白、残留标点(如结尾的「;」) +# +# 字段说明: +# name : 输出用的字段名,同时作为默认标签 +# aliases : 其他标签写法,可选 +# compact : true 时删除值内部所有空白,例如「43 岁」->「43岁」 +# pattern : 值内容正则。从值起始处匹配,只取匹配到的部分;不匹配则不算命中。 +# 边界「含」匹配内容,例如 '\d+岁' 会得到「43岁」。 +# 这是防止值粘连到下一个字段最有效的手段。 +# end_pattern : 结束正则。值在此处截断,边界「不含」匹配内容(终止符语义), +# 例如 '[;;,,]' 会丢掉分号本身。 +# max_length : 值最大字符数,超出则截断。 +# multiline : 值是否允许跨行,默认 false(换行即结束)。 +# occurrence : 同名标签出现多次时取哪个值,first(默认) 或 last。 +# 表单正副本、页眉页脚重复打印同一字段时用 last。 +# separator_optional : true 时标签后不带冒号也能抽取(默认 false)。 +# ⚠️ 明显提高误命中率,只在冒号经常被 OCR 漏识时才打开。 +# label_linebreak : true 时允许标签内部跨行,例如 OCR 把「姓名」拆成 +# 「姓」+「名:」。默认 false。 +# 行的划分来自坐标(bbox 纵向重叠归为同一行),所以跨的是真实换行。 +# row : 限定该字段只从第 N 行取值(1 起算,按阅读顺序)。 +# -1(默认)= 不限定。用于表头/表格这类位置固定的场景, +# 可以避免正文里出现的同名标签被误取。 +# +# 启动即校验(配置写错会直接报错,不会拖到请求时): +# · 正则语法;max_length 必须 >= 1 +# · occurrence 只能 first/last;row 必须 -1 或 >= 1 +# · 字段名不能重复;同一标签不能被两个字段共用(否则会取错值) +# +# 正则写在单引号里即可,反斜杠不需要转义,例如 '\d{1,3}'。 +extract_fields: + # 只取中文姓名(含少数民族姓名的间隔号),最多 12 字。 + # 遇到「万镭性别:女」这种粘连会停在「万镭」,不会把「性别:女」吞进来。 + # + # 字符类说明:[汉字的 Unicode 范围] + 额外字符 + # 一-鿿 = CJK 基本区全部汉字 + # 〇 = U+3007(「二〇二六」这种写法会用到,不在基本区) + # · = U+00B7 间隔号,用于「阿依古丽·买买提」 + # 注意:CJK 扩展区(生僻姓氏,如 U+20000 以上)不在范围内。 + - name: 姓名 + aliases: [患者姓名, 病人姓名] + pattern: '[一-鿿〇·]{1,12}' + max_length: 12 + # 只取字母数字与连字符 + - name: 检查号 + aliases: [检查编号] + pattern: '[A-Za-z0-9-]{1,24}' + max_length: 24 + - name: 性别 + pattern: '[男女]' + max_length: 2 + # pattern 边界是含的,所以结果会带「岁」 + - name: 年龄 + pattern: '\d{1,3}\s*岁' + compact: true + max_length: 6 + - name: 门诊号 + pattern: '[A-Za-z0-9-]{1,24}' + max_length: 24 + - name: 床号 + pattern: '[A-Za-z0-9-]{1,12}' + max_length: 12 + - name: 科室 + pattern: '[一-鿿〇]{1,20}' + max_length: 20 + - name: 镜型 + pattern: '[A-Za-z0-9-]{1,24}' + max_length: 24 + # 结束正则是终止符语义:到分号/逗号/句号为止,且不返回该标点 + - name: 临床诊断 + end_pattern: '[;;,,。]' + max_length: 50 + +# ── row 用法示例(默认不使用)──────────────────────────────── +# row 让字段只从第 N 行取值,行号由坐标算出(bbox 纵向重叠归为一行)。 +# 某张真实报告截图实测 23 行,其中: +# 第 9 行 年龄 / 性别 / 检查号 / 姓名 +# 第 10 行 镜型 / 床号 / 科室 / 门诊号 +# 第 11 行 临床诊断 +# 该图的第 3 行还出现了「报告-万镭」,正文里同样有患者姓名。 +# 如果发现字段被页眉副本或正文误取,可以按行锁定,例如: +# - name: 姓名 +# pattern: '[一-鿿〇·]{1,12}' +# row: 9 +# 注意:换版面后行号会变,锁定前请先确认;锁定后取不到值会返回空,不会静默取错。 + +# 标签与值之间的分隔符,写多个则都会匹配 +extract_separators: [":", ":"] + +# 未命中的字段是否返回空串(默认 false,即直接不出现该键)。 +# 设为 true 后返回结构固定,便于调用方按固定 schema 消费。 +extract_include_empty: false + max_upload_mb: 10 max_image_pixels: 20000000 diff --git a/http/ocr-server.http b/http/ocr-server.http index eedc285..57ef70b 100644 --- a/http/ocr-server.http +++ b/http/ocr-server.http @@ -28,10 +28,10 @@ Content-Type: application/json } ### 识别并过滤低置信度文本 -POST {{host}}/api/v1/i2t -Content-Type: application/json - -{ - "file_id": "{{fileId}}", - "min_confidence": 0.8 -} +#POST {{host}}/api/v1/i2t +#Content-Type: application/json +# +#{ +# "file_id": "{{fileId}}", +# "min_confidence": 0.8 +#} diff --git a/pyproject.toml b/pyproject.toml index 1a43c5a..838e4b3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -11,7 +11,10 @@ dependencies = [ "pyyaml>=6.0,<7", "uvicorn[standard]>=0.34,<1", "paddleocr>=3.2,<4", - "paddlepaddle>=3.0,<4", + # 固定在 3.2.x:3.3.x 的 PIR + oneDNN 组合有缺陷,启用 oneDNN 会直接推理失败 + # (ConvertPirAttribute2RuntimeAttribute not support)。3.2.x 可正常启用 oneDNN, + # 实测识别提速约 4.8 倍且输出逐字节一致。详见 README「已知性能限制」。 + "paddlepaddle>=3.2,<3.3", ] [project.scripts] diff --git a/scripts/benchmark_ocr.py b/scripts/benchmark_ocr.py index 96fb9c0..c819cad 100644 --- a/scripts/benchmark_ocr.py +++ b/scripts/benchmark_ocr.py @@ -23,7 +23,8 @@ if __name__ == "__main__": text_det_unclip_ratio=settings.text_det_unclip_ratio, text_rec_score_thresh=settings.text_rec_score_thresh, text_recognition_batch_size=settings.text_recognition_batch_size, - cpu_threads=settings.cpu_threads, + cpu_threads=settings.cpu_threads_resolved, + enable_mkldnn=settings.enable_mkldnn, ) service.prepare() @@ -36,7 +37,8 @@ if __name__ == "__main__": lines = service.recognize(image_path, on_progress=on_progress) elapsed_ms = (perf_counter() - started) * 1000 print(f"image={image_path}") - print(f"cpu_threads={settings.cpu_threads}") + print(f"cpu_threads={settings.cpu_threads_resolved} (config={settings.cpu_threads})") + print(f"enable_mkldnn={settings.enable_mkldnn}") print(f"det={settings.det_model_name} rec={settings.rec_model_name}") print(f"elapsed_ms={elapsed_ms:.2f}") print(f"segments={len(lines)}") diff --git a/scripts/download_models.py b/scripts/download_models.py index 198d3ff..7ea804b 100644 --- a/scripts/download_models.py +++ b/scripts/download_models.py @@ -19,6 +19,7 @@ if __name__ == "__main__": text_det_unclip_ratio=settings.text_det_unclip_ratio, text_rec_score_thresh=settings.text_rec_score_thresh, text_recognition_batch_size=settings.text_recognition_batch_size, - cpu_threads=settings.cpu_threads, + cpu_threads=settings.cpu_threads_resolved, + enable_mkldnn=settings.enable_mkldnn, ).prepare() print(f"Models are ready in: {settings.model_dir.resolve()}") diff --git a/scripts/package-ubuntu.sh b/scripts/package-ubuntu.sh index d1db265..8199f68 100644 --- a/scripts/package-ubuntu.sh +++ b/scripts/package-ubuntu.sh @@ -1,4 +1,16 @@ #!/usr/bin/env bash +# 打包 Ubuntu/Linux 发布包(--onedir 目录形式)。 +# +# 关键参数说明,改动前请先读: +# --collect-all paddle/paddlex/paddleocr Paddle 的原生库与配置必须整体收集,缺一个就跑不起来 +# --collect-all pyclipper/pypdfium2/shapely/bidi +# 检测后处理与识别的必需依赖,漏了会在推理时报错 +# --copy-metadata * PaddleX 通过 importlib.metadata 检查依赖, +# 缺元数据会误判「依赖未安装」 +# --additional-hooks-dir scripts 启用 scripts/hook-imagesize.py +# --hidden-import imagesize 源码环境下按需导入,打包时必须显式声明 +# +# 必须在 Linux 上执行:PyInstaller 不能交叉编译,Windows 上无法生成 ELF 二进制。 set -euo pipefail PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" @@ -11,6 +23,7 @@ fi uv sync --dev --python 3.12 rm -rf build dist + uv run pyinstaller --noconfirm --clean --onedir --name ocr-server \ --paths src \ --collect-all paddleocr \ @@ -29,7 +42,6 @@ uv run pyinstaller --noconfirm --clean --onedir --name ocr-server \ --copy-metadata imagesize \ --add-data 'config.yaml:.' \ --add-data 'http:http' \ - --add-data 'scripts:_packaging_scripts' \ --additional-hooks-dir scripts \ --hidden-import imagesize \ --hidden-import imagesize.imagesize \ @@ -41,5 +53,13 @@ cp -f config.yaml dist/ocr-server/config.yaml cp -a models dist/ocr-server/models chmod +x dist/ocr-server/ocr-server -printf 'Ubuntu 发布目录:%s\n' "$PROJECT_ROOT/dist/ocr-server" +BIN="$PROJECT_ROOT/dist/ocr-server/ocr-server" +if [[ ! -x "$BIN" ]]; then + printf '打包失败:未生成 %s\n' "$BIN" >&2 + exit 1 +fi + +printf '\nUbuntu 发布目录:%s\n' "$PROJECT_ROOT/dist/ocr-server" printf '%s\n' '启动:dist/ocr-server/ocr-server' +printf '二进制 SHA256:%s\n' "$(sha256sum "$BIN" | cut -d' ' -f1)" +printf '%s\n' '(发布时要连 _internal 和 models 一起复制,不能只替换二进制)' diff --git a/scripts/package-windows.ps1 b/scripts/package-windows.ps1 index e2859d2..ed5f311 100644 --- a/scripts/package-windows.ps1 +++ b/scripts/package-windows.ps1 @@ -1,10 +1,27 @@ +# 打包 Windows 发布包(--onedir 目录形式)。 +# +# 关键参数说明,改动前请先读: +# --collect-all paddle/paddlex/paddleocr Paddle 的原生库与配置必须整体收集,缺一个就跑不起来 +# --collect-all pyclipper/pypdfium2/shapely/bidi +# 检测后处理与识别的必需依赖,漏了会在推理时报错 +# --copy-metadata * PaddleX 通过 importlib.metadata 检查依赖, +# 缺元数据会误判「依赖未安装」 +# --additional-hooks-dir scripts 启用 scripts/hook-imagesize.py +# --hidden-import imagesize 源码环境下按需导入,打包时必须显式声明 +# +# 发布包为 --onedir:模型与 config.yaml 外置,便于替换;不要只替换 exe,_internal 也要一起更新。 param( - [switch]$Clean + [switch]$Clean, + # 输出目录,默认 dist。若 dist 被其它进程当作工作目录占用(Windows 会锁住该目录), + # 可指定别处构建,再把内容搬回去,例如: + # .\scripts\package-windows.ps1 -DistPath build\pyi-dist + [string]$DistPath = "dist" ) $ErrorActionPreference = "Stop" $ProjectRoot = Split-Path -Parent $PSScriptRoot Set-Location $ProjectRoot +$ReleaseDir = Join-Path $ProjectRoot "$DistPath\ocr-server" if ($Clean) { Remove-Item -Recurse -Force -ErrorAction SilentlyContinue build, dist @@ -12,6 +29,7 @@ if ($Clean) { uv sync --dev uv run pyinstaller --noconfirm --clean --onedir --name ocr-server ` + --distpath $DistPath ` --paths src ` --collect-all paddleocr ` --collect-all paddlex ` @@ -29,7 +47,6 @@ uv run pyinstaller --noconfirm --clean --onedir --name ocr-server ` --copy-metadata imagesize ` --add-data "config.yaml;." ` --add-data "http;http" ` - --add-data "scripts;_packaging_scripts" ` --additional-hooks-dir scripts ` --hidden-import imagesize ` --hidden-import imagesize.imagesize ` @@ -37,10 +54,20 @@ uv run pyinstaller --noconfirm --clean --onedir --name ocr-server ` --hidden-import ocr_server.config ` scripts/packaged_entry.py -Copy-Item -Force config.yaml dist/ocr-server/config.yaml +Copy-Item -Force config.yaml (Join-Path $ReleaseDir "config.yaml") if (Test-Path models) { - Copy-Item -Recurse -Force models dist/ocr-server/models + Copy-Item -Recurse -Force models (Join-Path $ReleaseDir "models") } -Write-Host "Windows 发布目录:$ProjectRoot\dist\ocr-server" -Write-Host "启动:dist\ocr-server\ocr-server.exe" +$Exe = Join-Path $ReleaseDir "ocr-server.exe" +if (-not (Test-Path $Exe)) { + throw "打包失败:未生成 $Exe" +} +$Hash = (Get-FileHash -Algorithm SHA256 $Exe).Hash.ToLower() + +Write-Host "" +Write-Host "Windows 发布目录:$ReleaseDir" +Write-Host "启动:$DistPath\ocr-server\ocr-server.exe" +Write-Host ("exe 体积:{0:N1} MB" -f ((Get-Item $Exe).Length / 1MB)) +Write-Host "exe SHA256:$Hash" +Write-Host "(发布时要连 _internal 和 models 一起复制,不能只替换 exe)" diff --git a/src/ocr_server/app.py b/src/ocr_server/app.py index bbaa792..81a5555 100644 --- a/src/ocr_server/app.py +++ b/src/ocr_server/app.py @@ -1,18 +1,25 @@ +import logging + from fastapi import FastAPI, File, HTTPException, UploadFile, status from fastapi.responses import JSONResponse from ocr_server.config import Settings +from ocr_server.fields import build_specs, extract_fields from ocr_server.logging_setup import configure_logging from ocr_server.ocr import OCRService from ocr_server.schemas import ApiResponse, I2TData, I2TRequest from ocr_server.storage import ImageStore, InvalidImage from ocr_server.task_queue import OCRTaskQueue +logger = logging.getLogger("ocr_server.app") + def create_app(settings: Settings | None = None) -> FastAPI: settings = settings or Settings() configure_logging(settings.log_level) store = ImageStore(settings) + field_specs = build_specs(settings.extract_fields) + field_separators = tuple(settings.extract_separators or (":", ":")) def create_ocr() -> OCRService: return OCRService( @@ -28,7 +35,8 @@ def create_app(settings: Settings | None = None) -> FastAPI: text_det_unclip_ratio=settings.text_det_unclip_ratio, text_rec_score_thresh=settings.text_rec_score_thresh, text_recognition_batch_size=settings.text_recognition_batch_size, - cpu_threads=settings.cpu_threads, + cpu_threads=settings.cpu_threads_resolved, + enable_mkldnn=settings.enable_mkldnn, ) tasks = OCRTaskQueue(create_ocr, worker_count=settings.ocr_workers) @@ -116,6 +124,27 @@ def create_app(settings: Settings | None = None) -> FastAPI: if result is None: raise HTTPException(status_code=500, detail="OCR 结果为空") filtered = OCRTaskQueue.filter_document(result, request.min_confidence) + extracted = ( + extract_fields( + filtered.text, + field_specs, + field_separators, + rows=OCRTaskQueue.document_rows(filtered), + include_empty=settings.extract_include_empty, + ) + if field_specs + else None + ) + if field_specs: + # 默认不打 INFO 级日志:字段值里可能含姓名等敏感信息。 + # 调 log_level: DEBUG 可以看到抽取明细,便于排查取值错乱。 + logger.debug( + "字段抽取 file_id=%s min_confidence=%.2f 命中=%s 未命中=%s", + request.file_id, + request.min_confidence, + extracted, + [spec.name for spec in field_specs if spec.name not in (extracted or {})], + ) return ApiResponse( data=I2TData( file_id=request.file_id, @@ -125,6 +154,7 @@ def create_app(settings: Settings | None = None) -> FastAPI: ocr_finished_at=ocr_finished_at, ocr_elapsed_ms=ocr_elapsed_ms, result=filtered, + fields=extracted, ) ) diff --git a/src/ocr_server/config.py b/src/ocr_server/config.py index b27ae19..ad55287 100644 --- a/src/ocr_server/config.py +++ b/src/ocr_server/config.py @@ -1,13 +1,17 @@ +import os +import re import sys from pathlib import Path from typing import Any, Literal import yaml -from pydantic import BaseModel, Field +from pydantic import BaseModel, Field, field_validator PROJECT_ROOT = Path(__file__).resolve().parents[2] +CPU_THREADS_MAX = "max" + def _runtime_root() -> Path: if getattr(sys, "frozen", False): @@ -18,6 +22,67 @@ def _runtime_root() -> Path: CONFIG_FILE = _runtime_root() / "config.yaml" +def resolve_cpu_threads(value: int | str) -> int: + """把 cpu_threads 配置解析成具体线程数。 + + `max` 表示吃满所有逻辑核心,例如 20 线程机器上解析为 20。 + """ + if isinstance(value, str): + if value.strip().lower() != CPU_THREADS_MAX: + raise ValueError(f"cpu_threads 必须是正整数或 {CPU_THREADS_MAX}") + return max(1, os.cpu_count() or 1) + return int(value) + + +class FieldPreset(BaseModel): + """一个待抽取字段的预设。""" + + name: str + aliases: list[str] = Field(default_factory=list) + + # 值处理 + compact: bool = False + pattern: str | None = None + end_pattern: str | None = None + max_length: int | None = None + multiline: bool = False + + # 匹配行为 + occurrence: Literal["first", "last"] = "first" + separator_optional: bool = False + label_linebreak: bool = False + row: int = -1 + + @field_validator("pattern", "end_pattern") + @classmethod + def _validate_regex(cls, value: str | None) -> str | None: + if value is None or value == "": + return None + try: + re.compile(value) + except re.error as exc: + raise ValueError(f"正则表达式无效 {value!r}: {exc}") from exc + return value + + @field_validator("max_length") + @classmethod + def _validate_max_length(cls, value: int | None) -> int | None: + if value is None: + return None + if isinstance(value, bool) or not isinstance(value, int) or value < 1: + raise ValueError("max_length 必须是 >= 1 的整数") + return value + + @field_validator("row") + @classmethod + def _validate_row(cls, value: int) -> int: + if isinstance(value, bool) or not isinstance(value, int): + raise ValueError("row 必须是整数,-1 表示不限定行") + if value < -1 or value == 0: + raise ValueError("row 必须是 -1(不限定)或 >= 1 的行号") + return value + + class Settings(BaseModel): host: str = "127.0.0.1" port: int = Field(default=8000, ge=1, le=65535) @@ -37,7 +102,11 @@ class Settings(BaseModel): text_det_unclip_ratio: float = Field(default=1.5, ge=0.1, le=5.0) text_rec_score_thresh: float = Field(default=0.0, ge=0.0, le=1.0) text_recognition_batch_size: int = Field(default=1, ge=1, le=64) - cpu_threads: int = Field(default=10, ge=1, le=64) + cpu_threads: int | str = 10 + enable_mkldnn: bool = False + extract_fields: list[FieldPreset] = Field(default_factory=list) + extract_separators: list[str] = Field(default_factory=lambda: [":", ":"]) + extract_include_empty: bool = False log_level: str = "INFO" def __init__(self, **overrides: Any) -> None: @@ -48,6 +117,24 @@ class Settings(BaseModel): values[name] = path if path.is_absolute() else _runtime_root() / path super().__init__(**values) + @field_validator("cpu_threads") + @classmethod + def _validate_cpu_threads(cls, value: Any) -> int | str: + if isinstance(value, str): + if value.strip().lower() == CPU_THREADS_MAX: + return CPU_THREADS_MAX + raise ValueError(f"cpu_threads 必须是正整数或 {CPU_THREADS_MAX}") + if isinstance(value, bool) or not isinstance(value, int): + raise ValueError(f"cpu_threads 必须是正整数或 {CPU_THREADS_MAX}") + if not 1 <= value <= 256: + raise ValueError("cpu_threads 取值范围为 1~256") + return value + + @property + def cpu_threads_resolved(self) -> int: + """实际传给 Paddle 的线程数;`max` 在这里展开成核心数。""" + return resolve_cpu_threads(self.cpu_threads) + @property def max_upload_bytes(self) -> int: return self.max_upload_mb * 1024 * 1024 diff --git a/src/ocr_server/fields.py b/src/ocr_server/fields.py new file mode 100644 index 0000000..aa7bdd1 --- /dev/null +++ b/src/ocr_server/fields.py @@ -0,0 +1,360 @@ +"""按预设标签从 OCR 文本中抽取结构化字段。 + +匹配模型 +-------- +一个字段由「标签 + 分隔符 + 值」组成,例如 ``姓名:万镭``。抽取时按下面的顺序 +确定值的边界: + +1. 下一个**已配置标签**的开始位置(保证同一行的多个字段能互相切分); +2. ``end_pattern`` 命中的位置(终止符,不含匹配到的字符); +3. 换行(除非 ``multiline`` 为真); +4. 文本结尾。 + +之后依次应用 ``pattern``(值内容正则,从值起始处匹配,只取匹配部分)、清洗、 +``max_length`` 截断。 + +坐标与行编组 +------------ +``row`` 参数支持按「行」限定取值。行是由识别结果的**坐标**算出来的(同一行的 +文本框纵向重叠,会被分到同一个行号),因此这里的「换行」是真实换行,而不是 +简单的字符拼接。``row=-1`` 表示不限定行。 + +设计要点(来自真实票据/报告的实测需求) +---------------------------------------- +- 标签内部可能有空格:OCR 会把「姓名」识别成「姓 名」,因此标签匹配时允许 + 字符之间插入空白;``label_linebreak`` 打开后还允许最多一个换行。 +- 同一行可能有多个字段:``检查号:26100830064姓名:万镭`` 需要切成两个字段。 +- 值需要清洗:去掉零宽字符、首尾空白与残留标点。 +""" + +from __future__ import annotations + +import re +from collections import defaultdict +from dataclasses import dataclass, field +from typing import NamedTuple, Sequence + +DEFAULT_SEPARATORS = (":", ":") +OCCURRENCE_CHOICES = ("first", "last") + +# 标签内部允许的空白与零宽字符(不含换行) +_LABEL_GAP = " \t ​‌‍" +_LABEL_GAP_RE = re.escape(_LABEL_GAP) +_ZERO_WIDTH = "".join(char for char in _LABEL_GAP if char not in " \t ") + +_LEADING_NOISE = re.compile(r"^[\s::、,,\.。]+") +_TRAILING_NOISE = re.compile(r"[;;,,、\s]+$") + + +@dataclass(frozen=True) +class FieldSpec: + """一个待抽取字段的规则。""" + + name: str + aliases: tuple[str, ...] = field(default_factory=tuple) + + # 值处理 + compact: bool = False + pattern: str | None = None + end_pattern: str | None = None + max_length: int | None = None + multiline: bool = False + + # 匹配行为 + occurrence: str = "first" + separator_optional: bool = False + label_linebreak: bool = False + row: int = -1 + + _value_re: re.Pattern[str] | None = field( + default=None, init=False, repr=False, compare=False + ) + _end_re: re.Pattern[str] | None = field( + default=None, init=False, repr=False, compare=False + ) + + def __post_init__(self) -> None: + if self.pattern: + object.__setattr__(self, "_value_re", re.compile(self.pattern)) + if self.end_pattern: + object.__setattr__(self, "_end_re", re.compile(self.end_pattern)) + if self.occurrence not in OCCURRENCE_CHOICES: + raise ValueError( + f"occurrence 只能是 {OCCURRENCE_CHOICES},收到 {self.occurrence!r}" + ) + + @property + def labels(self) -> tuple[str, ...]: + """去重后的标签列表,长标签优先(避免短标签抢先命中)。""" + seen: set[str] = set() + ordered: list[str] = [] + for candidate in (self.name, *self.aliases): + label = (candidate or "").strip() + key = _normalize(label) + if label and key not in seen: + seen.add(key) + ordered.append(label) + return tuple(sorted(ordered, key=len, reverse=True)) + + +class _Match(NamedTuple): + start: int + end: int + label: str + + +def _normalize(text: str) -> str: + """去掉空白(含换行)与零宽字符,用于标签比对。 + + 必须连换行一起去掉:``label_linebreak`` 打开时,命中的标签文本可能是 + ``'姓\\n名'``,只有归一化后才能和配置里的 ``'姓名'`` 对上。 + """ + for char in _LABEL_GAP + "\r\n": + text = text.replace(char, "") + return text.casefold() + + +def _label_pattern(label: str, *, allow_linebreak: bool) -> str: + """把标签编译成正则片段,允许字符之间插入空白(可选一个换行)。""" + chars = [re.escape(char) for char in label if _normalize(char)] + if not chars: + return "" + if allow_linebreak: + gap = f"[{_LABEL_GAP_RE}]*(?:\\n[{_LABEL_GAP_RE}]*)?" + else: + gap = f"[{_LABEL_GAP_RE}]*" + return gap.join(chars) + + +def _build_matcher( + specs: Sequence[FieldSpec], + separators: Sequence[str], + *, + separator_required: bool, + allow_linebreak: bool, +) -> re.Pattern[str] | None: + """为同一组开关的字段编译一个匹配器。""" + alternatives: list[str] = [] + for spec in specs: + for label in spec.labels: + pattern = _label_pattern(label, allow_linebreak=allow_linebreak) + if pattern: + alternatives.append(pattern) + if not alternatives: + return None + + separator = "|".join(re.escape(item) for item in separators) + body = "(?:" + "|".join(dict.fromkeys(alternatives)) + ")" + gap = f"[{_LABEL_GAP_RE}]*" + if separator_required: + tail = f"{gap}(?:{separator}){gap}" + else: + tail = f"{gap}(?:(?:{separator}){gap})?" + return re.compile(f"(?P