ocr-server/RAPIDOCR_PARAMETERS.md

RapidOCR 参数详解（结合本项目 RapidOCR 3.8.1）

本文面向 D:\PycharmProjects\ocr-server 的实际使用与调优。

核验环境（2026-07-17）：

• rapidocr==3.8.1
• onnxruntime-directml==1.23.0
• 项目入口：engine/ocr_engine.py
• 本项目目前使用整图 OCR，不再使用分块模式

重要： RapidOCR 官方 main/latest 文档目前主要描述 3.9.x。3.9.0 起默认模型和部分枚举发生变化，不能直接把新文档中的所有默认值套到本项目 3.8.1。

---

1. 先理解 RapidOCR 的参数层级

RapidOCR 参数分为三层：

1. 构造配置：创建 RapidOCR 实例时确定模型、推理后端、预处理及默认行为。
2. Det / Cls / Rec 模块配置：分别控制检测、方向分类、文字识别。
3. 运行时调用参数：调用 engine(image, ...) 时覆盖少量可动态调整的选项。

配置树的顶层结构是：

Global:       # OCR 流程和输出的全局设置
EngineConfig: # 各推理后端设置
Det:          # 文本检测
Cls:          # 文本行方向分类
Rec:          # 文本识别

参数路径使用点号表达，例如：

params = {
    "Global.text_score": 0.6,
    "Det.box_thresh": 0.55,
    "EngineConfig.onnxruntime.use_dml": True,
}

1.1 三种创建方式

使用包内默认配置

from rapidocr import RapidOCR

engine = RapidOCR()

使用完整 YAML

engine = RapidOCR(config_path="rapidocr.yaml")

YAML 中枚举参数写字符串：

Det:
  engine_type: onnxruntime
  lang_type: ch
  model_type: mobile
  ocr_version: PP-OCRv4

使用 params 字典覆盖

from rapidocr import EngineType, LangDet, ModelType, OCRVersion, RapidOCR

engine = RapidOCR(params={
    "Det.engine_type": EngineType.ONNXRUNTIME,
    "Det.lang_type": LangDet.CH,
    "Det.model_type": ModelType.MOBILE,
    "Det.ocr_version": OCRVersion.PPOCRV4,
    "Det.box_thresh": 0.55,
})

3.8.1 的重要规则： params 字典中的枚举字段必须传 RapidOCR 的 Enum，不能传普通字符串。包括：

• engine_type
• model_type
• ocr_version
• lang_type
• task_type

例如以下写法在 params 中可能触发 TypeError：

# 不适合 rapidocr 3.8.1 的 params 字典
{"Det.engine_type": "onnxruntime"}

但同一个值在 YAML 中应当写字符串，因为加载 YAML 后 RapidOCR 会自动将其转换成 Enum。

1.2 配置覆盖顺序

构造时的实际顺序为：

1. 如果 config_path 存在，加载该 YAML；
2. 否则加载 RapidOCR 包内 config.yaml；
3. 最后用 params 逐项覆盖。

因此：

RapidOCR(config_path="a.yaml", params={"Global.text_score": 0.7})

表示先加载 a.yaml，再把其中的 Global.text_score 改为 0.7。

如果 config_path 指向不存在的文件，3.8.1 源码会退回包内默认配置，而不是必然报错。生产环境应主动检查路径，避免拼错路径后静默使用默认配置。

---

2. OCR 三阶段是什么

完整 OCR 流程通常是：

输入图片
  ↓
Det：检测文字区域
  ↓
裁剪每个文本行
  ↓
Cls：判断文本行是否需要旋转 180°
  ↓
Rec：识别文本内容
  ↓
按置信度过滤并输出

三个开关的典型组合：

场景	use_det	use_cls	use_rec	返回类型/意义
完整 OCR	true	按需	true	RapidOCROutput
只检测文字框	true	false	false	TextDetOutput
已裁切文本行，只识别	false	false	true	TextRecOutput
已裁切文本行，方向分类后识别	false	true	true	无检测框，处理输入整体
只做方向分类	false	true	false	TextClsOutput

注意：如果关闭 Det，却把一张包含很多文本行的整页图交给 Rec，Rec 会把整张图当成一条待识别文本行，通常不是想要的效果。

---

3. Global 全局参数

