# OCR Server 基于 FastAPI 和 PaddleOCR **PP-OCRv5** 的图片文字识别服务,支持 Windows 和 Ubuntu 22.04(CPU;GPU 需要额外安装对应的 PaddlePaddle GPU 版本)。 ## 目录结构 ```text ocr-server/ ├── config.yaml # 项目配置文件(启动前修改) ├── http/ocr-server.http # IDEA / IntelliJ HTTP Client 测试请求 ├── 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/package-windows.ps1 # Windows exe 打包 ├── scripts/package-ubuntu.sh # Ubuntu ELF 打包 ├── scripts/packaged_entry.py # PyInstaller 入口 ├── 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 接口 └── scripts/GUI.html # 网页客户端,浏览器直接打开 ``` ## 模型位置和下载策略 当前已经预下载并放入项目目录: ```text models/official_models/PP-OCRv5_server_det models/official_models/PP-OCRv5_server_rec ``` 当前分发包内的模型是 PP-OCRv5 中文服务模型,总大小约 166 MB。模型文件只读使用,服务不会修改模型目录中的权重文件。 服务启动后不会立即加载模型。上传接口会立即把图片放入等待队列;第一次有工作线程开始识别时: 1. 优先检查 `model_dir/official_models/` 下的检测模型和识别模型; 2. 模型文件完整时,直接使用项目内模型,不访问网络; 3. 缺少任意模型时,只下载缺少的模型,并保存到同一个 `model_dir`; 4. 后续请求继续复用同一个进程内的 OCR 实例。 默认模型目录是项目根目录下的 `models`,可以直接修改项目根目录的 `config.yaml`: ```yaml model_dir: /opt/ocr-server-gpu/models ``` 配置文件中的路径支持绝对路径,也支持相对于项目根目录的路径。服务启动时读取一次配置,修改后需要重启服务。 也可以手动提前下载或补齐模型。推荐使用对应平台的快捷脚本: Windows(PowerShell / CMD): ```powershell scripts\download-models.bat ``` Ubuntu/Linux: ```bash chmod +x scripts/download-models.sh ./scripts/download-models.sh ``` 脚本会读取项目根目录的 `config.yaml`,把当前配置所需的检测模型和识别模型下载到 `model_dir/official_models/`。模型下载需要联网;完整分发包可以直接携带整个 `models/` 目录,从而不依赖首次启动联网。下载时不会覆盖已有完整模型目录。 也可以直接调用 Python 脚本: ```powershell uv run python scripts/download_models.py ``` 如果配置切换了模型名称,重新执行下载脚本即可补齐新模型。脚本不会删除或修改已有的其它模型目录。 ## 不同速度档位和模型选择 当前项目默认使用 **v5 检测 + v4 移动端识别** 的组合: ```yaml det_model_name: PP-OCRv5_server_det rec_model_name: PP-OCRv4_mobile_rec ``` 检测与识别可以独立指定,允许跨代际混用(本项目实测有效,见「推荐搭配」一节)。 `scripts/download_models.py` 已预置四套模型,切换时不需要联网。 | 档位 | 检测模型 | 识别模型 | 特点 | | --- | --- | --- | --- | | 低配 CPU | PP-OCRv5_mobile_det | PP-OCRv4_mobile_rec | 检测仅约 5MB,资源紧张时用 | | **当前默认** | PP-OCRv5_server_det | PP-OCRv4_mobile_rec | 保召回 + 识别快 8 倍,约 96MB | | 有 GPU | PP-OCRv5_server_det | PP-OCRv5_server_rec | 精度优先,配 `device: gpu` + `use_tensorrt` | | 速度优先(会丢字)| PP-OCRv4_mobile_det | PP-OCRv4_mobile_rec | ⚠️ v4 移动端检测在密集图上丢字约 90%,仅适合文本稀疏的图 | 切换前建议: 1. 先用 `scripts/benchmark_ocr.py` 和**真实业务图片**对比耗时、漏检率和**字符数**; 2. 只修改 `config.yaml` 的两个模型名(模型已预置,无需改 `model_dir`); 3. 验证不满意时,把模型名改回原值即可,不改动任何模型文件。 服务只读加载模型,不会修改权重。模型文件不在 git 里(`.gitignore` 已排除 `models/`), 但打包脚本会自动把 `models/` 复制进发布目录。 ### 当前推荐配置(实测最快且保召回) ```yaml det_model_name: PP-OCRv5_server_det # 检测保持 v5,保证召回 rec_model_name: PP-OCRv4_mobile_rec # 识别换移动端,快约 8 倍 enable_mkldnn: true # 依赖 paddlepaddle 3.2.x text_recognition_batch_size: 32 # 1.png 实测 23.87s -> 19.03s,输出不变 text_det_limit_side_len: 1024 # 比 640 多召回约 28% 字符 cpu_threads: 1 # 开 oneDNN 后几乎无影响,省核给 worker ocr_workers: 1 # 有并发上传时按核数加大 ``` 叠加效果(1.png,1920x1080,339 个文本框;经服务完整路径实测): | 配置 | 耗时 | 框数 | 字符数 | | --- | --- | --- | --- | | 初始状态(v5rec,3.3.1,无 oneDNN) | 729.39s | 339 | 1747 | | + 移动端识别(3.3.1,无 oneDNN) | 91.25s | 339 | 1746 | | + oneDNN(paddlepaddle 3.2.2) | **26.17s(约 27.9 倍)** | 339 | 1746 | **提速约 28 倍,而框数与字符数与精度优先档基本一致**,召回没有损失。 在这之上再调 `text_recognition_batch_size`(上表是 side=512 的数据,下表统一用 当前默认的 side=1024,同一台机器、同一张 1.png): | batch | 耗时 | 框数 | 字符数 | | --- | --- | --- | --- | | 8 | 23.87s | 428 | 2240 | | 16 | 21.62s | 428 | 2241 | | **32** | **19.03s** | 428 | 2241 | | 64 | 18.32s | 428 | 2238 | **框数完全一致,字符数只差 1~3 个**,调到 32 就能拿到大部分收益;换成 `64` 只再多省 0.7 秒,已经饱和。 ⚠️ 注意批次大小**不是逐字节一致**的:同一张 1.png,`batch=8` 得 2240 字符、 `batch=32` 得 2241 字符;官方样例图则是 253 → 250。逐条对比后确认,差异只出现在 **英文分词空格**(`日期 DATE` → `日期DATE`)和个别低置信字符(`高级搜索>` → `高级搜索>>`)上, 正文中文没有差异。切换 batch 仍建议核对一下真实图片的字符数。 同一配置下另外两张图(完整服务路径): | 图片 | 耗时 | 框数 | 字符数 | | --- | --- | --- | --- | | 2.png (1920x1080) | 7.49s(原 213.52s) | 73 | 430 | | general_ocr_002.png (896x528) | 8.01s(原 70.45s) | 35 | 245 | ### cpu_threads:开启 oneDNN 之后几乎不影响耗时 ```yaml cpu_threads: max # = os.cpu_count(),本机 20 逻辑核 → 20 cpu_threads: 1 # 当前默认 ``` **⚠️ 本节结论已更新。** 早期(未启用 oneDNN 时)确实需要靠线程数提性能, 但启用 oneDNN 后识别推理本身就已是多线程,再加线程不再获益。官方样例图 (896×528) 实测: ```text cpu_threads=1 -> 7.25s cpu_threads=4 -> 6.82s cpu_threads=8 -> 7.22s cpu_threads=14 -> 7.29s cpu_threads=20 -> 7.25s ``` 差异全部落在测量噪声内。所以**保持 `1` 即可**,把省下的核留给 `ocr_workers`(并发吞吐)或同机其它服务。 ### 不换模型的加速方式 不用换模型、不用动模型文件,先调这几个参数(按收益排序): ```yaml text_recognition_batch_size: 32 # 首选。1.png 实测 23.87s -> 19.03s,输出不变 text_det_limit_side_len: 768 # 其次。省约 3s,字符数约 -2% ocr_workers: 4 # 只在有并发上传时才有效,每个 worker 约 +105MB ``` `text_recognition_batch_size` 是性价比最高的旋钮:框越多收益越大,识别框数不变, 字符数只差 1~3 个(差异仅限英文分词空格与个别低置信字符)。调到 `32` 就能拿到 大部分收益,再往上饱和。 `text_det_limit_side_len` 主要影响检测耗时,调小会漏检小字,属于拿召回换速度, 务必用真实图片对比字符数后再定。详见下方「text_det_limit_side_len 与文本密度强相关」。 ## 日志与推理进度 服务使用普通换行日志,不使用 `\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` 字段与日志中的进度一致。 ### 为什么日志 handler 挂在 `ocr_server` logger 而不是 root ⚠️ 这是一个容易复现的坑,修改日志配置时请注意。 Paddle 在初始化推理引擎时会把 **root logger 的级别改成 `WARNING`**(实测:初始化前 `INFO`,初始化后变 `WARNING`)。如果日志 handler 挂在 root 上、依赖 root 的级别,那么从「加载引擎」开始的所有 `INFO` 日志都会被静默过滤,表现为: ```text 进度 5% 任务开始 加载 OCR 引擎: ... (此后 10% / 20% / 50% / 80% / 100% 全部消失) ``` 而接口其实是正常工作的(`progress` 字段仍会到 100),只是**日志被吞了**,非常容易误判为「卡住了」。 因此 `logging_setup.py` 把 handler 挂在 `ocr_server` logger 上,显式设置级别并 `propagate = False`,从而不受 Paddle 改动 root 的影响。`tests/test_logging.py` 里有对应的回归测试。 调整日志级别: ```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 秒 ← 主要瓶颈 ``` 注意:同一配置在不同时间实测波动较大(同一图片分别测到 66 秒和 128 秒),比较参数时请在相同时间段多测几次,不要只看单次结果。 ### 是否使用多核 不是单核推理。PaddleX 默认 `cpu_threads = 10`(可用 `cpu_threads` 配置项覆盖),测试机为 20 逻辑核 / 14 物理核,实测 CPU 占用: ```text 检测阶段 CPU 约 94%~105% (约 1 个核) 识别阶段 CPU 约 534%~686% (约 5.3~6.9 个核) 平均约 553%,即约 5.5 个核,20 核未跑满 ``` 结论: - 识别阶段是多线程的,约占 5~7 个核; - 检测阶段接近单核,这是关闭 oneDNN 后检测耗时约 13 秒的主要原因; - 20 核没有跑满,说明并行效率不高,瓶颈在「未启用 oneDNN 的 CPU 算子」,而不是核心数不够。 线程数对耗时的影响(同图、`batch 8`): ```text cpu_threads=4 约 114 秒 cpu_threads=10 约 60 秒 ``` 可调整 `cpu_threads` 实测,建议不超过物理核心数,并用 `benchmark_ocr.py` 对比。 关闭 oneDNN 是必须的:`enable_mkldnn=True` 会触发 PaddlePaddle 3.3.1 的缺陷并直接失败: ```text NotImplementedError: ConvertPirAttribute2RuntimeAttribute not support (at onednn_instruction.cc:118) ``` 因此该配置下慢的根因是「CPU 推理未启用 oneDNN」,不是队列或接口阻塞。 ### 让 oneDNN 可用:换 PaddlePaddle 版本(实测快 1.64 倍) `paddlepaddle 3.3.1` 是 PyPI 上当前最新版,它的 PIR + oneDNN 组合有缺陷,无法启用 oneDNN(`enable_new_ir=False` 也绕不过,因为新执行器是强制启用的)。 降级到 `paddlepaddle 3.2.2` 后 oneDNN 可正常启用。同一台机器、同一模型、同一张图、`cpu_threads=20`、`batch=8`,顺序执行无干扰: | PaddlePaddle | oneDNN | 识别耗时 | 行数 | | --- | --- | --- | --- | | 3.3.1 | 关闭(当前默认) | 84.01s | 34 | | 3.2.2 | 关闭 | 86.84s | 34 | | 3.2.2 | **开启** | **51.23s** | 34 | 结论: - **单纯降级不变快**(84.01s vs 86.84s,属于噪声),提速完全来自 oneDNN; - **3.2.2 + oneDNN 快 1.64 倍**; - 换 PaddlePaddle 版本**不换模型**,权重文件一个字节都不动。 #### oneDNN 是纯提速,不改变输出 同一环境下只切换 `enable_mkldnn` 开关,输出逐字节一致: ```text 官方样例图 paddle=3.3.1 mkldnn=False n=34 chars=252 md5=ecb944dadcdb 官方样例图 paddle=3.2.2 mkldnn=True n=34 chars=252 md5=ecb944dadcdb 1.png paddle=3.2.2 mkldnn=False predict=148.12s segments=452 chars=2374 md5=0ca69ecd7aaf 1.png paddle=3.2.2 mkldnn=True predict= 30.95s segments=452 chars=2374 md5=0ca69ecd7aaf ``` 1.png 上开启 oneDNN 后 **148.12s → 30.95s(快 4.8 倍)**,而 md5 完全相同。所以 oneDNN 只影响速度,不影响识别结果。 #### 降级版本本身不改变输出 项目环境内实测(同一模型、同一参数、同一张 1.png、`side=640`): | PaddlePaddle | oneDNN | 检测框数 | 字符数 | | --- | --- | --- | --- | | 3.3.1 | 关闭 | 339 | 1746 | | 3.2.2 | 开启 | 339 | 1746 | 同一配置连续跑 3 次,结果稳定为 339 框 / 1746 字符,说明**输出是确定性的,且 PaddlePaddle 版本不影响检测结果**,提速完全来自 oneDNN。 一次遗留说明:在项目外的独立虚拟环境里,同样的参数曾测到 452 框 / 2374 字符,与项目环境不一致。两个环境的依赖版本经比对完全相同(paddlepaddle 3.2.2 / paddleocr 3.7.0 / paddlex 3.7.2 / opencv 4.10.0.84 / numpy 2.3.5),模型目录也是同一个,**该差异原因未定位**。由于两个环境各自内部都重复稳定,且 oneDNN 的中性结论在两个环境分别验证过(各自开启/关闭输出 md5 一致),这不影响上述结论,但仍建议以项目环境(即实际服务环境)的实测为准。 #### 启用所需的改动(均已完成) 1. 依赖固定为 `paddlepaddle>=3.2,<3.3`(见 `pyproject.toml`,请勿手动升到 3.3.x); 2. `enable_mkldnn` 已作为配置项暴露,在 `config.yaml` 中设置即可(默认 `true`)。 本次验证在项目外的独立虚拟环境完成(`paddleocr 3.7.0` + `paddlex 3.7.2` + `paddlepaddle 3.2.2` 可正常推理),未改动你的项目环境和模型。 该提速与「v5 检测 + 移动端识别」的提速**相互独立、可以叠加**:1.png 从 729s 降到 30.95s(约 23.5 倍)。 ### 换成移动端模型:速度提升极大,但密集文本会严重丢字 ⚠️ 这一档**不适合文本密集的图片**,务必先用自己的图验证。 统一参数:`text_det_limit_side_len: 640`、`cpu_threads: 20`、`text_recognition_batch_size: 8`。 **稀疏图片(官方示例 896x528,文本少)** | 模型组合 | 体积 | 耗时 | 片段数 | 字符数 | | --- | --- | --- | --- | --- | | `PP-OCRv5_server_det` + `PP-OCRv5_server_rec` | 约 167 MB | 70.45s | 34 | 253 | | `PP-OCRv4_mobile_det` + `PP-OCRv4_mobile_rec` | 约 16 MB | 10.34s | 36 | — | 稀疏图上两者识别内容大体一致,移动端仅漏掉一行小字水印,看起来差异不大。 **密集图片(1920x1080,文本多)—— 差距是数量级的** | 图片 | 模型组合 | 耗时 | 片段数 | 字符数 | | --- | --- | --- | --- | --- | | 1.png | v5 server | 747.96s | 339 | 1747 | | 1.png | v4 mobile | **7.82s** | **46** | **166(仅剩 10%)** | | 2.png | v5 server | 213.52s | 73 | 428 | | 2.png | v4 mobile | **6.03s** | **27** | **243(剩 57%)** | 1.png 上移动端快了约 95 倍,但**丢掉了约 90% 的文字**。主要瓶颈在 `PP-OCRv4_mobile_det`:它只检出 46 个框,而 v5 server 检出 339 个,密集小字基本没检测出来。 结论: - 图片文本稀疏(票据、证件、少数字段)→ 移动端可用,收益巨大; - 图片文本密集(表格、文档、截图)→ **不要整体换成移动端**,检测器会大面积丢字; - 判断标准不是分辨率,而是**文本密度**,必须用自己的真实图片实测。 ### 推荐搭配:v5 检测 + 移动端识别 丢字的元凶是 `PP-OCRv4_mobile_det`(检测器),不是移动端识别模型。把检测保留 v5、只换识别,可以同时保住召回和速度。 1.png(1920x1080,339 个文本框),`text_det_limit_side_len: 640`、`cpu_threads: 20`、`batch: 8`: | 检测模型 | 识别模型 | 耗时 | 片段数 | 字符数 | | --- | --- | --- | --- | --- | | `PP-OCRv5_server_det` | `PP-OCRv5_server_rec` | 729.39s | 339 | 1747 | | `PP-OCRv5_server_det` | `PP-OCRv4_mobile_rec` | **91.25s** | 339 | **1746** | | `PP-OCRv4_mobile_det` | `PP-OCRv4_mobile_rec` | 7.82s | **46** | **166** | **快 8 倍,框数一致,字符数只差 1 个。** 识别阶段从 721s 降到 83.7s,说明瓶颈在识别模型,而移动端识别模型在密集文本上没有明显损失。 文本级对比(官方样例图,两者都是 35 个片段,检测模型相同): ```text v5rec : 登机牌|date|舱位|…|MU 2379|…|票号TKT NO.|…|起飞前1O分钟关闭GATESCLOSE1OMINUTESBEFORE DEPARTURETIME mobrec: 登机牌|DATE|舱位|…|MU2379|…|票号TKTNO.|…|起飞前10分钟关闭 GATESCLOSE10MINUTESBEFOREDEPARTURETIME ``` 该样本中移动端识别有两处反而更准:`date` 识别为 `DATE`、`前1O分钟` 识别为 `前10分钟`(v5 把数字 0 错认为字母 O)。主要差异只是空格分词方式。 配置写法(两个模型名可以独立指定、跨版本混用): ```yaml det_model_name: PP-OCRv5_server_det rec_model_name: PP-OCRv4_mobile_rec ``` 注意:混用不同代际的检测/识别模型属于非官方推荐组合,本项目实测可用且字符数一致,但仍请用你自己的图片验证后再上线。 ### text_det_limit_side_len 与文本密度强相关 对 1920x1080 的密集图片实测: | 边长 | 1.png | 2.png | | --- | --- | --- | | 640 | 339 框 / 1747 字符 | 73 框 / 428 字符 | | 320 | **0 框 / 0 字符** | 8 框 / 59 字符 | 1.png 在 320 下**完全检不出任何文字**:1920px 按 6 倍下采样后,约 10px 高的文字只剩约 1.7px。这不是平滑降精度,而是断崖式失效。 因此: - 大图请保持 `640` 或更高,**不要低于 640**; - `480` 以下只适合小尺寸、大字号的图片; - 检测耗时本身只占 1%~10%(上面两图分别是 7.9s 和 9.0s),压低它对总时长几乎没有帮助。 ### 识别耗时与文本框数量成正比 这是本项目的核心性能特征,来自实测: ```text 1.png 339 框 → 识别 740s (约 2.2 秒/框) 2.png 73 框 → 识别 204s (约 2.8 秒/框) 官方样例 34 框 → 识别 62s (约 1.8 秒/框) ``` 所以决定单张图耗时的是**框数**,而不是图片像素数。降低耗时的手段按有效性排序: 1. 减少框数(代价是丢字,例如提高 `text_det_box_thresh`); 2. 换更快的识别模型(注意上面的丢字风险); 3. 提高 `cpu_threads`、`text_recognition_batch_size`; 4. 让 oneDNN 可用(换 PaddlePaddle 版本)或使用 GPU。 切换方式(`config.yaml` 里已预置注释行,去掉注释即可): ```yaml det_model_name: PP-OCRv4_mobile_det rec_model_name: PP-OCRv4_mobile_rec ``` 模型文件需要存在于 `model_dir/official_models/` 下;不存在时首次识别会自动下载。当前仓库的 `models/official_models/` 已包含这两套移动端模型,改完配置重启即可离线切换。 切换前必须用 `benchmark_ocr.py` 和真实业务图片对比**字符数**:移动端体积小、速度快,但在文本密集的图片上会大面积丢字(实测 1.png 字符数只剩约 10%),详见上文「换成移动端模型」。这两个模型属于 PP-OCRv4,不是 PP-OCRv5。 其他提速方向: 1. 降低 `text_det_limit_side_len`(例如 `640`),可减少检测耗时; 2. 升级到 oneDNN 与 PIR 兼容的 PaddlePaddle 版本后再开启 `enable_mkldnn`; 3. GPU 部署。 ### 如何测速 ```powershell uv run --no-sync python scripts/benchmark_ocr.py 你的图.png 3 ``` ⚠️ **`--no-sync` 不能省**。`uv run` 默认会按 `pyproject.toml` 同步环境,而那里声明的是 CPU 版 `paddlepaddle`,会把装好的 `paddlepaddle-gpu` 静默冲掉——测出来的其实是 CPU 成绩。 修改 `config.yaml` 后重新执行,比较输出的 `elapsed_ms`、`segments`、`chars`。 建议至少使用 10 张代表性图片,不要只根据一张图片决定模型或参数;换模型或换设备时 **重点看 `segments` 和 `chars`**,只快不准是没用的。 ## Python 版本说明 本项目的 Python 版本约束是 `>=3.10,<3.14`,当前项目固定为 Python 3.12: ```text .python-version = 3.12 ``` 这次切换**没有修改系统全局 Python,也没有卸载 Python 3.15**。`uv python pin 3.12` 只修改了当前项目的 `.python-version` 文件;项目使用的 Python 3.12 是 uv 管理的独立解释器,位置是: ```text C:\Users\zimoyin\AppData\Roaming\uv\python\cpython-3.12-windows-x86_64-none\python.exe ``` 机器上原有的 Python 3.15 仍在: ```text C:\Users\zimoyin\AppData\Local\Python\pythoncore-3.15-64\python.exe ``` 项目虚拟环境位于: ```text D:\code\work\ocr-server\.venv\Scripts\python.exe ``` 在 Ubuntu 上,建议使用系统 Python 3.10–3.12 或 uv 创建项目虚拟环境,不会影响系统其他 Python 项目。 ### Windows 7:需要单独的 Python 3.8 构建 主包(Python 3.12)**无法在 Win7 上运行**:Win7 最高只支持 Python 3.8,exe 启动阶段会报缺 `api-ms-win-core-path-l1-1-0.dll`(Win8+ 才有)。 Win7 需要单独构建一版:**纯 CPU**、Python 3.8 + paddlepaddle 3.0.0。项目已经产出过一版: ```text dist/ocr-server-win7/ocr-server-win7.exe 约 993 MB(含 398 MB 模型) ``` 源码改动在分支 **`win7-python38`**(主分支保持 3.12,两者互不影响)。 #### 构建步骤 **1. 切到 Win7 分支。** 该分支已做 3.8 兼容:所有模块加 `from __future__ import annotations`, pydantic 模型(`config.py` / `schemas.py`)的注解改成 `Optional/List/Union`——pydantic 会 运行时求值注解,只加 future import 不够。 ```bash git checkout win7-python38 ``` **2. 建 Python 3.8 环境并装依赖。** ```powershell uv venv --python 3.8 .venv-win7 uv pip install --python .venv-win7\Scripts\python.exe ^ "crc32c==2.8" "paddleocr==3.7.0" "paddlepaddle==3.0.0" ^ "fastapi" "uvicorn[standard]" "pillow" "python-multipart" "pyyaml" "pyinstaller" ``` 三个版本限制,不要随手升级: | 包 | 限制 | 原因 | | --- | --- | --- | | `crc32c` | 必须 `2.8` | 更新的 2.9.post0 在 cp38 没有 Windows 轮子,会触发源码编译并失败 | | `paddlepaddle` | 只能 `3.0.0` | 3.2.x 没有 cp38 轮子 | | `uvicorn` | 会解析到 `0.33` | `>=0.34` 要求 Python >=3.9 | **3. 打包(必须排除 `bidi` 和 `watchfiles`)。** ```powershell .venv-win7\Scripts\python.exe -m PyInstaller --noconfirm --clean --onedir ^ --name ocr-server-win7 --distpath dist --paths src ^ --exclude-module bidi --exclude-module watchfiles ^ --collect-all paddleocr --collect-all paddlex --collect-all paddle ^ --collect-all cv2 --collect-all PIL --collect-all pyclipper ^ --collect-all pypdfium2 --collect-all shapely ^ --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" ^ --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 ``` > 为什么排除这两个:它们的原生扩展依赖 `api-ms-win-core-synch-l1-2-0.dll`(Win8+), > 在 Win7 上加载会失败。`watchfiles` 只在 `uvicorn --reload` 用;`bidi` 只用于阿拉伯语等 > RTL 模型的显示,中文识别用不到(源码里已去掉对它的强制可用性检查)。 **4. 后处理(三步都不能漏)。** ```powershell # 纯 CPU + 模型随包自带 python scripts/prepare_release_config.py config.yaml dist/ocr-server-win7/config.yaml "device=cpu" "model_dir=models" # 复制模型 cp -r models dist/ocr-server-win7/models # 删掉包内的 ucrtbase.dll,改用系统版 Remove-Item dist/ocr-server-win7/_internal/ucrtbase.dll ``` > 包内那份 `ucrtbase.dll` 来自较新的 Windows SDK,依赖 `api-ms-win-core-*-l1-2-0`(Win8+)。 > 删掉后由系统的 UCRT 接管(前提是目标机装了 KB2999226,见下)。 #### 目标机要求 - **Win7 SP1 + KB2999226**(Universal C Runtime),或直接安装 **VC++ 2015-2022 运行库**。 - **纯 CPU**:Win7 的 NVIDIA 驱动最高只到 472,而 CUDA 11.8 需要 520+,GPU 版不可用。 - 解压到普通目录再运行,例如 `D:\ocr-server-win7`。 #### 常见问题 **`Cannot open file ...\models\official_models\PP-OCRv5_server_det\inference.json`** ⚠️ **首要原因是安装路径里有中文**,不是模型缺失。Win7 的 ANSI 代码页是 GBK(936), 而 Paddle 的 C++ 层用 ANSI 接口做文件存在性检查:`IsFileExists()` 返回 0, 于是报「打不开」。 判断依据:程序只会在这四个文件都齐全时才去加载本地模型(`_is_complete_model()` 用的是 Python 的 `is_file()`),也就是说 **Python 认为文件存在、Paddle 的 C++ 层却认为不存在**—— 这是路径编码不一致,不是文件没拷全。 **解决:把整个包放到纯英文路径下再运行**,例如: ```text D:\ocr-server-win7\ocr-server-win7.exe ``` 不要放在 `C:\360极速浏览器X下载\`、`C:\Users\张三\Desktop\` 这类含中文的目录。 > 为什么开发和测试时没发现:本机 Win11 开启了「Beta: 使用 Unicode UTF-8 提供全球语言支持」 > (系统 ACP = 65001),中文路径在那种环境下能正常工作;Win7 默认 ACP = 936,行为不同。 > > 如果确实无法避免中文路径,可以先把模型复制到纯英文目录,再把 `config.yaml` 的 > `model_dir` 指过去,例如 `model_dir: D:\ocr-models`。 #### 备份与回退 Win7 构建只用独立的 `.venv-win7`,不影响 `.venv` / `.venv-gpu`。回退只需删除 `.venv-win7`。 完整构建环境记录在 `backups/env-win7-2026-10-19/`: | 文件 | 内容 | | --- | --- | | `BUILD-NOTES.md` | 构建配方、兼容性检查结果、已知坑 | | `freeze-win7.txt` | 85 个包的精确版本 | | `versions.txt` | 关键版本一览 | #### 更省事的替代方案 如果 Win7 那台机器只是**使用方**,不必本机跑 OCR:把服务放在 Win10+ / Linux 机器上, Win7 用浏览器打开 `scripts/GUI.html` 即可(需要 Chrome 109 或 Firefox 115 ESR; **IE11 不行**,不支持 `fetch`、可选链、`async/await`)。 ## Windows 安装和启动 源码启动: ```powershell cd D:\code\work\ocr-server uv sync powershell -ExecutionPolicy Bypass -File .\scripts\start.ps1 # 或双击 scripts\start.bat ``` ⚠️ **`start.*` 会优先跑 `dist\ocr-server\` 里的发布包**,找不到才退回源码(`.venv`)。 所以只要 `dist\` 里有旧包,**你改的源码就不会生效**,而且日志里看不出区别。 实测踩过一次:改了 `device` 相关的源码后启动,跑的还是几天前那个包, 配上新写的 `config.yaml`,直接崩在 PaddleX 内部。 判断方法看启动日志的 `model_dir`——指向 `dist\ocr-server\models` 就是跑的发布包: ```text INFO [ocr_server] 启动 OCR 服务 ... model_dir=D:\...\dist\ocr-server\models ← 发布包 INFO [ocr_server] 启动 OCR 服务 ... model_dir=D:\code\work\ocr-server\models ← 源码 ``` 改完源码要立刻验证,直接跑 `.venv\Scripts\ocr-server.exe`(Windows)或 `.venv/bin/ocr-server`(Linux),绕过发布包;要跑发布包就先重新打包。 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 host: 0.0.0.0 port: 8000 device: cpu ocr_workers: 1 ``` 然后启动: ```powershell uv run ocr-server ``` 也可以: ```powershell uv run python -m uvicorn ocr_server.app:app --host 0.0.0.0 --port 8000 ``` ## Ubuntu 22.04 安装和启动 适用于 Ubuntu 22.04 x86_64 CPU 环境(PaddlePaddle 官方 wheel 通常不覆盖 ARM 架构): ```bash sudo apt-get update sudo apt-get install -y curl libgl1 libglib2.0-0 cd /opt/ocr-server-gpu curl -LsSf https://astral.sh/uv/install.sh | sh # 重新打开 shell,或按安装提示加载 ~/.local/bin uv python install 3.12 uv sync --python 3.12 # paddle 不在依赖里,需按机器单独装一次;没有显卡就是 CPU 版 .venv/bin/python scripts/install_paddle.py # 按需修改项目根目录 config.yaml,然后启动 uv run --no-sync ocr-server ``` 如果服务器不能访问模型下载源,请在联网机器上执行 `scripts/download_models.py`,将完整项目的 `models/` 目录复制到 Ubuntu 服务器,再启动服务。依赖安装仍需要提前完成;完全离线安装还需要准备本地 Python wheel 缓存。 如果 Ubuntu 已经安装了兼容的 Python 3.10–3.12,也可以使用系统 Python(以实际可用的 `python3.10`、`python3.11` 或 `python3.12` 命令替换下面示例): ```bash python3.10 -m venv .venv .venv/bin/python -m pip install -U pip .venv/bin/python -m pip install -e . .venv/bin/python scripts/install_paddle.py .venv/bin/ocr-server ``` Ubuntu 源码启动: ```bash cd /opt/ocr-server-gpu uv sync --python 3.12 chmod +x scripts/start.sh ./scripts/start.sh ``` Ubuntu 22.04 打包为原生 ELF 二进制: ```bash cd /opt/ocr-server-gpu chmod +x scripts/package-ubuntu.sh ./scripts/package-ubuntu.sh # CPU 包 -> dist/ocr-server/ ./scripts/package-ubuntu.sh --gpu # GPU 包 -> dist/ocr-server-gpu/ ``` 发布目录(CPU 版与 GPU 版的目录名不同,一眼能分辨): ```text dist/ocr-server/ # CPU 版 ├── ocr-server ├── config.yaml └── models/ dist/ocr-server-gpu/ # GPU 版,另有 _internal/nvidia/ 下的 CUDA 运行库 ├── ocr-server-gpu ├── config.yaml └── models/ ``` 启动: ```bash ./dist/ocr-server/ocr-server # CPU 版 ./dist/ocr-server-gpu/ocr-server-gpu # GPU 版 # 或:./scripts/start.sh(优先 CPU 包,再 GPU 包,最后源码) ``` 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 ### 1. 上传图片 ```bash curl -X POST http://127.0.0.1:8000/api/v1/upload \ -F "file=@./receipt.jpg" ``` 返回示例(所有接口统一使用 `code`、`message`、`data`): ```json { "code": 0, "message": "success", "data": { "file_id": "b5a1e99c-9d7d-46f0-9e1e-1caa1fdc4e51", "filename": "receipt.jpg", "size": 123456, "width": 1600, "height": 1200, "status": "queued", "progress": 0, "queue_position": 1 } } ``` ### 2. 图片转文字 上传成功后图片会进入内存等待队列,默认由 1 个 OCR 工作线程按 FIFO 顺序识别。调用 `/api/v1/i2t` 时: - `queued`:任务还在等待,返回 `progress` 和 `queue_position`; - `processing`:任务正在识别,返回当前 `progress`; - `completed`:返回 JSON 识别结果; - `failed`:返回错误信息。 ```bash curl -X POST http://127.0.0.1:8000/api/v1/i2t \ -H "Content-Type: application/json" \ -d '{"file_id":"b5a1e99c-9d7d-46f0-9e1e-1caa1fdc4e51"}' ``` 未完成时返回示例: ```json { "code": 0, "message": "success", "data": { "file_id": "b5a1e99c-9d7d-46f0-9e1e-1caa1fdc4e51", "status": "processing", "progress": 20, "queue_position": null, "ocr_started_at": "2026-10-11T10:20:30.123456Z", "ocr_finished_at": null, "ocr_elapsed_ms": null, "result": null, "error": null } } ``` 完成时 `result` 使用紧凑的 JSON 对象映射: ```json { "text": "BOARDING PASS", "polygon": { "text1": { "text": "BOARDING", "confidence": 0.9841, "Location": { "xtop": 420, "ytop": 20, "xbottom": 660, "ybottom": 66 }, "line": 1, "paragraphs": 1 } } } ``` - 不再返回 `segments` 数组、`lines` 数组和 `paragraphs` 数组; - 每个 `textN` 对象包含文字、置信度、矩形坐标、行编号和段编号; - 同一行的 `line` 值相同; - 同一自然段的 `paragraphs` 值相同; - `Location` 包含 `xtop`、`ytop`、`xbottom`、`ybottom`。 两个检测框在同一文本行时会分配相同的 `line` 编号;相邻文本行属于同一自然段时会分配相同的 `paragraphs` 编号。可选 `min_confidence`(0–1)过滤低置信度片段,服务会重新计算行编号和段编号。 ### 3. 字段抽取(预设标签) 识别完成后可以按键值对抽取结构化字段,结果放在响应的 `data.fields` 里。 在 `config.yaml` 里配置预设: ```yaml extract_fields: - name: 姓名 aliases: [患者姓名, 病人姓名] pattern: '[一-鿿〇·]{1,12}' # 中文汉字 + 〇 + 间隔号,最多 12 字 max_length: 12 - name: 检查号 pattern: '[A-Za-z0-9-]{1,24}' max_length: 24 - name: 年龄 pattern: '\d{1,3}\s*岁' # 边界含匹配内容,结果会带「岁」 compact: true - name: 临床诊断 end_pattern: '[;;,,。]' # 终止符语义,不返回该标点 max_length: 50 extract_separators: [":", ":"] ``` 每个字段可用的配置项: | 配置项 | 说明 | 边界 | | --- | --- | --- | | `name` | 输出字段名,同时作为默认标签 | — | | `aliases` | 其他标签写法,可选 | — | | `compact` | `true` 时删除值内部所有空白(`43 岁` → `43岁`) | — | | `pattern` | **值内容正则**。从值起始处匹配,只取匹配到的部分;不匹配则该字段不返回 | **含**匹配内容 | | `end_pattern` | **结束正则**。值在此处截断 | **不含**匹配内容 | | `max_length` | 值最大字符数,超出则截断 | — | | `multiline` | 值是否允许跨行,默认 `false`(换行即结束) | — | | `occurrence` | 同名标签出现多次时取哪个,`first`(默认)或 `last` | — | | `separator_optional` | `true` 时标签后不带冒号也能抽(默认 `false`) | — | | `label_linebreak` | `true` 时允许标签内部跨行,如 `姓` + `名:`(默认 `false`) | — | | `row` | 只从第 N 行取值;`-1`(默认)不限定 | — | `pattern` 与 `end_pattern` 的边界语义相反,用途也不同: ```text pattern: '\d{1,3}\s*岁' → "43岁" (含,用来精确取形状) end_pattern: '[;;,,]' → "大便习惯改变" (不含,用来切掉终止符) ``` 正则写在**单引号**里即可,反斜杠不用转义(如 `'\d{1,3}'`)。正则写错会在**服务启动时**就报错,不会等到请求时才失败。 匹配与清洗规则: - **标签内部允许空白**:配置「姓名」也能匹配 OCR 识别出的「姓 名」「床 号」「镜 型」; - **同一行多个字段自动切分**:`检查号:26100830064姓名:万镭` 可同时抽出两个字段; - **值的结束位置**:下一个**已配置**标签 / `end_pattern` / 换行(除非 `multiline`)/ `max_length` / 文本结尾; - **自动清洗**:去掉零宽字符,任意空白(含换行)归一成单空格,去掉首尾空白、开头残留分隔符和结尾孤立标点(如 `;`); - **空值不返回**:`床号:` 后面没有内容时,该字段不会出现在结果里; - **同一字段取第一次出现的值**; - **必须带分隔符**:`姓名 万镭`(无冒号)不会被抽取。 ### 关于汉字字符类 `[一-鿿]` 写中文 pattern 时常用「字面范围」写法,比如 `[一-龥]`、`[一-鿿]`,含义是「某个 Unicode 范围内任意一个汉字」: | 写法 | 含义 | | --- | --- | | `一` | 汉字「一」,即范围内的第一个字 | | `-` | 表示范围 | | `龥` | U+9FA5,旧版 Unicode 里 CJK 基本区的最后一个字 | | `鿿` | U+9FFF,CJK 基本区(U+4E00–U+9FFF)真正的末位 | ⚠️ `[一-龥]`(到 U+9FA5)会漏掉两处,实测: ```text '二〇二六' → 只匹配到 '二' (〇 是 U+3007,不在基本区) '龦' → 不匹配 (U+9FA6,Unicode 4.1 之后新增) ``` 推荐写法(覆盖整个基本区并补上「〇」): ```yaml pattern: '[一-鿿〇]{1,12}' # 等价写法(用码位转义表示,结果相同): pattern: '[\u4e00-\u9fff〇]{1,12}' ``` 写法说明: - 单引号里的 `一` 不需要额外转义,Python 正则能直接识别;用码位写法更明确,不依赖「鿿」这种生僻字; - `〇`(U+3007)单独加上,用于「二〇二六」这类写法; - 少数民族姓名的间隔号 `·`(U+00B7)也要单独加,如 `[一-鿿〇·]`; - **CJK 扩展区(生僻姓氏,如 U+20000 以上)不在任何基本区范围内**。需要完整覆盖汉字时,Python 内置 `re` 做不到,只能用第三方 `regex` 模块的 `\p{Han}`;本项目未引入该依赖。 ### row:按行锁定字段位置 `row: N` 让字段只从**第 N 行**取值。行是由识别结果的**坐标**算出来的(bbox 纵向重叠的文本框归为同一行),所以「行」是真实的视觉行。 典型用途:报告的表头字段集中在固定几行,而正文或界面噪声里也会出现同样的字样,此时用 `row` 可以把它们排除掉。 一张真实报告截图的实测行结构(23 行): ```text 第 9 行 年龄:43岁性别:女检查号:26100830064姓名:万镭 第 10 行 镜型:CF-HQ290I床号:科室:消化内科门诊门诊号:701785075 第 11 行 临床诊断:大便习惯改变; ``` 注意这份材料里第 3 行还出现了 `报告-万镭`——正文同样含患者姓名。行为对比: ```text 不限定行 -> 姓名 = 张三 (取第一次出现,可能是页眉副本或正文) row: 9 -> 姓名 = 万镭 (精确锁定目标行) ``` 注意事项: - 行号随版面变化,**换模板就要重新确认行号**;锁定后如果没取到值会返回空(`include_empty: true` 时返回空串),不会静默取错; - 没有行信息时(例如直接调用库函数不传 `rows`),`row` 限定的字段取不到值,**不会退回全文**,避免误取; - `row` 与 `label_linebreak` 不要同时用:跨行标签在单行文本里不存在,会取不到值。 ### 其他开关 - **`separator_optional: true`**:标签后不带冒号也抽。代价是误命中率明显上升,只在冒号经常被 OCR 漏识时才打开。 - **`label_linebreak: true`**:允许标签内部跨行(`姓` + `名:`)。最多允许一个换行,避免把相隔很远的字拼成标签。 - **`extract_include_empty: true`**(全局):未命中的字段返回空串而非不出现,便于调用方用固定 schema 消费。 ```yaml extract_include_empty: true # -> {"姓名": "万镭", "床号": "", "镜型": "", ...} ``` ### 防止取错:机制与建议 已内置的防护: | 风险 | 机制 | | --- | --- | | 值粘连到下一个字段 | 值在**下一个已配置标签**前截断;再用 `pattern` 限定形状 | | 值吞掉后面的正文 | `end_pattern` 终止符、`max_length` 上限、默认换行即结束 | | 短标签嵌在长标签里(`号` vs `检查号`) | 匹配器**非重叠扫描 + 长标签优先**,同时配置时不会误命中 | | 值里出现别的标签字样(`姓名不详`) | 标签**必须紧跟分隔符**才算标签,故不会截断值 | | 低置信度噪声被抽成字段 | 抽取基于 `min_confidence` 过滤后的文本,调高该参数即可 | | 同名标签重复出现取错 | 用 `occurrence: last` 明确取最后一个 | | 配置冲突(标签被两个字段共用、字段名重复) | **服务启动时直接报错**,不会带病运行 | | 正则写错 | 启动时校验并报错 | | 不知道该值从哪来 | `log_level: DEBUG` 会输出每个字段的命中明细与未命中列表 | 使用建议: 1. **能用 `pattern` 就用**——它是性价比最高的手段,既约束形状又防止粘连: ```yaml pattern: '[A-Za-z0-9-]{1,24}' # 编号类 pattern: '\d{1,3}\s*岁' # 带单位的数值 pattern: '[一-鿿〇·]{1,12}' # 中文姓名 ``` 2. **把相邻字段都配上**,边界才生效(`姓名检查号` 这类粘连靠标签互相切分)。 3. **不要用过于宽泛的标签**,例如只配一个「号」,会把「检查号」「门诊号」都当成它。 4. **`compact: true` 要慎用**:它会删掉值里所有空格,地址类字段会被压成一串。 5. **`max_length` 只截断不报错**:需要「超长即视为未命中」时,用 `pattern` 的限定量词(如 `[一-鿿]{1,12}`)。 6. 上线前用**自己的真实样本**跑一遍,尤其注意同名标签重复、正副本这类场景。 ⚠️ **边界只对「已配置」的标签生效**。例如只配置了 `姓名` 时,`姓名:万镭性别:女` 中的 `性别:` 不是边界,值可能被吞成 `万镭性别`。两种解决办法: 1. 把相邻字段也配置上(推荐,`性别` 本身通常也要抽); 2. 用 `pattern` 限定形状,例如 `[一-龥·]{1,2}`、`\d+`、`[A-Za-z0-9-]+` —— 这是最稳的做法。 对一张真实报告截图的实测结果: ```json "fields": { "检查号": "26100830064", "姓名": "万镭", "性别": "女", "年龄": "43岁", "门诊号": "701785075", "科室": "消化内科门诊", "镜型": "CF-HQ290I", "临床诊断": "大便习惯改变" } ``` 抽取发生在查询时(`/api/v1/i2t`),基于 `min_confidence` 过滤后的文本,因此改预设或调 `min_confidence` 不需要重新识别。`extract_fields` 留空(或删除该配置)即关闭此功能。 ### 网页客户端(GUI.html) `scripts/GUI.html` 是个纯前端的网页客户端:填服务地址、选图片、看进度和识别结果, 双击用浏览器打开即可,不需要装任何东西。 浏览器里调接口属于跨域请求,所以服务端默认开了 CORS(`cors_allow_origins: ["*"]`, 见「配置」一节)。关掉它网页客户端就用不了,命令行脚本不受影响。 ### 命令行客户端 不想记接口细节就用 `scripts/api_client.py`,它只用标准库(不依赖 requests), 可直接拷到别的机器上跑: ```bash python scripts/api_client.py 图片.png python scripts/api_client.py 图片.png --min-confidence 0.6 python scripts/api_client.py --health ``` 常用参数(服务默认在 `http://127.0.0.1:8000`): | 参数 | 说明 | | --- | --- | | `图片1 图片2 …` | 要识别的图片,可给多个,依次处理 | | `--host URL` | 换服务地址,例如 `--host http://192.168.1.10:8000` | | `--min-confidence 0.6` | 只返回置信度 ≥ 0.6 的片段(服务端过滤,实测 0.999 时 34 段 → 2 段) | | `--json` | 打印完整 JSON 响应 | | `--quiet` | 不打印轮询进度 | | `--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 测试 已提供: ```text http/ocr-server.http ``` 在 IDEA 中打开文件,项目已附带 PaddleOCR 官方示例图片: ```text http/fixtures/general_ocr_002.png ``` 然后按顺序执行: 1. 健康检查; 2. 上传图片; 3. IDEA 自动保存上传响应中的 `file_id`; 4. 立即调用图片转文字接口,观察 `queued` / `processing` 进度; 5. 重复调用直到返回 `completed` 和 JSON 识别结果。 该测试图片来源于 PaddleOCR 官方示例。也可以把自己的图片复制到 `http/fixtures/`,再修改 `.http` 文件中的文件路径。 ## 配置 配置统一写在项目根目录的 `config.yaml`,服务启动时读取一次,修改后重启生效: ```yaml host: 127.0.0.1 port: 8000 upload_dir: data/uploads model_dir: models det_model_name: PP-OCRv5_server_det rec_model_name: PP-OCRv4_mobile_rec ocr_workers: 1 device: cpu lang: ch max_upload_mb: 10 max_image_pixels: 20000000 text_det_limit_side_len: 1024 text_det_limit_type: max text_det_input_shape: null text_det_thresh: 0.3 text_det_box_thresh: 0.6 text_det_unclip_ratio: 1.5 text_rec_score_thresh: 0.0 text_rec_input_shape: null text_recognition_batch_size: 32 cpu_threads: 1 enable_mkldnn: true mkldnn_cache_capacity: 10 use_tensorrt: false precision: fp32 enable_cinn: false log_level: INFO ``` | 配置项 | 默认值 | 说明 | | --- | --- | --- | | `host` | `127.0.0.1` | 监听地址 | | `port` | `8000` | 监听端口 | | `upload_dir` | `data/uploads` | 图片存储目录 | | `model_dir` | `models` | PaddleOCR 模型下载和缓存目录 | | `det_model_name` | `PP-OCRv5_server_det` | 文本检测模型名称 | | `rec_model_name` | `PP-OCRv4_mobile_rec` | 文本识别模型名称 | | `ocr_workers` | `1` | OCR 工作线程数;每个 worker 独立加载一份模型(约 +105MB/个) | | `max_upload_mb` | `10` | 单文件大小上限 | | `max_image_pixels` | `20000000` | 图片像素上限 | | `device` | `cpu` | `cpu` / `gpu` / `gpu:0` / `auto` / `npu` 等,见「CPU / GPU 切换」 | | `lang` | `ch` | PaddleOCR 语言 | | `text_det_limit_side_len` | `1024` | 检测图像最长边;调小可加速,代价是漏检小字 | | `text_det_limit_type` | `max` | 检测缩放限制类型 | | `text_det_input_shape` | `null` | 固定检测输入尺寸(如 `[3, 960, 960]`);`null` 表示动态缩放 | | `text_det_thresh` | `0.3` | 检测二值化阈值 | | `text_det_box_thresh` | `0.6` | 检测框置信度阈值 | | `text_det_unclip_ratio` | `1.5` | 检测框扩张比例 | | `text_rec_score_thresh` | `0.0` | 识别结果阈值 | | `text_rec_input_shape` | `null` | 固定识别输入尺寸(如 `[3, 48, 320]`);`null` 表示按宽高比填充 | | `text_recognition_batch_size` | `32` | 识别批量大小;**性价比最高的旋钮**,见下方说明 | | `cpu_threads` | `1` | CPU 推理线程数;正整数或 `max`。开 oneDNN 后该值几乎无影响 | | `enable_mkldnn` | `true` | 是否启用 oneDNN 加速;**需要 `paddlepaddle` 3.2.x**,见下方说明 | | `mkldnn_cache_capacity` | `10` | oneDNN 算子缓存容量,仅 `enable_mkldnn: true` 时生效 | | `use_tensorrt` | `false` | 是否启用 TensorRT;**只在 `device` 为 GPU 时生效** | | `precision` | `fp32` | `fp32` / `fp16`;`fp16` 只在 GPU 上生效 | | `enable_cinn` | `false` | 是否启用 CINN 编译器(面向国产加速卡);普通 CPU/GPU 保持 `false` | | `cors_allow_origins` | `["*"]` | 允许跨域的来源,只影响网页客户端;`[]` 表示关闭 | | `log_level` | `INFO` | 日志级别:`DEBUG`、`INFO`、`WARNING`、`ERROR` | 接口文档:启动后访问 。 ### 调优参数速查(按收益排序) | 参数 | 怎么调 | 实测收益 | | --- | --- | --- | | `text_recognition_batch_size` | `8` → `32` | 1.png 同分辨率 **23.87s → 19.03s**,框数不变,字符数 2240 → 2241 | | `text_det_limit_side_len` | `1024` → `768` | 19s → 16s,字符数从 2240 降到 2191(约 −2%) | | `ocr_workers` | 按并发量加大 | 推理接近单线程,并发上传时吞吐接近线性;每个 worker 约 +105MB 内存 | | `cpu_threads` | 保持 `1` | 开了 oneDNN 之后 1/4/8/14/20 差异都在噪声内 | | `device` / `use_tensorrt` | 有 NVIDIA 卡时改 GPU | 需换 `paddlepaddle-gpu`,见「CPU / GPU 切换」 | ### CPU / GPU 切换 ```yaml device: cpu # 默认。固定用 CPU,永远不碰 GPU device: gpu # 固定用第 0 块卡 device: gpu:1 # 固定用第 1 块卡 device: auto # 启动时探测:有可用 CUDA 设备就用 GPU,否则用 CPU ``` **推荐用 `auto`**:同一份 `config.yaml` 在「有卡的开发机」和「没卡的客户机」之间 搬来搬去不用改这一行,日志里会明确打出实际选了什么: ```text INFO [ocr_server.ocr] device=auto:检测到可用的 CUDA 设备,使用 GPU INFO [ocr_server.ocr] device=auto:没有可用的 GPU(当前 PaddlePaddle 3.2.2 是纯 CPU 版本),使用 CPU ``` 注意日志级别的区别:`auto` 探测不到卡是**预期行为**,报 INFO; 而显式写了 `device: gpu` 却用不了是**配置问题**,报 WARNING。 本机上三种取值的实际效果(有 RTX 5060,但装的是 CPU 版 paddle): | 配置 | 实际使用 | 日志级别 | | --- | --- | --- | | `device: auto` | cpu | INFO | | `device: cpu` | cpu | — | | `device: gpu` | cpu(回落) | WARNING | ⚠️ **只改 yaml 是启不了 GPU 的。** PyPI 上的 `paddlepaddle` 是纯 CPU 版本, 需要换成 `paddlepaddle-gpu`: ```bash # 先确认本机显卡型号和驱动版本 nvidia-smi ``` **先选对 CUDA 通道,选错装了也跑不起来**(见下表)。当前项目环境实测是 `paddlepaddle 3.2.2`(CPU 版),`is_compiled_with_cuda()` 为 `False`。 | 显卡 | 计算能力 | 该选哪个通道 | | --- | --- | --- | | RTX 50 系(5060 / 5070 / 5080 / 5090) | sm_120 Blackwell | **必须 `cu129`** | | RTX 40 系 / 30 系 | sm_89 / sm_86 | `cu126` 或 `cu129` | | 更老的卡 | ≤ sm_80 | `cu118` 也可以 | ⚠️ **RTX 50 系不能用 `cu118` / `cu126`**:这两个 wheel 的内核里没有 sm_120, 装上去会在第一次推理时抛 `Mismatched GPU Architecture: The installed PaddlePaddle package was compiled for 60 61 70 75 80 86, but your current GPU is 120`。 必须用 `cu129`,且 PaddlePaddle 版本要 ≥ 3.2.1。 ### 两套环境共存,随时切换(推荐) CPU 和 GPU **各用一套虚拟环境**,都建好之后切换是零成本的,不用卸载重装: ```bash .venv/Scripts/python.exe scripts/switch_env.py --list # 查看两套环境的现状 .venv/Scripts/python.exe scripts/switch_env.py --cpu # 建立/更新 .venv(CPU) .venv/Scripts/python.exe scripts/switch_env.py --gpu # 建立/更新 .venv-gpu(GPU) ``` ```text CPU 环境 .venv paddlepaddle==3.2.2 | CUDA 可用:False,GPU 数:0 GPU 环境 .venv-gpu paddlepaddle-gpu==3.2.2 | CUDA 可用:True,GPU 数:1 ``` | 用途 | 命令 | | --- | --- | | 跑源码(CPU) | `.venv\Scripts\ocr-server.exe` | | 跑源码(GPU) | `.venv-gpu\Scripts\ocr-server.exe` | | 打 CPU 包 | `.\scripts\package-windows.ps1` | | 打 GPU 包 | `$env:UV_PROJECT_ENVIRONMENT=".venv-gpu"; .\scripts\package-windows.ps1` | 之所以不做成「一个环境来回切」:`paddlepaddle` 与 `paddlepaddle-gpu` 互斥(都提供 `paddle` 顶层包和同一批文件),而且 GPU 版还要拖进约 **3.1GB** 的 CUDA 运行库, 反复装卸很浪费。代价是两套环境同时存在,磁盘多占约 4GB。 ### 只要一套环境时 装的方式是用项目自带的脚本,它会读 `nvidia-smi` 自动判断装哪个版本和哪个 CUDA 通道: ```bash uv run --no-sync python scripts/install_paddle.py # 有 N 卡就装 GPU 版,没有就装 CPU 版 uv run --no-sync python scripts/install_paddle.py --gpu # 强制 GPU 版,通道按显卡自动推荐 uv run --no-sync python scripts/install_paddle.py --cpu # 强制 CPU 版(顺带清掉 3GB 的 CUDA 库) uv run --no-sync python scripts/install_paddle.py --gpu --dry-run # 只看方案,不动环境 ``` 想手工装也行,等价命令是: ```bash uv pip uninstall paddlepaddle paddlepaddle-gpu uv pip install "paddlepaddle-gpu==3.2.2" \ --extra-index-url https://www.paddlepaddle.org.cn/packages/stable/cu129/ ``` > **为什么 `paddlepaddle` 不在 `pyproject.toml` 的依赖里?** > 因为它没法写死:CPU 版和 GPU 版互斥(同一批 `paddle` 文件,装了会互相覆盖), > GPU 版还要按显卡选 CUDA 通道。早先把它钉成 CPU 版时,`uv sync`、`uv run`、 > PyCharm 的自动同步都会把装好的 `paddlepaddle-gpu` 静默挤掉、服务悄悄退回 CPU—— > 实测踩过三次。 > > 现在的取舍是:**任何一次环境同步都会把 paddle 整个移除**(连 `protobuf`、`opt-einsum` > 这些依赖一起),服务启动时报错并告诉你运行 `install_paddle.py`。 > 会吵,但不会静默降级。**每次跑完 `uv sync` 记得重新执行一次 `install_paddle.py`。** **注意:不要用 PyPI 上的 `paddlepaddle-gpu`**——它停在 2.6.2 且早已废弃, 装上去和本项目的 PaddleOCR 3.x / paddlepaddle 3.2.x 对不上。 只能用 PaddlePaddle 官方源,实测该源上 `cu118` / `cu126` / `cu129` 三个通道 都有 `paddlepaddle_gpu-3.2.2` 的 Windows 与 Linux 轮子。 ⚠️ **RTX 50 系要留个心眼**:社区反馈 Blackwell 的预编译 wheel 支持还不够完整, 官方主要在 PaddleOCR-VL 上验证过(且只验证了 RTX 5070),经典 PP-OCR 推理管线 (也就是本项目用的这套)在部分平台仍有缺口,Windows 上尤其明显。 换完 wheel 后**务必先用 `benchmark_ocr.py` 跑通一次真实图片**再决定是否上 GPU; 跑不通就退回 CPU 包,不要卡在这里。 #### 装完之后能自由切换吗?能 GPU 版 wheel 里**同时带着完整的 CPU 内核**,PaddleX 在 `device` 为 cpu 时会显式 `config.disable_gpu()`,所以三种取值随时可切、不需要重装: | 配置 | 行为 | | --- | --- | | `device: cpu` | 强制 CPU,走 oneDNN | | `device: gpu` / `device: auto` | 走 GPU | 实测(RTX 5060 Laptop,paddlepaddle-gpu 3.2.2 cu129): | 图片 | CPU | GPU | 加速 | 框数 | 字符数 | | --- | --- | --- | --- | --- | --- | | 1.png(1920×1080,428 框) | 17.45s | **1.44s** | **12×** | 428 → 428 | 2241 → 2241 | | general_ocr_002.png(34 框) | 6.89s | **0.23s** | **30×** | 34 → 34 | 250 → 250 | 框数与字符数和 CPU **完全一致**——在这两张图上没有复现社区报告的 sm_120 静默丢框问题。 但**上线前必须用你自己的真实图片再核一遍**(尤其是扫描件 / PDF 渲染图, 社区那个 bug 正是在这类图上出现的,手机照片反而正常)。 #### ⚠️ `uv sync` / `uv run` 会把 GPU 环境悄悄冲掉 `pyproject.toml` 里声明的是 CPU 版 `paddlepaddle`。**裸跑 `uv sync` 或 `uv run`** (`uv run` 启动前也会同步一次)的结果是**卸载 `paddlepaddle-gpu` 和全部 `nvidia-*` 运行库、装回 CPU 版**,而且不报错: ```text Would uninstall 9 packages - nvidia-cublas-cu12==12.9.0.13 ...(7 个 nvidia-* 运行库) - paddlepaddle-gpu==3.2.2 + paddlepaddle==3.2.2 ``` 项目里的脚本都已经处理好了: | 场景 | 处理方式 | | --- | --- | | 打包脚本 | `uv sync --dev --inexact --no-install-package paddlepaddle`(实测 dry-run 为 no changes),其余 `uv run` 全部加了 `--no-sync` | | 启动脚本 | 优先直接执行 `.venv` 里的入口程序,不经过 uv;不得已走 uv 时用 `uv run --no-sync` | | `benchmark_ocr.py`、`download_models.py` | 命令里都要求带 `--no-sync` | **但你自己手动敲 `uv sync` 或 `uv run` 时它照样会冲掉。** 装完 GPU 后如果发现 「怎么又变回 CPU 了」,先想想是不是跑过这两个命令。判断方法看启动日志: ```text INFO [ocr_server.ocr] device=auto:检测到可用的 CUDA 设备,使用 GPU ← 正常 INFO [ocr_server.ocr] device=auto:没有可用的 GPU(当前 PaddlePaddle 3.2.2 是纯 CPU 版本)… ← 被冲掉了 ``` (单独用 `--no-install-package paddlepaddle` 不够:它会把 `paddlepaddle-gpu` 当多余包删掉; 单独用 `--inexact` 也不够:它会装上 CPU 版造成两个发行包并存、文件互相覆盖。必须两个合用。) #### 交付包:CPU / GPU 是两个产物 **光改配置在交付的 exe 包里是没用的**:PyInstaller 会把打包那一刻的 paddle 打进产物, CPU 包无论客户怎么改 yaml 都用不了 GPU。所以交付时打两个包: ```powershell # CPU 包 -> dist\ocr-server\ocr-server.exe .\scripts\package-windows.ps1 # GPU 包 -> dist\ocr-server-gpu\ocr-server-gpu.exe # 用 switch_env.py 建好的 GPU 环境来打,它会自动识别成 GPU 变体 $env:UV_PROJECT_ENVIRONMENT=".venv-gpu" .\scripts\package-windows.ps1 ``` ```bash # Linux 同理 ./scripts/package-ubuntu.sh # CPU 包 -> dist/ocr-server/ ./scripts/package-ubuntu.sh --gpu # GPU 包 -> dist/ocr-server-gpu/ ``` 打包脚本会自动做这几件事,不需要手工干预: | 行为 | 说明 | | --- | --- | | 自动识别变体 | 按构建环境实际安装的 paddle 判断,不靠人工声明 | | 产物名区分变体 | CPU → `dist/ocr-server/`,GPU → `dist/ocr-server-gpu/`,两个包不会互相覆盖 | | 预置 `device` | GPU 包的 `config.yaml` 里 `device` 写成 `auto`:客户机有卡就用卡、没卡自动回落 CPU,两种机器都能直接跑 | | `--copy-metadata` 用对发行包名 | CPU 版叫 `paddlepaddle`、GPU 版叫 `paddlepaddle-gpu`,写死任何一个在另一种环境下都会打包失败 | | 环境不匹配直接报错 | 加 `-Gpu` / `--gpu` 断言时,如果构建环境装的是 CPU 版,脚本会带着安装命令报错退出 | `-Gpu` / `--gpu` 只是**断言**,不是开关:不加该参数时脚本也按实际安装的版本判断。 ⚠️ **不要指望 GPU 包能当 CPU 包用。** 运行时的兜底(`device: auto` / `device: gpu`) 只能兜住「能 import paddle、但拿不到 CUDA 设备」这一种情况。如果客户机上 根本没有 NVIDIA 的 CUDA 运行库,`paddlepaddle-gpu` 可能在 **import 阶段**就报错 (典型是缺 `libcublasLt.so.12` 这类),那时候我们的兜底代码还没机会执行。 PaddlePaddle 官方安装指南的口径也是「没有 NVIDIA GPU 就装 CPU 版」。 所以:**确定没卡的客户机,发 CPU 包**;不确定的,两个包都带上。 变体没有「强制」开关:产物里打进的就是构建环境当前的 paddle,改个名字不会改变这一点, 只会让包名和内容对不上。要打 CPU 包就换回 CPU 版 paddle 再打。 #### GPU 包必须额外收 nvidia 运行库(打包脚本已处理) `paddlepaddle-gpu` 的 CUDA 运行库(cudnn / cublas / cufft 等)不在 `paddle` 包里, 而是装在**独立的 `nvidia-*` 发行包**里。PyInstaller 的 `--collect-all paddle` 收不到它们, 所以 GPU 包额外加了 `--collect-binaries nvidia`。 漏收的后果实测是**最难排查的那种**:引擎能正常加载、设备也正确识别成 GPU, 但第一次推理才报错: ```text PreconditionNotMetError: The third-party dynamic library (cudnn64_9.dll) that Paddle depends on is not configured correctly. (error code is 126) ``` 收进来的落点是 `_internal/nvidia/<包>/bin/`,正好是 paddle 在 `__init__.py` 里用 `os.add_dll_directory(os.path.dirname(paddle.__file__) + "/../nvidia/<包>/bin")` 寻找的路径。 **体积**(实测):CPU 包约 1.0GB;GPU 包约 **5.0GB**,其中 3.1GB 是 CUDA 运行库 (cudnn 1.06GB、cublas 736MB、cusparse 456MB、cusolver 442MB、cufft 275MB…), 源目录本身就那么大,不是重复打包。要瘦身只能砍裁用不到的库,有运行时踩坑风险。 开启 GPU 后还可以叠加: ```yaml device: gpu use_tensorrt: true # TensorRT 加速,首次推理会花时间构建引擎 precision: fp16 # 半精度,更快、显存更省,但需核对字符数 ``` **兜底行为**:如果配了 `device: gpu`(或 `auto`)但 GPU 实际不可用, 启动时会打印中文日志并**自动回落 CPU**,不会让服务起不来。 检查覆盖两种情况,不只是「装没装 GPU 版」: - 装的是纯 CPU 版 paddle → 直接回落; - 装的是 GPU 版但**机器上没有可用的 N 卡或驱动** → 也会回落 (这一点单查 `is_compiled_with_cuda()` 是查不出来的,那是编译期属性, 装了 GPU 版就返回 True,所以还要实际探一次可见设备数)。 上线前请确认启动日志里「加载 OCR 引擎」那一行打印的 `device=` 是你期望的值: ```text WARNING [ocr_server.ocr] 配置 device=gpu,但 GPU 无法启用:当前 PaddlePaddle 3.2.2 是纯 CPU 版本。… WARNING [ocr_server.ocr] use_tensorrt 已开启,但生效设备是 cpu;TensorRT 只在 GPU 上生效,本次忽略该项。 INFO [ocr_server.ocr] 加载 OCR 引擎: det=… rec=… device=cpu cpu_threads=1 … ``` 同理,`use_tensorrt: true` 但设备是 CPU 时会打印警告并忽略该项 (TensorRT 只在 GPU 分支生效)。 #### 为什么不能照搬 ONNX Runtime 的调优文章 网上关于「PP-OCR 部署优化」的资料大多讲的是 **ONNX Runtime / TensorRT** 路线 (`intra_op_num_threads`、`providers`、`trt_max_workspace_size`、INT8 量化等)。 本项目走的是 **Paddle Inference**(`paddleocr` → `paddlex` → `paddlepaddle`), 模型格式和执行引擎都不一样,那些参数名在这里并不存在。对应关系: | 常见文章里的说法 | 本项目实际参数 | | --- | --- | | `intra_op_num_threads` | `cpu_threads` | | `inter_op_num_threads` | 无对应(Paddle 只有单一线程数) | | `graph_optimization_level` | 无对应(Paddle 默认开启,`set_optimization_level(3)`) | | `batch_size` | `text_recognition_batch_size` | | `dynamic_shapes` | `text_det_limit_side_len`、`text_det_input_shape`、`text_rec_input_shape` | | TensorRT + `trt_fp16_enable` | `use_tensorrt: true` + `precision: fp16` | | `gpu_mem_limit` | 无对应(Paddle 用 `FLAGS_*` 环境变量控制) | | INT8 量化、ONNX 导出 | 不适用(Paddle 需另建校准集走 `run_mode: trt_int8`) | 简单说:**照抄那些文章的代码在本项目里会直接报「不认识的参数」**,请以上表为准。 ### 模型预置 `scripts/download_models.py` 会把交付包需要的八套模型一次性下载到 `model_dir/official_models/`,共约 398MB: ```bash uv run python scripts/download_models.py # 打包时 scripts/package-windows.ps1 / package-ubuntu.sh 会自动复制 models/ 进发布目录 ``` **检测** | 模型 | 体积 | 用途 | | --- | --- | --- | | `PP-OCRv5_server_det` | 85MB | 召回最好,密集小字靠它,默认用它 | | `PP-OCRv5_mobile_det` | 5MB | 资源紧张时用(比 v4 移动端检测强得多) | | `PP-OCRv4_server_det` | 109MB | v4 代际服务端,对比备选 | | `PP-OCRv4_mobile_det` | 5MB | ⚠️ 密集文本大面积漏检(1.png 只检出 46 框),别用在表格/文档图上 | **识别** | 模型 | 体积 | 用途 | | --- | --- | --- | | `PP-OCRv5_server_rec` | 82MB | 精度最高,也最慢。GPU 机器上可用它冲精度 | | `PP-OCRv5_mobile_rec` | 17MB | v5 代际移动端,速度与精度折中 | | `PP-OCRv4_server_rec` | 87MB | v4 代际服务端,对比备选 | | `PP-OCRv4_mobile_rec` | 11MB | 默认。密集文本字符数与 v5 服务端基本一致,快约 8 倍 | 八套都在本地之后,交付后**断网也能直接改 `det_model_name` / `rec_model_name` 切换**。 脚本会跳过已完整的目录,重复执行不会重新下载;上次下载中断留下的空壳目录(只含 `.cache`)会被自动清理。 体积提示:这八套会随发布包一起发给客户(约 398MB)。如果确定用不上某个代际, 可以从 `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 uv run pytest -q uv pip check ```