★ FEATURED ARTICLE 人工智能大模型微调LoRA模型优化模型量化强化学习【免费下载链接】unslothLocal UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4, MiniMax-H3, Gemma 4, FLUX and more.项目地址https://gitcode.com/GitHub_Trending/un/unsloth点击查看免费下载Unsloth Studio仓库 studio/ 目录内置了一套完整的扫描版 PDF 文本提取能力在 Chat 对话、项目来源project sources与 Data Recipes 三种场景中凡是纯图像页的扫描 PDF都会被自动转录为可检索文本已有可选文字层selectable text的页面则原样保留。本文以官方文档 studio/PDF_OCR.md 为主线结合仓库中core/rag模块的源码与测试完整讲解本地 OCR 的搭建步骤、全部RAG_OCR_*环境变量、视觉模型与 Tesseract 的双引擎回退链路、独立进程提取机制以及上传失败时如何精准定位并解决不可读页面问题。一、OCR 工作流总览三个入口、两套引擎1.1 三种应用场景扫描 PDF 的 OCR 并不只在某一个界面生效而是贯穿 Unsloth Studio 的检索链路覆盖三个入口Chat 上传对话中上传的扫描 PDF 会被纳入当前线程thread scope的 RAG 索引之后可在对话中按语义检索到扫描件内容项目来源project sources加入项目的扫描文档同样走 OCR 预处理项目内检索可用Data Recipes以扫描 PDF 为数据来源构建学习配方learning recipe时需要先把 PDF 正文提取成可用文本再走配方流程。三者共享同一套页面分类与转录机制核心实现在 studio/backend/core/rag/ 下的parsers.py、pdf_ocr.py、ingestion.py区别仅在 OCR 引擎的优先级与进程模型上。1.2 双引擎回退顺序文档明确给出两条 OCR 路径其优先级与触发条件在源码中一一对应场景第一优先回退引擎是否依赖已加载的聊天模型Chat / 项目上传已加载的本地vision GGUF模型本地Tesseract通过 PyMuPDF 集成是优先用视觉模型Data Recipes本地Tesseract无否不要求加载聊天模型Chat 场景的视觉模型路径实现在 captioner.py 的ocr_pages()先把扫描页用render_pdf_pages()渲染成 PNG默认 150 DPI再逐页调用已加载的视觉 GGUF 模型转录若视觉模型未加载或转录失败则回退到本地 Tesseract。而 Data Recipes 的 PDF 提取直接走 seed.py 中的pdf_ocr.extract_text()只依赖本地 Tesseract因此即使当前没有加载任何视觉模型也能工作。需要区分的是正文 OCR 与图片描述figure captioning是两套独立功能。Chat 界面另有独立的 figure-captioning 设置用于给正文之外的插图生成文字描述对应RAG_CAPTION_*配置组见 config.py不要与扫描页 OCR 混淆。二、哪些页面需要 OCR页面分类的判定逻辑只对纯图像页做 OCR、已有文字层原样保留这句话背后是一套精确的逐页判定逻辑位于 parsers.py 的_pdf()函数。每个页面最终生成一个Page对象携带text、page_number1 起始、char_count与needs_ocr四个字段见 parsers.py。判定规则可以归纳为三层无文字层的纯图像页页面中存在嵌入图像page.get_image_info()非空且没有可提取的纯文本plain.strip()为空时needs_ocr True。这是最典型的扫描页带可选中页眉/页脚的扫描页页面存在覆盖面积 ≥ 页面面积 50% 的大图时把图像区域上下各裁掉 10% 得到正文区域body见 parsers.py若该区域内可选文字长度小于OCR_MIN_CHARS默认 16 字符则判定为扫描页。这正是文档所说的带可选中页眉页脚的扫描件也要 OCR——页眉页脚的少量文字不会让整页免于转录不触发 OCR 的情形面积小于页面一半的小 logo、以及页面本身有足够可选正文时needs_ocr False完全空白的间隔页也不会被标记对应测试 test_pdf_local_ocr.py 中的test_blank_separator_needs_no_ocr。此外PDF 解析层还有两项重要保护一是密码保护的 PDF 会直接抛出encrypted PDF requires a passwordparsers.py二是默认启用布局感知的 Markdown 提取RAG_PDF_MARKDOWN1基于 pymupdf4llm但当检测到 RTL/印度系文字被字形重建破坏、或 Markdown 文本量显著少于原始文字层时会自动回退到 PyMuPDF 的逻辑顺序纯文本避免检索内容被破坏parsers.py。三、本地 OCR 环境搭建Tesseract 与语言数据扫描页转录的后备引擎是Tesseract通过PyMuPDF 的内置 OCR 集成page.get_textpage_ocr()调用。搭建过程分三步全部在运行 Unsloth Studio 后端的那台机器上完成3.1 安装 Tesseract 引擎与语言数据按操作系统安装 Tesseract 软件包及其语言数据例如# Debian / Ubuntu 示例安装引擎 英文语言数据 sudo apt-get install tesseract-ocr tesseract-ocr-eng也可从 Tesseract 官方 tessdata 仓库获取语言文件。仓库不会自动下载任何 OCR 数据——ocr_pages()的 docstring 明确写着No downloads or model loading. Tesseract language data must already be installedpdf_ocr.py这一点务必在部署时自行满足。3.2 设置 TESSDATA_PREFIXTESSDATA_PREFIX必须指向存放.traineddata文件的 tessdata 目录并且在启动 Unsloth Studio 之前设置好因为它是在进程启动后读取的环境变量。在代码中该值会被透传给 PyMuPDF 的tessdata参数pdf_ocr.py# 示例把 TESSDATA_PREFIX 指向系统 tessdata 目录后再启动 Studio export TESSDATA_PREFIX/usr/share/tesseract-ocr/5/tessdata # 然后启动 Unsloth Studio 后端注意tessdata os.environ.get(TESSDATA_PREFIX) or None如果未设置PyMuPDF 会使用其内置查找路径为了可控性官方文档建议显式配置。3.3 设置 RAG_OCR_LANGUAGERAG_OCR_LANGUAGE指定要使用的语言代码默认值为eng见 pdf_ocr.py。多个语言用连接此时对应语言的.traineddata文件都必须存在例如engdeu要求同时具备eng.traineddata与deu.traineddataexport RAG_OCR_LANGUAGEengdeu四、OCR 相关环境变量完整对照表所有 OCR 参数都集中在 config.py每个值均可通过环境变量覆盖并统一使用RAG_OCR_前缀环境变量默认值源码字段含义RAG_OCR_SCANNED1启用OCR_SCANNED是否默认对扫描页执行 OCR。设为0可关闭默认行为详见第五节Chat 界面的OCR scanned pages开关可对 Chat/项目上传单独覆盖RAG_OCR_MIN_CHARS16OCR_MIN_CHARS页面可选文本长度低于该值时才被纳入可能扫描页候选也用于判定带页眉页脚的扫描页正文是否可读RAG_OCR_MAX_PAGES20OCR_MAX_PAGES每个 PDF 最多转录的扫描页数上限。预期扫描件页数更多时应在启动 Studio 前调大RAG_OCR_DPI150OCR_DPI本地 OCR 与页面渲染使用的 DPI。分辨率过低的小字扫描件可尝试调高RAG_OCR_TIMEOUT_S60OCR_TIMEOUT_S视觉模型单页 OCR 的超时秒数RAG_OCR_MAX_TOKENS2048OCR_MAX_TOKENS视觉模型单页 OCR 的最大输出 token 数RAG_OCR_LANGUAGEeng直接读取Tesseract 语言代码多语言用连接TESSDATA_PREFIX未设置直接读取.traineddata文件所在目录另外正文之外还有一组RAG_CAPTION_*配置RAG_CAPTION_IMAGES、RAG_CAPTION_MAX_IMAGES、RAG_FIGURE_DPI、RAG_FIGURE_TILE_ROWS/COLS等见 config.py它们控制 Chat 的图片描述功能属于另一条独立链路OCR 文档中提到的Chat has a separate figure-captioning setting即指此。五、限制与失败上传宁可报错不可静默丢页这是 Unsloth Studio 扫描 OCR 最有价值的设计如果扫描页无法转录上传会失败并明确列出页码而不是静默接受一个内容残缺的文档。5.1 默认开关与覆盖优先级后端默认值在源码中是启用的OCR_SCANNED默认1设置RAG_OCR_SCANNED0可关闭默认扫描页 OCRChat 的OCR scanned pages设置可以对该开关进行覆盖——即后端默认关闭时Chat 仍可为 Chat/项目上传单独开启Data Recipes 则严格遵循后端默认值没有界面开关覆盖。这一点在 ingestion.py 中得到印证_ocr_scanned_pages()首先判断config.OCR_SCANNED if ocr is None else ocr其中ocr参数即来自 Chat 侧的可选覆盖。5.2 失败语义与错误信息当 OCR 转录完毕后仍有needs_ocr页面未被成功转录时extract_text()会抛出unreadable_pages_error()pdf_ocr.py。错误信息包含不可读页码列表最多列出前 20 个超出时追加(and N more)修复提示启用 OCR、配置 Tesseract 语言数据TESSDATA_PREFIX或改传带文字层的可检索 PDF当前OCR_MAX_PAGES上限的说明。对应测试 test_pdf_local_ocr.py 验证当 OCR 引擎完全不可用时上传状态为error错误文本包含scanned PDF pages: N与TESSDATA_PREFIX提示且不会残留任何半成品文件_block_files(route) []。5.3 页数上限不是静默截断OCR_MAX_PAGES默认 20存在两种行为超出预算的部分_ocr_scanned_pages()会记录 warningpages past the cap stay untranscribed (raise RAG_OCR_MAX_PAGES to cover them)并截断ingestion.py已纳入预算但转录失败的部分直接导致上传失败并报出页码。测试test_ocr_page_cap_does_not_silently_drop_pagestest_pdf_local_ocr.py把上限压到 1、构造 2 页扫描件验证结果是error/failed而不是少一页但成功。另外候选页排序时可选短页/空白页不会挤占真正的扫描页预算scanned.sort(key lambda number: number not in required)见 ingestion.py。5.4 空文档也会失败空文档同样不会被静默接受一个提取后没有任何文本的文档不会以0 个可检索 chunk的形态进入索引而是作为失败处理避免用户日后检索时遇到内容空洞的文件。5.5 失败后的处置路径上传失败后的标准处置文档给出了四条建议配置正确的 OCR 语言数据检查TESSDATA_PREFIX与RAG_OCR_LANGUAGE是否匹配已安装的.traineddata启用 OCR对 Data Recipes 确认RAG_OCR_SCANNED未设为0对 Chat 检查OCR scanned pages开关扫描件页数较多时在启动 Studio 前调大RAG_OCR_MAX_PAGES改传一份带文字层的可检索 PDFsearchable PDF然后重新附加文件。测试test_failed_scan_replacement_preserves_searchable_originaltest_pdf_local_ocr.py进一步验证用失败的新文件替换旧文件时原有的可检索文档会被完整保留不会被失败的替换拖下水。六、源码级深入一条扫描 PDF 的完整 OCR 旅程把上述机制串起来一个扫描 PDF 从上传到可检索在 Chat 场景大致经历如下调用链以 ingestion.py 的_ocr_scanned_pages()为中心解析分类parsers.parse()逐页生成Page标记needs_ocr判定规则见第二节预算裁剪收集所有候选扫描页按必需页优先排序后截断到OCR_MAX_PAGES视觉模型优先若captioner.vision_endpoint()可用先把页面渲染成 PNGrender_pdf_pages(dpiOCR_DPI)逐页交给视觉 GGUF 转录进度通过_progress(conn, job_id, ocr, ...)上报为 0.25 → 0.40 区间ingestion.pyTesseract 回退对needs_ocr且视觉模型未转录的页面调用pdf_ocr.ocr_pages()用本地 Tesseract 补齐ingestion.py。这使得只有文本类 GGUF 模型无视觉能力的部署也能处理扫描 PDF合并与校验把 OCR 文本写回对应Page仍缺页则整体失败见第五节。6.1 文本合并策略保留一切可选文字OCR 结果与原有文字层按互补不覆盖的原则合并逻辑见 pdf_ocr.py 与 ingestion.py若原页面没有文本或原文本已完整包含在 OCR 结果中直接用 OCR 结果若两者都存在且不同则用原文本 \n\n OCR 文本拼接保证页眉页脚等可选文字与扫描正文都进入检索。测试test_scan_with_digital_header_still_gets_ocrtest_pdf_local_ocr.py验证带数字页眉的扫描页页眉文字只出现一次、扫描正文成功转录——既没丢页眉也没重复。6.2 Data Recipes 的独立进程提取文档特别强调Recipe PDF 提取运行在独立的 worker 进程中OCR 不会阻塞其他请求。源码在 seed.py 中落实# MuPDF is not thread-safe; each worker owns its document and OCR state. raw await to_process.run_sync( pdf_ocr.extract_text, str(file_path), config.OCR_SCANNED, config.OCR_MAX_PAGES, cancellable True, limiter _pdf_extraction_limiter, )这里有两层隔离一是把pdf_ocr.extract_text()通过run_sync放到独立进程中执行注释点明 MuPDF 非线程安全每个 worker 独占自己的文档与 OCR 状态二是通过CapacityLimiter(2)限制并发 PDF 提取数_pdf_extraction_limiter见 seed.py防止大量扫描件同时转录打满 CPU。这也是OCR 不阻塞其他请求的工程实现——长文档的转录被移出主事件循环。6.3 OCR 引擎自身的防御设计ocr_pages()内部还有一处细节当某页 OCR 抛异常例如语言包缺失时会记录 warning 并break 提前退出而不是对整份文档的每一页都反复尝试一个不可用的引擎pdf_ocr.py。测试test_local_ocr_engine_failure_returns_no_texttest_pdf_local_ocr.py覆盖了这一路径引擎不可用时返回空 dict由上层统一触发失败提示。七、测试验证矩阵仓库如何保证 OCR 可靠性仓库为扫描 PDF OCR 维护了两份测试test_pdf_local_ocr.py本地 Tesseract 路径与 test_pdf_ocr_regressions.py回归防护。前者覆盖的关键场景如下可作为自测清单测试用例验证点test_recipe_scanned_pdf_extracts_local_ocrData Recipes 上传纯扫描/混合 PDF正文成功转录且页码正确test_chat_scanned_pdf_searchable_without_visionChat 场景无视觉模型时Tesseract 兜底让扫描件可检索test_scan_with_digital_header_still_gets_ocr带数字页眉的扫描页仍判为需 OCR页眉不重复test_recipe_missing_ocr_rejects_incomplete_pdfOCR 不可用时上传报错并列出页码不留残件test_ocr_page_cap_does_not_silently_drop_pages页数上限内失败必须显式报错而非静默截断test_chat_vision_failure_falls_back_locally视觉模型失败时自动落到本地 Tesseracttest_blank_separator_needs_no_ocr空白间隔页不触发 OCRtest_recipe_respects_disabled_ocrRAG_OCR_SCANNED0时 Data Recipes 拒绝扫描件并明确报错test_failed_scan_replacement_preserves_searchable_original失败的替换不破坏原有可检索文档八、局限与使用注意事项OCR 本质是有损识别文档明确提醒其可靠性边界以下场景应重点核对转录结果手写内容识别率显著低于印刷体错误率高发低分辨率扫描RAG_OCR_DPI默认 150可适当调高但原始扫描质量决定上限复杂表格行列结构可能被压平成线性文本破坏表格语义多语言混排需确认RAG_OCR_LANGUAGE覆盖全部语种缺少任一语言包都会导致该页转录失败。因此使用扫描 PDF 做 RAG 检索或构建 Data Recipe 后建议把提取结果与原文档对照抽查。若某页反复无法识别优先考虑替换为带文字层的可检索 PDF例如通过 OCR 软件另存为带文本层的版本而不是无限调高 DPI 或页数预算。九、快速排障清单把本文内容压缩成一张可执行的检查表供遇到扫描 PDF 上传失败时逐项排查引擎是否可用Tesseract 是否已安装TESSDATA_PREFIX是否指向包含.traineddata的目录语言是否匹配RAG_OCR_LANGUAGE列出的每个语言代码是否都有对应的.traineddata文件开关是否开启Data Recipes 场景确认RAG_OCR_SCANNED未被设为0Chat 场景确认OCR scanned pages开关已开启预算是否足够扫描页总数是否超过RAG_OCR_MAX_PAGES默认 20超长扫描件需在启动 Studio 前调大换一份 PDF仍失败时上传带文字层的可检索 PDF查看具体页码错误信息中的页码列表会精确指出哪几页不可读据此判断是单页质量差还是全局配置问题。上述所有配置、默认值与行为均可直接在仓库中核验环境变量见 config.pyOCR 执行与错误构造见 pdf_ocr.py页面分类见 parsers.pyChat 双引擎回退见 ingestion.pyData Recipes 独立进程提取见 seed.py。赞分享人工智能大模型微调LoRA模型优化模型量化强化学习【免费下载链接】unslothLocal UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4, MiniMax-H3, Gemma 4, FLUX and more.项目地址https://gitcode.com/GitHub_Trending/un/unsloth点击查看免费下载相关推荐bentopdf OCR PDF 工具深度指南基于 Tesseract 的扫描件文字层识别与多语言配置bentopdf OCR PDF 工具深度指南基于 Tesseract 的扫描件文字层识别与多语言配置 本文围绕 bentopdfPrivacy First前端Ekko Studio OCR 与文档提取技能实战从扫描 PDF 到结构化 Markdown 的本地优先工作流Ekko Studio OCR 与文档提取技能实战从扫描 PDF 到结构化 Markdown 的本地优先工作流 导读 Ekko Studio本地优先的多 AAI 应用人工智能AI Agent本地部署前端后端工作流自动化为什么选择Workbench5大优势让Dotfiles管理更简单高效为什么选择Workbench5大优势让Dotfiles管理更简单高效 如果你正为 macOS 上 .zshrc 、 .gitconfig 这类配置文件的备份而上一篇3个核心概念读懂OTE模板Template、端点Endpoint与提取器Extractor通俗详解下一篇Moonshine开发者指南如何集成到现有应用的完整流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