以下默认值以本项目安装的 RapidOCR 3.8.1 包内 config.yaml 为准，而不是当前 3.9.x 在线文档。

参数	3.8.1 默认值	作用	调优建议
text_score	0.5	最终识别置信度过滤阈值	误识别太多时提高；漏掉低置信度文字时降低
use_det	true	是否执行文本检测	整页图片一般开启
use_cls	true	是否执行 0°/180°方向分类	方向固定时可关闭以降低耗时
use_rec	true	是否执行文字识别	只要框时可关闭
min_height	30	全局预处理的小尺寸/竖图补边相关阈值	通常保留模型默认
width_height_ratio	8	竖长图触发补边逻辑的宽高比阈值	通常不要作为第一调优项
max_side_len	2000	整体输入预处理允许的最大边	大图精度与内存/耗时的重要平衡项
min_side_len	30	整体输入预处理允许的最小边	极小图片可能被放大
return_word_box	false	是否计算字/词级坐标	需要细粒度坐标时开启，会增加后处理工作
return_single_char_box	false	是否将英文数字进一步拆到单字符坐标	仅在 return_word_box=True 时有意义
font_path	null	可视化结果使用的字体	只影响可视化，不改善识别准确率
log_level	info	RapidOCR 日志级别	排查后端和模型加载时可设 debug
model_root_dir	null	内置/自动下载模型的根目录	null 时使用包目录下 models

3.1 text_score 与 box_thresh 不一样

这是最常混淆的一组参数：

• Det.box_thresh：检测阶段判断一个候选区域是否像文本。
• Global.text_score：识别完成后，按识别置信度过滤结果。

例子：

• 图片中某行完全没有检测框：先检查 limit_side_len、thresh、box_thresh。
• 框已经检测到了，但最终结果中没有这行：可能是 text_score 太高，或者 Rec 识别失败。

3.2 max_side_len 与 Det.limit_side_len 不一样

• Global.max_side_len：进入整个 OCR 流程前，对原图做一次全局尺寸约束；3.8.1 默认 2000。
• Det.limit_side_len：检测模型自身预处理的缩放目标；3.8.1 默认 736。

两者可能连续生效。把 Det.limit_side_len 调得很大，如果图片之前已被 Global.max_side_len 缩小，也无法恢复被缩掉的细节。

调大图小字时，应先确认这两个层级，而不是只调整其中一个。

3.3 字/词/字符坐标

return_word_box=True 时，RapidOCR 会结合识别结果和文本行框计算更细粒度坐标。其“word”的粒度与语言、版本有关，不应简单理解成永远返回英文意义上的单词：

• 中文及中英混合通常更接近按字拆分；
• 纯英文通常更接近按词拆分；
• return_single_char_box=True 用于进一步获取英文/数字字符级坐标，而且依赖 return_word_box=True。

本项目每次调用都显式传入：

return_word_box=True

因此构造配置中的 Global.return_word_box 会在首次项目调用时被覆盖为 True。

---

4. Det 文本检测参数

Det 的目标是找到文字区域，输出四点框。

4.1 模型选择参数

参数	3.8.1 默认值	作用
engine_type	onnxruntime	Det 使用的推理后端
lang_type	ch	检测模型语言类别
model_type	mobile	模型规模，本地 3.8.1 只有 mobile/server 枚举
ocr_version	PP-OCRv4	OCR 模型系列
task_type	det	模型任务类型，通常不要修改
model_path	null	明确指定模型文件
model_dir	null	部分后端使用的模型目录

如果 model_path 不为空，ONNXRuntime 会直接使用该文件；模型选择元数据主要用于 model_path=null 时定位 RapidOCR 托管的默认模型。

4.2 检测预处理与后处理参数

参数	3.8.1 默认值	含义	调大/调小的典型影响
limit_side_len	736	检测前图像缩放边长限制	调大通常保留更多小字细节，但更慢、更耗显存/内存
limit_type	min	limit_side_len 作用方式	与模型训练预处理有关，不建议随意改
std	[0.5,0.5,0.5]	输入归一化标准差	必须匹配模型训练配置
mean	[0.5,0.5,0.5]	输入归一化均值	必须匹配模型训练配置
thresh	0.3	DB 像素二值化阈值	降低会产生更多候选区域，也可能增加噪声
box_thresh	0.5	候选文本框平均得分阈值	降低增加召回；提高减少假框
max_candidates	1000	最多处理候选区域数	超密集页面可能受限；调大增加后处理成本
unclip_ratio	1.6	检测框向外扩张比例	调大可避免切掉字符边缘，但可能框入邻行
use_dilation	true	二值图是否做膨胀	有助于连接断裂区域，也可能粘连相邻文字
score_mode	fast	文本框评分方式	fast 优先速度；其他值须以版本源码支持为准

