PaddleNLP Pipelines File Converter 模块指南：将 PDF、Word、图片、Markdown 与 TXT 统一转换为可检索文本

人工智能大模型预训练微调LoRARLHF强化学习分布式训练【免费下载链接】PaddleNLPEasy-to-use and powerful LLM and SLM library with awesome model zoo.项目地址https://gitcode.com/gh_mirrors/pa/PaddleNLP点击查看免费下载在文档问答、语义检索、知识库构建等 Pipeline 场景中第一道工序往往不是模型推理而是文件解析把散落在 PDF、Word、Markdown、TXT 甚至图片中的非结构化内容转成结构统一、可供后续切分PreProcessor与向量化Retriever/Embedding使用的纯文本文档。PaddleNLP Pipelines 的file_converter节点模块正是为此设计的一组内置组件本指南基于仓库中 file_converter 模块文档结合其源码实现pipelines/nodes/file_converter逐一讲解各转换器的能力边界、公共参数、底层解析逻辑与实际调用方式读完即可在自己的索引管线中正确选用并配置文件转换节点。模块定位与统一设计一切转换器共享的文本化约定file_converter模块归属于pipelines.nodes组件体系其 API 参考文档以 MkDocs 的::: pipelines.pipelines.nodes.file_converter.docx/image/markdown/pdf/txt五个指令分别呈现五个转换器类。从源码结构看所有转换器都继承自抽象基类 BaseConverterclass BaseConverter(BaseComponent): outgoing_edges 1 def __init__(self, remove_numeric_tables: bool False, valid_languages: Optional[List[str]] None): self.set_config(remove_numeric_tablesremove_numeric_tables, valid_languagesvalid_languages) self.remove_numeric_tables remove_numeric_tables self.valid_languages valid_languages基类奠定了三条全模块通用的设计约定统一输出结构每个转换器的convert()都返回List[Dict]每个元素形如{content: 提取到的文本, content_type: text, meta: 元数据}保证下游 PreProcessor、DocumentStore 无需关心文件原始格式统一运行入口基类实现的run()接受file_paths单个Path或Path列表与meta逐文件调用子类convert()最后返回{documents: documents}与边名output_1因此每个转换器都自带outgoing_edges 1可直接作为 Pipeline 节点接入配置可序列化构造参数通过self.set_config(...)记录可导出为 YAML 组件配置供声明式 Pipeline 加载。转换器全景五种文件格式、六个类模块对外导出的转换器定义在 file_converter/init.py 中其中带可选依赖的类使用safe_import延迟导入类名对应文件依赖典型用途TextConvertertxt.py无纯文本 TXT 直接读取MarkdownConvertermarkdown.pymarkdown、BeautifulSoupMarkdown 转纯文本剥离格式MarkdownRawTextConvertermarkdown.py同上Markdown 转文本并保留标题层级标记PDFToTextConverterpdf.pypypdf文本型 PDF 逐页抽取PDFToTextOCRConverterpdf.pypdf2image、PaddleOCR扫描版 PDF 按页 OCRDocxToTextConverterdocx.pypython-docx、PILWord 段落文本与内嵌图片抽取ImageToTextConverterimage.pyPaddleOCR图片文字识别模块还保留了一个简化版DocxTotxtConverter仅按换行符拼接段落文本。转换器依赖 PaddleOCR 等可选组件未安装时会通过 import_utils 抛出带preprocessing/ocr分组标记的引导性错误便于用户按提示补装依赖。公共参数详解去噪与语言校验除各自专属参数外所有转换器都共享两个继承自BaseConverter的构造参数它们直接影响抽取文本的质量remove_numeric_tables启发式过滤数字表格行参数类型bool默认False。其动机在源码 docstring 中说明得很清楚表格结构对不具备表格解析能力的 Reader 模型可能是噪声但表格中又可能含有可作为答案候选项的长字符串因此该选项只删除以数字为主的行保留含字符串的行。在ImageToTextConverter.convert()中可以看到具体判定逻辑image.pydigits [word for word in words if any(i.isdigit() for i in word)] if remove_numeric_tables: if words and len(digits) / len(words) 0.4 and not line.strip().endswith(.): logger.debug(fRemoving line {line} from file) continue即某一行中超过 40% 的单词包含数字、且行尾不是句号时判定为数字表格行并丢弃。注意两个例外——DocxToTextConverter与MarkdownConverter在文档中明确标注该参数不适用前者直接raise Exception拒绝该参数后者忽略。valid_languages编码错误检测参数类型List[str]内容为 ISO 639-1 语言码列表。若抽取文本的语言不在列表中说明文件极可能因编码错误产生了乱码。判定逻辑实现在基类validate_language()base.pydef validate_language(self, text: str, valid_languagesNone) - bool: if valid_languages is None: valid_languages self.valid_languages if not valid_languages: return True try: lang langdetect.detect(text) except langdetect.lang_detect_exception.LangDetectException: lang None return lang in valid_languages使用langdetect库检测语言检测异常时视为不合法未设置该参数时直接放行。在ImageToTextConverter中语言校验失败只会打印logger.warning提示文件可能未按正确文本格式解码不会中断流程。TextConverter最轻量的纯文本读取TextConverter 的实现极为直接以utf-8可用encoding参数覆盖读取整个文件errorsignore容忍部分非法字节把全文塞进单个 documentwith open(file_path, encodingencoding, errorsignore) as f: text f.read() document {content: text, content_type: text, meta: meta}convert()的完整签名还接受remove_numeric_tables、valid_languages未显式传入时回退到构造参数。适合日志、说明文档等已接近纯文本的素材开销最小。MarkdownConverter剥离格式只留正文MarkdownConverter 采用Markdown → HTML → 纯文本的两段式策略先用markdown库渲染 HTML再用正则移除pre/code代码块最后由BeautifulSoup提取全部文本节点html markdown(markdown_string) html re.sub(rpre(.*?)/pre, , html) html re.sub(rcode(.*?)/code , , html) soup BeautifulSoup(html, html.parser) text .join(soup.findAll(textTrue))同文件中的MarkdownRawTextConverter则是变体它在剥离代码块后先把h1~h6分别改写为#~######前缀再提取文本从而在最终文本中保留标题层级信息便于后续按语义结构切分文档。PDFToTextConverter文本型 PDF 的多进程逐页抽取PDFToTextConverter 针对内含文本层的 PDF如 Word 导出件、电子期刊底层使用pypdf的page.extract_text()抽取每页文字。它的特点在于按页并行解析_read_pdf()把总页数按进程数均分成若干页区间通过multiprocessing.Pool.map_async并行执行extract_pages()每个 worker 独立用pypdf.PdfReader读取对应页区间split_len page_length // process_num page_list [i for i in range(0, page_length, split_len)] ... page_text run_process(page_combination, file_path, process_num)process_num默认 20但代码会取min(os.cpu_count(), process_num)并警告进程数不能超过 CPU 核数。逐页解析的结果会按页拆分为多个 document返回每页一个{content: 该页文本, content_type: text, meta: meta}这与 TXT/Markdown 的单文档输出不同是检索粒度设计上的一个重要差异。仓库中的测试 test_pdf.py 以tests/fixtures/example_pdf.pdf为输入、process_num1串行转换断言返回恰好 2 个文档对应两页 PDF验证了逐页输出的行为。PDFToTextOCRConverter扫描版 PDF 的图像化 OCR当 PDF 是扫描件无文本层时PDFToTextOCRConverter先借助pdf2image.convert_from_path把每一页渲染为 JPEG 临时图片再委托内部的ImageToTextConverter逐个识别最终以换页符\f拼接全文images convert_from_path(file_path) for image in images: temp_img tempfile.NamedTemporaryFile(..., suffix.jpeg, deleteFalse) image.save(temp_img.name) pages.append(self.image_2_text.convert(temp_img.name)[0][content]) raw_text \f.join(pages)该转换器构造时默认valid_languages[eng]对应 Tesseract 语言包命名同时组合使用ImageToTextConverter实例说明它是PDF 渲染 图片识别两能力的复合节点。ImageToTextConverter基于 PaddleOCR 的图片文字识别ImageToTextConverter 是 OCR 能力的核心实现其亮点在于直接复用 PaddleNLP 生态的 PaddleOCR并自动适配推理设备use_gpu True if gpu in paddle.device.get_device() else False self.recognize PaddleOCR(use_angle_clsTrue, langch, use_gpuuse_gpu)构造时依据paddle.device.get_device()是否含gpu自动选择 GPU/CPU开启方向分类use_angle_clsTrue与中文模型langch。_image_to_text()调用self.recognize.ocr(img_path, clsTrue)把识别结果中每行文本line[-1][0]拼接为整段文字返回随后convert()按公共参数执行数字表格行过滤与语言校验每个识别页面产出一个 document。DocxToTextConverter段落文本与内嵌图片的协同抽取DocxToTextConverter 是功能最丰富的实现通过python-docx解析 Word 文档并特别处理了图文混排遍历file.paragraphs通过paragraph._element.xpath(.//pic:pic)定位段落内嵌图片再从文档的related_parts中取出ImagePart实体get_image_list()有文本的段落先累积进text_dict当遇到无文本、无图片的段落边界时把累积文本合并为一条 document同时把save_images()落盘的图片文件名写入该文档的meta[images]save_images()用图片二进制计算 MD5 作为文件名{md5}_{序号}.{ext}统一保存到构造时自动创建的parse_files/目录实现文本与其上下文图片绑定的抽取效果。由于 DOCX 本身没有页的概念文档中明确说明该方法返回的是段落列表而非页列表接口命名仅为与其它转换器保持一致。另外该转换器对remove_numeric_tables与valid_languages均不支持传入True会直接抛异常。在真实管线中如何组装YAML 索引管线示例转换器的价值最终体现在管线编排中。仓库 docker/dense_qa.yaml 给出了一个完整的密集检索 QA 索引管线示例用FileTypeClassifier按扩展名把输入文件分流到四条转换器分支再汇入PreProcessor切分后灌入检索器components: - name: TextFileConverter type: TextConverter - name: ImageFileConverter type: ImageToTextConverter - name: PDFFileConverter type: PDFToTextConverter - name: DocxFileConverter type: DocxToTextConverter - name: FileTypeClassifier type: FileTypeClassifier pipelines: - name: indexing type: Indexing nodes: - name: FileTypeClassifier inputs: [File] - name: TextFileConverter inputs: [FileTypeClassifier.output_1] - name: PDFFileConverter inputs: [FileTypeClassifier.output_2] - name: DocxFileConverter inputs: [FileTypeClassifier.output_4] - name: ImageFileConverter inputs: [FileTypeClassifier.output_6] - name: Preprocessor inputs: [PDFFileConverter, TextFileConverter, DocxFileConverter, ImageFileConverter]同样地semantic_search.yaml 也以相同方式注册了这四类转换器。在实际编码场景中也可以脱离 YAML 直接实例化调用例如from pipelines.nodes.file_converter import PDFToTextConverter, TextConverter pdf_converter PDFToTextConverter(languageen, valid_languages[en]) documents, _ pdf_converter.run(file_paths[annual_report.pdf], meta{source: finance})其中run()的返回值可直接作为下游PreProcessor节点的输入或自行落入DocumentStore。小结如何为你的文档集选择合适的转换器输入文件推荐转换器关键取舍纯文本 / 日志TextConverter开销最小整文件单文档Markdown 笔记MarkdownConverter/MarkdownRawTextConverter前者纯文本后者保留标题层级有文本层的 PDFPDFToTextConverter逐页多文档输出支持多进程加速扫描版 PDFPDFToTextOCRConverter依赖 PaddleOCR 与 pdf2imageWord.docxDocxToTextConverter段落级输出图片落盘parse_files/并写入 meta图片ImageToTextConverter自动选择 GPU/CPU默认中文识别模型最后强调两点通用规则其一remove_numeric_tables与valid_languages是贯穿所有转换器的质量开关按语料噪声与语言分布开启即可显著改善下游检索精度其二各转换器输出文档的粒度整文件、按页、按段落不同会直接影响切分与检索的单元设计选型时应结合文档特点与 QA 任务粒度综合权衡。更完整的组件列表与用法可参考 Pipelines 文档主页 及模块源码 file_converter 目录。赞分享人工智能大模型预训练微调LoRARLHF强化学习分布式训练【免费下载链接】PaddleNLPEasy-to-use and powerful LLM and SLM library with awesome model zoo.项目地址https://gitcode.com/gh_mirrors/pa/PaddleNLP点击查看免费下载相关推荐PyMuPDF4LLM 实战指南将 PDF 与 Office 文档转换为 LLM / RAG 友好的 Markdown、JSON 与 TXTPyMuPDF4LLM 实战指南将 PDF 与 Office 文档转换为 LLM / RAG 友好的 Markdown、JSON 与 TXT PyMuPDF4图像处理PaddleOCR doc2md无需 OCR 即可将 Word、Excel 与 PowerPoint 一键转换为 MarkdownPaddleOCR doc2md无需 OCR 即可将 Word、Excel 与 PowerPoint 一键转换为 Markdown doc2md 是 Padd人工智能计算机视觉深度学习PinchTab 多页面导航与返回基准基于 group-12 的后退按钮自动化测试实战PinchTab 多页面导航与返回基准基于 group 12 的后退按钮自动化测试实战 本篇指南围绕 PinchTab 优化基准optimization b上一篇Envoy Gateway 架构深度解析理解 XDS、Bootstrap 和 Translator 核心组件下一篇node-fetch 错误处理完全指南AbortError、FetchError 与 err.type 分类体系创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考