feat: add enable_detection switch to skip text detection

enable_detection: false 跳过检测模型,直接把整图当一行文本送识别。
实测:单行图可正确识别;多行整图因识别模型固定缩放到高 48px 会返回空结果,已加告警。

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
zimoyin
2026-10-13 15:59:25 +08:00
parent 6821d0d137
commit a7d4ff6454
8 changed files with 162 additions and 16 deletions
+40
View File
@@ -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` |
+10
View File
@@ -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 中返回字/词级四点坐标,会增加耗时和响应体积。
+1
View File
@@ -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()
+1
View File
@@ -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()}")
+1
View File
@@ -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,
)
+1
View File
@@ -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: [":", ":"])
+53 -1
View File
@@ -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,6 +286,9 @@ class OCRService:
with Image.open(image_path) as image:
image_array = np.ascontiguousarray(image.convert("RGB"))
self._emit_progress(20, "图片就绪")
if not self._enable_detection:
lines = self._recognize_directly(engine, image_array)
else:
try:
results = engine.predict(
input=image_array,
@@ -302,6 +308,52 @@ class OCRService:
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:
+40
View File
@@ -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