revert: remove enable_detection and return_word_box options

按需求移除两个开关:
- enable_detection:跳过检测直接识别,实测只对单行图有效,多行文档会返回空结果
- return_word_box:字/词级坐标,默认即关闭且开销在噪声内,无实际收益
恢复正常的两段式链路:文本检测 → 文本识别。

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
zimoyin
2026-10-13 19:16:21 +08:00
parent 932f1a8b13
commit cf7088a13d
10 changed files with 31 additions and 366 deletions
+3 -87
View File
@@ -305,12 +305,10 @@ NotImplementedError: ConvertPirAttribute2RuntimeAttribute not support
一次遗留说明:在项目外的独立虚拟环境里,同样的参数曾测到 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`**,需要新增配置项。
1. 依赖固定为 `paddlepaddle>=3.2,<3.3`(见 `pyproject.toml`,请勿手动升到 3.3.x);
2. `enable_mkldnn` 已作为配置项暴露,在 `config.yaml` 中设置即可(默认 `true`)。
本次验证在项目外的独立虚拟环境完成(`paddleocr 3.7.0` + `paddlex 3.7.2` + `paddlepaddle 3.2.2` 可正常推理),未改动你的项目环境和模型。
@@ -590,86 +588,6 @@ 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
配置:
```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. 上传图片
@@ -1018,8 +936,6 @@ 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` |
接口文档:启动后访问 <http://127.0.0.1:8000/docs>。
-15
View File
@@ -52,21 +52,6 @@ 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 中返回字/词级四点坐标,会增加耗时和响应体积。
return_word_box: false
# 是否启用 oneDNN(MKLDNN)CPU 加速。
# true = 启用,CPU 推理明显更快(1.png 实测 148.12s -> 30.95s,快 4.8 倍),
# 且输出逐字节一致(md5 相同),不影响精度。
-2
View File
@@ -25,8 +25,6 @@ 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()
-2
View File
@@ -21,7 +21,5 @@ 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()}")
-2
View File
@@ -37,8 +37,6 @@ 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,
)
tasks = OCRTaskQueue(create_ocr, worker_count=settings.ocr_workers)
-2
View File
@@ -104,8 +104,6 @@ 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: [":", ":"])
extract_include_empty: bool = False
+20 -143
View File
@@ -49,8 +49,6 @@ 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
self.device = device
@@ -66,8 +64,6 @@ 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()
self._inference_lock = threading.Lock()
@@ -145,13 +141,12 @@ class OCRService:
with self._process_model_lock:
logger.info(
"加载 OCR 引擎: det=%s rec=%s device=%s cpu_threads=%d "
"enable_mkldnn=%s enable_detection=%s model_dir=%s",
"enable_mkldnn=%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()
@@ -170,7 +165,6 @@ 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 引擎加载完成")
@@ -286,92 +280,22 @@ 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,
return_word_box=self._return_word_box,
)
except NotImplementedError as exc:
if self._enable_mkldnn:
import paddle
try:
results = engine.predict(input=image_array)
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)
)
# 没有检测框,但必须给出坐标:文本区域就是整张图。
# 否则 build_document 会丢弃无坐标的片段,导致结果里有字却返回空。
height, width = int(image_array.shape[0]), int(image_array.shape[1])
whole_image = [
[0.0, 0.0],
[float(width), 0.0],
[float(width), float(height)],
[0.0, float(height)],
]
lines = self._parse_recognition_output(outputs, polygon=whole_image)
if not lines:
logger.warning(
"跳过检测后没有识别出任何文字。该模式要求图片本身是单行文本;"
"如果是多行图片,请把 enable_detection 改回 true。"
)
return lines
@staticmethod
def _parse_recognition_output(
outputs: Any, polygon: list[list[float]] | None = None
) -> list[dict[str, Any]]:
"""解析识别模型(无检测)的输出。单次输入只会返回一个结果。
``polygon`` 是无检测模式下的兜底坐标(整张图),缺了它后续 build_document
会因为「没有坐标」而丢弃该片段。
"""
fallback = polygon or []
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": list(fallback)}
)
return lines
def _parse_results(self, results: Any) -> list[dict[str, Any]]:
lines: list[dict[str, Any]] = []
for result in results:
@@ -379,65 +303,18 @@ 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 []
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)
lines.append(
{
"text": str(text),
"confidence": score,
"polygon": self._to_polygon(polygon),
}
)
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):
-1
View File
@@ -51,7 +51,6 @@ class OCRTextBox(BaseModel):
Location: OCRLocation
line: int
paragraphs: int
words: list[list[list[float]]] | None = None
class OCRDocument(BaseModel):
+5 -11
View File
@@ -220,7 +220,6 @@ 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)
@@ -240,13 +239,8 @@ class OCRTaskQueue:
@classmethod
def filter_document(cls, document: OCRDocument, min_confidence: float) -> OCRDocument:
# The compact response is intentionally rebuilt from its own polygon map.
# words 必须一并带上:这个函数在每次 i2t 请求里都会被调用(即使
# min_confidence 为 0),漏掉就会让 return_word_box 的结果全部丢失。
selected: list[dict[str, Any]] = []
for item in document.polygon.values():
if item.confidence < min_confidence:
continue
segment: dict[str, Any] = {
selected = [
{
"text": item.text,
"confidence": item.confidence,
"polygon": [
@@ -256,9 +250,9 @@ class OCRTaskQueue:
[item.Location.xtop, item.Location.ybottom],
],
}
if item.words:
segment["words"] = item.words
selected.append(segment)
for item in document.polygon.values()
if item.confidence >= min_confidence
]
return cls.build_document(selected)
@classmethod
+3 -101
View File
@@ -101,54 +101,15 @@ def test_ocr_service_resolves_threads_and_stores_mkldnn() -> None:
assert plain._enable_mkldnn is False
def test_build_document_preserves_word_boxes() -> None:
def test_filter_document_drops_low_confidence() -> 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_filter_document_keeps_word_boxes() -> None:
"""i2t 每次都走 filter_document,words 不能被过滤流程丢掉。"""
recognized = [
{
"text": "姓名:万镭",
"confidence": 0.9,
"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)
filtered = OCRTaskQueue.filter_document(document, 0.0)
assert filtered.polygon["text1"].words == recognized[0]["words"]
def test_filter_document_drops_low_confidence_with_words() -> None:
recognized = [
{"text": "保留", "confidence": 0.9, "polygon": [[0, 0], [10, 0], [10, 10], [0, 10]],
"words": [[[0, 0], [10, 0], [10, 10], [0, 10]]]},
{"text": "丢弃", "confidence": 0.2, "polygon": [[0, 20], [10, 20], [10, 30], [0, 30]],
"words": [[[0, 20], [10, 20], [10, 30], [0, 30]]]},
{"text": "保留", "confidence": 0.9, "polygon": [[0, 0], [10, 0], [10, 10], [0, 10]]},
{"text": "丢弃", "confidence": 0.2, "polygon": [[0, 20], [10, 20], [10, 30], [0, 30]]},
]
document = OCRTaskQueue.build_document(recognized)
filtered = OCRTaskQueue.filter_document(document, 0.5)
assert [item.text for item in filtered.polygon.values()] == ["保留"]
assert filtered.polygon["text1"].words is not None
def test_document_rows_groups_by_coordinates() -> None:
@@ -171,65 +132,6 @@ 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_applies_fallback_polygon() -> None:
"""无检测模式必须带上兜底坐标,否则 build_document 会把片段丢掉。"""
from ocr_server.ocr import OCRService
whole = [[0, 0], [640, 0], [640, 42], [0, 42]]
parsed = OCRService._parse_recognition_output(
[{"rec_text": "MU2379", "rec_score": 0.97}], polygon=whole
)
assert parsed[0]["polygon"] == whole
from ocr_server.task_queue import OCRTaskQueue
document = OCRTaskQueue.build_document(parsed)
assert document.text == "MU2379"
assert len(document.polygon) == 1
assert document.polygon["text1"].text == "MU2379"
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