diff --git a/.gitignore b/.gitignore index 8ce2328..9348a4e 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,6 @@ http/fixtures/*.png dist*/ build/ *.spec + +# 打包产物的压缩包(体积可达数 GB),不要进仓库 +*.zip diff --git a/README.md b/README.md index 297da80..ee714cb 100644 --- a/README.md +++ b/README.md @@ -8,22 +8,21 @@ ocr-server/ ├── config.yaml # 项目配置文件(启动前修改) ├── http/ocr-server.http # IDEA / IntelliJ HTTP Client 测试请求 -├── models/ # 可随发布包分发的 PP-OCRv5 模型(约 166 MB) -│ └── official_models/ -│ ├── PP-OCRv5_server_det/ -│ └── PP-OCRv5_server_rec/ +├── models/ # 预置的 8 套 PP-OCR 模型(约 398 MB) +│ └── official_models/ # 发布包默认也读这里(见「模型路径」) ├── data/uploads/ # 上传图片运行时目录 ├── src/ocr_server/ -├── scripts/start.ps1 # Windows 源码/发布包启动 -├── scripts/start.bat # Windows 启动快捷方式 -├── scripts/start.sh # Ubuntu 源码/发布包启动 +├── scripts/start.ps1 # Windows 源码/发布包启动 +├── scripts/start.bat # Windows 启动快捷方式 +├── scripts/start.sh # Ubuntu 源码/发布包启动 ├── scripts/package-windows.ps1 # Windows exe 打包 +├── scripts/package-ubuntu.sh # Ubuntu ELF 打包 ├── scripts/packaged_entry.py # PyInstaller 入口 -├── scripts/package-ubuntu.sh # Ubuntu ELF 打包 -├── scripts/download-models.bat # Windows 下载/补齐模型 -├── scripts/download-models.sh # Ubuntu/Linux 下载/补齐模型 -├── scripts/download_models.py # Python 下载入口 -└── scripts/benchmark_ocr.py # 测量当前配置的 OCR 耗时 +├── scripts/switch_env.py # 建立/切换 CPU 与 GPU 两套虚拟环境 +├── scripts/install_paddle.py # 按显卡安装 CPU/GPU 版 paddlepaddle +├── scripts/download_models.py # 下载/补齐预置模型 +├── scripts/benchmark_ocr.py # 测量当前配置的 OCR 耗时与召回 +└── scripts/api_client.py # 命令行调用 OCR 接口 ``` ## 模型位置和下载策略 @@ -932,6 +931,35 @@ extract_include_empty: true 抽取发生在查询时(`/api/v1/i2t`),基于 `min_confidence` 过滤后的文本,因此改预设或调 `min_confidence` 不需要重新识别。`extract_fields` 留空(或删除该配置)即关闭此功能。 +### 命令行客户端 + +不想记接口细节就用 `scripts/api_client.py`,它只用标准库,不依赖 requests,可直接拷到别的机器上跑: + +```bash +# 服务默认在 http://127.0.0.1:8000,可用 --host 指定别的地址 +python scripts/api_client.py 图片.png +python scripts/api_client.py 图片1.png 图片2.png # 多张依次处理 +python scripts/api_client.py 图片.png --min-confidence 0.6 # 只要置信度 >= 0.6 的片段 +python scripts/api_client.py 图片.png --json # 打印原始 JSON 响应 +python scripts/api_client.py --health # 只探活 +``` + +输出示例: + +```text +服务 http://127.0.0.1:8000 正常:{'code': 0, 'message': 'success', 'data': {'status': 'ok'}} +[general_ocr_002.png] + 耗时 462.45 ms,34 个文本片段 + ── 识别文本 ──────────────────────────────────────── + PASS BOARDING 登机牌 + SEAT NO. 座位号 SERIAL NO. CLASS 序号 舱位 + ... +``` + +它做的事就是完整走一遍 `POST /api/v1/upload` → 轮询 `POST /api/v1/i2t`,把排队位置和进度打在 +同一行,结束后打印识别文本与抽取到的字段。`--timeout` 可调单张最长的等待秒数(默认 300, +GPU 首次推理有 10~20 秒预热,别设太短)。 + ## IDEA HTTP Client 测试 已提供: @@ -1350,6 +1378,31 @@ uv run python scripts/download_models.py 可以从 `src/ocr_server/ocr.py` 的 `STAGED_DET_MODELS` / `STAGED_REC_MODELS` 里删掉再重新下载,打包时 `models/` 目录里没有的自然不会被带上。 +#### 让发布包共用项目里的 models 目录 + +不想让每个发布包各带一份 398MB 模型,可以让它们都指向同一份。**只改发布包里的 +`config.yaml` 就行,不用重新打包**——`model_dir` 写绝对路径时原样使用: + +```yaml +model_dir: D:\code\work\ocr-server\models +``` + +改完启动日志里能直接看到用的是哪份模型,便于确认: + +```text +INFO [ocr_server] 启动 OCR 服务 ... model_dir=D:\code\work\ocr-server\models +``` + +当前 `dist/ocr-server/` 与 `dist/ocr-server-gpu/` 已经这样配好了。注意这条路要求 +**该目录在运行服务的机器上确实存在**;包内原本复制的 `models/` 此时不再被读取, +想省 398MB 可以删掉。 + +改发布配置用现成的脚本(它会保持 UTF-8,不会写坏中文注释): + +```bash +python scripts/prepare_release_config.py dist/ocr-server/config.yaml dist/ocr-server/config.yaml "model_dir=D:\code\work\ocr-server\models" +``` + ## 测试 ```bash diff --git a/scripts/api_client.py b/scripts/api_client.py new file mode 100644 index 0000000..09528df --- /dev/null +++ b/scripts/api_client.py @@ -0,0 +1,188 @@ +"""调用 OCR 服务的命令行客户端:上传图片 -> 轮询结果 -> 打印识别内容。 + +只用标准库,不依赖 requests/httpx,方便在任意机器上直接跑。 + +用法: + python scripts/api_client.py 图片.png + python scripts/api_client.py 图片1.png 图片2.png # 多张依次处理 + python scripts/api_client.py 图片.png --min-confidence 0.6 # 过滤低置信片段 + python scripts/api_client.py 图片.png --json # 打印原始响应 + python scripts/api_client.py --health # 只探活 + python scripts/api_client.py 图片.png --host http://192.168.1.10:8000 + +服务端接口(见 README「API」): + POST /api/v1/upload 上传图片,返回 file_id,任务进入队列 + POST /api/v1/i2t 用 file_id 查结果;未完成时返回 queued/processing 与进度 + GET /healthz 健康检查 +""" + +import argparse +import json +import mimetypes +import sys +import time +import urllib.error +import urllib.request +import uuid +from pathlib import Path + +DEFAULT_HOST = "http://127.0.0.1:8000" +POLL_INTERVAL_SECONDS = 0.5 +FINISHED_STATUSES = ("completed", "failed") + + +def post_json(url: str, payload: dict, timeout: float) -> dict: + request = urllib.request.Request( + url, + data=json.dumps(payload).encode("utf-8"), + headers={"Content-Type": "application/json"}, + method="POST", + ) + with urllib.request.urlopen(request, timeout=timeout) as response: + return json.loads(response.read().decode("utf-8")) + + +def upload_image(url: str, image_path: Path, timeout: float) -> dict: + boundary = "----ocrclient" + uuid.uuid4().hex + content_type = mimetypes.guess_type(image_path.name)[0] or "application/octet-stream" + head = ( + f"--{boundary}\r\n" + f'Content-Disposition: form-data; name="file"; filename="{image_path.name}"\r\n' + f"Content-Type: {content_type}\r\n\r\n" + ).encode("utf-8") + tail = f"\r\n--{boundary}--\r\n".encode("utf-8") + body = head + image_path.read_bytes() + tail + + request = urllib.request.Request( + url, + data=body, + headers={"Content-Type": f"multipart/form-data; boundary={boundary}"}, + method="POST", + ) + with urllib.request.urlopen(request, timeout=timeout) as response: + return json.loads(response.read().decode("utf-8")) + + +def wait_for_result( + host: str, file_id: str, timeout: float, quiet: bool, min_confidence: float +) -> dict: + """轮询 /api/v1/i2t 直到任务结束。中途把进度打到同一行。""" + deadline = time.monotonic() + timeout + last_progress = -1 + while time.monotonic() < deadline: + payload = post_json( + f"{host}/api/v1/i2t", + {"file_id": file_id, "min_confidence": min_confidence}, + timeout=30, + ) + data = payload.get("data") or {} + status = data.get("status") + if status in FINISHED_STATUSES: + if not quiet and last_progress >= 0: + print() # 结束进度行 + return data + if not quiet: + progress = data.get("progress", 0) + extra = "" + if status == "queued" and data.get("queue_position"): + extra = f" 排队第 {data['queue_position']} 位" + if progress != last_progress: + print(f"\r 进度 {progress:>3}% {status}{extra} ", end="", flush=True) + last_progress = progress + time.sleep(POLL_INTERVAL_SECONDS) + raise TimeoutError(f"等待超过 {timeout:.0f} 秒,任务仍未结束") + + +def print_result(data: dict, show_json: bool) -> None: + if show_json: + print(json.dumps(data, ensure_ascii=False, indent=2)) + return + + result = data.get("result") or {} + text = result.get("text", "") + polygon = result.get("polygon") or {} + print(f" 耗时 {data.get('ocr_elapsed_ms')} ms,{len(polygon)} 个文本片段") + if text: + print(" ── 识别文本 " + "─" * 40) + for line in text.splitlines(): + print(f" {line}") + fields = data.get("fields") + if fields: + print(" ── 抽取字段 " + "─" * 40) + for key, value in fields.items(): + print(f" {key}: {value}") + + +def process_one(host: str, image_path: Path, args: argparse.Namespace) -> bool: + print(f"[{image_path.name}]") + if not image_path.is_file(): + print(f" 文件不存在:{image_path}", file=sys.stderr) + return False + + try: + uploaded = upload_image(f"{host}/api/v1/upload", image_path, timeout=args.timeout) + except urllib.error.HTTPError as exc: + detail = exc.read().decode("utf-8", "ignore") + print(f" 上传失败 HTTP {exc.code}:{detail}", file=sys.stderr) + return False + except urllib.error.URLError as exc: + print(f" 连不上服务 {host}:{exc.reason}", file=sys.stderr) + return False + + file_id = (uploaded.get("data") or {}).get("file_id") + if not file_id: + print(f" 上传响应异常:{uploaded}", file=sys.stderr) + return False + + try: + data = wait_for_result(host, file_id, args.timeout, args.quiet, args.min_confidence) + except TimeoutError as exc: + print(f" {exc}", file=sys.stderr) + return False + + if data.get("status") == "failed": + print(f" 识别失败:{data.get('error')}", file=sys.stderr) + return False + print_result(data, args.json) + return True + + +def main() -> int: + parser = argparse.ArgumentParser(description="OCR 服务命令行客户端") + parser.add_argument("images", nargs="*", type=Path, help="要识别的图片路径") + parser.add_argument("--host", default=DEFAULT_HOST, help=f"服务地址,默认 {DEFAULT_HOST}") + parser.add_argument("--timeout", type=float, default=300.0, help="单张图片最长等待秒数") + parser.add_argument("--json", action="store_true", help="打印完整 JSON 响应") + parser.add_argument("--quiet", action="store_true", help="不打印轮询进度") + parser.add_argument("--health", action="store_true", help="只做健康检查") + parser.add_argument( + "--min-confidence", + type=float, + default=0.0, + help="只返回置信度不低于该值的片段(服务端过滤),默认 0 表示全要", + ) + args = parser.parse_args() + host = args.host.rstrip("/") + + # 先校验参数再探活:参数写错时不该因为连不上服务而报出误导性的错误。 + if not args.images and not args.health: + parser.error("请至少给一张图片路径(或用 --health 只探活)") + + try: + with urllib.request.urlopen(f"{host}/healthz", timeout=10) as response: + print(f"服务 {host} 正常:{json.loads(response.read().decode('utf-8'))}") + except urllib.error.HTTPError as exc: + print(f"服务 {host} 响应异常:HTTP {exc.code}", file=sys.stderr) + return 1 + except urllib.error.URLError as exc: + print(f"连不上服务 {host}:{exc.reason}", file=sys.stderr) + return 1 + if args.health: + return 0 + + failed = sum(0 if process_one(host, path, args) else 1 for path in args.images) + return 1 if failed else 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/scripts/prepare_release_config.py b/scripts/prepare_release_config.py index 2b670c3..d93e764 100644 --- a/scripts/prepare_release_config.py +++ b/scripts/prepare_release_config.py @@ -17,7 +17,9 @@ from pathlib import Path def apply_override(text: str, key: str, value: str) -> str: pattern = re.compile(rf"^{re.escape(key)}:.*$", re.MULTILINE) if pattern.search(text): - return pattern.sub(f"{key}: {value}", text, count=1) + # 必须用函数式替换:re.sub 会把替换串里的反斜杠当转义序列, + # Windows 路径(D:\code\...)会直接抛 "bad escape \c"。 + return pattern.sub(lambda _match: f"{key}: {value}", text, count=1) # 源文件里没有这一项(例如被注释掉了),追加到末尾。 return text.rstrip("\n") + f"\n{key}: {value}\n" diff --git a/tests/test_release_helpers.py b/tests/test_release_helpers.py index e2801ea..3eaf066 100644 --- a/tests/test_release_helpers.py +++ b/tests/test_release_helpers.py @@ -9,6 +9,7 @@ PREPARE_CONFIG = PROJECT_ROOT / "scripts" / "prepare_release_config.py" PADDLE_ENV = PROJECT_ROOT / "scripts" / "paddle_env.py" INSTALL_PADDLE = PROJECT_ROOT / "scripts" / "install_paddle.py" SWITCH_ENV = PROJECT_ROOT / "scripts" / "switch_env.py" +API_CLIENT = PROJECT_ROOT / "scripts" / "api_client.py" SAMPLE = """\ # 中文注释必须原样保留 @@ -101,6 +102,24 @@ def test_install_paddle_rejects_unknown_cuda_channel() -> None: assert result.returncode == 2 +def test_api_client_help_and_missing_args() -> None: + assert run_script(API_CLIENT, "--help").returncode == 0 + # 不给图片又不带 --health:argparse 应该报错退出(2) + assert run_script(API_CLIENT).returncode == 2 + + +def test_api_client_fails_cleanly_when_server_unreachable() -> None: + """服务不可达时要干净退出并给出可读提示,而不是抛未捕获的异常。 + + 不断言具体是「连接被拒」还是「HTTP 错误」:CI/沙箱里可能有透明代理, + 两者都会出现。真正要保证的是有明确报错、没有 traceback。 + """ + result = run_script(API_CLIENT, "--health", "--host", "http://127.0.0.1:1") + assert result.returncode == 1 + assert "http://127.0.0.1:1" in result.stderr + assert "Traceback" not in result.stderr + + def test_switch_env_list_reports_both_variants() -> None: """--list 只读,不能改动任何环境。""" result = run_script(SWITCH_ENV, "--list")