feat: add return_word_box option and simplify progress checkpoints
Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
@@ -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>。
|
||||
|
||||
@@ -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 相同),不影响精度。
|
||||
|
||||
@@ -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()
|
||||
|
||||
|
||||
@@ -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()}")
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
@@ -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):
|
||||
|
||||
@@ -51,6 +51,7 @@ class OCRTextBox(BaseModel):
|
||||
Location: OCRLocation
|
||||
line: int
|
||||
paragraphs: int
|
||||
words: list[list[list[float]]] | None = None
|
||||
|
||||
|
||||
class OCRDocument(BaseModel):
|
||||
|
||||
@@ -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
@@ -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]
|
||||
|
||||
Reference in New Issue
Block a user