diff --git a/README.md b/README.md index 491886d..44859c0 100644 --- a/README.md +++ b/README.md @@ -162,26 +162,26 @@ ocr_workers: 1 ```text 2026-10-12 10:00:00 INFO [ocr_server.task] file_id=xxx 已加入 OCR 队列 image=1.png 2026-10-12 10:00:01 INFO [ocr_server.task] file_id=xxx 开始处理 image=1.png -2026-10-12 10:00:01 INFO [ocr_server.task] file_id=xxx 进度 5% 任务开始,准备推理 +2026-10-12 10:00:01 INFO [ocr_server.task] file_id=xxx 进度 5% 任务开始 2026-10-12 10:00:02 INFO [ocr_server.ocr] OCR 引擎加载完成 -2026-10-12 10:00:02 INFO [ocr_server.task] file_id=xxx 进度 10% 模型已就绪 -2026-10-12 10:00:02 INFO [ocr_server.task] file_id=xxx 进度 20% 图片已解码,开始文字检测 -2026-10-12 10:00:40 INFO [ocr_server.task] file_id=xxx 进度 50% 文字检测完成 -2026-10-12 10:01:35 INFO [ocr_server.task] file_id=xxx 进度 80% 文字识别完成 -2026-10-12 10:01:35 INFO [ocr_server.task] file_id=xxx 进度 100% 识别完成 +2026-10-12 10:00:02 INFO [ocr_server.task] file_id=xxx 进度 10% 模型就绪 +2026-10-12 10:00:02 INFO [ocr_server.task] file_id=xxx 进度 20% 图片就绪 +2026-10-12 10:00:40 INFO [ocr_server.task] file_id=xxx 进度 50% 框识别完成 +2026-10-12 10:01:35 INFO [ocr_server.task] file_id=xxx 进度 80% 文本识别完成 +2026-10-12 10:01:35 INFO [ocr_server.task] file_id=xxx 进度 100% 完成 2026-10-12 10:01:35 INFO [ocr_server.task] file_id=xxx 处理结束 status=completed elapsed=94000.00ms ``` 进度含义: -| 进度 | 含义 | -| --- | --- | -| 5% | 工作线程取到任务,准备推理 | -| 10% | OCR 引擎就绪(首次包含模型加载时间) | -| 20% | 图片已解码,开始文字检测 | -| 50% | 文字检测完成 | -| 80% | 文字识别完成 | -| 100% | 结果组装完成,任务结束 | +| 进度 | 关键点 | 含义 | +| --- | --- | --- | +| 5% | 任务开始 | 工作线程取到任务,准备推理 | +| 10% | 模型就绪 | OCR 引擎就绪(首次包含模型加载时间) | +| 20% | 图片就绪 | 图片已解码,进入检测 | +| 50% | 框识别完成 | 文本框检测完成 | +| 80% | 文本识别完成 | 文本框内容识别完成 | +| 100% | 完成 | 结果组装完成,任务结束 | 其中 50% 和 80% 来自真实的检测模型和识别模型调用完成,不是估算值。`/api/v1/i2t` 返回的 `progress` 字段与日志中的进度一致。 @@ -192,7 +192,7 @@ ocr_workers: 1 Paddle 在初始化推理引擎时会把 **root logger 的级别改成 `WARNING`**(实测:初始化前 `INFO`,初始化后变 `WARNING`)。如果日志 handler 挂在 root 上、依赖 root 的级别,那么从「加载引擎」开始的所有 `INFO` 日志都会被静默过滤,表现为: ```text -进度 5% 任务开始,准备推理 +进度 5% 任务开始 加载 OCR 引擎: ... (此后 10% / 20% / 50% / 80% / 100% 全部消失) ``` @@ -590,6 +590,47 @@ Windows 不能直接生成 Ubuntu ELF 二进制。`package-ubuntu.sh` 必须在 GPU 部署不使用当前 CPU 依赖作为判断依据,请按照 PaddlePaddle 官方文档安装与 CUDA、cuDNN、驱动匹配的 GPU 版本,然后再安装本项目依赖。 +## 文本框开关:return_word_box + +配置: + +```yaml +return_word_box: false +``` + +默认 `false`:每个 `polygon.textN` 只返回该文本片段的整体 `Location`,速度更快、JSON 更小。 + +开启: + +```yaml +return_word_box: true +``` + +识别结果中每个文本片段会增加 `words`: + +```json +{ + "text1": { + "text": "检查号:26100830064", + "confidence": 0.99, + "Location": { + "xtop": 0, + "ytop": 0, + "xbottom": 300, + "ybottom": 30 + }, + "line": 1, + "paragraphs": 1, + "words": [ + [[0, 0], [60, 0], [60, 30], [0, 30]], + [[60, 0], [120, 0], [120, 30], [60, 30]] + ] + } +} +``` + +`words` 是按 PaddleOCR 返回的字/词级四点 polygon 数组,顺序与识别文本对应。开启后会增加识别耗时与响应体积,只有需要逐字定位时才建议打开;整体文本框 `Location` 无论开关都保留。 + ## API ### 1. 上传图片 @@ -938,6 +979,7 @@ log_level: INFO | `text_recognition_batch_size` | `1` | 识别批量大小;内存足够时可提高 | | `cpu_threads` | `max` | CPU 推理线程数;正整数或 `max`(`max` = 吃满所有逻辑核心) | | `enable_mkldnn` | `true` | 是否启用 oneDNN 加速;**需要 `paddlepaddle` 3.2.x**,见下方说明 | +| `return_word_box` | `false` | 是否返回文本片段内部的字/词级 polygon(会增加耗时和 JSON 体积) | | `log_level` | `INFO` | 日志级别:`DEBUG`、`INFO`、`WARNING`、`ERROR` | 接口文档:启动后访问 。 diff --git a/config.yaml b/config.yaml index d866db6..16fdc28 100644 --- a/config.yaml +++ b/config.yaml @@ -52,6 +52,11 @@ text_recognition_batch_size: 8 # 而且会挤占同机其它服务。建议用 benchmark_ocr.py 实测后再定。 cpu_threads: 1 +# 是否返回每个识别文本框内部的字/词级 polygon。 +# false:默认,只返回行/文本片段框,速度更快、JSON 更小。 +# true :在 data.result.polygon.textN.words 中返回字/词级四点坐标,会增加耗时和响应体积。 +return_word_box: false + # 是否启用 oneDNN(MKLDNN)CPU 加速。 # true = 启用,CPU 推理明显更快(1.png 实测 148.12s -> 30.95s,快 4.8 倍), # 且输出逐字节一致(md5 相同),不影响精度。 diff --git a/scripts/benchmark_ocr.py b/scripts/benchmark_ocr.py index c819cad..9b49af3 100644 --- a/scripts/benchmark_ocr.py +++ b/scripts/benchmark_ocr.py @@ -25,6 +25,7 @@ if __name__ == "__main__": text_recognition_batch_size=settings.text_recognition_batch_size, cpu_threads=settings.cpu_threads_resolved, enable_mkldnn=settings.enable_mkldnn, + return_word_box=settings.return_word_box, ) service.prepare() diff --git a/scripts/download_models.py b/scripts/download_models.py index 7ea804b..f0373bd 100644 --- a/scripts/download_models.py +++ b/scripts/download_models.py @@ -21,5 +21,6 @@ if __name__ == "__main__": text_recognition_batch_size=settings.text_recognition_batch_size, cpu_threads=settings.cpu_threads_resolved, enable_mkldnn=settings.enable_mkldnn, + return_word_box=settings.return_word_box, ).prepare() print(f"Models are ready in: {settings.model_dir.resolve()}") diff --git a/src/ocr_server/app.py b/src/ocr_server/app.py index 81a5555..36da498 100644 --- a/src/ocr_server/app.py +++ b/src/ocr_server/app.py @@ -37,6 +37,7 @@ def create_app(settings: Settings | None = None) -> FastAPI: text_recognition_batch_size=settings.text_recognition_batch_size, cpu_threads=settings.cpu_threads_resolved, enable_mkldnn=settings.enable_mkldnn, + return_word_box=settings.return_word_box, ) tasks = OCRTaskQueue(create_ocr, worker_count=settings.ocr_workers) diff --git a/src/ocr_server/config.py b/src/ocr_server/config.py index ad55287..69018c6 100644 --- a/src/ocr_server/config.py +++ b/src/ocr_server/config.py @@ -104,6 +104,7 @@ class Settings(BaseModel): text_recognition_batch_size: int = Field(default=1, ge=1, le=64) cpu_threads: int | str = 10 enable_mkldnn: bool = False + return_word_box: bool = False extract_fields: list[FieldPreset] = Field(default_factory=list) extract_separators: list[str] = Field(default_factory=lambda: [":", ":"]) extract_include_empty: bool = False diff --git a/src/ocr_server/ocr.py b/src/ocr_server/ocr.py index e623c53..65d29fb 100644 --- a/src/ocr_server/ocr.py +++ b/src/ocr_server/ocr.py @@ -49,6 +49,7 @@ class OCRService: text_recognition_batch_size: int = 1, cpu_threads: int | str = 10, enable_mkldnn: bool = False, + return_word_box: bool = False, ) -> None: self.lang = lang self.device = device @@ -64,6 +65,7 @@ class OCRService: self._text_recognition_batch_size = text_recognition_batch_size self._cpu_threads = resolve_cpu_threads(cpu_threads) self._enable_mkldnn = bool(enable_mkldnn) + self._return_word_box = bool(return_word_box) self._engine: Any | None = None self._lock = threading.Lock() self._inference_lock = threading.Lock() @@ -165,6 +167,7 @@ class OCRService: text_rec_score_thresh=self._text_rec_score_thresh, text_recognition_batch_size=self._text_recognition_batch_size, cpu_threads=self._cpu_threads, + return_word_box=self._return_word_box, ) self._install_progress_hooks(self._engine) logger.info("OCR 引擎加载完成") @@ -233,8 +236,8 @@ class OCRService: if inner is None: logger.debug("未找到内部 OCR pipeline,跳过进度挂钩") return - self._hook_model(inner, "text_det_model", 50, "文字检测完成") - self._hook_model(inner, "text_rec_model", 80, "文字识别完成") + self._hook_model(inner, "text_det_model", 50, "框识别完成") + self._hook_model(inner, "text_rec_model", 80, "文本识别完成") @staticmethod def _inner_pipeline(engine: Any) -> Any | None: @@ -269,9 +272,9 @@ class OCRService: with self._inference_lock: self._progress_callback = on_progress self._progress_reached = 0 - self._emit_progress(5, "开始推理") + self._emit_progress(5, "任务开始") engine = self._get_engine() - self._emit_progress(10, "模型已就绪") + self._emit_progress(10, "模型就绪") # Passing an ndarray avoids PaddleX treating Windows paths as URLs. import numpy as np @@ -279,9 +282,12 @@ class OCRService: with Image.open(image_path) as image: image_array = np.ascontiguousarray(image.convert("RGB")) - self._emit_progress(20, "图片已解码,开始文字检测") + self._emit_progress(20, "图片就绪") try: - results = engine.predict(input=image_array) + results = engine.predict( + input=image_array, + return_word_box=self._return_word_box, + ) except NotImplementedError as exc: if self._enable_mkldnn: import paddle @@ -293,7 +299,7 @@ class OCRService: ) from exc raise lines = self._parse_results(results) - self._emit_progress(80, "文字识别完成") + self._emit_progress(80, "文本识别完成") return lines def _parse_results(self, results: Any) -> list[dict[str, Any]]: @@ -303,18 +309,65 @@ class OCRService: texts = payload.get("rec_texts", []) scores = payload.get("rec_scores", []) boxes = payload.get("rec_polys", payload.get("dt_polys", [])) + word_boxes = payload.get("text_word_boxes", []) + word_regions = payload.get("text_word_region", []) for index, text in enumerate(texts): score = float(scores[index]) if index < len(scores) else 0.0 polygon = boxes[index] if index < len(boxes) else [] - lines.append( - { - "text": str(text), - "confidence": score, - "polygon": self._to_polygon(polygon), - } - ) + item: dict[str, Any] = { + "text": str(text), + "confidence": score, + "polygon": self._to_polygon(polygon), + } + if self._return_word_box: + words = word_boxes[index] if index < len(word_boxes) else [] + if (words is None or len(words) == 0) and index < len(word_regions): + words = word_regions[index] + item["words"] = self._to_word_boxes(words) + lines.append(item) return lines + @staticmethod + def _to_word_boxes(value: Any) -> list[list[list[float]]]: + """把 Paddle 的字/词框规范成 [word][point][x/y]。 + + PaddleOCR 的 ``text_word_boxes`` 返回矩形数组 + ``[xtop, ytop, xbottom, ybottom]``,而 ``text_word_region`` 返回 + 四点 polygon;这里统一成响应中的四点 polygon。 + """ + if value is None: + return [] + result: list[list[list[float]]] = [] + try: + for box in value: + numbers = list(box) + if len(numbers) == 4 and all( + not hasattr(item, "__len__") for item in numbers + ): + left, top, right, bottom = (float(item) for item in numbers) + result.append( + [[left, top], [right, top], [right, bottom], [left, bottom]] + ) + continue + if len(numbers) == 8 and all( + not hasattr(item, "__len__") for item in numbers + ): + result.append( + [ + [float(numbers[index]), float(numbers[index + 1])] + for index in range(0, 8, 2) + ] + ) + continue + polygon = [ + [float(point[0]), float(point[1])] for point in numbers + ] + if polygon: + result.append(polygon) + except (IndexError, TypeError, ValueError): + return [] + return result + @staticmethod def _result_payload(result: Any) -> dict[str, Any]: if isinstance(result, dict): diff --git a/src/ocr_server/schemas.py b/src/ocr_server/schemas.py index bdb172c..ce651cb 100644 --- a/src/ocr_server/schemas.py +++ b/src/ocr_server/schemas.py @@ -51,6 +51,7 @@ class OCRTextBox(BaseModel): Location: OCRLocation line: int paragraphs: int + words: list[list[list[float]]] | None = None class OCRDocument(BaseModel): diff --git a/src/ocr_server/task_queue.py b/src/ocr_server/task_queue.py index a276774..8527ba8 100644 --- a/src/ocr_server/task_queue.py +++ b/src/ocr_server/task_queue.py @@ -135,7 +135,7 @@ class OCRTaskQueue: logger.info( "file_id=%s 开始处理 image=%s", task.file_id, task.image_path.name ) - report(5, "任务开始,准备推理") + report(5, "任务开始") try: recognized = ocr.recognize(task.image_path, on_progress=report) document = self.build_document(recognized) @@ -143,7 +143,7 @@ class OCRTaskQueue: task.result = document task.progress = 100 task.status = "completed" - logger.info("file_id=%s 进度 100%% 识别完成", task.file_id) + logger.info("file_id=%s 进度 100%% 完成", task.file_id) except Exception as exc: logger.exception("file_id=%s OCR 识别失败", task.file_id) with task._lock: @@ -220,6 +220,7 @@ class OCRTaskQueue: ), line=line_number, paragraphs=paragraph_number, + words=segment.get("words") if segment.get("words") else None, ) return OCRDocument(text="\n\n".join(paragraph_texts), polygon=polygon) diff --git a/tests/test_queue.py b/tests/test_queue.py index ae5d4f4..b6b527e 100644 --- a/tests/test_queue.py +++ b/tests/test_queue.py @@ -12,11 +12,11 @@ class FakeOCR: def recognize(self, _: Path, on_progress=None) -> list[dict]: for percent, message in ( - (5, "开始推理"), - (10, "模型已就绪"), - (20, "图片已解码,开始文字检测"), - (50, "文字检测完成"), - (80, "文字识别完成"), + (5, "任务开始"), + (10, "模型就绪"), + (20, "图片就绪"), + (50, "框识别完成"), + (80, "文本识别完成"), ): self.progress.append(percent) if on_progress is not None: @@ -101,6 +101,23 @@ def test_ocr_service_resolves_threads_and_stores_mkldnn() -> None: assert plain._enable_mkldnn is False +def test_build_document_preserves_word_boxes() -> None: + recognized = [ + { + "text": "姓名:万镭", + "confidence": 0.99, + "polygon": [[0, 0], [100, 0], [100, 20], [0, 20]], + "words": [ + [[0, 0], [50, 0], [50, 20], [0, 20]], + [[50, 0], [100, 0], [100, 20], [50, 20]], + ], + } + ] + document = OCRTaskQueue.build_document(recognized) + + assert document.polygon["text1"].words == recognized[0]["words"] + + def test_document_rows_groups_by_coordinates() -> None: """行文本按坐标(bbox 纵向重叠)归并,供字段抽取的 row 选项使用。""" recognized = [ @@ -128,12 +145,12 @@ def test_progress_is_monotonic_and_includes_checkpoints() -> None: seen: list[int] = [] service._progress_callback = lambda percent, message: seen.append(percent) - service._emit_progress(5, "开始推理") - service._emit_progress(10, "模型已就绪") - service._emit_progress(20, "图片已解码") + service._emit_progress(5, "任务开始") + service._emit_progress(10, "模型就绪") + service._emit_progress(20, "图片就绪") service._emit_progress(10, "重复的低进度应被忽略") - service._emit_progress(50, "文字检测完成") - service._emit_progress(80, "文字识别完成") - service._emit_progress(100, "识别完成") + service._emit_progress(50, "框识别完成") + service._emit_progress(80, "文本识别完成") + service._emit_progress(100, "完成") assert seen == [5, 10, 20, 50, 80, 100]