4.3 检测调优顺序

小字检测不到

建议按以下顺序检查：

1. 原始图片是否已被业务预处理缩小；
2. Global.max_side_len 是否过小；
3. 适当提高 Det.limit_side_len；
4. 小幅降低 Det.box_thresh；
5. 再考虑小幅降低 Det.thresh。

不要一开始就同时大幅降低两个阈值，否则很难判断是哪项有效，而且容易产生大量背景假框。

框太紧、字符边缘被切掉

优先小幅提高：

Det:
  unclip_ratio: 1.8

框入邻行时反向降低。

假框很多

优先提高：

Det:
  box_thresh: 0.6

若大量纹理像素形成候选，再提高 thresh。

---

5. Cls 文本行方向分类参数

Cls 通常只判断裁切文本行是 0° 还是 180°。它不是通用的任意角度纠偏模块，不能替代 90°旋转、透视矫正或倾斜校正。

参数	3.8.1 默认值	作用
engine_type	onnxruntime	分类推理后端
lang_type	ch	3.8.1 的 LangCls 只支持 ch
model_type	mobile	模型规格
ocr_version	PP-OCRv4	模型系列
task_type	cls	固定为分类任务
model_path	null	自定义分类模型路径
cls_image_shape	[3,48,192]	分类输入形状
cls_batch_num	6	一次分类的文本行数量
cls_thresh	0.9	达到该置信度才按分类结果旋转
label_list	["0","180"]	分类标签

调优建议：

• 扫描件方向稳定：关闭 use_cls，通常能降低延迟。
• 确实混有上下颠倒文本：开启 use_cls。
• 不要期待 Cls 修正任意角度倾斜。
• cls_batch_num 增大可能提高大量文本行时的吞吐，但会增加瞬时内存/显存；应实测。
• cls_image_shape、label_list 必须与模型匹配，不是通用性能旋钮。

本项目 .env 当前为：

OCR_USE_CLS=true

所以会运行分类阶段。

---

6. Rec 文字识别参数

Rec 接收裁切后的文本行，输出文字和识别置信度。

参数	3.8.1 默认值	作用
engine_type	onnxruntime	识别推理后端
lang_type	ch	字符语言/字典族
model_type	mobile	模型规模
ocr_version	PP-OCRv4	OCR 模型系列
task_type	rec	固定为识别任务
model_path	null	自定义识别模型路径
model_dir	null	部分后端模型目录
rec_keys_path	null	自定义字符字典路径
rec_img_shape	[3,48,320]	识别模型输入形状
rec_batch_num	6	一次识别的文本行数量

6.1 lang_type 支持范围（本地 3.8.1）

本地 LangRec 枚举包括：

ch, ch_doc, en, arabic, chinese_cht, cyrillic,
devanagari, japan, korean, ka, latin, ta, te,
eslav, th, el

模型文件、lang_type 和字符字典必须彼此匹配。

6.2 rec_keys_path 不是“额外允许字符”

它是识别模型的字符索引映射。随意给一个新字典，并不会让原模型学会新字符，反而可能导致输出索引映射错误。

只有自定义模型确实按该字典训练/导出时才应设置。

6.3 rec_img_shape 不应随意改

它必须符合模型输入和预处理约定。仅为了“识别更长文本”直接改宽度，不保证有效；动态宽度能力、模型导出方式和后端均会影响是否支持。

6.4 rec_batch_num

• 增大：可能提高多文本行吞吐，增加峰值内存/显存。
• 减小：降低峰值资源，可能降低吞吐。
• 对一张只有少量文本行的图片，增大批量不一定更快。

---

7. EngineConfig 与推理后端

Det.engine_type、Cls.engine_type、Rec.engine_type 决定各阶段使用哪个后端；EngineConfig.<后端> 只是该后端的参数。

例如：

params = {
    "Det.engine_type": EngineType.ONNXRUNTIME,
    "Rec.engine_type": EngineType.ONNXRUNTIME,
    "EngineConfig.onnxruntime.use_dml": True,
}

