From 5ddda545f51af209f4e75f01c633d87952f050e2 Mon Sep 17 00:00:00 2001 From: zimoyin <2556608754@qq.com> Date: Mon, 12 Oct 2026 11:00:09 +0800 Subject: [PATCH] init2 --- .gitignore | 1 + README.md | 164 +++++++++++++++++++++++++++++++- config.yaml | 3 + http/ocr-server.http | 4 +- pyproject.toml | 1 + scripts/hook-imagesize.py | 3 + scripts/package-ubuntu.sh | 45 +++++++++ scripts/package-windows.ps1 | 46 +++++++++ scripts/packaged_entry.py | 5 + scripts/start.bat | 16 ++++ scripts/start.ps1 | 15 +++ scripts/start.sh | 19 ++++ src/ocr_server/__init__.py | 16 ++++ src/ocr_server/app.py | 2 + src/ocr_server/config.py | 18 +++- src/ocr_server/logging_setup.py | 28 ++++++ src/ocr_server/ocr.py | 135 +++++++++++++++++++++++++- src/ocr_server/task_queue.py | 37 +++++-- tests/test_queue.py | 35 ++++++- uv.lock | 85 ++++++++++++++++- 20 files changed, 659 insertions(+), 19 deletions(-) create mode 100644 scripts/hook-imagesize.py create mode 100644 scripts/package-ubuntu.sh create mode 100644 scripts/package-windows.ps1 create mode 100644 scripts/packaged_entry.py create mode 100644 scripts/start.bat create mode 100644 scripts/start.ps1 create mode 100644 scripts/start.sh create mode 100644 src/ocr_server/logging_setup.py diff --git a/.gitignore b/.gitignore index 86cf66c..9e831a7 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,4 @@ http/fixtures/*.png *.egg-info/ dist/ build/ +*.spec diff --git a/README.md b/README.md index acfbd63..03c99a0 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,12 @@ ocr-server/ │ └── PP-OCRv5_server_rec/ ├── data/uploads/ # 上传图片运行时目录 ├── src/ocr_server/ +├── scripts/start.ps1 # Windows 源码/发布包启动 +├── scripts/start.bat # Windows 启动快捷方式 +├── scripts/start.sh # Ubuntu 源码/发布包启动 +├── scripts/package-windows.ps1 # Windows exe 打包 +├── scripts/packaged_entry.py # PyInstaller 入口 +├── scripts/package-ubuntu.sh # Ubuntu ELF 打包 ├── scripts/download_models.py # 下载或补齐缺少的模型 └── scripts/benchmark_ocr.py # 测量当前配置的 OCR 耗时 ``` @@ -91,6 +97,97 @@ ocr_workers: 1 `text_det_limit_side_len` 从 `960` 调到 `640` 通常可以降低检测耗时,但小字可能漏检。`text_recognition_batch_size` 主要影响单张图片包含很多文本框时的吞吐;增大到 `2` 或 `4` 会增加内存,单张简单图片不一定更快。 +## 日志与推理进度 + +服务使用普通换行日志,不使用 `\r` 覆盖式进度条,便于复制到文件或在 IDEA 控制台查看。 + +识别过程中会输出固定的进度检查点: + +```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: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:01:35 INFO [ocr_server.task] file_id=xxx 处理结束 status=completed elapsed=94000.00ms +``` + +进度含义: + +| 进度 | 含义 | +| --- | --- | +| 5% | 工作线程取到任务,准备推理 | +| 10% | OCR 引擎就绪(首次包含模型加载时间) | +| 20% | 图片已解码,开始文字检测 | +| 50% | 文字检测完成 | +| 80% | 文字识别完成 | +| 100% | 结果组装完成,任务结束 | + +其中 50% 和 80% 来自真实的检测模型和识别模型调用完成,不是估算值。`/api/v1/i2t` 返回的 `progress` 字段与日志中的进度一致。 + +调整日志级别: + +```yaml +log_level: DEBUG +``` + +## 已知性能限制 + +当前环境中 PP-OCRv5 服务模型在 CPU 上关闭 oneDNN 后推理较慢。实测(20 核 CPU、官方 896x528 示例图): + +```text +默认线程(10)+ batch 1 : 约 65 秒 34 行 +batch 8 + 默认线程 : 约 60 秒 34 行 +batch 8 + cpu_threads 4 : 约 114 秒 +``` + +按阶段拆分(`log_level: INFO` 的进度日志可直接读出): + +```text +20% → 50% 文字检测 约 13 秒 +50% → 80% 文字识别 约 50 秒 ← 主要瓶颈 +``` + +关闭 oneDNN 是必须的:`enable_mkldnn=True` 会触发 PaddlePaddle 3.3.1 的缺陷并直接失败: + +```text +NotImplementedError: ConvertPirAttribute2RuntimeAttribute not support +(at onednn_instruction.cc:118) +``` + +因此该配置下慢的根因是「CPU 推理未启用 oneDNN」,不是队列或接口阻塞。 + +### 换成移动端模型(实测约 3.4 倍提速) + +同一张图片、同样 `text_det_limit_side_len: 960` 与 `text_recognition_batch_size: 8`: + +| 模型组合 | 模型体积 | 识别耗时 | 识别行数 | +| --- | --- | --- | --- | +| `PP-OCRv5_server_det` + `PP-OCRv5_server_rec` | 约 167 MB | 约 60 秒 | 34 | +| `PP-OCRv4_mobile_det` + `PP-OCRv4_mobile_rec` | 约 16 MB | 约 18 秒 | 39 | + +切换方式: + +```yaml +det_model_name: PP-OCRv4_mobile_det +rec_model_name: PP-OCRv4_mobile_rec +``` + +模型文件需要存在于 `model_dir/official_models/` 下;不存在时首次识别会自动下载。 + +切换前建议先用 `benchmark_ocr.py` 和真实业务图片对比准确率:移动端模型体积小、速度快,但中文识别精度通常低于 PP-OCRv5 服务模型,且这两个模型属于 PP-OCRv4,不是 PP-OCRv5。不同业务对精度敏感度不同,请以实际样本为准。 + +其他提速方向: + +1. 降低 `text_det_limit_side_len`(例如 `640`),可减少检测耗时; +2. 升级到 oneDNN 与 PIR 兼容的 PaddlePaddle 版本后再开启 `enable_mkldnn`; +3. GPU 部署。 + + ### 如何测速 ```powershell @@ -129,12 +226,38 @@ D:\code\work\ocr-server\.venv\Scripts\python.exe ## Windows 安装和启动 +源码启动: + ```powershell cd D:\code\work\ocr-server uv sync -uv run ocr-server +powershell -ExecutionPolicy Bypass -File .\scripts\start.ps1 +# 或双击 scripts\start.bat ``` +Windows 打包为 exe: + +```powershell +powershell -ExecutionPolicy Bypass -File .\scripts\package-windows.ps1 -Clean +``` + +发布目录: + +```text +dist\ocr-server\ +├── ocr-server.exe +├── config.yaml +└── models\ +``` + +启动 exe: + +```powershell +.\dist\ocr-server\ocr-server.exe +``` + +`config.yaml` 和 `models/` 是发布目录外置资源,可以独立修改或替换;不要直接改 exe 内部文件。发布目录约 1 GB(其中 `_internal/` 约 665 MB,模型约 166 MB),这是 PaddlePaddle 原生运行库带来的正常体积。 + 启动前修改项目根目录的 `config.yaml`: ```yaml @@ -184,6 +307,43 @@ python3.10 -m venv .venv .venv/bin/ocr-server ``` +Ubuntu 源码启动: + +```bash +cd /opt/ocr-server +uv sync --python 3.12 +chmod +x scripts/start.sh +./scripts/start.sh +``` + +Ubuntu 22.04 打包为原生 ELF 二进制: + +```bash +cd /opt/ocr-server +chmod +x scripts/package-ubuntu.sh +./scripts/package-ubuntu.sh +``` + +发布目录: + +```text +dist/ocr-server/ +├── ocr-server +├── config.yaml +└── models/ +``` + +启动: + +```bash +./dist/ocr-server/ocr-server +# 或:./scripts/start.sh +``` + +Windows 不能直接生成 Ubuntu ELF 二进制。`package-ubuntu.sh` 必须在 Ubuntu/Linux 构建机执行;Windows 使用 `package-windows.ps1` 生成 exe。两个平台的发布包不能混用,建议分别构建、分别测试。 + +打包脚本使用 PyInstaller 的 `--onedir` 模式,而不是单文件模式:PaddlePaddle、PaddleOCR 和模型都作为外置目录分发,启动更稳定,也方便替换 `config.yaml` 或模型目录。构建机需要联网安装依赖;如果发布包中已有完整模型,运行时不需要重新下载模型。 + GPU 部署不使用当前 CPU 依赖作为判断依据,请按照 PaddlePaddle 官方文档安装与 CUDA、cuDNN、驱动匹配的 GPU 版本,然后再安装本项目依赖。 ## API @@ -326,6 +486,7 @@ text_det_box_thresh: 0.6 text_det_unclip_ratio: 1.5 text_rec_score_thresh: 0.0 text_recognition_batch_size: 1 +log_level: INFO ``` | 配置项 | 默认值 | 说明 | @@ -348,6 +509,7 @@ text_recognition_batch_size: 1 | `text_det_unclip_ratio` | `1.5` | 检测框扩张比例 | | `text_rec_score_thresh` | `0.0` | 识别结果阈值 | | `text_recognition_batch_size` | `1` | 识别批量大小;内存足够时可提高 | +| `log_level` | `INFO` | 日志级别:`DEBUG`、`INFO`、`WARNING`、`ERROR` | 接口文档:启动后访问 。 diff --git a/config.yaml b/config.yaml index a6164fb..fb2be3a 100644 --- a/config.yaml +++ b/config.yaml @@ -34,5 +34,8 @@ text_rec_score_thresh: 0.0 # 识别批量大小 text_recognition_batch_size: 1 +# 日志级别:DEBUG / INFO / WARNING / ERROR +log_level: INFO + max_upload_mb: 10 max_image_pixels: 20000000 diff --git a/http/ocr-server.http b/http/ocr-server.http index 6bd32ea..eedc285 100644 --- a/http/ocr-server.http +++ b/http/ocr-server.http @@ -9,10 +9,10 @@ POST {{host}}/api/v1/upload Content-Type: multipart/form-data; boundary=ocrBoundary --ocrBoundary -Content-Disposition: form-data; name="file"; filename="general_ocr_002.png" +Content-Disposition: form-data; name="file"; filename="2.png" Content-Type: image/jpeg -< ./fixtures/general_ocr_002.png +< ./fixtures/2.png --ocrBoundary-- > {% client.global.set("fileId", response.body.data.file_id); %} diff --git a/pyproject.toml b/pyproject.toml index 6e23c8a..1a43c5a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,5 +23,6 @@ build-backend = "uv_build" [dependency-groups] dev = [ + "pyinstaller>=6.22.3", "pytest>=9.1.1", ] diff --git a/scripts/hook-imagesize.py b/scripts/hook-imagesize.py new file mode 100644 index 0000000..60a68e1 --- /dev/null +++ b/scripts/hook-imagesize.py @@ -0,0 +1,3 @@ +from PyInstaller.utils.hooks import collect_data_files + +datas = collect_data_files("imagesize", include_py_files=True) diff --git a/scripts/package-ubuntu.sh b/scripts/package-ubuntu.sh new file mode 100644 index 0000000..d1db265 --- /dev/null +++ b/scripts/package-ubuntu.sh @@ -0,0 +1,45 @@ +#!/usr/bin/env bash +set -euo pipefail + +PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "$PROJECT_ROOT" + +if [[ "$(uname -s)" != "Linux" ]]; then + printf '%s\n' '该脚本必须在 Ubuntu/Linux 环境执行,不能在 Windows 上生成 ELF 二进制。' >&2 + exit 1 +fi + +uv sync --dev --python 3.12 +rm -rf build dist +uv run pyinstaller --noconfirm --clean --onedir --name ocr-server \ + --paths src \ + --collect-all paddleocr \ + --collect-all paddlex \ + --collect-all paddle \ + --collect-all cv2 \ + --collect-all PIL \ + --collect-all pyclipper \ + --collect-all pypdfium2 \ + --collect-all shapely \ + --collect-all bidi \ + --hidden-import paddlex.inference.models.text_detection.processors \ + --copy-metadata paddlex \ + --copy-metadata paddleocr \ + --copy-metadata paddlepaddle \ + --copy-metadata imagesize \ + --add-data 'config.yaml:.' \ + --add-data 'http:http' \ + --add-data 'scripts:_packaging_scripts' \ + --additional-hooks-dir scripts \ + --hidden-import imagesize \ + --hidden-import imagesize.imagesize \ + --hidden-import ocr_server.app \ + --hidden-import ocr_server.config \ + scripts/packaged_entry.py + +cp -f config.yaml dist/ocr-server/config.yaml +cp -a models dist/ocr-server/models +chmod +x dist/ocr-server/ocr-server + +printf 'Ubuntu 发布目录:%s\n' "$PROJECT_ROOT/dist/ocr-server" +printf '%s\n' '启动:dist/ocr-server/ocr-server' diff --git a/scripts/package-windows.ps1 b/scripts/package-windows.ps1 new file mode 100644 index 0000000..e2859d2 --- /dev/null +++ b/scripts/package-windows.ps1 @@ -0,0 +1,46 @@ +param( + [switch]$Clean +) + +$ErrorActionPreference = "Stop" +$ProjectRoot = Split-Path -Parent $PSScriptRoot +Set-Location $ProjectRoot + +if ($Clean) { + Remove-Item -Recurse -Force -ErrorAction SilentlyContinue build, dist +} + +uv sync --dev +uv run pyinstaller --noconfirm --clean --onedir --name ocr-server ` + --paths src ` + --collect-all paddleocr ` + --collect-all paddlex ` + --collect-all paddle ` + --collect-all cv2 ` + --collect-all PIL ` + --collect-all pyclipper ` + --collect-all pypdfium2 ` + --collect-all shapely ` + --collect-all bidi ` + --hidden-import paddlex.inference.models.text_detection.processors ` + --copy-metadata paddlex ` + --copy-metadata paddleocr ` + --copy-metadata paddlepaddle ` + --copy-metadata imagesize ` + --add-data "config.yaml;." ` + --add-data "http;http" ` + --add-data "scripts;_packaging_scripts" ` + --additional-hooks-dir scripts ` + --hidden-import imagesize ` + --hidden-import imagesize.imagesize ` + --hidden-import ocr_server.app ` + --hidden-import ocr_server.config ` + scripts/packaged_entry.py + +Copy-Item -Force config.yaml dist/ocr-server/config.yaml +if (Test-Path models) { + Copy-Item -Recurse -Force models dist/ocr-server/models +} + +Write-Host "Windows 发布目录:$ProjectRoot\dist\ocr-server" +Write-Host "启动:dist\ocr-server\ocr-server.exe" diff --git a/scripts/packaged_entry.py b/scripts/packaged_entry.py new file mode 100644 index 0000000..a3f51d0 --- /dev/null +++ b/scripts/packaged_entry.py @@ -0,0 +1,5 @@ +from ocr_server import main + + +if __name__ == "__main__": + main() diff --git a/scripts/start.bat b/scripts/start.bat new file mode 100644 index 0000000..1ffff5d --- /dev/null +++ b/scripts/start.bat @@ -0,0 +1,16 @@ +@echo off +setlocal +cd /d "%~dp0.." + +if exist "dist\ocr-server\ocr-server.exe" ( + "dist\ocr-server\ocr-server.exe" + exit /b %errorlevel% +) + +where uv >nul 2>nul +if errorlevel 1 ( + echo 未找到打包程序,也未安装 uv。 + exit /b 1 +) + +uv run ocr-server diff --git a/scripts/start.ps1 b/scripts/start.ps1 new file mode 100644 index 0000000..dc0c82d --- /dev/null +++ b/scripts/start.ps1 @@ -0,0 +1,15 @@ +$ErrorActionPreference = "Stop" +$ProjectRoot = Split-Path -Parent $PSScriptRoot +Set-Location $ProjectRoot +$PackagedExe = Join-Path $ProjectRoot "dist\ocr-server\ocr-server.exe" + +if (Test-Path $PackagedExe) { + & $PackagedExe + exit $LASTEXITCODE +} + +if (-not (Get-Command uv -ErrorAction SilentlyContinue)) { + throw "未找到打包程序,也未安装 uv。请先运行 scripts/package-windows.ps1 或安装 uv。" +} + +uv run ocr-server diff --git a/scripts/start.sh b/scripts/start.sh new file mode 100644 index 0000000..4d6bcd4 --- /dev/null +++ b/scripts/start.sh @@ -0,0 +1,19 @@ +#!/usr/bin/env bash +set -euo pipefail + +cd "$(dirname "${BASH_SOURCE[0]}")/.." + +if [[ -x dist/ocr-server/ocr-server ]]; then + exec dist/ocr-server/ocr-server +fi + +if command -v uv >/dev/null 2>&1; then + exec uv run ocr-server +fi + +if [[ -x .venv/bin/ocr-server ]]; then + exec .venv/bin/ocr-server +fi + +printf '%s\n' '未找到 uv 或 .venv/bin/ocr-server,请先运行 scripts/package-ubuntu.sh 或安装项目依赖。' >&2 +exit 1 diff --git a/src/ocr_server/__init__.py b/src/ocr_server/__init__.py index 5ae738a..036cc6f 100644 --- a/src/ocr_server/__init__.py +++ b/src/ocr_server/__init__.py @@ -1,11 +1,27 @@ +import logging + from ocr_server.app import app, create_app from ocr_server.config import Settings +from ocr_server.logging_setup import configure_logging __all__ = ["Settings", "app", "create_app"] +logger = logging.getLogger("ocr_server") + def main() -> None: import uvicorn settings = Settings() + configure_logging(settings.log_level) + logger.info( + "启动 OCR 服务 http://%s:%d workers=%d device=%s det=%s rec=%s model_dir=%s", + settings.host, + settings.port, + settings.ocr_workers, + settings.device, + settings.det_model_name, + settings.rec_model_name, + settings.model_dir, + ) uvicorn.run("ocr_server.app:app", host=settings.host, port=settings.port) diff --git a/src/ocr_server/app.py b/src/ocr_server/app.py index 00d8142..a294171 100644 --- a/src/ocr_server/app.py +++ b/src/ocr_server/app.py @@ -2,6 +2,7 @@ from fastapi import FastAPI, File, HTTPException, UploadFile, status from fastapi.responses import JSONResponse from ocr_server.config import Settings +from ocr_server.logging_setup import configure_logging from ocr_server.ocr import OCRService from ocr_server.schemas import ApiResponse, I2TData, I2TRequest from ocr_server.storage import ImageStore, InvalidImage @@ -10,6 +11,7 @@ from ocr_server.task_queue import OCRTaskQueue def create_app(settings: Settings | None = None) -> FastAPI: settings = settings or Settings() + configure_logging(settings.log_level) store = ImageStore(settings) def create_ocr() -> OCRService: diff --git a/src/ocr_server/config.py b/src/ocr_server/config.py index 83a078b..2624960 100644 --- a/src/ocr_server/config.py +++ b/src/ocr_server/config.py @@ -1,3 +1,4 @@ +import sys from pathlib import Path from typing import Any, Literal @@ -6,14 +7,22 @@ from pydantic import BaseModel, Field PROJECT_ROOT = Path(__file__).resolve().parents[2] -CONFIG_FILE = PROJECT_ROOT / "config.yaml" + + +def _runtime_root() -> Path: + if getattr(sys, "frozen", False): + return Path(sys.executable).resolve().parent + return PROJECT_ROOT + + +CONFIG_FILE = _runtime_root() / "config.yaml" class Settings(BaseModel): host: str = "127.0.0.1" port: int = Field(default=8000, ge=1, le=65535) - upload_dir: Path = PROJECT_ROOT / "data" / "uploads" - model_dir: Path = PROJECT_ROOT / "models" + upload_dir: Path = _runtime_root() / "data" / "uploads" + model_dir: Path = _runtime_root() / "models" det_model_name: str = "PP-OCRv5_server_det" rec_model_name: str = "PP-OCRv5_server_rec" ocr_workers: int = Field(default=1, ge=1, le=32) @@ -28,13 +37,14 @@ class Settings(BaseModel): text_det_unclip_ratio: float = Field(default=1.5, ge=0.1, le=5.0) text_rec_score_thresh: float = Field(default=0.0, ge=0.0, le=1.0) text_recognition_batch_size: int = Field(default=1, ge=1, le=64) + log_level: str = "INFO" def __init__(self, **overrides: Any) -> None: values = _read_config_file() values.update(overrides) for name in ("upload_dir", "model_dir"): path = Path(values[name]) - values[name] = path if path.is_absolute() else PROJECT_ROOT / path + values[name] = path if path.is_absolute() else _runtime_root() / path super().__init__(**values) @property diff --git a/src/ocr_server/logging_setup.py b/src/ocr_server/logging_setup.py new file mode 100644 index 0000000..6d3986a --- /dev/null +++ b/src/ocr_server/logging_setup.py @@ -0,0 +1,28 @@ +import logging +import sys + +LOG_FORMAT = "%(asctime)s %(levelname)-5s [%(name)s] %(message)s" +DATE_FORMAT = "%Y-%m-%d %H:%M:%S" + +LOG_LEVELS = { + "CRITICAL": logging.CRITICAL, + "ERROR": logging.ERROR, + "WARNING": logging.WARNING, + "INFO": logging.INFO, + "DEBUG": logging.DEBUG, +} + + +def resolve_level(name: str) -> int: + return LOG_LEVELS.get(str(name).upper(), logging.INFO) + + +def configure_logging(level: str | int = "INFO") -> None: + """Configure plain newline-terminated logs (never carriage-return progress bars).""" + resolved = resolve_level(level) if isinstance(level, str) else level + handler = logging.StreamHandler(sys.stdout) + handler.setFormatter(logging.Formatter(LOG_FORMAT, DATE_FORMAT)) + handler.terminator = "\n" + root = logging.getLogger() + root.setLevel(resolved) + root.handlers = [handler] diff --git a/src/ocr_server/ocr.py b/src/ocr_server/ocr.py index ac94794..7b69ad9 100644 --- a/src/ocr_server/ocr.py +++ b/src/ocr_server/ocr.py @@ -1,8 +1,15 @@ +import importlib +import logging import os +import sys import shutil import threading from pathlib import Path -from typing import Any +from typing import Any, Callable + +logger = logging.getLogger("ocr_server.ocr") + +ProgressCallback = Callable[[int, str], None] class OCRNotAvailable(RuntimeError): @@ -50,6 +57,8 @@ class OCRService: self._engine: Any | None = None self._lock = threading.Lock() self._inference_lock = threading.Lock() + self._progress_callback: ProgressCallback | None = None + self._progress_reached = 0 def _get_engine(self) -> Any: if self._engine is None: @@ -61,12 +70,72 @@ class OCRService: # Set it before importing PaddleOCR because PaddleX reads it at import time. os.environ["PADDLE_PDX_CACHE_HOME"] = str(self.model_dir) try: + # PaddleX checks optional extras through package metadata. A + # frozen bundle has the OCR-core modules but may not expose + # distribution metadata in the normal location. Patch the + # dependency gate before importing PaddleOCR, because the OCR + # pipeline decorator captures this module at import time. + import paddlex.utils.deps as paddlex_deps + + paddlex_deps.require_deps = lambda *args, **kwargs: None + paddlex_deps.require_extra = lambda *args, **kwargs: None + original_is_dep_available = paddlex_deps.is_dep_available + paddlex_deps.is_dep_available = lambda dep, /, **kwargs: ( + True + if dep + in { + "imagesize", + "opencv-contrib-python", + "pyclipper", + "pypdfium2", + "python-bidi", + "shapely", + } + else original_is_dep_available(dep, **kwargs) + ) + paddlex_deps.is_extra_available = lambda *args, **kwargs: True + paddlex_deps.pipeline_requires_extra = lambda *args, **kwargs: ( + lambda cls: cls + ) + paddlex_deps.EXTRAS = { + "ocr": {}, + "ocr-core": {}, + } from paddleocr import PaddleOCR + import pyclipper + processors = importlib.import_module( + "paddlex.inference.models.text_detection.processors" + ) + + # The detector imports pyclipper conditionally based on + # package metadata; bind it explicitly in every loaded + # module instance used by the frozen pipeline. + processors.pyclipper = pyclipper + sys.modules[processors.__name__].pyclipper = pyclipper + if getattr(sys, "frozen", False): + import paddlex.inference.pipelines.base as pipeline_base + + pipeline_base.DependencyError = type( + "DependencyError", (Exception,), {} + ) + paddlex_pipeline_base = importlib.import_module( + "paddleocr._pipelines.base" + ) + paddlex_pipeline_base.DependencyError = type( + "DependencyError", (Exception,), {} + ) except ImportError as exc: raise OCRNotAvailable( "PaddleOCR 未安装,请先安装项目依赖" ) from exc with self._process_model_lock: + logger.info( + "加载 OCR 引擎: det=%s rec=%s device=%s model_dir=%s", + self._det_model_name, + self._rec_model_name, + self.device, + self.model_dir, + ) self._engine = PaddleOCR( **self._model_arguments(), device=self.device, @@ -82,6 +151,8 @@ class OCRService: text_rec_score_thresh=self._text_rec_score_thresh, text_recognition_batch_size=self._text_recognition_batch_size, ) + self._install_progress_hooks(self._engine) + logger.info("OCR 引擎加载完成") return self._engine def prepare(self) -> None: @@ -114,16 +185,72 @@ class OCRService: if model_path.exists() and not self._is_complete_model(model_path): shutil.rmtree(model_path) - def recognize(self, image_path: Path) -> list[dict[str, Any]]: + def _emit_progress(self, percent: int, message: str) -> None: + """Report monotonic progress; never emits a lower percent than already reached.""" + if percent <= self._progress_reached: + return + self._progress_reached = percent + logger.debug("OCR 进度 %3d%% %s", percent, message) + callback = self._progress_callback + if callback is not None: + callback(percent, message) + + def _install_progress_hooks(self, engine: Any) -> None: + inner = self._inner_pipeline(engine) + 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, "文字识别完成") + + @staticmethod + def _inner_pipeline(engine: Any) -> Any | None: + try: + wrapper = engine.paddlex_pipeline + except AttributeError: + return None + return getattr(wrapper, "_pipeline", None) + + def _hook_model( + self, owner: Any, attribute: str, percent: int, message: str + ) -> None: + model = getattr(owner, attribute, None) + if model is None or getattr(model, "_ocr_progress_hooked", False): + return + + def wrapped(*args: Any, **kwargs: Any) -> Any: + def generate() -> Any: + yield from model(*args, **kwargs) + self._emit_progress(percent, message) + + return generate() + + wrapped._ocr_progress_hooked = True + setattr(owner, attribute, wrapped) + + def recognize( + self, + image_path: Path, + on_progress: ProgressCallback | None = None, + ) -> list[dict[str, Any]]: with self._inference_lock: + self._progress_callback = on_progress + self._progress_reached = 0 + self._emit_progress(5, "开始推理") + engine = self._get_engine() + self._emit_progress(10, "模型已就绪") + # Passing an ndarray avoids PaddleX treating Windows paths as URLs. import numpy as np from PIL import Image with Image.open(image_path) as image: image_array = np.ascontiguousarray(image.convert("RGB")) - results = self._get_engine().predict(input=image_array) - return self._parse_results(results) + self._emit_progress(20, "图片已解码,开始文字检测") + results = engine.predict(input=image_array) + lines = self._parse_results(results) + self._emit_progress(80, "文字识别完成") + return lines def _parse_results(self, results: Any) -> list[dict[str, Any]]: lines: list[dict[str, Any]] = [] diff --git a/src/ocr_server/task_queue.py b/src/ocr_server/task_queue.py index b5ef364..0b9aec4 100644 --- a/src/ocr_server/task_queue.py +++ b/src/ocr_server/task_queue.py @@ -1,5 +1,6 @@ from __future__ import annotations +import logging from dataclasses import dataclass, field from datetime import datetime, timezone from pathlib import Path @@ -12,6 +13,8 @@ from uuid import UUID from ocr_server.ocr import OCRService from ocr_server.schemas import OCRDocument, OCRLocation, OCRTextBox, TaskStatus +logger = logging.getLogger("ocr_server.task") + @dataclass class OCRTask: @@ -57,6 +60,9 @@ class OCRTaskQueue: with self._tasks_lock: self._tasks[file_id] = task self._queue.put(task) + logger.info( + "file_id=%s 已加入 OCR 队列 image=%s", file_id, image_path.name + ) return task def get(self, file_id: UUID) -> OCRTask | None: @@ -115,20 +121,31 @@ class OCRTaskQueue: def _run(self, task: OCRTask, ocr: OCRService) -> None: started_at = datetime.now(timezone.utc) started_clock = perf_counter() + + def report(percent: int, message: str) -> None: + with task._lock: + if percent <= task.progress: + return + task.progress = percent + logger.info("file_id=%s 进度 %3d%% %s", task.file_id, percent, message) + with task._lock: task.status = "processing" - task.progress = 10 task.ocr_started_at = started_at + logger.info( + "file_id=%s 开始处理 image=%s", task.file_id, task.image_path.name + ) + report(5, "任务开始,准备推理") try: + recognized = ocr.recognize(task.image_path, on_progress=report) + document = self.build_document(recognized) with task._lock: - task.progress = 20 - recognized = ocr.recognize(task.image_path) - with task._lock: - task.progress = 80 - task.result = self.build_document(recognized) + task.result = document task.progress = 100 task.status = "completed" + 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: task.status = "failed" task.progress = 100 @@ -137,6 +154,14 @@ class OCRTaskQueue: with task._lock: task.ocr_finished_at = datetime.now(timezone.utc) task.ocr_elapsed_ms = round((perf_counter() - started_clock) * 1000, 2) + status_value = task.status + elapsed_ms = task.ocr_elapsed_ms + logger.info( + "file_id=%s 处理结束 status=%s elapsed=%.2fms", + task.file_id, + status_value, + elapsed_ms, + ) @classmethod def build_document(cls, recognized: list[dict[str, Any]]) -> OCRDocument: diff --git a/tests/test_queue.py b/tests/test_queue.py index e0ffd66..0af0b42 100644 --- a/tests/test_queue.py +++ b/tests/test_queue.py @@ -5,7 +5,22 @@ from ocr_server.task_queue import OCRTaskQueue class FakeOCR: - def recognize(self, _: Path) -> list[dict]: + """Fake engine that mirrors OCRService.recognize and reports progress.""" + + def __init__(self) -> None: + self.progress: list[int] = [] + + def recognize(self, _: Path, on_progress=None) -> list[dict]: + for percent, message in ( + (5, "开始推理"), + (10, "模型已就绪"), + (20, "图片已解码,开始文字检测"), + (50, "文字检测完成"), + (80, "文字识别完成"), + ): + self.progress.append(percent) + if on_progress is not None: + on_progress(percent, message) return [ {"text": "Hello", "confidence": 0.95, "polygon": [[0, 0], [40, 0], [40, 10], [0, 10]]}, {"text": "世界", "confidence": 0.85, "polygon": [[45, 0], [85, 0], [85, 10], [45, 10]]}, @@ -43,3 +58,21 @@ def test_queue_completes_task() -> None: assert task.ocr_finished_at is not None assert task.ocr_elapsed_ms is not None assert queue.snapshot(file_id)[3] is not None + + +def test_progress_is_monotonic_and_includes_checkpoints() -> None: + from ocr_server.ocr import OCRService + + service = OCRService() + 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(10, "重复的低进度应被忽略") + service._emit_progress(50, "文字检测完成") + service._emit_progress(80, "文字识别完成") + service._emit_progress(100, "识别完成") + + assert seen == [5, 10, 20, 50, 80, 100] diff --git a/uv.lock b/uv.lock index f0a707a..ee2c599 100644 --- a/uv.lock +++ b/uv.lock @@ -152,6 +152,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/c2/56/ce14f76c1892f335fbcd82568d347fd1652e1a4b0b76ac4a4cd90e1ae202/aistudio_sdk-0.3.9-py3-none-any.whl", hash = "sha256:41621d052ddb7a58643438a7ca541f58ef0ab94a2acdfff0a71db81bf68dc027", size = 67186, upload-time = "2026-07-27T06:44:45.294Z" }, ] +[[package]] +name = "altgraph" +version = "0.17.5" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/7e/f8/97fdf103f38fed6792a1601dbc16cc8aac56e7459a9fff08c812d8ae177a/altgraph-0.17.5.tar.gz", hash = "sha256:c87b395dd12fabde9c99573a9749d67da8d29ef9de0125c7f536699b4a9bc9e7", size = 48428, upload-time = "2025-11-21T20:35:50.583Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/a9/ba/000a1996d4308bc65120167c21241a3b205464a2e0b58deda26ae8ac21d1/altgraph-0.17.5-py2.py3-none-any.whl", hash = "sha256:f3a22400bce1b0c701683820ac4f3b159cd301acab067c51c653e06961600597", size = 21228, upload-time = "2025-11-21T20:35:49.444Z" }, +] + [[package]] name = "annotated-doc" version = "0.0.5" @@ -908,6 +917,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/56/43/4ca9e49d27a1fcf6bece6f6aec0ea46bb9112489b93d4b688fb415457bdb/iniconfig-2.3.1-py3-none-any.whl", hash = "sha256:9121e2c1fdb355232495be3194c8dfe87ccc2d5dee45947b78e68f499790d7a7", size = 7552, upload-time = "2026-10-06T22:48:36.959Z" }, ] +[[package]] +name = "macholib" +version = "1.16.4" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "altgraph" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/10/2f/97589876ea967487978071c9042518d28b958d87b17dceb7cdc1d881f963/macholib-1.16.4.tar.gz", hash = "sha256:f408c93ab2e995cd2c46e34fe328b130404be143469e41bc366c807448979362", size = 59427, upload-time = "2025-11-22T08:28:38.373Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/c7/d1/a9f36f8ecdf0fb7c9b1e78c8d7af12b8c8754e74851ac7b94a8305540fc7/macholib-1.16.4-py2.py3-none-any.whl", hash = "sha256:da1a3fa8266e30f0ce7e97c6a54eefaae8edd1e5f86f3eb8b95457cae90265ea", size = 38117, upload-time = "2025-11-22T08:28:36.939Z" }, +] + [[package]] name = "modelscope" version = "1.40.2" @@ -1237,6 +1258,7 @@ dependencies = [ [package.dev-dependencies] dev = [ + { name = "pyinstaller" }, { name = "pytest" }, ] @@ -1252,7 +1274,10 @@ requires-dist = [ ] [package.metadata.requires-dev] -dev = [{ name = "pytest", specifier = ">=9.1.1" }] +dev = [ + { name = "pyinstaller", specifier = ">=6.22.3" }, + { name = "pytest", specifier = ">=9.1.1" }, +] [[package]] name = "opencv-contrib-python" @@ -1500,6 +1525,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/75/2e/e7b35b712edb068d382ddc8b2bea8a04974100515ba2daa22b478b265842/pandas-3.0.6-cp313-cp313-win_arm64.whl", hash = "sha256:cc39303913e2ea129915670de5d1c9fbd647f543bb72e5543bac8baa94e9e42f", size = 8952032, upload-time = "2026-09-17T23:21:37.729Z" }, ] +[[package]] +name = "pefile" +version = "2024.8.26" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/03/4f/2750f7f6f025a1507cd3b7218691671eecfd0bbebebe8b39aa0fe1d360b8/pefile-2024.8.26.tar.gz", hash = "sha256:3ff6c5d8b43e8c37bb6e6dd5085658d658a7a0bdcd20b6a07b1fcfc1c4e9d632", size = 76008, upload-time = "2024-08-26T20:58:38.155Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/54/16/12b82f791c7f50ddec566873d5bdd245baa1491bac11d15ffb98aecc8f8b/pefile-2024.8.26-py3-none-any.whl", hash = "sha256:76f8b485dcd3b1bb8166f1128d395fa3d87af26360c2358fb75b80019b957c6f", size = 74766, upload-time = "2024-08-26T21:01:02.632Z" }, +] + [[package]] name = "pillow" version = "11.3.0" @@ -1910,6 +1944,46 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/71/46/17f022dd3e953bf20a04a028a21ec746d942f8d2af30fa0f124fa0e6a684/pygments-2.21.0-py3-none-any.whl", hash = "sha256:2363c69b61c4a97c838da3b130dcd6468f4848992b21a82f2a63ec34377137d9", size = 1250147, upload-time = "2026-08-17T08:02:44.912Z" }, ] +[[package]] +name = "pyinstaller" +version = "6.22.3" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "altgraph" }, + { name = "macholib", marker = "sys_platform == 'darwin'" }, + { name = "packaging" }, + { name = "pefile", marker = "sys_platform == 'win32'" }, + { name = "pyinstaller-hooks-contrib" }, + { name = "pywin32-ctypes", marker = "sys_platform == 'win32'" }, + { name = "setuptools" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/63/41/f90302845945abd4ed647933ff5ee7c6ac93983187be67f897b6cb613331/pyinstaller-6.22.3.tar.gz", hash = "sha256:05eb2f5615503e72939a7224d68b4aff572c6b0438ee4a17d0a4b481f399362d", size = 4437180, upload-time = "2026-09-12T21:54:09.669Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ec/af/898f70947e27f8e65d55183c780e77112e023c0b4a6fba6255d4d563a27d/pyinstaller-6.22.3-py3-none-macosx_10_13_universal2.whl", hash = "sha256:052f4a1cd4f81092ccb7a18fe8ebc9ecf832a5917317e39fb3775af4e959b253", size = 1071847, upload-time = "2026-09-12T21:53:01.711Z" }, + { url = "https://files.pythonhosted.org/packages/c4/96/99f5184985141c2b024bfa61335e9142ae444555224f303186e59b7bb438/pyinstaller-6.22.3-py3-none-manylinux2014_aarch64.whl", hash = "sha256:312da84b4b31ab9750066a823734c11b7c68757fdd67c9f038bf19c330a954e4", size = 758172, upload-time = "2026-09-12T21:53:06.171Z" }, + { url = "https://files.pythonhosted.org/packages/69/9f/9ccb12cc1e6617042cb028fe79f0a756f5f03305bd14b584a4e043fe3844/pyinstaller-6.22.3-py3-none-manylinux2014_i686.whl", hash = "sha256:020d4fe0627f5c73dfbcfad1a6578ef354d5fe4bdccd9d8e5a615528f5a45d2b", size = 772135, upload-time = "2026-09-12T21:53:10.291Z" }, + { url = "https://files.pythonhosted.org/packages/c1/43/4b1d5193a88628c052db89f064433681076959a9f41d0d9f660001b49079/pyinstaller-6.22.3-py3-none-manylinux2014_ppc64le.whl", hash = "sha256:9e4f7bd64b2103f14b4a6240fb9155e9fe7bc61391b4043bbddb7d3ebc8ab0fa", size = 770461, upload-time = "2026-09-12T21:53:14.592Z" }, + { url = "https://files.pythonhosted.org/packages/cb/83/f173f8757c618d83e116fa2b8e57c5cd796e5ad09792e664eabd6ac5edae/pyinstaller-6.22.3-py3-none-manylinux2014_s390x.whl", hash = "sha256:f82d0fb89f21c3ed6f482ee16f341bc59e8a31dbabb9bae9ef04e53ade4dc0d9", size = 764997, upload-time = "2026-09-12T21:53:19.079Z" }, + { url = "https://files.pythonhosted.org/packages/7b/b6/dd21d61fc5e25377be24eabf13e99e4e46548a5abe2bf7b15d8b3d9cc74a/pyinstaller-6.22.3-py3-none-manylinux2014_x86_64.whl", hash = "sha256:451a4ae14b719365bf1a2f0a99dae7b3463060061c3a394c70d5264cfb439528", size = 764974, upload-time = "2026-09-12T21:53:23.176Z" }, + { url = "https://files.pythonhosted.org/packages/6c/fd/d9590942972b1fc205519f7ccffb0d5cd8eb1d6fa61edad319c71d25baed/pyinstaller-6.22.3-py3-none-musllinux_1_1_aarch64.whl", hash = "sha256:ea240b5dfa831ff673c97505eee0ec24670bccf71396c83109440348944c83d0", size = 764450, upload-time = "2026-09-12T21:53:27.419Z" }, + { url = "https://files.pythonhosted.org/packages/72/d6/f22c55d1768433b65c460b19a3136dd9769b6c74b786149b829344654c7d/pyinstaller-6.22.3-py3-none-musllinux_1_1_x86_64.whl", hash = "sha256:a2b6fc26601e8c2596c3d54981566934a3382e85d05d0fe91b55b6a8dcc6b282", size = 763863, upload-time = "2026-09-12T21:53:31.609Z" }, + { url = "https://files.pythonhosted.org/packages/c5/87/cf28cfd42ceca889171e6dd5e7f1553d4372db83d047049ffb7cf95fcbd4/pyinstaller-6.22.3-py3-none-win32.whl", hash = "sha256:46a3e30a118341a1ec20667a5a95aa7e0aa8c4fa129893c0151b3eb3f801a722", size = 1390905, upload-time = "2026-09-12T21:53:38.133Z" }, + { url = "https://files.pythonhosted.org/packages/24/83/c5422204772a27aef643280fdc887b7ef55679989096b21dceb1b9625fc4/pyinstaller-6.22.3-py3-none-win_amd64.whl", hash = "sha256:500bd58c7bf7e584a8435adccbd763a0b918d5c12b08d74ff50fd79b2915458b", size = 1454907, upload-time = "2026-09-12T21:53:44.812Z" }, + { url = "https://files.pythonhosted.org/packages/67/2e/ebc93968bf63f81b122e205da116b16036b653b7ce2cc8ad86e3ddd19586/pyinstaller-6.22.3-py3-none-win_arm64.whl", hash = "sha256:31df3cc4261e804a53d358b7897c293ec8b88b167a7cca06c78018085c855f97", size = 1402956, upload-time = "2026-09-12T21:53:51.369Z" }, +] + +[[package]] +name = "pyinstaller-hooks-contrib" +version = "2026.8" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "packaging" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/c9/3b/fab1a12a21bf9223af012e5dd002b7d4265683d21d9fabbd0ccb347316e4/pyinstaller_hooks_contrib-2026.8.tar.gz", hash = "sha256:4d825786ad7a9b7dbcc52d612748a34562fe273461bcfd88f4d549c594bbf8f9", size = 176955, upload-time = "2026-09-30T07:53:52.56Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/8f/f1/3eee0263b487e571aed9204257b45bc2a0b6fec34d0a1adade4d8d8a968c/pyinstaller_hooks_contrib-2026.8-py3-none-any.whl", hash = "sha256:6d21d65323ea4467753afc21f52d7d0e69416ae8101dd88269bf273ad48db084", size = 462145, upload-time = "2026-09-30T07:53:51.167Z" }, +] + [[package]] name = "pypdfium2" version = "5.14.0" @@ -2073,6 +2147,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/4f/ef/c66110d46fb800dda0bf33164182dfadabe26a90e4476844d502a23dca8e/pytz-2026.5-py2.py3-none-any.whl", hash = "sha256:e658af3757f9e26a9d25dd2aff38335acd92bc9104f890a894b2c1ba28311b03", size = 506342, upload-time = "2026-10-04T02:37:56.814Z" }, ] +[[package]] +name = "pywin32-ctypes" +version = "0.2.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/85/9f/01a1a99704853cb63f253eea009390c88e7131c67e66a0a02099a8c917cb/pywin32-ctypes-0.2.3.tar.gz", hash = "sha256:d162dc04946d704503b2edc4d55f3dba5c1d539ead017afa00142c38b9885755", size = 29471, upload-time = "2024-08-14T10:15:34.626Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/de/3d/8161f7711c017e01ac9f008dfddd9410dff3674334c233bde66e7ba65bbf/pywin32_ctypes-0.2.3-py3-none-any.whl", hash = "sha256:8a1513379d709975552d202d942d9837758905c8d01eb82b8bcc30918929e7b8", size = 30756, upload-time = "2024-08-14T10:15:33.187Z" }, +] + [[package]] name = "pyyaml" version = "6.0.2"