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, ...)` 时覆盖少量可动态调整的选项。

配置树的顶层结构是：

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

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

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

### 1.1 三种创建方式

#### 使用包内默认配置

```python
from rapidocr import RapidOCR

engine = RapidOCR()
```

#### 使用完整 YAML

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

YAML 中枚举参数写字符串：

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

#### 使用 `params` 字典覆盖

```python
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`：

```python
# 不适合 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` 逐项覆盖。

因此：

```python
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 流程通常是：

```text
输入图片
  ↓
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`。

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

```python
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`。

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

#### 框太紧、字符边缘被切掉

优先小幅提高：

```yaml
Det:
  unclip_ratio: 1.8
```

框入邻行时反向降低。

#### 假框很多

优先提高：

```yaml
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` 当前为：

```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` 枚举包括：

```text
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.<后端>` 只是该后端的参数。

例如：

```python
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 配置示例

```python
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。

正确关系是：

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

示例：

```python
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。

检查命令：

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

预期包含：

```text
DmlExecutionProvider
CPUExecutionProvider
```

### 9.2 `dm_ep_cfg` 拼写

RapidOCR 3.8.1 配置字段是：

```yaml
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`。

```python
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 中是独立的推理引擎：

```python
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：

```yaml
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` 还包括：

```text
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 的实际签名：

```python
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()` 直接修改实例属性，而不是建立仅本次调用的临时配置。

```python
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 直接加载该路径：

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

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

### 14.2 `model_path=null` 时

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

```text
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

本地枚举仅包含：

```python
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 副本，唯一配置链是：

```text
项目根 .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` 启动时检查以下文件：

```text
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：

```python
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 稳定起点

```python
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 并发服务起点

```python
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 小字优先配置

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

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

### 17.4 减少误识别

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

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

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

### 17.5 已裁切单行文本

```python
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

```python
"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 不存在时会回退，必须检查：

```python
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 参数说明](https://rapidai.github.io/RapidOCRDocs/main/install_usage/rapidocr/parameters/)
- [RapidOCR 使用说明](https://rapidai.github.io/RapidOCRDocs/main/install_usage/rapidocr/usage/)
- [RapidOCR 推理引擎说明](https://rapidai.github.io/RapidOCRDocs/main/install_usage/rapidocr/how_to_use_infer_engine/)
- [RapidOCR 模型列表](https://rapidai.github.io/RapidOCRDocs/latest/model_list/)
- [RapidOCR GitHub 仓库](https://github.com/RapidAI/RapidOCR)
- [RapidOCR Releases](https://github.com/RapidAI/RapidOCR/releases)
- [ONNXRuntime DirectML Execution Provider](https://onnxruntime.ai/docs/execution-providers/DirectML-ExecutionProvider.html)
- [ONNXRuntime CUDA Execution Provider](https://onnxruntime.ai/docs/execution-providers/CUDA-ExecutionProvider.html)

本地核验文件：

- `.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`

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