feat: add return_word_box option and simplify progress checkpoints

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
zimoyin
2026-10-13 14:39:02 +08:00
parent d4bbddc4e4
commit 52696aca90
10 changed files with 165 additions and 42 deletions
+57 -15
View File
@@ -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` |
接口文档:启动后访问 <http://127.0.0.1:8000/docs>。
+5
View File
@@ -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 相同),不影响精度。
+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,
return_word_box=settings.return_word_box,
)
service.prepare()
+1
View File
@@ -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()}")
+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,
return_word_box=settings.return_word_box,
)
tasks = OCRTaskQueue(create_ocr, worker_count=settings.ocr_workers)
+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
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
+63 -10
View File
@@ -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(
{
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):
+1
View File
@@ -51,6 +51,7 @@ class OCRTextBox(BaseModel):
Location: OCRLocation
line: int
paragraphs: int
words: list[list[list[float]]] | None = None
class OCRDocument(BaseModel):
+3 -2
View File
@@ -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)
+28 -11
View File
@@ -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]