feat: 新增命令行 API 客户端,修复发布配置改写的反斜杠 bug

scripts/api_client.py:完整走一遍 upload -> 轮询 i2t -> 打印识别文本与抽取字段。
只用标准库(不依赖 requests),可直接拷到别的机器上跑;支持多图、
--min-confidence(服务端过滤)、--json、--health。参数校验放在探活之前,
参数写错时不会因为连不上服务而报出误导性错误。

scripts/prepare_release_config.py:re.sub 的**替换串**里反斜杠是转义序列,
写 Windows 路径(model_dir=D:\...)必然抛 "bad escape \c"。改用函数式替换。

.gitignore 补 *.zip:打包产物压出来有数 GB,别误提交。

README:补命令行客户端用法、发布包共用项目 models 目录的做法。

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
zimoyin
2026-10-14 11:59:39 +08:00
parent 5ab4bef80e
commit 0a299dec18
5 changed files with 278 additions and 13 deletions
+65 -12
View File
@@ -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