pdf-craft v1.0.5 更新解读：GPU 显存优化、目录页检测加固与内容覆盖修复

• AI 应用
• OCR

pdf-craft 是一个专注于扫描版图书 PDF 处理、可将其转换为 EPUB / Markdown 等格式的开源项目（pyproject.toml）。本文以 v1.0.5 版本更新日志（docs/changelog/v1.0.5.md）为主体，逐项拆解该版本的三类核心改动——GPU 显存溢出修复、目录（TOC）检测精度提升、内容覆盖（content override）问题修复，并结合仓库源码（pdf_craft/extractor/toc/toc_pages.py、pdf_craft/pdf/ocr.py 等）说明其底层实现机制。读完本文，你将理解 v1.0.5 之前扫描版图书转换链路中的显存瓶颈从何而来、目录页误检的统计学根源，以及新引入的_TOC_SCORE_MIN_RATIO阈值如何工作，同时掌握升级后如何使用toc_assumed等参数控制行为。

v1.0.5 改动总览

Full Changelog覆盖了 v1.0.4 至 v1.0.5 的全部提交（docs/changelog/v1.0.5.md末尾记录）。当前仓库版本线已演进至 2.4.0（见 pyproject.toml 的version字段），v1.0.5 属于早期 1.x 版本线的重要质量修复节点，其修复思路在后续版本中持续沿用。

一、GPU 显存溢出修复：模型加载顺序与显存峰值控制

1.1 问题背景

v1.0.4 及更早版本中，在 RTX 3060（12GB VRAM）这类中端消费级显卡上对扫描版图书执行本地 OCR 时，经常出现CUDA out of memory错误（Issue #305）。扫描版 PDF 的每一页都要渲染成高分辨率图像后送入视觉模型进行版面分析与文字识别，模型参数、图像张量、中间激活共同叠加，显存峰值很容易超出 12GB 的物理上限。

1.2 修复方式：升级 doc-page-extractor 并优化加载顺序

修复本身不在 pdf-craft 主仓库，而是通过升级核心 OCR 引擎依赖doc-page-extractor完成的（PR #309）。模型参数的预加载与逐页推理被重新编排，将最耗显存的模型初始化阶段提前并串行化，避免多个大型模型同时驻留显存。

从当前仓库的依赖约束可以看到这条治理路径的延续：

• pyproject.toml 中doc-page-extractor>=1.2.1,<2.0.0，且可选依赖local = ["doc-page-extractor[local]>=1.2.1,<2.0.0"]，注释明确说明：将上游本地运行时作为一个整体依赖声明，使其内部的 transformer / CUDA 相关需求由 doc-page-extractor 自己负责，避免在 pdf-craft 侧重复声明引发版本漂移。

• 在 pdf_craft/pdf/ocr.py 中，OCR类将模型生命周期收敛为两个显式入口：

  • predownload(revision)→self._extractor.download_models(revision)，提前把模型权重下载到本地缓存；
  • load_models()→self._extractor.load_models()，负责把模型加载进显存。

  这种"先下载、后加载、加载完成即进入逐页推理"的分离设计，正是对"模型加载顺序优化"的落地：权重就位之后再统一加载，避免推理过程中边加载边推理造成的显存抖动。

1.3 显存治理的配套机制（源码佐证）

即使显存溢出修复后，OCR.recognize仍保留了多项降低显存/内存压力的配套能力（pdf_craft/pdf/ocr.py）：

• dpi参数：默认 300 DPI 渲染扫描页（ref.render(dpi=dpi if dpi is not None else 300)），调低 DPI 可显著减小送入模型的图像尺寸，从而降低张量显存占用；该参数在 v1.0.6 中正式对外开放（docs/changelog/v1.0.6.md）。
• max_page_image_file_size：超过上限时自动降低渲染分辨率，防止单页图像过大。
• device_number：显式指定 CUDA 设备编号，便于在多卡环境下手动分流。
• 对于UnlimitedOCRVendorConfig等云端厂商 OCR，recognize_vendor会将超过 8192 像素的长边等比缩放到 8192 后再请求，并记录scale_x/scale_y用于把返回的坐标还原到原始分辨率（pdf_craft/pdf/ocr.py_PreparedVendorPage与_parse_vendor_response）。

