From a7d4ff64543b0358c67190520c389a83bfcadbf8 Mon Sep 17 00:00:00 2001 From: zimoyin <2556608754@qq.com> Date: Tue, 13 Oct 2026 15:59:25 +0800 Subject: [PATCH] feat: add enable_detection switch to skip text detection MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit enable_detection: false 跳过检测模型,直接把整图当一行文本送识别。 实测:单行图可正确识别;多行整图因识别模型固定缩放到高 48px 会返回空结果,已加告警。 Co-Authored-By: Claude Code --- README.md | 40 ++++++++++++++++++ config.yaml | 10 +++++ scripts/benchmark_ocr.py | 1 + scripts/download_models.py | 1 + src/ocr_server/app.py | 1 + src/ocr_server/config.py | 1 + src/ocr_server/ocr.py | 84 ++++++++++++++++++++++++++++++-------- tests/test_queue.py | 40 ++++++++++++++++++ 8 files changed, 162 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 44859c0..562f812 100644 --- a/README.md +++ b/README.md @@ -590,6 +590,45 @@ Windows 不能直接生成 Ubuntu ELF 二进制。`package-ubuntu.sh` 必须在 GPU 部署不使用当前 CPU 依赖作为判断依据,请按照 PaddlePaddle 官方文档安装与 CUDA、cuDNN、驱动匹配的 GPU 版本,然后再安装本项目依赖。 +## 跳过检测:enable_detection + +正常 OCR 由两个模型接力完成: + +```text +文本检测模型(det)→ 找出所有文本框(位置) + ↓ +文本识别模型(rec)→ 逐个识别框里的文字 +``` + +`enable_detection: true`(默认)就是这条链路。⚠️ 检测模型**不是画框/可视化**,它的作用是定位文字区域;服务里没有任何绘制标注图的步骤(PaddleOCR 的 `save_to_img` 我们从未调用)。 + +把它设为 `false` 可以**跳过检测、直接把整张图当作一行文本送识别模型**: + +```yaml +enable_detection: false +``` + +⚠️ **只适用于图片本身就是单行文本的场景**(例如你自己裁好的一行字、一个字段条)。原因是识别模型会把输入统一缩放到**高约 48px**: + +| 输入 | 实测结果 | +| --- | --- | +| 裁出的单行(42×640) | `MU237903DECW035`,置信度 0.9765 ✅ | +| 整张多行图(896×528) | **空结果**,置信度 0 ❌(被压成 48×81,文字全糊) | + +所以多行图片用这个模式会返回空结果,服务会打印告警: + +```text +WARNING 跳过检测后没有识别出任何文字。该模式要求图片本身是单行文本; + 如果是多行图片,请把 enable_detection 改回 true。 +``` + +其他注意事项: + +- 关闭检测后 `text_det_limit_side_len`、`text_det_thresh` 等**检测参数不再生效**; +- 识别结果只有一条文本片段,`polygon` 为空(因为没有检测框); +- 该模式下 `return_word_box` 也无法给出词级框(缺检测框作为基准); +- 进度日志仍保留全部关键点,50% 显示为「跳过框识别」,便于和前一条链路对齐。 + ## 文本框开关:return_word_box 配置: @@ -979,6 +1018,7 @@ log_level: INFO | `text_recognition_batch_size` | `1` | 识别批量大小;内存足够时可提高 | | `cpu_threads` | `max` | CPU 推理线程数;正整数或 `max`(`max` = 吃满所有逻辑核心) | | `enable_mkldnn` | `true` | 是否启用 oneDNN 加速;**需要 `paddlepaddle` 3.2.x**,见下方说明 | +| `enable_detection` | `true` | 是否先做文本框检测再识别;`false` 时跳过检测、直接识别(仅适合单行图) | | `return_word_box` | `false` | 是否返回文本片段内部的字/词级 polygon(会增加耗时和 JSON 体积) | | `log_level` | `INFO` | 日志级别:`DEBUG`、`INFO`、`WARNING`、`ERROR` | diff --git a/config.yaml b/config.yaml index 16fdc28..da83075 100644 --- a/config.yaml +++ b/config.yaml @@ -52,6 +52,16 @@ text_recognition_batch_size: 8 # 而且会挤占同机其它服务。建议用 benchmark_ocr.py 实测后再定。 cpu_threads: 1 +# 是否先做文本框检测(det 模型),再做文字识别(rec 模型)。 +# true(默认)= 检测 + 识别:先找出所有文本框,再逐个识别。适合正常的多行文档/截图。 +# false = 跳过检测,直接把整张图当作「一行文本」送识别模型。 +# ⚠️ 只适用于图片本身就是单行文本的场景(例如你自己裁好的一行文字)。 +# 识别模型会把输入统一缩放到高约 48px,多行图会被压扁到读不出内容, +# 此时服务会返回空结果并打印告警。 +# 关闭检测后 text_det_limit_side_len / text_det_* 等检测参数不再生效。 +# 备注:检测模型不是「画框」,而是用来定位文字区域;正常 OCR 必须保留。 +enable_detection: true + # 是否返回每个识别文本框内部的字/词级 polygon。 # false:默认,只返回行/文本片段框,速度更快、JSON 更小。 # true :在 data.result.polygon.textN.words 中返回字/词级四点坐标,会增加耗时和响应体积。 diff --git a/scripts/benchmark_ocr.py b/scripts/benchmark_ocr.py index 9b49af3..08373b6 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, + enable_detection=settings.enable_detection, return_word_box=settings.return_word_box, ) service.prepare() diff --git a/scripts/download_models.py b/scripts/download_models.py index f0373bd..06fe571 100644 --- a/scripts/download_models.py +++ b/scripts/download_models.py @@ -21,6 +21,7 @@ if __name__ == "__main__": text_recognition_batch_size=settings.text_recognition_batch_size, cpu_threads=settings.cpu_threads_resolved, enable_mkldnn=settings.enable_mkldnn, + enable_detection=settings.enable_detection, 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 36da498..e7e4ae1 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, + enable_detection=settings.enable_detection, return_word_box=settings.return_word_box, ) diff --git a/src/ocr_server/config.py b/src/ocr_server/config.py index 69018c6..1b905fa 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 + enable_detection: bool = True return_word_box: bool = False extract_fields: list[FieldPreset] = Field(default_factory=list) extract_separators: list[str] = Field(default_factory=lambda: [":", ":"]) diff --git a/src/ocr_server/ocr.py b/src/ocr_server/ocr.py index 65d29fb..1e5230b 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, + enable_detection: bool = True, return_word_box: bool = False, ) -> None: self.lang = lang @@ -65,6 +66,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._enable_detection = bool(enable_detection) self._return_word_box = bool(return_word_box) self._engine: Any | None = None self._lock = threading.Lock() @@ -143,12 +145,13 @@ class OCRService: with self._process_model_lock: logger.info( "加载 OCR 引擎: det=%s rec=%s device=%s cpu_threads=%d " - "enable_mkldnn=%s model_dir=%s", + "enable_mkldnn=%s enable_detection=%s model_dir=%s", self._det_model_name, self._rec_model_name, self.device, self._cpu_threads, self._enable_mkldnn, + self._enable_detection, self.model_dir, ) self._warn_if_mkldnn_unsupported() @@ -283,25 +286,74 @@ class OCRService: with Image.open(image_path) as image: image_array = np.ascontiguousarray(image.convert("RGB")) self._emit_progress(20, "图片就绪") - try: - results = engine.predict( - input=image_array, - return_word_box=self._return_word_box, - ) - except NotImplementedError as exc: - if self._enable_mkldnn: - import paddle + if not self._enable_detection: + lines = self._recognize_directly(engine, image_array) + else: + try: + results = engine.predict( + input=image_array, + return_word_box=self._return_word_box, + ) + except NotImplementedError as exc: + if self._enable_mkldnn: + import paddle - raise RuntimeError( - "oneDNN 推理失败:当前 PaddlePaddle %s 与 oneDNN 不兼容。" - "请改用 paddlepaddle 3.2.x,或在配置中把 enable_mkldnn 设为 false。" - % getattr(paddle, "__version__", "unknown") - ) from exc - raise - lines = self._parse_results(results) + raise RuntimeError( + "oneDNN 推理失败:当前 PaddlePaddle %s 与 oneDNN 不兼容。" + "请改用 paddlepaddle 3.2.x,或在配置中把 enable_mkldnn 设为 false。" + % getattr(paddle, "__version__", "unknown") + ) from exc + raise + lines = self._parse_results(results) self._emit_progress(80, "文本识别完成") return lines + def _recognize_directly( + self, engine: Any, image_array: Any + ) -> list[dict[str, Any]]: + """跳过文本框检测,直接把整张图当作一行文本送识别模型。 + + ⚠️ 识别模型会把输入统一缩放到高约 48px。整张多行图会被压扁、读不出内容, + 因此该模式**只适用于本身就是单行文本的图片**。检测关闭后, + ``text_det_limit_side_len`` 等检测参数不再生效。 + """ + inner = self._inner_pipeline(engine) + if inner is None or not hasattr(inner, "text_rec_model"): + raise OCRNotAvailable("当前 OCR 引擎不支持跳过检测的识别模式") + self._emit_progress(50, "跳过框识别") + outputs = list( + inner.text_rec_model([image_array], return_word_box=self._return_word_box) + ) + lines = self._parse_recognition_output(outputs) + if not lines: + logger.warning( + "跳过检测后没有识别出任何文字。该模式要求图片本身是单行文本;" + "如果是多行图片,请把 enable_detection 改回 true。" + ) + return lines + + @staticmethod + def _parse_recognition_output(outputs: Any) -> list[dict[str, Any]]: + """解析识别模型(无检测)的输出。单次输入只会返回一个结果。""" + lines: list[dict[str, Any]] = [] + for output in outputs: + if not isinstance(output, dict): + continue + texts = output.get("rec_text") or [] + scores = output.get("rec_score") or [] + if not isinstance(texts, (list, tuple)): + texts = [texts] + if not isinstance(scores, (list, tuple)): + scores = [scores] + for index, text in enumerate(texts): + # return_word_box 打开时识别结果是 (文本, 附加信息) 元组 + value = text[0] if isinstance(text, (list, tuple)) and text else text + if not value: + continue + score = float(scores[index]) if index < len(scores) else 0.0 + lines.append({"text": str(value), "confidence": score, "polygon": []}) + return lines + def _parse_results(self, results: Any) -> list[dict[str, Any]]: lines: list[dict[str, Any]] = [] for result in results: diff --git a/tests/test_queue.py b/tests/test_queue.py index 544eb77..88659e8 100644 --- a/tests/test_queue.py +++ b/tests/test_queue.py @@ -171,6 +171,46 @@ def test_document_rows_empty_document() -> None: assert OCRTaskQueue.document_rows(document) == [] +def test_parse_recognition_output_handles_list_and_scalar() -> None: + from ocr_server.ocr import OCRService + + listed = OCRService._parse_recognition_output( + [{"rec_text": ["MU2379", "03DEC"], "rec_score": [0.97, 0.95]}] + ) + assert [item["text"] for item in listed] == ["MU2379", "03DEC"] + assert listed[0]["confidence"] == 0.97 + + scalar = OCRService._parse_recognition_output( + [{"rec_text": "MU2379", "rec_score": 0.97}] + ) + assert scalar == [{"text": "MU2379", "confidence": 0.97, "polygon": []}] + + +def test_parse_recognition_output_with_word_box_tuple() -> None: + from ocr_server.ocr import OCRService + + parsed = OCRService._parse_recognition_output( + [{"rec_text": [("MU2379", [[1, 2, 3]])], "rec_score": [0.97]}] + ) + + assert parsed == [{"text": "MU2379", "confidence": 0.97, "polygon": []}] + + +def test_parse_recognition_output_skips_empty() -> None: + from ocr_server.ocr import OCRService + + assert OCRService._parse_recognition_output([{"rec_text": [""], "rec_score": [0.0]}]) == [] + assert OCRService._parse_recognition_output([{"rec_text": [], "rec_score": []}]) == [] + assert OCRService._parse_recognition_output([None, "junk"]) == [] + + +def test_enable_detection_defaults_to_true() -> None: + from ocr_server.config import Settings + + assert Settings().enable_detection is True + assert Settings(enable_detection=False).enable_detection is False + + def test_progress_is_monotonic_and_includes_checkpoints() -> None: from ocr_server.ocr import OCRService