如果把 EngineConfig.tensorrt.use_fp16=True 写好了，但三个模块仍是 EngineType.ONNXRUNTIME，TensorRT 参数不会被使用。

RapidOCR 支持 Det、Cls、Rec 分别使用不同后端，但混用会增加部署依赖、初始化复杂度和排障成本。一般先统一后端。

---

8. ONNXRuntime 参数

8.1 通用会话参数

参数	3.8.1 默认值	作用
intra_op_num_threads	-1	单个算子内部并行线程数
inter_op_num_threads	-1	算子之间并行线程数
enable_cpu_mem_arena	false	是否启用 ORT CPU 内存池
cpu_ep_cfg.arena_extend_strategy	kSameAsRequested	CPU 内存池扩展策略

3.8.1 源码中：

• -1 表示不显式设置，由 ONNXRuntime 处理；
• 只有线程数位于 1..os.cpu_count() 时才写入 SessionOptions；
• 超出 CPU 数或无效值会被跳过，不会按填写值生效。

Web 服务调优时不要只追求单请求最快：

• 单进程、单请求：可适当提高 intra_op_num_threads；
• 多个并发请求：每个 Session 使用过多线程会相互争抢，反而使尾延迟恶化；
• inter_op_num_threads 并非越大越好，应以真实并发压测决定。

8.2 CPU 配置示例

params = {
    "Det.engine_type": EngineType.ONNXRUNTIME,
    "Cls.engine_type": EngineType.ONNXRUNTIME,
    "Rec.engine_type": EngineType.ONNXRUNTIME,
    "EngineConfig.onnxruntime.intra_op_num_threads": 4,
    "EngineConfig.onnxruntime.inter_op_num_threads": 2,
}

本项目 OCR_DEVICE=cpu 时正是这样构建参数。

---

9. DirectML 参数

DirectML 不是独立的 engine_type；它是 ONNXRuntime 的 Execution Provider。

正确关系是：

Det/Cls/Rec.engine_type = onnxruntime
EngineConfig.onnxruntime.use_dml = true
安装 onnxruntime-directml

示例：

params = {
    "Det.engine_type": EngineType.ONNXRUNTIME,
    "Cls.engine_type": EngineType.ONNXRUNTIME,
    "Rec.engine_type": EngineType.ONNXRUNTIME,
    "EngineConfig.onnxruntime.use_dml": True,
}

9.1 生效条件

本地 3.8.1 源码会检查：

1. 操作系统必须是 Windows；
2. Windows Build 必须不低于 18362；
3. onnxruntime.get_available_providers() 中必须有 DmlExecutionProvider。

不满足时会记录警告，并回退到默认可用 Provider，通常是 CPU。

检查命令：

.venv/Scripts/python.exe -c "import onnxruntime as ort; print(ort.get_available_providers())"

预期包含：

DmlExecutionProvider
CPUExecutionProvider

9.2 dm_ep_cfg 拼写

RapidOCR 3.8.1 配置字段是：

EngineConfig:
  onnxruntime:
    use_dml: true
    dm_ep_cfg: null

是 dm_ep_cfg，不是 dml_ep_cfg。

当它为 null 时，3.8.1 会复用 CPU Provider 配置；若 CUDA 也被认为可用，则可能复用 CUDA 配置。一般不需要手动填写 DirectML provider options。

9.3 DirectML 常见误区

• 日志打印“推理设备: DirectML”只代表应用选择了 DML 配置，不单独证明实际 Session 使用 DML。
• 要结合可用 Provider 和 RapidOCR/ORT 日志确认。
• 同一环境不要混装多个互斥的 onnxruntime、onnxruntime-gpu、onnxruntime-directml 包，否则 Provider 和二进制版本可能相互覆盖。
• DirectML 首次初始化可能较慢；是否比 CPU 快必须用真实图片、完整三阶段和并发模型实测。

---

10. ONNXRuntime CUDA 参数

CUDA 也是 ONNXRuntime Execution Provider，不是 EngineType.CUDA。

params = {
    "Det.engine_type": EngineType.ONNXRUNTIME,
    "Cls.engine_type": EngineType.ONNXRUNTIME,
    "Rec.engine_type": EngineType.ONNXRUNTIME,
    "EngineConfig.onnxruntime.use_cuda": True,
    "EngineConfig.onnxruntime.cuda_ep_cfg.device_id": 0,
}

