feat: 外露推理调优参数并支持 device: auto

把此前只能改代码的参数摊到 config.yaml,交付后按客户机器调整:
  use_tensorrt / precision / enable_cinn / mkldnn_cache_capacity
  text_det_input_shape / text_rec_input_shape

device 新增 auto:启动时探测可用的 CUDA 设备,有卡用 GPU、没卡用 CPU,
同一份配置在不同机器之间搬运不用改。探测不到卡是预期路径,报 INFO;
显式写 gpu 却用不了是配置问题,报 WARNING——便于区分这两种情况。

设备名校验加了两层(配置层拦拼写错误 + 运行时最后一道防线)。起因是实测
踩到:冻结包里的代码比 config.yaml 旧时,字符串 auto 被原样传给 PaddleX,
抛出的 AssertionError 完全看不出是配置写错了。

text_recognition_batch_size 默认值 8 -> 32:实测 1.png 同分辨率 23.87s ->
19.03s,框数不变、字符数 2240 -> 2241(差异仅英文分词空格与个别低置信字符)。

顺带把参数装配收敛到 OCRService.from_settings():启动、下载脚本、压测脚本
原本各自手工罗列参数,压测脚本已经漏掉了新配置项。

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
zimoyin
2026-10-14 03:53:38 +08:00
parent cf7088a13d
commit 09ab14c707
5 changed files with 475 additions and 32 deletions
+92 -8
View File
@@ -21,9 +21,66 @@ rec_model_name: PP-OCRv4_mobile_rec
# ⚠️ PP-OCRv4_mobile_det 检测不出密集小字:1.png 只检出 46 框(v5 为 339 框),
# 字符数只剩约 10%。仅适合文本稀疏的图片(票据/证件/少数字段)。
# 每个线程会独立占用一份 OCR 模型内存。
# ── 交付包预置的模型 ─────────────────────────────────────────
# scripts/download_models.py 会把下面八套(v4/v5 × 服务端/移动端 × 检测/识别)
# 全部下载到 model_dir/official_models/,共约 398MB。
# 交付后断网也能直接改模型名切换,不必重新下载。
#
# 检测 识别
# PP-OCRv5_server_det 85MB PP-OCRv5_server_rec 82MB
# PP-OCRv5_mobile_det 5MB PP-OCRv5_mobile_rec 17MB
# PP-OCRv4_server_det 109MB PP-OCRv4_server_rec 87MB
# PP-OCRv4_mobile_det 5MB PP-OCRv4_mobile_rec 11MB
#
# 怎么选(按客户机器分档):
# 低配 CPU(4 核以下/内存吃紧):PP-OCRv5_mobile_det + PP-OCRv4_mobile_rec
# 常规 CPU(本机默认) :PP-OCRv5_server_det + PP-OCRv4_mobile_rec
# 有 GPU :PP-OCRv5_server_det + PP-OCRv5_server_rec + use_tensorrt
# 要最高精度、不在乎速度 :PP-OCRv5_server_det + PP-OCRv5_server_rec
#
# ⚠️ PP-OCRv4_mobile_det 在密集文本上会大面积漏检:1.png 只检出 46 框(v5 为 339 框),
# 字符数只剩约 10%。预置它是为了完整性,别用在表格/文档类图片上。
# ⚠️ 换组合前先用真实图片对比「字符数」,不要只看速度(见 README)。
# 每个线程会独立占用一份 OCR 模型内存(实测每多一个 worker 约 +105MB)。
# 识别推理本身接近单线程,所以并发上传时加大 worker 数可以得到接近线性的吞吐提升。
ocr_workers: 1
device: cpu
# ── 推理设备 ──────────────────────────────────────────────────
# 取值:cpu / gpu / gpu:0 / auto / npu 等,具体可用性取决于 PaddlePaddle 编译版本。
#
# auto = 启动时探测有没有可用的 CUDA 设备,有就用 GPU、没有就用 CPU,
# 日志里会明确打出实际选了什么(INFO 级)。适合同一份配置在不同客户机
# 之间搬运:不用为了换机器改这一行。GPU 版分发包默认就是 auto。
# cpu = 固定用 CPU,永远不碰 GPU。
# gpu = 固定用 GPU(gpu:1 指定第 2 块卡)。如果这台机器不保证有卡,别用它。
#
# ⚠️ 光把这里改成 gpu 是启不了 GPU 的。PyPI 上的 paddlepaddle 是纯 CPU 版,
# 必须安装与本机 CUDA 匹配的 paddlepaddle-gpu(版本同样要固定 3.2.x,
# 原因见文件末尾 enable_mkldnn 的说明)。
# 详见 README「CPU / GPU 切换」。
#
# 兜底行为:配置了 gpu 但 GPU 不可用时,启动会打印中文警告并自动回落 CPU,
# 不会让服务起不来(装的是纯 CPU 版,或装了 GPU 版但机器没有可用 N 卡/驱动,
# 两种情况都能兜住)。上线前请确认日志里「加载 OCR 引擎」那一行打印的
# device 是不是你期望的。
#
# 交付时 CPU / GPU 是两个产物(原因和打包命令见 README「CPU / GPU 切换」):
# CPU 包 -> dist\ ,本项为 cpu
# GPU 包 -> dist-gpu\ ,打包脚本已自动把本项写成 gpu
device: auto
# 是否启用 TensorRT(只在 device=gpu 时生效;device=cpu 时会打印警告并忽略)。
# 开启后可显著加速,但首次推理会花时间做引擎构建/调优,且换机器要重建。
use_tensorrt: false
# 推理精度:fp32 / fp16。fp16 只在 GPU(尤其 TensorRT)上生效,CPU 下无影响。
# fp16 更快、显存占用更低,但精度可能略降,上线前请用真实图片核对字符数。
precision: fp32
# 是否启用 CINN 编译器(面向国产加速卡等场景,普通 CPU/GPU 保持 false 即可)。
enable_cinn: false
lang: ch
# 识别速度/精度参数。
@@ -33,23 +90,47 @@ lang: ch
# side=320 -> 检出 0 框 / 0 字符 (完全失效)
# 原因:分辨率下采样后小字高度不足,检测模型看不见。这是断崖式失效,不是平滑降精度。
# 结论:大图保持 640 或更高;480/512 只适合小尺寸、大字号的图片。
#
# 往上调则是拿速度换召回(1.png 实测,v5 server det + v4 mobile rec):
# side=1024 -> 检 428 框 / 2240 字符,约 19s ← 当前值
# side= 768 -> 检 405 框 / 2191 字符,约 16s
# side= 640 -> 检 339 框 / 1746 字符,约 11s (字符数少 22%)
# 也就是说 1024 比 640 多召回约 28% 的字符,代价是慢 8 秒左右。
# 低配客户机可以降到 768 折中;只要速度就 640,但要接受漏字。
text_det_limit_side_len: 1024
# 检测缩放类型
text_det_limit_type: max
# 固定检测输入尺寸,形如 [3, 960, 960]。null = 用上面的 limit_side_len 动态缩放。
# 一般不用动;只有在需要可复现的固定算力占用时才设。
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_recognition_batch_size: 8
# 固定识别输入尺寸,形如 [3, 48, 320]。null = 按文本框宽高比动态填充(推荐)。
text_rec_input_shape: null
# 识别批量大小。框越多收益越大,是性价比最高的旋钮。
# 1.png(1920x1080) 实测:
# side=1024:batch=8 -> 23.87s / 2240 字符,batch=32 -> 19.03s / 2241 字符
# side= 640:batch=8 -> 19.87s,batch=32 -> 11.22s(框数同为 339)
# 结论:调到 32 就能拿到大部分收益;再往上收益饱和(48 反而略慢,属噪声)。
#
# ⚠️ 批次大小会轻微影响识别结果(不是逐字节一致)。1.png 上 2240 -> 2241 字符,
# 官方样例图上 253 -> 250,差异只出现在英文分词空格和个别低置信字符上。
# 框数(segments)完全一致。要切换 batch 请先核对真实图片的字符数。
# 批量越大峰值内存越高,低配机器(内存 < 4GB)建议用 16。
text_recognition_batch_size: 32
# CPU 推理线程数(Paddle 的 cpu_math_library_num_threads)。
# 取值为正整数,或 max。
# max = 吃满所有逻辑核心,例如 20 逻辑核机器上解析为 20(本机即为 20)。
# 注意:max 不一定最快。超线程会争抢,超过物理核心数后收益递减,
# 而且会挤占同机其它服务。建议用 benchmark_ocr.py 实测后再定。
# 取值为正整数,或 max(吃满所有逻辑核心,20 逻辑核机器上解析为 20)。
#
# 实测结论:开启 oneDNN 之后这个参数几乎不影响耗时。官方样例图(896x528)实测:
# 1 -> 7.25s 4 -> 6.82s 8 -> 7.22s 14 -> 7.29s 20 -> 7.25s
# 差异都在测量噪声内。也就是说识别推理已经跑在多线程上,再加线程不再获益。
# 保持 1 即可,省下来的核留给 ocr_workers 或同机其它服务。
# (README 里「建议调到 max」是 oneDNN 之前的结论,已过期。)
cpu_threads: 1
# 是否启用 oneDNN(MKLDNN)CPU 加速。
@@ -63,6 +144,9 @@ cpu_threads: 1
# (同图同参数:3.3.1 检出 339 框,3.2.2 检出 452 框),上线前请用真实数据核对。
enable_mkldnn: true
# oneDNN 算子缓存容量,只在 enable_mkldnn: true 时生效,一般不用动。
mkldnn_cache_capacity: 10
# 日志级别:DEBUG / INFO / WARNING / ERROR
log_level: INFO