AI 应用OCR【免费下载链接】pdf-craftPDF craft can convert PDF files into various other formats. This project will focus on processing PDF files of scanned books.项目地址https://gitcode.com/gh_mirrors/pd/pdf-craft点击查看免费下载导读pdf-craft v1.0.6 是一版聚焦渲染控制、文本质量与容错能力的增量发布为 PDF 转 Markdown / EPUB 的核心提取链路带来了三个可直接配置的实战参数dpi页面渲染分辨率、max_page_image_file_size单页图像体积上限与ignore_ocr_errors单页 OCR 失败容错并内置了 Unicode 代理字符surrogate自动清理。读完本文你将掌握这些参数在 craft.py 中的定义位置、在 ocr.py 与 page_ref.py 中的底层生效机制以及如何在扫描书转换场景中组合使用它们平衡清晰度、文件体积与转换成功率。一、版本背景一次围绕扫描书处理链路的增强pdf-craft 的定位是把 PDF 转换为多种其他格式重点处理扫描书籍见仓库 README 与 v1.0.6.md。扫描书没有原生文本层整个转换链路高度依赖两件事把 PDF 页面栅格化为位图供 OCR 识别与后续排版以及从 OCR 结果中重组文本。v1.0.6 的四个变更恰好落在这一链路的关键节点上变更类型核心内容面向的问题特性新增dpi参数控制页面渲染分辨率默认 300 DPI图像质量与文件体积无法按需取舍特性新增max_page_image_file_size超限自动降 DPI单页图像过大导致输出文件失控膨胀特性新增ignore_ocr_errors单页识别失败不中断整体转换一本书中个别坏页导致整批转换失败特性自动清理 OCR 文本与 PDF 元数据中的 Unicode 代理字符输出文本混入无效码点破坏下游工具兼容性同期还升级了依赖epub-generator至 0.1.6并补充了 DeepWiki 文档徽标文档工程层面的改动不影响运行时行为。二、灵活 DPI 控制从固定 300 到按需可调在 v1.0.6 之前页面渲染分辨率是内部固定的v1.0.6 起dpi成为一级配置项默认值为300 DPI。2.1 参数定义位置在公开门面 craft.py 中ExtractionOptions数据类以dpi: int | None None声明该参数。None语义是未显式指定随后在 transform.py 的收尾阶段由draft.dpi if draft.dpi is not None else 300落到默认值 300dataclass(frozenTrue) class ExtractionOptions: page_indexes: Container[int] | None None ocr_size: DeepSeekOCRSize gundam dpi: int | None None # 页面渲染分辨率None 时回落 300 max_page_image_file_size: int | None None ... ignore_ocr_errors: IgnoreOCRErrorsChecker False2.2 底层生效链路dpi会贯穿三条路径OCR 识别在 ocr.py 的recognize/recognize_vendor中接收dpi并将其传入页面栅格化调用家具元素furniture写入transform.py 中write_furnitures(..., dpidraft.dpi if draft.dpi is not None else 300, ...)确保页眉页脚等家具元素与正文在同一分辨率下对齐PDF 回填patch阶段pipeline.py 通过extraction._render_dpi()读取提取阶段写入的渲染 DPI见 package.py再用该 DPI 重新栅格化原 PDF以像素级坐标把翻译/修复文本按区域回填。若此时用错 DPI区域坐标换算就会错位因此 DPI 必须全程一致。2.3 调参建议追求清晰度扫描质量差的旧书低分辨率、笔画断裂可上调至 400600OCR 识别率通常会随之提升追求体积与速度正文型文档可下调至 150200减少渲染与 OCR 耗时该参数直接影响单页位图的像素总数宽英寸 × dpi × 高英寸 × dpi是文件体积与识别质量的直接杠杆。三、自动图像尺寸优化max_page_image_file_size 的降采样机制max_page_image_file_size解决的问题很具体当高 DPI 渲染出的页面位图过大时自动降低 DPI防止输出文件不可控地膨胀。原文档示例中给出的取值是5242880即 5 MB/页。3.1 核心算法实现在 page_ref.py 的PDFPageRef.render()中def render(self, dpi: int, max_image_file_size: int | None None) - Image: if max_image_file_size is not None: width_inch, height_inch self._document.page_size(self._page_index) max_dpi round( self._dpi_with_size( file_sizemax_image_file_size, width_inchwidth_inch, height_inchheight_inch, ) ) dpi min(dpi, max_dpi) # 超出预算时取较低者 return self._document.render_page(page_indexself._page_index, dpidpi)其数学依据写在_dpi_with_size的注释中file_size width_px * height_px * bytes_per_pixel * compression_ratio 其中 width_px width_inch * dpiheight_px height_inch * dpi即按位图字节数估算反解出在预算内允许的最大 DPI。常量定义在 page_ref.py_PNG_COMPRESSION_RATIO 0.5 # 面向文档图像的经验压缩率 _BYTES_PER_PIXEL 3 # RGB 三通道最终dpi min(用户指定 dpi, 预算允许的 max_dpi)保证页面图像绝不会超过指定的字节预算。3.2 使用要点单位为字节5242880 5 MB请按单页上限而非全书总量来估算页数 × 单页上限 ≈ 总量上限该参数是硬预算比手动调 DPI 更适合批量、异构文档页面尺寸不一时预算会按每页实际英寸尺寸分别折算在recognize本地 OCR与recognize_vendor云端 OCR两条路径中均已接线ocr.py 与 ocr.py。四、容错 OCRignore_ocr_errors 的三种用法ignore_ocr_errors用于单页 OCR 识别失败时继续处理后续页面而不是终止整次转换。它在 error.py 中被类型化为IgnoreOCRErrorsChecker bool | Callable[[OCRError], bool]即既可以是布尔开关也可以是接收异常、返回是否忽略的判定函数。4.1 底层判定逻辑ocr.py 的_check_ignore_error统一处理两种形态def _check_ignore_error(check: bool | Callable[[_T], bool], error: _T) - bool: if isinstance(check, bool): return check # True全部忽略False立即抛出 else: return check(error) # 回调按异常逐页决策在页面级处理中ocr.pyOCR 失败会被包装为携带page_index与step_index的OCRError见 error.py若判定为忽略该页会写一个page_{index}.failed标记并生成降级回退页同时继续后续页面若判定为不忽略则立即抛出并中止。4.2 三种推荐用法# 用法 1全局忽略——坏页尽量多希望能出多少出多少 transform_markdown(..., ignore_ocr_errorsTrue) # 用法 2精确忽略——只容忍特定异常类型如渲染层面的 PDFError 或超时类错误 from pdf_craft import transform_markdown from pdf_craft.error import OCRError def should_ignore(error: OCRError) - bool: return isinstance(error, OCRError) and error.step_index 1 # 仅容忍第一阶段失败 transform_markdown(..., ignore_ocr_errorsshould_ignore) # 用法 3按页码忽略——对已知坏页放行其余照常严格 def ignore_pages(error: OCRError) - bool: return error.page_index in {7, 42, 88} transform_markdown(..., ignore_ocr_errorsignore_pages)4.3 边界与兜底需要特别留意当所有页都失败且无任何可用页时即使ignore_ocr_errorsTrue提取也会抛出NoUsableOCRPagesErrorerror.py提示全部请求页面在忽略错误后仍无可用页。这是防止静默产出空书的最终防线。被忽略的失败页会以回退页形式进入流程最终转换结果中该页内容质量可能下降——因此该参数适合先保整体、后补坏页的工作流而非掩盖系统性故障的手段。五、文本质量改进Unicode 代理字符自动清理Unicode 代理区surrogate码点UD800 至 UDFFF是 UTF-16 编码的内部拼接单元不是合法独立字符。OCR 引擎或 PDF 元数据解析器一旦把它们泄漏进文本流下游工具JSON 序列化、XML 解析、数据库、渲染器就可能报错或显示乱码。5.1 实现位置清理函数位于 surrogates.py逻辑极其轻量# surrogate characters (UD800 to UDFFF) def remove_surrogates(text: str) - str: return .join(char for char in text if not (0xD800 ord(char) 0xDFFF))并通过 common/init.py 的from .surrogates import *导出。5.2 实际调用链从源码看该函数在页面文本规范化路径中被调用page_extractor.py 的_normalize_text会在整理空白前先执行remove_surrogates(text)def _normalize_text(self, text: str | None) - str: if text is None: return text remove_surrogates(text) # 先剔除代理字符 text re.sub(r\s, , text) # 再压缩连续空白 return text.strip()这意味着 OCR 输出的每一段文本在进入章节提取、渲染流程之前都会经过代理字符清洗。按 v1.0.6 变更说明PDF 元数据标题、作者、出版社等同样受益于该清理从而保证 PCEX 提取物与下游 Markdown / EPUB 渲染、翻译管线拿到的是合法 Unicode 文本。六、完整实战示例三参数组合使用原文档给出了一个可直接运行的示例它恰好演示了三个新参数的组合。以下为其完整形态保持原语义并补充注释与最佳实践说明from pdf_craft import transform_markdown transform_markdown( pdf_pathinput.pdf, markdown_pathoutput.md, dpi300, # 渲染分辨率清晰度不够可提到 400~600体积敏感可降到 150~200 max_page_image_file_size5242880, # 单页位图上限 5MB超限时自动降 DPI见 page_ref.py 预算算法 ignore_ocr_errorsTrue, # 单页 OCR 失败不中断继续处理后续页面 )按上一节的分析等效的精细化版本可以这样写from pdf_craft import transform_markdown from pdf_craft.error import OCRError def tolerant_ocr(error: OCRError) - bool: # 只忽略页面渲染阶段step_index 1的失败其余错误仍然暴露 return error.step_index 1 transform_markdown( pdf_pathscanned_book.pdf, markdown_pathscanned_book.md, dpi360, max_page_image_file_size4 * 1024 * 1024, # 4MB/页 ignore_ocr_errorstolerant_ocr, )运行前提说明该函数面向扫描书 PDF需要项目按 INSTALLATION.md 完成环境与模型就绪ignore_ocr_errors传入可调用对象时判定函数会收到带page_index与step_index的OCRError类型定义见 error.py可按需构造更细的容错策略。七、与整体架构的关系参数如何贯穿提取—渲染—回填三阶段从 transform.py 的PDFExtractionEngine与 craft.py 的AsyncPDFCraft门面可以确认这三个参数不是孤立开关而是统一在ExtractionOptions中建模、一次性贯穿整条提取管线提取阶段transform.py 将dpi、max_page_image_file_size、ignore_ocr_errors原样下传给 OCR 引擎与页面栅格化持久化阶段render_dpi会被写入提取物页面记录package.py 的_render_dpi()可随时读回供后续渲染与回填复用回填阶段pipeline.py 的PDFTranslationPipeline与 patcher.py 的PDFPatcher均以提取阶段记录的 DPI 为基准重新栅格化原 PDF保证翻译/修复文本的像素级定位一致。因此无论最终产物是 Markdown、EPUB还是翻译后回填进原 PDF对应translate_pdf/patch_pdf_with_extraction路径见 craft.pyv1.0.6 的 DPI 相关配置都具备端到端的一致性保障。相关测试用例可在 test_book_metadata.py以dpiNone、max_page_image_file_sizeNone、ignore_ocr_errorsFalse校验默认提取选项以及 test_pdf_patcher.py、test_pdf_craft_extraction.py 中找到对应验证。八、升级建议与注意事项小结依赖变更epub-generator升级至 0.1.6涉及 EPUB 生成侧升级到 v1.0.6 时建议一并刷新锁定文件仓库内的 poetry.lock / pyproject.toml默认值语义dpi与max_page_image_file_size的默认值为None等价于沿用 300 DPI、不做体积限制——即老版本行为升级后无参数代码完全不受影响容错并非万灵药ignore_ocr_errorsTrue会掩盖单页质量问题最终产出中失败页可能缺失或退化若整本书失败页占比很高应优先排查渲染分辨率、OCR 后端配置与模型加载相关排查可参考 TROUBLESHOOTING.md字节预算的单位max_page_image_file_size单位为字节配置时注意 KB/MB 换算建议按最大页数 × 单页预算估算最终产物体积上限代理字符清理是静默的remove_surrogates在文本规范化路径自动生效无需额外配置若自定义 OCR 后端产出文本仍建议在接入侧自行校验因为清理发生在页面文本组装环节page_extractor.py。综上v1.0.6 的核心价值在于把渲染分辨率、体积预算、失败容忍度三个此前固定的内部行为开放为可配置参数并补齐了 Unicode 合法性的底层防线对扫描书批量转换场景建议优先实践dpimax_page_image_file_size的组合控制质量与体积再按坏页分布决定ignore_ocr_errors采用全局开关还是精确回调。赞分享AI 应用OCR【免费下载链接】pdf-craftPDF craft can convert PDF files into various other formats. This project will focus on processing PDF files of scanned books.项目地址https://gitcode.com/gh_mirrors/pd/pdf-craft点击查看免费下载相关推荐PDF-Lib终极字体渲染优化指南10个技巧提升文本显示质量PDF Lib终极字体渲染优化指南10个技巧提升文本显示质量 PDF Lib是一个强大的JavaScript库允许开发者在任何JavaScript环境中创建开发工具Windows Vista/7 Python 3.8-3.14兼容性解决方案技术指南Windows Vista/7 Python 3.8 3.14兼容性解决方案技术指南 如何在Windows Vista SP2、Windows Server 2操作系统xone驱动完全解析从安装到配置的快速入门教程xone驱动完全解析从安装到配置的快速入门教程 xone是一款专为Linux系统设计的Xbox One和Xbox Series X|S配件内核驱动作为xpa上一篇Hitboxer终极指南免费解决游戏键盘输入冲突的神器下一篇drawio-desktop 完整上手教程免费打开 Visio VSDX 文件5 分钟跑通三系统批量导出创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考