参数	默认值	作用
use_cuda	false	请求启用 CUDA EP
cuda_ep_cfg.device_id	0	GPU 编号
arena_extend_strategy	kNextPowerOfTwo	GPU 内存池扩展策略
cudnn_conv_algo_search	EXHAUSTIVE	cuDNN 卷积算法搜索策略
do_copy_in_default_stream	true	是否在默认流中执行复制

生效还需要：

• 安装兼容的 onnxruntime-gpu；
• CUDA/cuDNN 与 ORT 版本匹配；
• get_available_providers() 包含 CUDAExecutionProvider。

仅设置 use_cuda=True 不会自动安装 CUDA，也不保证实际使用 GPU。条件不满足时，RapidOCR 3.8.1 会警告并回退。

---

11. TensorRT 参数

TensorRT 在 RapidOCR 中是独立的推理引擎：

params = {
    "Det.engine_type": EngineType.TENSORRT,
    "Cls.engine_type": EngineType.TENSORRT,
    "Rec.engine_type": EngineType.TENSORRT,
    "EngineConfig.tensorrt.device_id": 0,
    "EngineConfig.tensorrt.use_fp16": True,
}

参数	3.8.1 默认值	作用
device_id	0	GPU 编号
use_fp16	true	使用 FP16
use_int8	false	使用 INT8；通常需要正确量化支持
workspace_size	1073741824	TensorRT workspace，默认 1 GiB
cache_dir	null	engine 缓存目录
force_rebuild	false	是否强制重建 engine
det_profile	见默认配置	检测动态 shape 范围
rec_profile	见默认配置	识别动态 shape 范围
cls_profile	见默认配置	分类动态 shape 范围

默认动态 shape：

EngineConfig:
  tensorrt:
    det_profile:
      min_shape: [1, 3, 32, 32]
      opt_shape: [1, 3, 736, 736]
      max_shape: [1, 3, 2048, 2048]
    rec_profile:
      min_shape: [1, 3, 48, 32]
      opt_shape: [6, 3, 48, 320]
      max_shape: [6, 3, 48, 2048]
    cls_profile:
      min_shape: [1, 3, 48, 32]
      opt_shape: [6, 3, 48, 192]
      max_shape: [6, 3, 48, 192]

注意：

• 输入 shape 超出 profile 可能失败或触发重新构建；
• 首次 ONNX 转 TensorRT engine 会明显较慢，后续使用缓存；
• .engine 通常与 GPU 架构、TensorRT/CUDA 版本、模型和 profile 相关，不宜跨机器盲目复用；
• use_fp16=True 并不保证所有算子都以 FP16 执行，也不保证所有 GPU 都同等受益；
• TensorRT 部署依赖比 ONNXRuntime CPU/DirectML 高，先确认稳定性再追求吞吐。

---

12. 其他后端参数概览

本地 3.8.1 的 EngineType 还包括：

openvino, paddle, torch, mnn

配置树还有：

• EngineConfig.openvino
• EngineConfig.paddle
• EngineConfig.torch
• EngineConfig.mnn

但“配置中出现”不等于当前环境已安装对应依赖，也不等于任意模型组合都可运行。切换前应同时确认：

1. 本地 RapidOCR 版本支持该后端；
2. 后端 Python 包和原生运行库已安装；
3. 模型格式与该后端匹配；
4. 枚举、模型选择和配置项属于同一个版本。

---

13. RapidOCR.__call__() 运行时参数

本地 RapidOCR 3.8.1 的实际签名：

engine(
    img_content,
    use_det=None,
    use_cls=None,
    use_rec=None,
    return_word_box=None,
    return_single_char_box=None,
    text_score=None,
    box_thresh=None,
    unclip_ratio=None,
)

13.1 参数表

参数	作用
img_content	图片路径、URL（取决于加载器支持）、numpy.ndarray、bytes 或 Path
use_det	覆盖检测开关
use_cls	覆盖方向分类开关
use_rec	覆盖识别开关
return_word_box	覆盖字/词级坐标开关
return_single_char_box	覆盖英文数字单字符坐标开关
text_score	覆盖最终识别置信度阈值
box_thresh	直接更新 Det 后处理器的框阈值
unclip_ratio	直接更新 Det 后处理器的扩框比例

