tess4j.Word.getConfidence()为何总是返回-1？

Question

在使用Tess4J进行OCR识别时，`tess4j.Word.getConfidence()` 方法常返回 `-1`，而非预期的 0–100 置信度值。根本原因在于：Tesseract 本身仅对 *字符级（char）* 置信度提供稳定支持，而 `Word.getConfidence()` 是 Tess4J 封装的“伪字段”——其底层依赖 Tesseract 的 `ResultIterator::WordConfidence()`，但该接口在多数版本（尤其 v4+ LSTM 模式下）默认不启用词级置信度计算，或因 `PageIteratorLevel.WORD` 迭代器未正确初始化/未调用 `GetWordText()` 后续方法导致缓存未填充。此外，若图像质量差、语言模型不匹配或未启用 `OcrEngineMode.TESSERACT_ONLY`（混合引擎下词置信度可能被禁用），也会触发回退至 `-1`。解决方案包括：确保使用 `TessBaseAPI.SetVariable("save_best_choices", "T")` 并配合 `ResultIterator.GetWords()` 正确遍历；优先采用 `Symbol.getConfidence()` 或 `getUTF8Text()` + 字符级置信度聚合；升级至 Tess4J 5.4+ 并验证 Tesseract 5.3+ 原生支持。

Answer 1

```html

一、现象层：表征与复现路径

开发者在调用 tess4j.Word.getConfidence() 时，高频观察到返回值恒为 -1，而非文档宣称的 0–100 整数区间。该现象在 Tess4J 4.5.x + Tesseract 4.1.1（LSTM 默认启用）、Tess4J 5.2 + Tesseract 5.0.1 等主流组合中稳定复现，且与输入图像 DPI（300+）、二值化预处理（Otsu/Adaptive）无关。

二、机制层：Tesseract 底层置信度架构解析

• Tesseract v4+ 默认采用 LSTM 神经网络引擎，其 WordConfidence() 接口不直接输出词级概率，而是依赖解码器后处理阶段的 best_choices 缓存；
• PageIteratorLevel.WORD 迭代器需严格遵循「先调用 GetUTF8Text() 或 GetWordText() → 再调用 WordConfidence()」顺序，否则内部 word_confidence_ 字段未触发 lazy-init，强制返回 -1；
• 混合引擎模式（OcrEngineMode.TESSERACT_LSTM_COMBINED）下，Tesseract 会跳过词级置信度聚合逻辑，仅保留字符级输出。

三、配置层：关键变量与引擎模式影响

配置项	推荐值	作用说明
save_best_choices	"T"	强制保存每个识别单元的候选字及其置信度，是 WordConfidence() 的前提条件
tessedit_create_txtfile	"0"	禁用冗余文本输出，避免干扰迭代器状态机
ocr_engine_mode	TESSERACT_ONLY	LSTM-only 模式下词置信度仍不可靠，但 TESSERACT_ONLY 是唯一可能激活该能力的模式

四、实践层：可落地的三级解决方案

1. 规避策略：弃用 Word.getConfidence()，改用 Symbol.getConfidence() 获取每个字符置信度，再按词聚合（如取均值、最小值或加权平均）；
2. 补全策略：在 ITessAPI 初始化后插入：
   api.SetVariable("save_best_choices", "T");
   并确保遍历逻辑为：resultIt.GetWords(PageIteratorLevel.WORD, true)（true 表示 force_init）；
3. 升级策略：迁移至 Tess4J 5.4+（封装 Tesseract 5.3+），验证 ResultIterator::WordConfidence() 在 TESSERACT_ONLY 模式下是否返回有效值（需配合 SetPageSegMode(PAGE_SEG_MODE.SINGLE_BLOCK) 提升稳定性）。

五、验证层：调试流程图与断点检查点

graph TD
  A[初始化 TessBaseAPI] --> B[SetVariable save_best_choices=T]
  B --> C[SetPageSegMode SINGLE_BLOCK]
  C --> D[SetOcrEngineMode TESSERACT_ONLY]
  D --> E[Recognize]
  E --> F[GetIterator]
  F --> G{调用 GetWordText?}
  G -->|Yes| H[WordConfidence 返回有效值]
  G -->|No| I[WordConfidence = -1]
  H --> J[记录 confidence 均值与标准差]
  I --> K[检查日志：tesseract::lstm::LSTMRecognizer::BestChoiceConfidence]

六、演进层：Tesseract 5.3+ 的原生支持进展

Tesseract 5.3 引入 Word::confidence_ 字段的显式计算逻辑（见 ccmain/wordrec.cpp#L1278），当启用 --oem 1（即 TESSERACT_ONLY）且语言模型含 .lstm 后缀时，会基于 LSTM 输出的 top-3 候选字进行贝叶斯加权融合。但该能力仍受制于训练数据覆盖度——若待识别词未在训练语料中以完整单词形式出现，则 confidence 仍回退至 -1。

七、工程层：生产环境健壮性封装建议

public static double getWordConfidenceSafely(Word word) {
  int raw = word.getConfidence();
  if (raw == -1) {
    return Arrays.stream(word.getSymbols())
                 .mapToInt(Symbol::getConfidence)
                 .filter(c -> c > 0)
                 .average()
                 .orElse(0.0);
  }
  return Math.max(0.0, Math.min(100.0, raw / 100.0)); // 归一化至 [0,1]
}

八、陷阱层：被忽视的三大隐性依赖

• 图像预处理依赖：即使启用 save_best_choices，若输入图像存在严重倾斜（>±5°）或行距压缩（< 1.2× 字高），PageIterator 无法准确定界 WORD 级别区域，导致置信度缓存失效；
• 语言包依赖：非拉丁语系（如 chi_sim、jpn）的 .lstm 模型默认关闭词级置信度，需手动编译时添加 -DENABLE_WORD_CONFIDENCE=ON；
• JNI 生命周期依赖：Tess4J 5.3 中 Word 对象强引用 ResultIterator，若迭代器提前 delete，后续调用 getConfidence() 必然返回 -1。

```