Kotaemon 集成 PaddleOCR 指南基于 PaddleOCR-VL 与 PPStructureV3 的高精度文档解析【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon本篇技术指南面向需要在 Kotaemon 中处理扫描件、多语言 PDF、复杂表格、公式与印章类文档的开发者讲解如何在 RAG 索引链路中接入两个 PaddleOCR 解析器——PaddleOCRVLReader基于 PaddleOCR-VL 1.5 视觉语言模型与PPStructureV3Reader基于 PPStructureV3 结构化版面分析管线。读完本文你将掌握从 PaddlePaddle 安装、PADDLE_DEVICE设备配置、解析器参数解析到 UI 中切换 File Loader 的完整落地流程并理解提取结果如何被转换为 Kotaemon 的Document对象进入索引。概览Kotaemon 中的两个 PaddleOCR 读取器Kotaemon 通过两个读取器Reader接入 PaddleOCR让文档摄入document ingestion具备完整的版面理解能力可覆盖多语言文本、表格、图表、公式与印章seal等复杂元素PaddleOCRVLReader封装 PaddleOCR-VL 1.50.9B 视觉语言模型主打鲁棒的版面解析与 VQA 式解析对倾斜、卷曲、扫描噪声、光照变化以及屏幕翻拍均较为稳健并支持跨页表格合并与段落标题识别PPStructureV3Reader基于 PPStructureV3 管线做结构化版面分析包含版面检测、OCR 流程以及表格、图表、公式、印章识别。两个读取器均位于仓库的 libs/kotaemon/kotaemon/loaders/paddleocr_loader 目录下其模块结构为文件职责paddleocr_vl_loader.pyPaddleOCRVLReader实现ppstructure_v3_loader.pyPPStructureV3Reader实现adapter.pyPaddleOCRResult适配器把 PaddleOCR 原始输出统一转换为Document它们与 Adobe、Docling、Azure AI Document Intelligence 等读取器一同注册在 libs/kotaemon/kotaemon/loaders/init.py 中并在索引摄入模块 libs/kotaemon/kotaemon/indices/ingests/files.py 中被实例化paddle_device str(config(PADDLE_DEVICE, defaultgpu)) paddle_struct_reader PPStructureV3Reader(devicepaddle_device) paddle_vl_reader PaddleOCRVLReader(devicepaddle_device)环境准备安装 PaddlePaddle 与 paddleocr 依赖1. 安装 PaddlePaddleCPU / GPU先安装 PaddlePaddle 深度学习框架。安装时必须选择与你系统配置和硬件CPU/GPU匹配的版本更多 wheel 选项可参考 PaddlePaddle 官方安装页同时请确认你的设备满足 PaddleOCR-VL 的推理设备支持要求。# CPU uv pip install paddlepaddle3.3.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ # GPU要求 GPU 驱动版本 ≥ 550.54.14Linux / Windows uv pip install paddlepaddle-gpu3.3.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu130/2. 安装 PaddleOCR 解析器 extras在 Kotaemon 仓库中paddleocr是 libs/kotaemon/pyproject.toml 中定义的可选依赖extrapaddleocr [paddleocr[doc-parser]]。执行以下命令即可安装包含doc-parser能力集的 paddleocruv pip install -e libs/kotaemon[paddleocr]安装完成后两个读取器通过_dependencies [paddleocr[doc-parser]]见 paddleocr_vl_loader.py 与 ppstructure_v3_loader.py声明自身的依赖若未安装代码会抛出提示信息Please install paddleocr: pip install paddleocr[doc-parser]。3. 配置推理设备PADDLE_DEVICE可在.env文件中设置PADDLE_DEVICE环境变量控制执行设备。该变量在 files.py 中通过config(PADDLE_DEVICE, defaultgpu)读取默认值为gpu并同时注入到两个读取器的device参数PADDLE_DEVICEgpu # cpu, gpu:0从源码可见device参数支持gpu:0、cpu、npu:0、xpu:0等取值见 paddleocr_vl_loader.py 与 ppstructure_v3_loader.py。CPU 推理注意事项源码级佐证两个读取器在pipeline_属性中惰性加载 PaddleOCR 管线时若设备以cpu开头会强制设置enable_mkldnn False。原因是 PaddleX 在 CPU 推理时默认启用 MKL-DNN而 PaddlePaddle 3.3 会触发 PIR/oneDNN 崩溃上游 issue 编号 77340因此在问题修复前于 Kotaemon 中禁用了该开关见 paddleocr_vl_loader.py 与 ppstructure_v3_loader.py。配置 File Loader在 UI 中切换 PaddleOCR 解析器配置完成后按以下步骤启用运行 Kotaemon 并打开应用 UI进入Settings → File Loader位于索引/摄入设置中选择以下 PaddleOCR 解析器之一PaddleOCR PPStructureV3 (tablefigure extraction)PaddleOCR-VL (VLM document parsing)保存设置随后上传或摄入文档。索引期间 Kotaemon 会自动使用所选 PaddleOCR 解析器并将提取内容转换为Document对象。从源码结构看UI 中列出的解析器选项与 files.py 中预实例化的paddle_struct_reader、paddle_vl_reader相对应二者已在模块加载时绑定PADDLE_DEVICE指定的设备。源码深度解析两个读取器如何工作PaddleOCRVLReaderVLM 驱动的版面解析PaddleOCRVLReader的类注释paddleocr_vl_loader.py明确了其能力边界处理文本、表格、公式、图表、印章识别与文字定位text spotting对倾斜、卷曲、扫描、光照、屏幕翻拍鲁棒支持跨页表格合并与段落标题识别模型来自PaddlePaddle/PaddleOCR-VL-1.5。其核心流程在load_data中paddleocr_vl_loader.pyfile_path Path(file_path) if file_path.suffix.lower() not in self.supported_file_types: raise ValueError(...) # Force dynamic graph mode to avoid int(Tensor) in static mode (paddlex) import paddle paddle.disable_static() raw_result self.pipeline_.predict(str(file_path)) return PaddleOCRResult( raw_resultraw_result, file_pathfile_path, extra_infoextra_info or {}, ).to_documents()值得注意的实现细节支持的文件类型为.pdf, .jpg, .jpeg, .png, .bmp, .tiff, .tif, .webppaddleocr_vl_loader.py不在此列会直接抛出ValueError强制动态图模式调用paddle.disable_static()以避免 PaddleX 静态图模式下int(Tensor)转换问题代码注释明确说明管线惰性加载pipeline_使用Param.auto(cacheTrue)装饰首次调用时才构建PaddleOCRVL实例并缓存构建时所有None参数会被过滤未显式配置的子模型参数均走 PaddleOCR 默认值paddleocr_vl_loader.py。PaddleOCRVLReader暴露的全部可调参数均为可空Param如下表所示参数作用device推理设备gpu:0、cpu、npu:0、xpu:0supported_file_types支持的文件扩展名列表pipeline_version管线版本默认v1.5layout_detection_model_name/layout_detection_model_dir版面检测模型名称与本地目录layout_threshold/layout_nms/layout_unclip_ratio版面检测阈值、NMS 阈值、unclip 比例layout_merge_bboxes_mode版面框合并策略vl_rec_model_name/vl_rec_model_dirVLM 识别模型名称与目录vl_rec_backendVLM 后端如本地 / 远端服务vl_rec_server_urlVLM 远端服务地址vl_rec_max_concurrencyVLM 推理最大并发数vl_rec_api_model_name/vl_rec_api_key调用 VLM API 的模型名与密钥doc_orientation_classify_model_name/doc_orientation_classify_model_dir文档方向分类模型doc_unwarping_model_name/doc_unwarping_model_dir文档展平去卷曲模型use_doc_orientation_classify是否启用文档方向分类use_doc_unwarping是否启用文档展平use_layout_detection是否启用版面检测use_chart_recognition是否启用图表识别use_seal_recognition是否启用印章识别use_ocr_for_image_block是否对图片块执行 OCRformat_block_content是否格式化块内容merge_layout_blocks是否合并版面块markdown_ignore_labels输出为 Markdown 时忽略的标签列表use_queues是否使用队列PPStructureV3Reader结构化版面分析管线PPStructureV3Readerppstructure_v3_loader.py基于 PPStructureV3 管线实现文档结构提取涵盖版面检测、OCR 流程、表格/图表/公式/印章识别默认版面模型为PaddlePaddle/PP-DocLayout-L。其load_data流程与 VLM 版基本一致ppstructure_v3_loader.py差异在于支持的文件类型为.pdf, .jpg, .jpeg, .png, .tiff, .tif不含.webp与.bmp见 ppstructure_v3_loader.py不强制切换动态图模式直接调用self.pipeline_.predict(str(file_path))。PPStructureV3Reader的参数体系比 VLM 版更细覆盖完整传统 OCR 子任务全部默认None即使用 PaddleOCR 默认值版面检测layout_detection_model_name/dir、layout_threshold、layout_nms、layout_unclip_ratio、layout_merge_bboxes_mode图表与区域chart_recognition_model_name/dir、chart_recognition_batch_size、region_detection_model_name/dir文档预处理doc_orientation_classify_*、doc_unwarping_*文本检测text_detection_model_name/dir、text_det_limit_side_len、text_det_limit_type、text_det_thresh、text_det_box_thresh、text_det_unclip_ratio文本行方向textline_orientation_model_name/dir、textline_orientation_batch_size文字识别text_recognition_model_name/dir、text_recognition_batch_size、text_rec_score_thresh表格识别table_classification_model_name/dir、wired_table_structure_recognition_model_name/dir、wireless_table_structure_recognition_model_name/dir、wired_table_cells_detection_model_name/dir、wireless_table_cells_detection_model_name/dir、table_orientation_classify_model_name/dir区分有线表与无线表印章识别seal_text_detection_model_name/dir、seal_det_limit_side_len、seal_det_limit_type、seal_det_thresh、seal_det_box_thresh、seal_det_unclip_ratio、seal_text_recognition_model_name/dir、seal_text_recognition_batch_size、seal_rec_score_thresh公式识别formula_recognition_model_name/dir、formula_recognition_batch_size开关与输出use_doc_orientation_classify、use_doc_unwarping、use_textline_orientation、use_seal_recognition、use_table_recognition、use_formula_recognition、use_chart_recognition、use_region_detection、format_block_content、markdown_ignore_labels、lang、ocr_version。这些参数与 PaddleOCRPPStructureV3构造参数一一对应Kotaemon 仅负责把非None的参数透传因此若想自定义模型路径或精度阈值可据此推断通过Param子类化这两个 Reader 并在初始化时传入对应参数即可覆盖默认模型。统一适配层PaddleOCRResult 如何把结果变成 Document两个读取器提取的原始结果统一交给 adapter.py 中的PaddleOCRResult处理。该适配器假设 PPStructureV3 与 PaddleOCRVL 的输出结构相似adapter.py结果是一个页面结果列表每页包含parsing_res_list块列表每个块具有block_label与block_content。块标签block_label分类策略适配器将版面块按标签分为四类adapter.py类别标签集合处理方式文本text_labelstext、paragraph_title、doc_title、abstract、content、footnote、reference、reference_content、aside_text、algorithm按页合并为一个文本Document表格table_labelstable清洗 HTML 后生成typetable的Document并保留table_origin图片image_labelsimage、chart生成typeimage的Document并尝试按 bbox 裁剪原图生成 base64image_origin公式formula_labelsformula、display_formula、inline_formula包裹为$$...$$后并入文本块此外定义了一组ignore_labels如footer、header、seal、figure_title、number、formula_number等直接跳过因为这些元素对 RAG 检索价值有限adapter.py。落在上述类别之外的标签会按文本块处理adapter.py。页面信息与图源裁剪每个Document的元数据会写入page_label、file_name、file_path并合并extra_infoadapter.py保证后续检索时可以追溯到具体页面。对图片/图表块适配器会取块的block_bbox与页面width/height将像素坐标归一化到 0–1 区间_normalize_bboxadapter.py复用 azureai_document_intelligence_loader.py 中导出的crop_image函数按 bbox 从 PDF/图片裁剪出图块编码为 PNG base64 data URL 存入image_origin_get_image_originadapter.py任何一步失败如裁剪异常都会静默降级只保留文本内容与typeimage元数据。表格内容会经过_clean_table_html清洗去掉htmlbody包裹层后再入库adapter.py。最终to_documents按「文本 表格 图片」的顺序拼接返回adapter.py。这些Document随后进入索引管线的切分默认TokenSplitterchunk_size1024、chunk_overlap256见 files.py与向量化流程。在索引管线中的接入位置从源码结构看PaddleOCR 读取器通过两条路径接入索引默认实例模块导入时即创建paddle_struct_reader与paddle_vl_readerfiles.pyUI 中 File Loader 的选择会映射到对应读取器DocumentIngestor调度DocumentIngestor根据文件扩展名从KH_DEFAULT_FILE_EXTRACTORS与override_file_extractors中选择读取器files.pypdf_mode则决定 PDF 的默认解析方式normal/mathpix/ocr/multimodal。摄入完成后读取器输出的Document会被切分为节点nodes进入向量索引供后续问答链路检索使用。实战建议与注意事项设备选择GPU 环境推荐设置PADDLE_DEVICEgpu默认值CPU 环境务必设置为cpuKotaemon 会自动关闭 MKL-DNN 规避 PaddlePaddle 3.3 的已知崩溃文件类型差异PaddleOCRVLReader额外支持.bmp与.webpPPStructureV3Reader仅支持.pdf/.jpg/.jpeg/.png/.tiff/.tif上传前请确认扩展名模型首跑两者首次预测时会下载对应模型VLM 版为 PaddleOCR-VL-1.5结构版为 PP-DocLayout-L 等首次运行耗时较长属正常现象自定义模型与阈值通过子类化Param覆盖layout_detection_model_dir、text_recognition_model_dir、layout_threshold等参数可指向本地已下载的模型目录或调整精度/速度权衡排查依赖若遇到ImportError提示安装paddleocr[doc-parser]说明 extras 未安装成功请重新执行uv pip install -e libs/kotaemon[paddleocr]。如需了解仓库中其他文档解析方案如 Docling可参考 docs/integrations/docling.md读取器基类与Param机制的说明见 libs/kotaemon/kotaemon/loaders/base.py 与 libs/kotaemon/kotaemon/base/component.py。【免费下载链接】kotaemonAn open-source RAG-based tool for chatting with your documents.项目地址: https://gitcode.com/GitHub_Trending/kot/kotaemon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考