其它构造参数（例如 limit_side_len、rec_batch_num、engine_type）不能直接作为本地 3.8.1 __call__() 的关键字参数传入。

13.2 运行时“覆盖”会保留到后续调用

这是 3.8.1 源码里非常容易忽略的行为：update_params() 直接修改实例属性，而不是建立仅本次调用的临时配置。

engine(img1, text_score=0.8)
engine(img2)  # text_score 仍然是 0.8，不会自动恢复构造值

传 None 表示“不修改当前状态”，不是“恢复默认值”。

因此共享同一个 RapidOCR 实例的 Web 服务，不应允许不同并发请求随意传不同的运行时阈值。否则一次请求可能修改后续请求看到的状态，并存在并发竞态。

推荐做法：

• 服务启动时固定构造参数；
• 业务请求只传固定的 use_det/use_cls/use_rec/return_word_box；
• 如果必须支持不同配置，创建独立的引擎实例池，或者在外部做串行化与显式恢复。

13.3 未知参数

__call__() 的 Python 签名不接受任意 **kwargs。传入未声明参数会由 Python 直接报 TypeError。

---

14. 模型选择、模型路径与自动下载

14.1 model_path 指定时

ONNXRuntime 直接加载该路径：

params = {
    "Det.model_path": "model/custom_det.onnx",
}

此时 RapidOCR 不会根据 ocr_version/model_type/lang_type 替你验证文件内容是否真的匹配这些声明。最终是否可用取决于模型输入输出、后处理和字典是否兼容。

14.2 model_path=null 时

RapidOCR 会根据以下组合查找托管模型：

engine_type + ocr_version + task_type + lang_type + model_type

若本地模型不存在，则按照内置模型清单下载并校验 SHA256。该能力只适用于 RapidOCR 已登记的托管模型组合，不表示任意自定义路径缺失时都会自动下载。

14.3 model_root_dir

Global.model_root_dir=null 时，本地 3.8.1 会设为 RapidOCR 安装目录下的 models。如果运行环境对 site-packages 没有写权限，而又需要下载非内置模型，应显式指定一个可写目录。

---

15. 版本差异

15.1 本项目：RapidOCR 3.8.1

本地枚举仅包含：

OCRVersion: PP-OCRv4, PP-OCRv5
ModelType: mobile, server

包内无参默认配置是：

• Det：PP-OCRv4 mobile + ONNXRuntime
• Cls：PP-OCRv4 mobile + ONNXRuntime
• Rec：PP-OCRv4 mobile + ONNXRuntime

15.2 RapidOCR 3.9.0 及以后

官方文档说明 3.9.0 起默认组合改为：

• Det：PP-OCRv6 small
• Cls：PP-OCRv4 mobile
• Rec：PP-OCRv6 small
• 默认后端仍是 ONNXRuntime

这意味着升级后，如果没有显式固定模型，默认模型可能改变，准确率、速度、模型文件和输出行为都可能变化。

升级建议：

1. 先生成目标版本默认配置；
2. 对照新版本 Enum 和参数树；
3. 明确固定 Det/Cls/Rec 模型；
4. 用真实业务样本比较准确率、耗时和资源占用；
5. 不要直接复制 3.9.x 示例到 3.8.1。

---

16. 本项目当前实际配置

项目不维护 RapidOCR YAML 副本，唯一配置链是：

项目根 .env
  → config/config.py::Settings
  → main.py
  → OCRProcessor
  → RapidOCR(params=...)

修改 .env 后需要重启服务。项目开放以下常用参数：

.env	默认值	RapidOCR 映射/作用
OCR_USE_DET	true	每次调用的 use_det
OCR_USE_CLS	false	每次调用的 use_cls
OCR_USE_REC	true	每次调用的 use_rec
OCR_MODEL_DIR	model	三个模型文件所在目录；相对项目根解析
OCR_TEXT_SCORE	0.5	Global.text_score
OCR_MAX_SIDE_LEN	2000	Global.max_side_len
OCR_DET_LIMIT_SIDE_LEN	736	Det.limit_side_len
OCR_DET_BOX_THRESH	0.5	Det.box_thresh
OCR_REC_BATCH_NUM	6	Rec.rec_batch_num
OCR_DEVICE	cpu	cpu/cuda/dml/tensorrt
OCR_DEVICE_ID	0	GPU 编号
OCR_INTRA_THREADS	4	ORT CPU 算子内线程数
OCR_INTER_THREADS	2	ORT CPU 算子间线程数