升级建议：如果你仍在 1.0.4 及更早版本并受 OOM 困扰，优先升级doc-page-extractor至 v1.0.5 配套版本；12GB 显存环境下建议配合dpi与max_page_image_file_size组合控制输入图像规模。

二、目录页（TOC）检测精度提升：前 17% 连续序列 + 分数下限

目录检测是 pdf-craft 处理扫描版图书的关键能力：v1.0.4 引入了基于 Aho-Corasick 子串匹配的统计式目录页定位（见 docs/changelog/v1.0.4.md），v1.0.5 则针对其误检问题打了两处关键补丁。

2.1 算法核心思路回顾

find_toc_pages（pdf_craft/extractor/toc/toc_pages.py）利用一个朴素而有效的统计特征：目录页中的文本会大规模与后续书页中的章节标题匹配。流程如下：

1. 遍历所有页面的标题布局（ref属于TITLE_TAGS的 layout），将规范化后的标题注册进_SubstringMatcher（内部为ahocorasick.Automaton），payload 记录(page_index, order)。
2. 对每一页正文做子串匹配，统计每个标题在该页的出现次数；单条匹配的分数 =该页匹配次数 / 该子串在文档中出现的总次数，分母惩罚了"书籍标题反复出现在页眉页脚"这类高熵标题。
3. 页面分数求和后降序排列，用相邻分数最大落差（max-diff）切分出候选目录页集合。
4. 候选页按页码升序，交给_human_like_toc_filter做"类人类阅读习惯"过滤。

2.2 补丁一：页码必须是前 17% 内的连续序列

_human_like_toc_filter中新增了双重要求（pdf_craft/extractor/toc/toc_pages.py）：

_MAX_TOC_RATIO = 0.1 # 目录页数上限：max(_MIN_TOC_LIMIT, total_pages * 0.1) _TOC_HEAD_RATIO = 0.18 # 目录页必须位于文档前 18%（即"前 17% 左右"的实现） _TOC_SCORE_MIN_RATIO = 3.0 # 经验估计，以后再调整吧 _MIN_TOC_LIMIT = 3 # 目录页数下限

具体逻辑：

• max_toc_page_index = round(total_pages * _TOC_HEAD_RATIO)：页码超过文档前 18% 的候选页直接剔除——真实的印刷目录必然出现在书的前部，若统计分数最高的页面散落在全书各处，说明匹配到的很可能是正文中的标题而非目录。
• 目录页数上限max_toc_pages = max(_MIN_TOC_LIMIT, int(total_pages * _MAX_TOC_RATIO))，防止把整本书都判成目录。
• 连续性检查：从得分最高的候选页出发，只保留page_index == last_page_index + 1的连续递增序列serial_refs；一旦出现断层立即截断。这一改动直接对应 changelog 中的 "ensuring page indexes are consecutive sequences"——真实目录页在物理上必然是连续相邻的几页，而误检的标题页通常是分散的。

2.3 补丁二：_TOC_SCORE_MIN_RATIO分数下限

连续性过滤之后，还有一道"置信度"闸门（pdf_craft/extractor/toc/toc_pages.py）：

max_content_score = 0.0 if cut_position < len(page_refs): max_content_score = page_refs[cut_position].score # 切分点之后的第一名 = 内容页最高分 # 被剔除但分数较高的非连续候选页也会抬高内容基线 for ref in toc_page_refs: if ref.page_index not in serial_page_indexes: max_content_score = max(max_content_score, ref.score) max_toc_score = serial_refs[0].score if max_toc_score < _TOC_SCORE_MIN_RATIO * max_content_score: return [] # 说明目录页不足以与非目录页拉开差距，不可贸然判断

含义：连续序列中最高分页的得分，必须至少是"内容页最高分"的 3 倍，否则判定候选页与普通正文页在统计上没有显著差异，直接返回空列表（宁可漏检、不可误检）。_TOC_SCORE_MIN_RATIO = 3.0是经验估计值（源码注释为"经验估计，以后再调整吧"），属于可调参数，后续若出现新的误报/漏报场景，可以此常量为起点做调参实验。

2.4 标题规范化的辅助作用

