Add FireRed OCR comparison and preserve attribution layout

2026-10-29 00:14:13 +08:00
parent cad96d59c8
commit 166ea871d3
10 changed files with 355 additions and 16 deletions
@@ -88,3 +88,23 @@ EPUB 在临时文件中构建并通过结构审计后才替换输出。没有依
 ```

 源 SHA、行 ID 或 expected 不匹配就停止；重复条目和空替换也拒绝。原始 `pages/*.json` 不改写，校正写在派生 `book.json` 和报告里，可在重建时重复应用。识别内容变化会改变输出版本标识。此功能用于有证据的文字校对，不替代全书审读。
+
+
+## FireRed OCR 服务与前 50 页对比
+
+`--ocr firered --ocr-url http://HOST:PORT` 使用显式指定的 OpenAI-compatible 服务，默认模型别名为 `firered-ocr`，可用 `--ocr-model` 更换。客户端仅新增标准库 HTTP 调用，复用 Pillow，不下载模型。当前适配器面向无需认证的内网服务。
+
+```bash
+.venv/bin/python scripts/pdf_to_epub.py input/chinese.pdf \
+  --output output/pdf/firered-sample.epub --work .work/pdf-firered \
+  --language zh-CN --title '书名' --author '作者' --pages 1-50 \
+  --ocr firered --ocr-url http://192.168.50.100:8001 --cover-page 1
+```
+
+输入图片最长边限制为 1600px，请求 temperature=0、max_tokens=1800，适配本次服务 4096-token 上下文。`--ocr-prompt FILE` 可以指定识别提示；实验使用官方 `conv_for_infer.py` 的提示，来源为 [FireRed-OCR 官方仓库](https://github.com/FireRedTeam/FireRed-OCR)。图片有效内容及设置参与缓存指纹，原始 Markdown、响应、用量和耗时写入工作目录。响应必须正常结束；截断结果保留为 rejected 文件并停止，不当作完整页面接受。
+
+FireRed 返回 Markdown，没有可信的字行坐标和逐字置信度。适配器保留段落和简单标题，未知 bbox 为 null，不虚构坐标。可用 `--geometry-work .work/previous-vision` 引用同源、同页 Vision 缓存的几何信息；模块检查源 SHA 并通过文本对齐匹配坐标，记录来源和匹配比例，正文仍全部来自 FireRed。没有几何参考时不保证还原署名等空间对齐。
+
+署名／日期等短窄右侧行保持独立段落和右对齐，日期不再误当页眉页脚删去；这些段落也不会跨页拼接。扫描混合图文仍需显式保留原页，不自动裁图。
+
+`scripts/compare_pdf_ocr.py` 生成逐页原扫描／Vision／FireRed 对照。两引擎文本一致率不等于准确率；可提供人工核对片段测算局部字错率，不能推广为全部页面准确率。首轮结果和方法见 [50 页验收记录](QA_FIRERED_50_2026-10-29.md)。
@@ -0,0 +1,40 @@
+# FireRed 前 50 页对比与 EPUB 结构修复
+
+日期：2026-10-29。样本为用户提供的《中国的世界高原（上）》扫描 PDF，共 476 页；本次只请求并输出原 PDF 第 1–50 页。
+
+源 SHA256：`aebc9f263ab0599f6d11c7db6c5e89e1316f2a950f2faa9ddbc72a94fe3da335`。
+
+## 识别条件
+
+- 服务 `http://192.168.50.100:8001/v1`，公开别名 `firered-ocr`，vLLM 报告上下文 4096；未暴露权重版本，不推断模型大小或量化方式。
+- 官方提示、temperature=0、max_tokens=1800、最长边1600px；全部50页正常 stop。原响应保存在 `.work/pdf-firered-50/comparison-pages/` 与 `firered-raw/`。
+- Vision 对照使用已有180dpi缓存，因此不是同输入分辨率的严格模型基准。原参考中封面、扉页、目录的图片保留页没有 Vision 文本，不能将其计为漏识别。
+
+## 人工片段对比
+
+从第4、12、16、30、50页人工转录5个诊断片段，共721个归一化字符。同页寻找最佳对应子串，计算编辑距离；NFKC处理后仅保留字母、数字、汉字，排除标点和空白。
+
+| 引擎 | 编辑数 | 局部字错率 |
+| --- | ---: | ---: |
+| 原 Vision | 16 | 2.22% |
+| FireRed | 1 | 0.14% |
+
+这些片段不是随机样本，不代表全部50页或全书准确率。FireRed 在第30页把“拥有”识别成“有”；另有标点遗漏，不能视为已完整校对。首次人工转录曾将“饿肚”误写为“挨肚”，放大原扫描复核后更正；旧转录与放大截图留在本地审计目录，最终表格使用更正结果。原始 OCR 未被手工修订。
+
+## 排版与结构
+
+两份输出都是前50页的部分重排初稿：44页文字重排，6页保留原图（第1、2、13、14、15、30页）。第30页含照片，保留整页以防图片丢失；其原始 FireRed 文本仍参与 OCR 对比。
+
+修复署名、日期被并入正文及失去右对齐的问题：短窄右侧块分别输出为 attribution 段落，日期不当作页脚移除。FireRed 本身无坐标，本样例借用同源 Vision 的文字匹配几何，正文不取自 Vision。无法匹配的坐标保留未知，不伪造。
+
+每份 EPUB 均通过结构审计，保留50个来源页锚点，实际点击12个目录目标成功；第4、12、16、30、50页在900px和390px宽度检查未报越界。已直接查看署名日期截图，确认独立且右对齐。Chromium连续XHTML检查不能代表所有阅读器分页，也不等于全文OCR验收。
+
+## 本地交付与复现
+
+- `output/pdf/中国的世界高原_上_FireRed_前50页样例.epub`
+- `output/pdf/中国的世界高原_上_Vision_前50页结构修复对照.epub`
+- `.work/pdf-firered-50/comparison/index.html`：全部50页扫描及两种原始OCR逐页对照。
+- `.work/pdf-firered-50/qa-final/review.html`、`.work/pdf-vision-50/qa-final/review.html`：响应式排版、导航检查。
+- `.work/pdf-firered-50/review-record.json`：绑定输入、输出哈希与抽查范围。
+
+代码验证：`python -m pytest -q`，103 passed、2 skipped。模型响应、图像、书籍摘录及 EPUB 留在本地，不提交仓库。原476页 Vision 初稿未在本次覆盖或重做。