模型目录会在配置加载时转成绝对路径，OCRProcessor 启动时检查以下文件：

ch_PP-OCRv5_det_mobile.onnx
ch_PP-LCNet_x0_25_textline_ori_cls_mobile.onnx
ch_PP-OCRv5_rec_mobile.onnx

三阶段模型契约固定为 PP-OCRv5 mobile：

Det: EngineType.ONNXRUNTIME, LangDet.CH, ModelType.MOBILE, OCRVersion.PPOCRV5
Cls: EngineType.ONNXRUNTIME, LangCls.CH, ModelType.MOBILE, OCRVersion.PPOCRV5
Rec: EngineType.ONNXRUNTIME, LangRec.CH, ModelType.MOBILE, OCRVersion.PPOCRV5

这些模型契约不是普通调优参数，因此不通过 .env 开放。其余本文介绍的底层参数用于理解 RapidOCR；除上表外，项目目前并未提供外部配置入口。

每次识别仍显式固定三阶段开关，并请求 return_word_box=True。阈值在引擎构造时设置，不按单个请求动态修改，避免共享实例状态串扰。

---

17. 推荐配置示例

17.1 本项目 DirectML 稳定起点

params = {
    "Global.text_score": 0.5,
    "Global.max_side_len": 2000,

    "Det.model_path": "model/ch_PP-OCRv5_det_mobile.onnx",
    "Det.engine_type": EngineType.ONNXRUNTIME,
    "Det.lang_type": LangDet.CH,
    "Det.model_type": ModelType.MOBILE,
    "Det.ocr_version": OCRVersion.PPOCRV5,
    "Det.limit_side_len": 736,
    "Det.thresh": 0.3,
    "Det.box_thresh": 0.5,
    "Det.unclip_ratio": 1.6,

    "Cls.model_path": "model/ch_PP-LCNet_x0_25_textline_ori_cls_mobile.onnx",
    "Cls.engine_type": EngineType.ONNXRUNTIME,
    "Cls.model_type": ModelType.MOBILE,

    "Rec.model_path": "model/ch_PP-OCRv5_rec_mobile.onnx",
    "Rec.engine_type": EngineType.ONNXRUNTIME,
    "Rec.lang_type": LangRec.CH,
    "Rec.model_type": ModelType.MOBILE,
    "Rec.ocr_version": OCRVersion.PPOCRV5,

    "EngineConfig.onnxruntime.use_dml": True,
}

上面是依据文件命名给出的统一方向，不代表已经验证这些模型的全部元数据。应用前应使用真实样本回归。

17.2 CPU 并发服务起点

params = {
    "EngineConfig.onnxruntime.intra_op_num_threads": 4,
    "EngineConfig.onnxruntime.inter_op_num_threads": 1,
    "Global.text_score": 0.5,
    "Det.limit_side_len": 736,
    "Rec.rec_batch_num": 6,
}

线程数必须按机器核心数和服务并发压测，不存在对所有机器都最优的固定值。

17.3 小字优先配置

params = {
    "Global.max_side_len": 3000,
    "Det.limit_side_len": 1280,
    "Det.box_thresh": 0.45,
    "Det.unclip_ratio": 1.7,
}

影响：通常更慢、更耗内存/显存，也可能增加假框。应逐项修改，并记录召回、误检和时延。

17.4 减少误识别

params = {
    "Det.box_thresh": 0.6,
    "Global.text_score": 0.65,
}

• 提高 box_thresh：减少低质量检测框；
• 提高 text_score：过滤低置信度识别结果。

两者同时提高会降低召回率，应以业务验收集评估。

17.5 已裁切单行文本

result = engine(
    line_image,
    use_det=False,
    use_cls=False,
    use_rec=True,
    return_word_box=False,
)

这适合输入已经是单行文本的情况，不适合整页图片。

---

18. 常见无效、冲突或误导性配置

18.1 只设置 use_dml/use_cuda，但后端不是 ONNXRuntime

"Det.engine_type": EngineType.TENSORRT,
"EngineConfig.onnxruntime.use_dml": True,

