1 项目背景业务场景「云帆科技」运维部的小周遇到了一个棘手的问题。公司决定把过去五年积累的所有项目结项报告约 500 份 PDF导入 RAGFlow方便新员工了解历史项目经验。但实际导入后效果惨不忍睹——有的 PDF 是 Word 转的解析结果还算完整有的是扫描件大面积 OCR 乱码有的是客户提供的排版花哨——双栏、竖排、图文混排。小周在调查时发现这 500 份 PDF 其实可以分为三类文本型 PDF40%可直接提取文字、扫描型 PDF50%需要 OCR、混合型 PDF10%部分页面是扫描图。而 RAGFlow 默认的解析配置只适合文本型——导致 60% 的文档解析质量极差。更麻烦的是扫描件里大量项目表格在 OCR 后完全散架变成了一堆无意义的文字碎片。痛点如果不了解 DeepDoc 如何处理不同类型文档解析质量两极分化同一套配置处理文本型 PDF 效果完美处理扫描件却一塌糊涂——因为不了解 OCR 和版面分析的开关要按文档类型调整。表格毁灭项目报告中的财务报表、测试数据表经过 OCR 后列对齐全丢失“2023年Q3” 和 “营收 500万” 被拆分到了不同段落。图文信息丢失架构图、流程图、截图中的关键信息OCR 只能识别文字但无法理解图的结构——这个箭头指向哪里’完全检索不到。解析耗时不可控开启版面分析后单页可能需要 10 秒500 份文档 × 50 页 25000 页 约 70 小时的解析时间——没有规划就盲目导入了。DeepDoc 解析不同类型文档的复杂度金字塔 L1 文本型 PDF最简单: 直接提取文字保留位置信息 L2 Word/PPT/Excel: 从 XML 结构抽取保留层级和格式 L3 Markdown/HTML: 按语法解析保留标题和代码块 L4 扫描型 PDF普通: OCR 基础版面分析 L5 扫描型 PDF复杂: OCR 表格识别 图表区域 多栏布局 L6 拍照/截图最难: 倾斜矫正 去噪 OCR 质量不稳定2 项目设计小胖砰地把一叠打印纸摔在桌上“大师我们导入 500 份项目报告光解析就跑了两天两夜还没完更气人的是解析出来的内容读都读不通——项目名’和’项目内容’混在一起表格全散架了。DeepDoc 到底靠不靠谱”大师“先别急。DeepDoc 不是一键魔棒”——它是一套工具箱你要根据文档类型选对工具。不同类型的文档需要不同的解析策略。就好比你不能拿螺丝刀去切西瓜。技术映射DeepDoc 厨房工具箱——切肉用菜刀削皮用刨刀打蛋用打蛋器。把 PDF 简单粗暴地全部用同一种模式处理相当于用菜刀打鸡蛋。小胖“那你倒是说说PDF、Word、扫描件各该用什么策略”大师“先看 PDF 的分类处理策略”PDF 类型判断方法解析策略关键参数文本型Word 转的可以选中文字、复制粘贴直接提取文字 版面分析enable_ocr: false扫描型图片扫描无法选中文字、放大后模糊OCR 版面分析 图像预处理enable_ocr: true混合型部分页扫描有的页能选文字有的不能自动判断 按页启用 OCRlayout_recognize: true# DeepDoc PDF 解析配置示例parser_config{parser_id:pdf,enable_ocr:True,# 对扫描页启用OCRlayout_recognize:True,# 启用DeepDoc版面分析模型language:chinese,# OCR语言关键table_enhance:True,# 增强表格识别max_page:50,# 单页最大处理数}小白打开笔记本“那非 PDF 的处理呢Word 文档的内部结构是怎么解析的”大师“DOCX/PowerPoint/Excel 这三兄弟内部其实是 ZIP 压缩包里面是 XML 文件。DeepDoc 直接解析 XML 提取文本、表格、样式不需要 OCR速度很快但也有一些局限——比如内嵌图片、SmartArt、数学公式可能丢失。”DOCX 解析流程 DOCX 文件 → 解压 ZIP → 读取 document.xml → 遍历 XML 树段落、表格、标题、列表 → 提取文本 保留层级结构 → 输出结构化文本小胖“那 Excel 呢电子表格里的合并单元格、多 Sheet 怎么办”大师“Excel 是 DeepDoc 处理表格类文档的强项。它会把每个 Sheet 按行列读取将合并单元格还原为实际值最终输出为 Markdown 表格格式。比如”### Sheet: 薪资标准表 | 职级 | 基本工资 | 岗位津贴 | 绩效系数 | |------|---------|---------|---------| | P1 | 5000 | 1000 | 0.8 | | P2 | 8000 | 1500 | 0.9 | | P3 | 12000 | 2500 | 1.0 |“这种 Markdown 表格格式对大模型非常友好——模型能理解行列关系回答’P2 的岗位津贴’时可以直接从表格中提取。”技术映射DOCX 解析 拆信封读信——打开 ZIP 信封取出 XML 信纸逐字阅读。Excel 解析 清点仓库——按货架(Sheet)、货位(行列)逐一盘点。小白“那扫描件的 OCR 是怎么回事为什么有的扫描件识别得很好有的却一塌糊涂”大师“OCR 质量取决于四个因素缺一个都会掉链子”分辨率DPI建议 200-300 DPI。低于 150 DPI文字边缘模糊OCR 引擎难以区分笔画。高于 400 DPI处理时间增加但收益递减。图像质量倾斜、阴影、水印、红章遮挡——这些都会导致 OCR 识别率骤降。DeepDoc 会自动做倾斜矫正和去噪但不能保证 100% 还原。字体和字号宋体、黑体等常见字体识别率高95%手写体、艺术字、极小米粒字识别率低50%。语言设置这是最容易犯错的配置。中文文档如果选了language: englishOCR 引擎会用英文模型去识别中文字符——结果全是乱码。技术映射OCR 近视的人戴眼镜看远处的字——分辨率不够度数不对、图像模糊眼镜脏了、语言不对镜片装反了都会看不清。小胖“那架构图、流程图怎么办那些箭头和方框 OCR 也认不了啊。”大师“这确实是个难点。DeepDoc 的版面分析能识别出’这是一个图’、‘这是一个表格’、‘这是正文’——但对于图里的逻辑关系箭头方向、层级结构目前还无法自动解析为文字描述。应对策略有两种一是人工为每张图写 Alt Text替代文本嵌入到文档中二是使用多模态模型如 GPT-4V对图片生成描述文本再作为切片一起索引。”技术映射架构图解析 给盲人描述一幅画——需要人或高级 AI用文字把画面的核心逻辑讲出来而不是指望着看懂。小白“最后问一个工程问题。500 份文档的解析要排队有没有办法加速”大师“三个加速方向”增加 Worker 数量环境变量WS控制 Task Executor 的 Worker 数。默认为 1改为 3-5 可以并行处理多个文档但每个 Worker 会独立加载模型内存占用倍增。按文档类型分批先处理简单的文本型 PDF不需要 OCR快再处理扫描件需要 OCR慢。避免一个慢文档堵住整个队列。关闭不必要的特性layout_recognizetrue会启用深度学习模型做版面分析非常耗资源。如果文档是纯文本结构的关闭这个选项解析速度快 5-10 倍。3 项目实战环境准备目标用一份混合格式测试文档集对比不同 DeepDoc 解析配置的效果。前提RAGFlow 已部署准备以下测试文档1 份文本型 PDFWord 转的纯文字制度1 份扫描型 PDF合同扫描件200 DPI1 份 DOCX含表格和项目符号的文档1 份 XLSX含合并单元格和多 Sheet 的薪资表分步实现步骤1查看 DeepDoc 支持的解析器列表目标通过源码了解 RAGFlow 支持哪些解析器。# 查看 deepdoc 目录结构lsragflow/deepdoc/parser/# 典型输出# __init__.py# pdf_parser.py # PDF 解析器含 OCR# docx_parser.py # Word 文档解析器# excel_parser.py # Excel 解析器# pptx_parser.py # PowerPoint 解析器# markdown_parser.py # Markdown 解析器# html_parser.py # HTML 解析器# image_parser.py # 图片解析器OCR# csv_parser.py # CSV 解析器# txt_parser.py # 纯文本解析器# 查看 PDF 解析器支持的核心参数grep-ndef parse\|def __call__\|enable_ocr\|layoutragflow/deepdoc/parser/pdf_parser.py|head-20步骤2配置文本型 PDF 解析目标用最优配置上传并解析纯文本 PDF不需要 OCR。# API 上传文本型 PDFcurl-XPOST http://localhost:8080/api/v1/datasets/ds_id/documents\-HAuthorization: Bearer$TOKEN\-Ffiletest_docs/考勤管理办法_文本型.pdf\-Fparser_config{ parser_id: pdf, enable_ocr: false, layout_recognize: false, language: chinese, chunk_method: title, chunk_size: 800 }# python 方式fromragflowimportRAGFlow ragRAGFlow(api_keyxxx,base_urlhttp://localhost:8080/api/v1)dsrag.get_dataset(your-dataset-id)# 文本型关闭 OCR 和版面分析速度最快doc_textds.upload_document(test_docs/考勤管理办法_文本型.pdf,parser_config{parser_id:pdf,enable_ocr:False,layout_recognize:False,language:chinese,})print(f文本型 PDF 上传完成:{doc_text.id})坑点如果文本型 PDF 的字体是嵌入的非标准字体如某些中文字体直接提取文字也可能失败。这时需要改为enable_ocr: true。步骤3配置扫描型 PDF 解析目标上传扫描件启用 OCR 并配置图像预处理参数。# 扫描型 PDF必须开启 OCRcurl-XPOST http://localhost:8080/api/v1/datasets/ds_id/documents\-HAuthorization: Bearer$TOKEN\-Ffiletest_docs/项目合同_扫描件.pdf\-Fparser_config{ parser_id: pdf, enable_ocr: true, layout_recognize: true, language: chinese, table_enhance: true, ocr_engine: paddleocr, image_dpi: 300, chunk_method: table, chunk_size: 500 }# 扫描型全功能开启doc_scands.upload_document(test_docs/项目合同_扫描件.pdf,parser_config{parser_id:pdf,enable_ocr:True,layout_recognize:True,# 版面分析language:chinese,table_enhance:True,# 表格增强ocr_engine:paddleocr,})# 追踪解析进度扫描件可能很慢importtimefor_inrange(120):# 最多等 10 分钟time.sleep(5)docds.get_document(doc_scan.id)print(f扫描件状态:{doc.status}(chunks{getattr(doc,chunk_count,0)}))ifdoc.statusin[success,failed]:break步骤4解析 Word 和 Excel 文档目标验证 DOCX 和 XLSX 的结构化解析效果。# 解析 Word 文档DOCXdoc_docxds.upload_document(test_docs/薪酬管理办法.docx,parser_config{parser_id:docx,chunk_method:title,chunk_size:800,overlap_size:100,})# 解析 Excel 文档XLSXdoc_xlsxds.upload_document(test_docs/薪资标准表.xlsx,parser_config{parser_id:excel,sheet_index:all,# 解析所有 Sheetoutput_format:markdown,# 输出 Markdown 表格chunk_method:table,# 按表格切分chunk_size:1000,})# 等待解析完成...print(fDOCX 解析完成:{doc_docx.status})print(fXLSX 解析完成:{doc_xlsx.status})坑点Excel 如果包含嵌入图片、宏、公式计算这些内容在解析过程中会丢失。只保留静态值和文本。步骤5批量解析与质量对比目标对同一批文档用不同解析参数量化对比质量差异。# batch_parse_compare.py - 批量解析对比fromragflowimportRAGFlowimportjsonimporttime ragRAGFlow(api_keyxxx,base_urlhttp://localhost:8080/api/v1)test_docs[(文本型PDF,docs/text_policy.pdf,pdf,{enable_ocr:False}),(扫描型PDF,docs/scan_contract.pdf,pdf,{enable_ocr:True}),(Word文档,docs/salary_policy.docx,docx,{}),(Excel表格,docs/salary_table.xlsx,excel,{}),]results[]fordoc_type,file_path,parser_id,extra_configintest_docs:# 创建专属数据集dsrag.create_dataset(namefDeepDoc测试-{doc_type},chunk_methodtitleifparser_id!excelelsetable)starttime.time()docds.upload_document(file_path,parser_config{parser_id:parser_id,language:chinese,**extra_config})# 等待完成max_w300for_inrange(max_w//5):time.sleep(5)docds.get_document(doc.id)ifdoc.statusin[success,failed]:breakelapsedtime.time()-start results.append({type:doc_type,status:doc.status,chunks:getattr(doc,chunk_count,0),tokens:getattr(doc,token_count,0),time_seconds:round(elapsed,1),})# 清理rag.delete_dataset(ds.id)# 输出对比报告print(\n DeepDoc 解析对比报告 )print(f{类型:10}{状态:8}{切片数:8}{耗时(s):10})print(-*40)forrinresults:print(f{r[type]:10}{r[status]:8}{r[chunks]:8}{r[time_seconds]:10})预期输出示例 DeepDoc 解析对比报告 类型 状态 切片数 耗时(s) ---------------------------------------- 文本型PDF success 47 35.2 扫描型PDF success 52 420.8 Word文档 success 38 12.5 Excel表格 success 15 8.3测试验证# test_deepdoc_quality.py - 解析质量验证importpytestpytest.mark.parametrize(file_path,parser_id,expected_min_chunks,[(test_docs/text_policy.pdf,pdf,10),# 文本型至少10个切片(test_docs/scan_contract.pdf,pdf,5),# 扫描件即使少也应该有内容(test_docs/salary_policy.docx,docx,8),(test_docs/salary_table.xlsx,excel,2),])deftest_parse_produces_chunks(file_path,parser_id,expected_min_chunks):验证每种类型都能解析出足够数量的切片dsrag.create_dataset(namefTEST-{parser_id})docds.upload_document(file_path,parser_config{parser_id:parser_id})# 等待解析 (简化版实际需加等待逻辑)importtimefor_inrange(60):time.sleep(2)docds.get_document(doc.id)ifdoc.statusin[success,failed]:breakassertdoc.statussuccess,f解析失败:{file_path}assertdoc.chunk_countexpected_min_chunks,\f切片数不足:{doc.chunk_count}{expected_min_chunks}# 清理rag.delete_dataset(ds.id)deftest_ocr_chinese_language():验证中文OCR设置正确时不会输出乱码dsrag.create_dataset(nameTEST-OCR)docds.upload_document(test_docs/chinese_scan.pdf,parser_config{parser_id:pdf,enable_ocr:True,language:chinese,})# 等待解析完成...chunksds.list_chunks(doc.id)# 检查前5个切片中是否有汉字importre chinese_char_countsum(len(re.findall(r[\u4e00-\u9fff],chunk.content))forchunkinchunks[:5])assertchinese_char_count0,未检测到中文字符OCR语言设置可能错误完整代码清单Git 仓库https://github.com/infiniflow/ragflow路径说明deepdoc/parser/pdf_parser.pyPDF 解析器文本提取 OCRdeepdoc/parser/docx_parser.pyDOCX 解析器XML 结构抽取deepdoc/parser/excel_parser.pyExcel 解析器行列 合并单元格deepdoc/parser/markdown_parser.pyMarkdown 解析器deepdoc/vision/视觉模块OCR、版面分析、表格识别rag/flow/pipeline.pyPipeline串联解析→切片→向量化4 项目总结优点 缺点维度RAGFlow DeepDocTika TesseractUnstructured.ioAzure Document IntelligencePDF 解析能力★★★ 版面分析OCR★★☆ 基础 PDF★★☆ 多种 parser★★★ 企业级 AI表格识别★★★ 行列合并单元格★★☆ 基础表格★★☆ 部分支持★★★ 深度表格OCR 中文★★★ PaddleOCR★★☆ Tesseract 中文★★☆ 依赖引擎★★★ 中文优化Office 格式★★★ DOCX/XLSX/PPTX★★★ 全格式★★☆ 部分格式★★★ 全格式处理速度★★☆ 扫描件慢★★★ 较快★★☆ 中等★★☆ 云端延迟私有部署★★★ 完全本地★★★ 完全本地★★★ 完全本地★☆☆ 仅云端适用场景多格式制度文档PDF Word Excel 混合的知识库一种配置无法适应所有格式——需要按文件类型选择解析器。历史档案数字化纸质合同/报告扫描为 PDF 后通过 OCR 实现全文检索。财务表格解析Excel 薪资表、报销标准表的结构化解析支持表格式问答。项目文档归档项目方案Word、排期表Excel、架构图PDF的统一知识化。多语言文档处理中英混排文档的 OCR 分段按语言选择不同模型。不适用场景CAD/工程图纸矢量图中的尺寸标注、符号无法通过 OCR 识别语义。手写体文档潦草手写 OCR 准确率极低 40%不适合知识库场景。注意事项OCR 语言必须先设对中文文档用language: chinese英文用english中英混合用chinese中文 OCR 模型对英文也有基本识别能力。版面分析增加耗时layout_recognize: true会让每页增加 5-10 秒处理时间。纯文本 PDF 应关闭。扫描件 DPI 建议如果用扫描仪生成 PDF建议设置扫描 DPI 为 300。低于 150 的 OCR 质量明显下降。PDF 加密保护如果 PDF 设置了打开密码或编辑限制DeepDoc 可能无法解析——需要先解除保护。图片文件的内存管理大分辨率图片4000x3000OCR 时内存消耗极大建议预处理缩小到 2000px 宽度内。常见踩坑经验故障现象根因解决方法中文扫描件 OCR 全乱码language: english被误设为默认改为language: chinese表格解析后行列错位扫描件表格线模糊OCR 把它们当成了文字开启table_enhance: true解析结果只有文字、没有结构layout_recognize: false版面分析未启用设为true注意速度变慢PDF 解析出来全是空白PDF 文本编码非标准如 CID fonts临时改为enable_ocr: trueDeepDoc 模型下载失败huggingface 或 modelscope 网络不通手动下载模型文件放到指定目录或使用镜像思考题一份 200 页的年度财务报告 PDF 中前 180 页是文本型Word 转的最后 20 页是扫描的签字盖章页。如果全程用 OCR 模式耗时 3 小时如果不用 OCR最后 20 页无法解析。请设计一个按页自适应方案自动检测每页是否为扫描页并切换解析策略。公司有 1000 份历史合同扫描件每份 5 页OCR 后平均每份有 10% 的文字识别错误如甲方被识别为甲万。这些错误会导致检索时关键词匹配失败。请设计一个 OCR 后处理纠错方案利用合同文本的结构化特征固定条款模板、常见术语自动修复常见 OCR 错误。答案提示见第10章末尾或附录 D。延伸阅读与资源10倍开发者的 Dify 魔法书从零构建全栈 AI 应用后端工程师转型AI第一课-Ollama 与私有化大模型实战大型语言模型(LLM) vLLM 高性能推理落地实战Agent开发之LlamaIndex 实战修炼与源码进阶大语言模型Transformers 实战修炼与源码剖析
第9章：RAGFlow DeepDoc 文档解析入门
1 项目背景业务场景「云帆科技」运维部的小周遇到了一个棘手的问题。公司决定把过去五年积累的所有项目结项报告约 500 份 PDF导入 RAGFlow方便新员工了解历史项目经验。但实际导入后效果惨不忍睹——有的 PDF 是 Word 转的解析结果还算完整有的是扫描件大面积 OCR 乱码有的是客户提供的排版花哨——双栏、竖排、图文混排。小周在调查时发现这 500 份 PDF 其实可以分为三类文本型 PDF40%可直接提取文字、扫描型 PDF50%需要 OCR、混合型 PDF10%部分页面是扫描图。而 RAGFlow 默认的解析配置只适合文本型——导致 60% 的文档解析质量极差。更麻烦的是扫描件里大量项目表格在 OCR 后完全散架变成了一堆无意义的文字碎片。痛点如果不了解 DeepDoc 如何处理不同类型文档解析质量两极分化同一套配置处理文本型 PDF 效果完美处理扫描件却一塌糊涂——因为不了解 OCR 和版面分析的开关要按文档类型调整。表格毁灭项目报告中的财务报表、测试数据表经过 OCR 后列对齐全丢失“2023年Q3” 和 “营收 500万” 被拆分到了不同段落。图文信息丢失架构图、流程图、截图中的关键信息OCR 只能识别文字但无法理解图的结构——这个箭头指向哪里’完全检索不到。解析耗时不可控开启版面分析后单页可能需要 10 秒500 份文档 × 50 页 25000 页 约 70 小时的解析时间——没有规划就盲目导入了。DeepDoc 解析不同类型文档的复杂度金字塔 L1 文本型 PDF最简单: 直接提取文字保留位置信息 L2 Word/PPT/Excel: 从 XML 结构抽取保留层级和格式 L3 Markdown/HTML: 按语法解析保留标题和代码块 L4 扫描型 PDF普通: OCR 基础版面分析 L5 扫描型 PDF复杂: OCR 表格识别 图表区域 多栏布局 L6 拍照/截图最难: 倾斜矫正 去噪 OCR 质量不稳定2 项目设计小胖砰地把一叠打印纸摔在桌上“大师我们导入 500 份项目报告光解析就跑了两天两夜还没完更气人的是解析出来的内容读都读不通——项目名’和’项目内容’混在一起表格全散架了。DeepDoc 到底靠不靠谱”大师“先别急。DeepDoc 不是一键魔棒”——它是一套工具箱你要根据文档类型选对工具。不同类型的文档需要不同的解析策略。就好比你不能拿螺丝刀去切西瓜。技术映射DeepDoc 厨房工具箱——切肉用菜刀削皮用刨刀打蛋用打蛋器。把 PDF 简单粗暴地全部用同一种模式处理相当于用菜刀打鸡蛋。小胖“那你倒是说说PDF、Word、扫描件各该用什么策略”大师“先看 PDF 的分类处理策略”PDF 类型判断方法解析策略关键参数文本型Word 转的可以选中文字、复制粘贴直接提取文字 版面分析enable_ocr: false扫描型图片扫描无法选中文字、放大后模糊OCR 版面分析 图像预处理enable_ocr: true混合型部分页扫描有的页能选文字有的不能自动判断 按页启用 OCRlayout_recognize: true# DeepDoc PDF 解析配置示例parser_config{parser_id:pdf,enable_ocr:True,# 对扫描页启用OCRlayout_recognize:True,# 启用DeepDoc版面分析模型language:chinese,# OCR语言关键table_enhance:True,# 增强表格识别max_page:50,# 单页最大处理数}小白打开笔记本“那非 PDF 的处理呢Word 文档的内部结构是怎么解析的”大师“DOCX/PowerPoint/Excel 这三兄弟内部其实是 ZIP 压缩包里面是 XML 文件。DeepDoc 直接解析 XML 提取文本、表格、样式不需要 OCR速度很快但也有一些局限——比如内嵌图片、SmartArt、数学公式可能丢失。”DOCX 解析流程 DOCX 文件 → 解压 ZIP → 读取 document.xml → 遍历 XML 树段落、表格、标题、列表 → 提取文本 保留层级结构 → 输出结构化文本小胖“那 Excel 呢电子表格里的合并单元格、多 Sheet 怎么办”大师“Excel 是 DeepDoc 处理表格类文档的强项。它会把每个 Sheet 按行列读取将合并单元格还原为实际值最终输出为 Markdown 表格格式。比如”### Sheet: 薪资标准表 | 职级 | 基本工资 | 岗位津贴 | 绩效系数 | |------|---------|---------|---------| | P1 | 5000 | 1000 | 0.8 | | P2 | 8000 | 1500 | 0.9 | | P3 | 12000 | 2500 | 1.0 |“这种 Markdown 表格格式对大模型非常友好——模型能理解行列关系回答’P2 的岗位津贴’时可以直接从表格中提取。”技术映射DOCX 解析 拆信封读信——打开 ZIP 信封取出 XML 信纸逐字阅读。Excel 解析 清点仓库——按货架(Sheet)、货位(行列)逐一盘点。小白“那扫描件的 OCR 是怎么回事为什么有的扫描件识别得很好有的却一塌糊涂”大师“OCR 质量取决于四个因素缺一个都会掉链子”分辨率DPI建议 200-300 DPI。低于 150 DPI文字边缘模糊OCR 引擎难以区分笔画。高于 400 DPI处理时间增加但收益递减。图像质量倾斜、阴影、水印、红章遮挡——这些都会导致 OCR 识别率骤降。DeepDoc 会自动做倾斜矫正和去噪但不能保证 100% 还原。字体和字号宋体、黑体等常见字体识别率高95%手写体、艺术字、极小米粒字识别率低50%。语言设置这是最容易犯错的配置。中文文档如果选了language: englishOCR 引擎会用英文模型去识别中文字符——结果全是乱码。技术映射OCR 近视的人戴眼镜看远处的字——分辨率不够度数不对、图像模糊眼镜脏了、语言不对镜片装反了都会看不清。小胖“那架构图、流程图怎么办那些箭头和方框 OCR 也认不了啊。”大师“这确实是个难点。DeepDoc 的版面分析能识别出’这是一个图’、‘这是一个表格’、‘这是正文’——但对于图里的逻辑关系箭头方向、层级结构目前还无法自动解析为文字描述。应对策略有两种一是人工为每张图写 Alt Text替代文本嵌入到文档中二是使用多模态模型如 GPT-4V对图片生成描述文本再作为切片一起索引。”技术映射架构图解析 给盲人描述一幅画——需要人或高级 AI用文字把画面的核心逻辑讲出来而不是指望着看懂。小白“最后问一个工程问题。500 份文档的解析要排队有没有办法加速”大师“三个加速方向”增加 Worker 数量环境变量WS控制 Task Executor 的 Worker 数。默认为 1改为 3-5 可以并行处理多个文档但每个 Worker 会独立加载模型内存占用倍增。按文档类型分批先处理简单的文本型 PDF不需要 OCR快再处理扫描件需要 OCR慢。避免一个慢文档堵住整个队列。关闭不必要的特性layout_recognizetrue会启用深度学习模型做版面分析非常耗资源。如果文档是纯文本结构的关闭这个选项解析速度快 5-10 倍。3 项目实战环境准备目标用一份混合格式测试文档集对比不同 DeepDoc 解析配置的效果。前提RAGFlow 已部署准备以下测试文档1 份文本型 PDFWord 转的纯文字制度1 份扫描型 PDF合同扫描件200 DPI1 份 DOCX含表格和项目符号的文档1 份 XLSX含合并单元格和多 Sheet 的薪资表分步实现步骤1查看 DeepDoc 支持的解析器列表目标通过源码了解 RAGFlow 支持哪些解析器。# 查看 deepdoc 目录结构lsragflow/deepdoc/parser/# 典型输出# __init__.py# pdf_parser.py # PDF 解析器含 OCR# docx_parser.py # Word 文档解析器# excel_parser.py # Excel 解析器# pptx_parser.py # PowerPoint 解析器# markdown_parser.py # Markdown 解析器# html_parser.py # HTML 解析器# image_parser.py # 图片解析器OCR# csv_parser.py # CSV 解析器# txt_parser.py # 纯文本解析器# 查看 PDF 解析器支持的核心参数grep-ndef parse\|def __call__\|enable_ocr\|layoutragflow/deepdoc/parser/pdf_parser.py|head-20步骤2配置文本型 PDF 解析目标用最优配置上传并解析纯文本 PDF不需要 OCR。# API 上传文本型 PDFcurl-XPOST http://localhost:8080/api/v1/datasets/ds_id/documents\-HAuthorization: Bearer$TOKEN\-Ffiletest_docs/考勤管理办法_文本型.pdf\-Fparser_config{ parser_id: pdf, enable_ocr: false, layout_recognize: false, language: chinese, chunk_method: title, chunk_size: 800 }# python 方式fromragflowimportRAGFlow ragRAGFlow(api_keyxxx,base_urlhttp://localhost:8080/api/v1)dsrag.get_dataset(your-dataset-id)# 文本型关闭 OCR 和版面分析速度最快doc_textds.upload_document(test_docs/考勤管理办法_文本型.pdf,parser_config{parser_id:pdf,enable_ocr:False,layout_recognize:False,language:chinese,})print(f文本型 PDF 上传完成:{doc_text.id})坑点如果文本型 PDF 的字体是嵌入的非标准字体如某些中文字体直接提取文字也可能失败。这时需要改为enable_ocr: true。步骤3配置扫描型 PDF 解析目标上传扫描件启用 OCR 并配置图像预处理参数。# 扫描型 PDF必须开启 OCRcurl-XPOST http://localhost:8080/api/v1/datasets/ds_id/documents\-HAuthorization: Bearer$TOKEN\-Ffiletest_docs/项目合同_扫描件.pdf\-Fparser_config{ parser_id: pdf, enable_ocr: true, layout_recognize: true, language: chinese, table_enhance: true, ocr_engine: paddleocr, image_dpi: 300, chunk_method: table, chunk_size: 500 }# 扫描型全功能开启doc_scands.upload_document(test_docs/项目合同_扫描件.pdf,parser_config{parser_id:pdf,enable_ocr:True,layout_recognize:True,# 版面分析language:chinese,table_enhance:True,# 表格增强ocr_engine:paddleocr,})# 追踪解析进度扫描件可能很慢importtimefor_inrange(120):# 最多等 10 分钟time.sleep(5)docds.get_document(doc_scan.id)print(f扫描件状态:{doc.status}(chunks{getattr(doc,chunk_count,0)}))ifdoc.statusin[success,failed]:break步骤4解析 Word 和 Excel 文档目标验证 DOCX 和 XLSX 的结构化解析效果。# 解析 Word 文档DOCXdoc_docxds.upload_document(test_docs/薪酬管理办法.docx,parser_config{parser_id:docx,chunk_method:title,chunk_size:800,overlap_size:100,})# 解析 Excel 文档XLSXdoc_xlsxds.upload_document(test_docs/薪资标准表.xlsx,parser_config{parser_id:excel,sheet_index:all,# 解析所有 Sheetoutput_format:markdown,# 输出 Markdown 表格chunk_method:table,# 按表格切分chunk_size:1000,})# 等待解析完成...print(fDOCX 解析完成:{doc_docx.status})print(fXLSX 解析完成:{doc_xlsx.status})坑点Excel 如果包含嵌入图片、宏、公式计算这些内容在解析过程中会丢失。只保留静态值和文本。步骤5批量解析与质量对比目标对同一批文档用不同解析参数量化对比质量差异。# batch_parse_compare.py - 批量解析对比fromragflowimportRAGFlowimportjsonimporttime ragRAGFlow(api_keyxxx,base_urlhttp://localhost:8080/api/v1)test_docs[(文本型PDF,docs/text_policy.pdf,pdf,{enable_ocr:False}),(扫描型PDF,docs/scan_contract.pdf,pdf,{enable_ocr:True}),(Word文档,docs/salary_policy.docx,docx,{}),(Excel表格,docs/salary_table.xlsx,excel,{}),]results[]fordoc_type,file_path,parser_id,extra_configintest_docs:# 创建专属数据集dsrag.create_dataset(namefDeepDoc测试-{doc_type},chunk_methodtitleifparser_id!excelelsetable)starttime.time()docds.upload_document(file_path,parser_config{parser_id:parser_id,language:chinese,**extra_config})# 等待完成max_w300for_inrange(max_w//5):time.sleep(5)docds.get_document(doc.id)ifdoc.statusin[success,failed]:breakelapsedtime.time()-start results.append({type:doc_type,status:doc.status,chunks:getattr(doc,chunk_count,0),tokens:getattr(doc,token_count,0),time_seconds:round(elapsed,1),})# 清理rag.delete_dataset(ds.id)# 输出对比报告print(\n DeepDoc 解析对比报告 )print(f{类型:10}{状态:8}{切片数:8}{耗时(s):10})print(-*40)forrinresults:print(f{r[type]:10}{r[status]:8}{r[chunks]:8}{r[time_seconds]:10})预期输出示例 DeepDoc 解析对比报告 类型 状态 切片数 耗时(s) ---------------------------------------- 文本型PDF success 47 35.2 扫描型PDF success 52 420.8 Word文档 success 38 12.5 Excel表格 success 15 8.3测试验证# test_deepdoc_quality.py - 解析质量验证importpytestpytest.mark.parametrize(file_path,parser_id,expected_min_chunks,[(test_docs/text_policy.pdf,pdf,10),# 文本型至少10个切片(test_docs/scan_contract.pdf,pdf,5),# 扫描件即使少也应该有内容(test_docs/salary_policy.docx,docx,8),(test_docs/salary_table.xlsx,excel,2),])deftest_parse_produces_chunks(file_path,parser_id,expected_min_chunks):验证每种类型都能解析出足够数量的切片dsrag.create_dataset(namefTEST-{parser_id})docds.upload_document(file_path,parser_config{parser_id:parser_id})# 等待解析 (简化版实际需加等待逻辑)importtimefor_inrange(60):time.sleep(2)docds.get_document(doc.id)ifdoc.statusin[success,failed]:breakassertdoc.statussuccess,f解析失败:{file_path}assertdoc.chunk_countexpected_min_chunks,\f切片数不足:{doc.chunk_count}{expected_min_chunks}# 清理rag.delete_dataset(ds.id)deftest_ocr_chinese_language():验证中文OCR设置正确时不会输出乱码dsrag.create_dataset(nameTEST-OCR)docds.upload_document(test_docs/chinese_scan.pdf,parser_config{parser_id:pdf,enable_ocr:True,language:chinese,})# 等待解析完成...chunksds.list_chunks(doc.id)# 检查前5个切片中是否有汉字importre chinese_char_countsum(len(re.findall(r[\u4e00-\u9fff],chunk.content))forchunkinchunks[:5])assertchinese_char_count0,未检测到中文字符OCR语言设置可能错误完整代码清单Git 仓库https://github.com/infiniflow/ragflow路径说明deepdoc/parser/pdf_parser.pyPDF 解析器文本提取 OCRdeepdoc/parser/docx_parser.pyDOCX 解析器XML 结构抽取deepdoc/parser/excel_parser.pyExcel 解析器行列 合并单元格deepdoc/parser/markdown_parser.pyMarkdown 解析器deepdoc/vision/视觉模块OCR、版面分析、表格识别rag/flow/pipeline.pyPipeline串联解析→切片→向量化4 项目总结优点 缺点维度RAGFlow DeepDocTika TesseractUnstructured.ioAzure Document IntelligencePDF 解析能力★★★ 版面分析OCR★★☆ 基础 PDF★★☆ 多种 parser★★★ 企业级 AI表格识别★★★ 行列合并单元格★★☆ 基础表格★★☆ 部分支持★★★ 深度表格OCR 中文★★★ PaddleOCR★★☆ Tesseract 中文★★☆ 依赖引擎★★★ 中文优化Office 格式★★★ DOCX/XLSX/PPTX★★★ 全格式★★☆ 部分格式★★★ 全格式处理速度★★☆ 扫描件慢★★★ 较快★★☆ 中等★★☆ 云端延迟私有部署★★★ 完全本地★★★ 完全本地★★★ 完全本地★☆☆ 仅云端适用场景多格式制度文档PDF Word Excel 混合的知识库一种配置无法适应所有格式——需要按文件类型选择解析器。历史档案数字化纸质合同/报告扫描为 PDF 后通过 OCR 实现全文检索。财务表格解析Excel 薪资表、报销标准表的结构化解析支持表格式问答。项目文档归档项目方案Word、排期表Excel、架构图PDF的统一知识化。多语言文档处理中英混排文档的 OCR 分段按语言选择不同模型。不适用场景CAD/工程图纸矢量图中的尺寸标注、符号无法通过 OCR 识别语义。手写体文档潦草手写 OCR 准确率极低 40%不适合知识库场景。注意事项OCR 语言必须先设对中文文档用language: chinese英文用english中英混合用chinese中文 OCR 模型对英文也有基本识别能力。版面分析增加耗时layout_recognize: true会让每页增加 5-10 秒处理时间。纯文本 PDF 应关闭。扫描件 DPI 建议如果用扫描仪生成 PDF建议设置扫描 DPI 为 300。低于 150 的 OCR 质量明显下降。PDF 加密保护如果 PDF 设置了打开密码或编辑限制DeepDoc 可能无法解析——需要先解除保护。图片文件的内存管理大分辨率图片4000x3000OCR 时内存消耗极大建议预处理缩小到 2000px 宽度内。常见踩坑经验故障现象根因解决方法中文扫描件 OCR 全乱码language: english被误设为默认改为language: chinese表格解析后行列错位扫描件表格线模糊OCR 把它们当成了文字开启table_enhance: true解析结果只有文字、没有结构layout_recognize: false版面分析未启用设为true注意速度变慢PDF 解析出来全是空白PDF 文本编码非标准如 CID fonts临时改为enable_ocr: trueDeepDoc 模型下载失败huggingface 或 modelscope 网络不通手动下载模型文件放到指定目录或使用镜像思考题一份 200 页的年度财务报告 PDF 中前 180 页是文本型Word 转的最后 20 页是扫描的签字盖章页。如果全程用 OCR 模式耗时 3 小时如果不用 OCR最后 20 页无法解析。请设计一个按页自适应方案自动检测每页是否为扫描页并切换解析策略。公司有 1000 份历史合同扫描件每份 5 页OCR 后平均每份有 10% 的文字识别错误如甲方被识别为甲万。这些错误会导致检索时关键词匹配失败。请设计一个 OCR 后处理纠错方案利用合同文本的结构化特征固定条款模板、常见术语自动修复常见 OCR 错误。答案提示见第10章末尾或附录 D。延伸阅读与资源10倍开发者的 Dify 魔法书从零构建全栈 AI 应用后端工程师转型AI第一课-Ollama 与私有化大模型实战大型语言模型(LLM) vLLM 高性能推理落地实战Agent开发之LlamaIndex 实战修炼与源码进阶大语言模型Transformers 实战修炼与源码剖析