匹配质量还依赖normalize_text（pdf_craft/extractor/toc/text.py）的预处理：去除全部标点、拉丁字母转小写、NFD 拆解并丢弃重音符号（Mn类）、针对拉丁语把连字符换行截断的单词拼回、针对中韩等非拉丁语言删除字间空格。扫描件 OCR 噪声较大，这一规范化步骤保证了"目录文本"与"正文标题"在字符串层面尽可能一致，是统计匹配可行的前提。

2.5 测试与参数入口

• 测试用例 tests/test_toc_extraction.py 覆盖了toc_assumed开关对目录页剔除行为的影响：toc_assumed=False时find_toc_pages不会被调用（find.assert_not_called()），目录仅由章节标题层级生成；toc_assumed=True时检测出的目录页页码会写入TocInfo.page_indexes，并在生成正文时被排除（test_printed_toc_switch_only_controls_page_exclusion）。
• 顶层 API 中，toc_assumed定义于ExtractionOptions（pdf_craft/craft.py），并被传入analyse_toc(..., toc_assumed=options.toc_assumed, toc_llm=options.toc_llm)。其语义与 v1.0.4 一致：EPUB 默认True（尽量从 PDF 中定位印刷目录以还原导航结构），Markdown 默认False（仅按标题层级生成目录）。
• analyse_toc（pdf_craft/extractor/toc/analysing.py）中，找到目录页后优先用 LLM（toc_llm）分析层级，失败则回退到统计方法analyse_toc_levels；整个流程的结果会序列化为 XML 缓存到toc_path，重复运行时直接命中缓存。

三、内容覆盖（Content Override）问题修复

v1.0.5 的第三项修复来自 PR #312，针对内容处理阶段的覆盖（override）问题。结合 v1.0.4 的改进背景（docs/changelog/v1.0.4.md）：该版本重构了跨页段落合并逻辑，"improved paragraph merging across page boundaries with better handling of override assets and line continuation"——即当跨页段落携带覆盖资产（如图片、公式）时需要正确处理。v1.0.5 的 PR #312 正是对这类 override 场景中残留缺陷的收尾修复，确保在生成章节内容时，前一项（如上一页的行内图片）不会被后续项错误覆盖。

说明：PR #312 的改动未在主仓库中留下可直接引用的独立源码片段，属于对上一版本段落合并重构的修正性补丁；其效果可通过 v1.0.5 之后版本中章节流组装逻辑（pdf_craft/extractor/chapter/generation.py）与相关章节测试（如 tests/test_jointer.py、tests/test_flow_items.py）侧面验证——它们覆盖了文本片段与资产在段落流中的边界保持行为。

四、升级与实践指引

4.1 安装与升级

项目使用 Poetry 管理依赖（pyproject.toml），Python 版本要求>=3.11,<3.14。1.x 版本的典型安装方式（对应 v1.0.4 文档中的指引）为：

pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu pip install pdf-craft==1.0.5

本地 OCR（扫描件必需）请确保doc-page-extractor升级到 v1.0.5 配套的修复版本；若使用云端 OCR（DeepSeek OCR / Unlimited 等厂商模式，见 pdf_craft/pdf/ocr.py 的is_vendor判断），则不涉及本地显存，可跳过 CPU/GPU 版 PyTorch 的安装。

4.2 目录检测相关参数速查

4.3 验证方式

• 单元测试：tests/test_toc_extraction.py 可独立运行，验证目录开关行为；tests/test_toc_text.py、tests/test_toc_llm_analyser.py 覆盖标题规范化与层级分析。
• 冒烟测试资产：tests/smoke/下的 JSON 配置与 tests/assets/pdf/ 中的样例 PDF（含citation.pdf、index.pdf等多目录/多版式样本）可用于回归。

五、总结

v1.0.5 是 pdf-craft 1.x 版本线上承上启下的质量补丁：通过升级doc-page-extractor重构模型加载顺序，缓解了 12GB 显存显卡上的 OOM 问题；通过"前 18% 页码 + 连续页码序列 +_TOC_SCORE_MIN_RATIO分数下限"三重约束，让统计式目录检测从"高分即目录"进化为"高分且符合人类阅读习惯才判定"，显著降低误检与重复目录问题；并顺带修复了跨页内容覆盖缺陷。理解这些机制，有助于你在使用 pdf-craft 处理扫描版图书时，针对显存、目录误检等实际问题做出正确的参数调优与升级决策。

• AI 应用
• OCR