DML 参数对 TensorRT Det 无效。

18.2 只写 GPU 参数，没有安装对应 Provider

use_cuda=True 或 use_dml=True 只是请求使用该 Provider。Provider 不存在时会回退，必须检查：

onnxruntime.get_available_providers()

18.3 同时打开多个 ONNXRuntime 加速 Provider

同时 use_cuda=True 和 use_dml=True 会形成 Provider 优先级，并不代表两张后端共同加速一个推理。3.8.1 的插入顺序还会影响谁排在前面。一般一次只启用一个主要 GPU Provider。

18.4 显式 model_path 与模型声明不一致

文件可能仍能加载，但声明会误导下载逻辑、维护者和未来后端。应统一 ocr_version/model_type/lang_type/task_type。

18.5 修改 mean/std/image_shape/label_list 来“调准确率”

这些通常是模型契约，不是普通阈值。与模型不匹配会直接破坏结果。

18.6 只调 Det.limit_side_len，忽略 Global.max_side_len

原图可能已经先被全局缩放，检测阶段无法恢复细节。

18.7 把 text_score 当检测阈值

它只过滤识别置信度。根本没有框时，降低 text_score 通常无效。

18.8 把 Cls 当任意旋转矫正

默认标签只有 0/180，不处理所有角度。

18.9 运行时参数被误认为只影响一次调用

本地 3.8.1 会把非 None 运行时值写回共享实例。Web 并发中动态阈值可能相互影响。

18.10 依赖 main/latest 默认值但不锁定版本

RapidOCR 3.9.0 已更换默认 Det/Rec 模型。生产环境应锁定包版本和模型选择。

---

19. 推荐调优方法

不要凭单张图片调参数。建议准备固定验收集，至少覆盖：

• 正常扫描件；
• 小字高分辨率图；
• 模糊、压缩、低对比度图；
• 横排、上下颠倒文本；
• 中英数字混合；
• 空白和复杂纹理背景。

记录指标：

• 文本行召回率；
• 误检框数量；
• 字符/字段准确率；
• 单请求 P50/P95 延迟；
• 并发吞吐；
• 峰值内存/显存；
• 空白图和异常图片行为。

推荐顺序：

1. 固定 RapidOCR、ONNXRuntime 和模型文件；
2. 确认实际 Execution Provider；
3. 调输入尺寸（Global.max_side_len、Det.limit_side_len）；
4. 调检测（box_thresh、thresh、unclip_ratio）；
5. 调最终过滤（text_score）；
6. 调批量与线程以优化性能；
7. 最后比较不同模型和后端。

每次只改一到两个相关参数，并保存对照结果。

---

20. 本项目的优先建议

1. 调参只修改项目根 .env 中已开放的 OCR_* 变量，并重启服务。
2. 输入方向稳定时可关闭 OCR_USE_CLS，对比准确率和延迟后决定。
3. API 当前消费细粒度坐标，因此保留 return_word_box=True；若未来只需要文本行框，可再单独评估关闭。
4. 不要向并发请求开放运行时阈值修改：3.8.1 会持久修改共享引擎状态。
5. DirectML 以实际 Provider 为准，不要只依据应用日志中的设备名称。
6. 升级 RapidOCR 前做模型回归；3.9.x 的默认模型、枚举和参数契约已有变化。

---

21. 参考来源

官方资料：

• RapidOCR 参数说明
• RapidOCR 使用说明
• RapidOCR 推理引擎说明
• RapidOCR 模型列表
• RapidOCR GitHub 仓库
• RapidOCR Releases
• ONNXRuntime DirectML Execution Provider
• ONNXRuntime CUDA Execution Provider

本地核验文件：

• .venv/Lib/site-packages/rapidocr/config.yaml
• .venv/Lib/site-packages/rapidocr/main.py
• .venv/Lib/site-packages/rapidocr/utils/parse_parameters.py
• .venv/Lib/site-packages/rapidocr/utils/typings.py
• .venv/Lib/site-packages/rapidocr/inference_engine/onnxruntime/main.py
• .venv/Lib/site-packages/rapidocr/inference_engine/onnxruntime/provider_config.py
• config/config.py
• engine/ocr_engine.py
• .env

对于本文未给出明确结论的第三方模型兼容性、具体后端性能和模型元数据，应以实际模型来源、对应版本源码和业务样本验证为准。