全面掌握 Haystack Converters API把各种格式文件变成 Document 的完整指南【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack本文基于 Haystack 2.20 版本参考文档converters_api.md系统梳理 Haystack 全部转换器Converters组件的接口约定、参数取值与实际用法并结合当前仓库 haystack/components/converters/ 下的源码实现讲解每个转换器底层的解析逻辑。读完后你能够独立选型合适的转换器处理 PDF、Office、网页、CSV/JSON 等各类数据源理解sources/meta的统一契约并把转换器正确接入 Haystack 的 Pipeline 数据流。一、Converters 在 Haystack 中的定位Converters 是 Haystack 文档处理管线的入口组件负责把磁盘文件、内存字节流或外部服务返回的数据统一转换为 Haystack 的核心数据类Document。参考文档 converters_api.md 描述的是 2.20 版本的完整 API 面覆盖以下模块模块组件用途azureAzureOCRDocumentConverter调用 Azure Document Intelligence 转换 PDF、图片、Office 文档csvCSVToDocumentCSV 转 Document支持按行拆分docxDOCXToDocument等Word 文档转 Document含表格/链接格式控制htmlHTMLToDocument基于 Trafilatura 提取网页正文jsonJSONConverterJSON 文件按 jq 表达式提取内容markdownMarkdownToDocumentMarkdown 转纯文本 DocumentmsgMSGToDocumentOutlook .msg 邮件转 Document 附件multi_file_converterMultiFileConverter一个组件按 MIME 类型分发处理 9 种格式openapi_functionsOpenAPIServiceToFunctionsOpenAPI 定义转 OpenAI 函数调用格式output_adapterOutputAdapter用 Jinja 模板重塑任意组件输出pdfminerPDFMinerToDocument基于 pdfminer.six 的 PDF 文本提取pptxPPTXToDocumentPPT 转 DocumentpypdfPyPDFToDocument基于 PyPDF 的 PDF 文本提取tikaTikaDocumentConverter调用 Apache Tika 服务转换多种格式txtTextFileToDocument纯文本转 DocumentxlsxXLSXToDocumentExcel 转 CSV/Markdown 表格 Document当前仓库中haystack.components.converters包通过惰性导入机制haystack/components/converters/init.py按需加载这些组件只有真正用到某个组件时才会触发对应子模块及其第三方依赖如pypdf、jq、python-docx的导入避免安装全部可选依赖。二、统一接口契约sources、meta 与 ByteStream参考文档中所有文件型转换器的run()方法都遵循同一契约component.output_types(documentslist[Document]) def run(sources: list[Union[str, Path, ByteStream]], meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] None)sources文件路径str或Path或ByteStream对象的列表支持一次批量转换多个文件meta要附加到输出 Document 上的元数据。传入单个字典时内容会加到所有生成的 Document 上传入列表时列表长度必须与sources数量一致两者 zip 对应。若sources中的元素是ByteStream其自带的meta会合并进输出 Document返回值字典至少包含documents键部分组件还有额外输出见后文。源码层面这套契约由 haystack/components/converters/utils.py 中的两个工具函数支撑get_bytestream_from_source(source)把路径统一读成ByteStream并把原始路径写入bytestream.meta[file_path]已经是ByteStream则直接透传类型不支持时抛ValueErrornormalize_metadata(meta, sources_count)把meta的三种形态None/ 单个 dict / dict 列表归一化为与sources等长的列表。实现上对单个 dict 会执行deepcopy保证每个 source 拿到独立副本避免一个 source 的元数据修改污染其他 source列表长度不匹配时直接抛ValueError。各转换器的run()内部普遍采用“单个文件失败只记录 warning 并跳过”的容错策略如 csv.py 中对读取和转换异常分别logger.warning后continue保证批量转换不会因为个别坏文件整体中断。store_full_path是几乎所有转换器共有的构造参数为True时 Document 的meta[file_path]保存完整路径为False默认时只保留文件名os.path.basename。在 CSV、DOCX 等组件源码中都能看到相同的处理分支。三、MultiFileConverter按 MIME 类型自动分发的超级组件MultiFileConverter是参考文档中唯一标注为 Super Component 的转换器见 haystack/components/converters/multi_file_converter.py一次run()就能处理混合文件集合。支持的文件类型CSV、DOCX、HTML、JSON、MD、TEXT、PDF无 OCR、PPTX、XLSX。from haystack.components.converters import MultiFileConverter converter MultiFileConverter(encodingutf-8, json_content_keycontent) results converter.run(sources[test.txt, sample.pdf, data.json], meta{})构造参数encoding读取文本类文件时的编码默认utf-8json_content_keyJSON 文件转 Document 时用作内容的键名默认content。从源码结构看MultiFileConverter用super_component装饰内部在__init__中构建了一条完整的内部 Pipeline入口是FileTypeRouter按 源码中定义的ConverterMimeType枚举 列出 9 种 MIME 类型如application/pdf、text/csv并显式注册.docx/.xlsx/.pptx扩展名映射以保证 Windows 上的正确识别每个 MIME 路由到对应的基础转换器DOCXToDocument(link_formatmarkdown)、HTMLToDocument(output_formatmarkdown, include_tablesTrue, include_linksTrue)、JSONConverter(content_key...)、PyPDFToDocument()、PPTXToDocument()、XLSXToDocument()、CSVToDocument()以及用于 MD/TEXT 的两个TextFileToDocument各转换器的documents输出汇入DocumentJoiner最终输出映射为documents同时透传路由器的unclassified无法识别 MIME 的 source和failed分支。这种设计使你在索引管线中只需放置一个组件即可消化多格式数据源且无法识别的文件不会中断流程而是进入unclassified输出供下游处理。四、CSV 转换文件模式与行模式CSVToDocumenthaystack/components/converters/csv.py把 CSV 文件转换为 Document默认 UTF-8 编码。from haystack.components.converters.csv import CSVToDocument converter CSVToDocument() results converter.run(sources[sample.csv], meta{date_added: 2025-01-01T00:00:00}) print(results[documents][0].content) # col1,col2\nrow1,row1\nrow2,row2\n构造参数encoding默认utf-8若 source 的ByteStream.meta中带有encoding会覆盖该默认值源码中bytestream.meta.get(encoding, self.encoding)store_full_path默认Falseconversion_mode默认file仅关键字参数file时每个文件生成一个 Document内容为整段原始 CSV 文本row时每行生成独立 Documentdelimiter默认,与quotechar默认仅在 row 模式下生效会传给csv.DictReader。源码中还会在初始化时校验二者必须是单字符否则抛ValueError。row 模式下run()额外要求content_column指定哪一列作为 Document 的content。结合源码可以看到几个实现细节缺少content_column时直接抛ValueError严格模式不回退文件超过约 5MB 时会记录内存告警_ROW_MODE_SIZE_WARN_BYTES使用restkeyextra_columns处理列数多于表头的“参差行”避免None键破坏 Document id 生成每行的content_column之外列会被并入meta与已有键冲突时自动加csv_前缀必要时再加数字后缀并写入row_number记录行号。五、Office 文档转换DOCXToDocument 与表格、链接格式控制DOCXToDocumenthaystack/components/converters/docx.py基于python-docx库解析 Word 文档。from haystack.components.converters.docx import DOCXToDocument, DOCXTableFormat, DOCXLinkFormat converter DOCXToDocument(table_formatDOCXTableFormat.CSV, link_formatDOCXLinkFormat.MARKDOWN) results converter.run(sources[sample.docx], meta{date_added: 2025-01-01T00:00:00})构造参数table_formatDOCXTableFormat.MARKDOWN/CSV或字符串markdown/csv默认 CSVlink_formatMARKDOWN输出text、PLAIN输出text (address)或NONE默认只保留文字store_full_path。源码中DOCXLinkFormat实际就是 utils.py 中定义的LinkFormat枚举别名DOCXTableFormat与LinkFormat都实现了from_str静态方法做大小写不敏感的字符串归一化这也是to_dict/from_dict序列化时能正确还原枚举的原因。另外DOCXMetadatadataclass 定义了 15 个从core_properties提取的字段author、category、comments、content_status、created、identifier、keywords、language、last_modified_by、last_printed、modified、revision、subject、title、versionrun()会把这些字段以meta[docx]子字典挂到每个 Document 上——文档的作者、版本、修改时间等信息无需额外处理即可进入元数据。表格渲染上Markdown 模式会先计算每列最大宽度并左对齐填充首行后插入分隔行与标准 GFM 表格语法一致。PPTXToDocumentPPTXToDocument只暴露store_full_path一个构造参数用法与其他转换器一致from haystack.components.converters.pptx import PPTXToDocument converter PPTXToDocument() results converter.run(sources[sample.pptx], meta{date_added: 2025-01-01T00:00:00})XLSXToDocumentXLSXToDocument支持读取指定工作表或全部工作表全部读取时每个 sheet 生成一个 Document表格内容保存为 CSV 或 Markdownfrom haystack.components.converters.xlsx import XLSXToDocument converter XLSXToDocument(table_formatcsv) results converter.run(sources[sample.xlsx], meta{date_added: 2025-01-01T00:00:00})构造参数table_formatcsv默认或markdownsheet_name工作表名/序号可为str、int或其列表为None时读取所有 sheetread_excel_kwargs透传给pandas.read_excel的参数table_format_kwargscsv时透传给pandas.DataFrame.to_csvmarkdown时透传给to_markdownstore_full_path仅关键字参数默认False。文档示例输出形如,A,B 1,col_a,col_b 2,1.5,test六、JSON 转换jq 过滤与元数据提取JSONConverterhaystack/components/converters/json.py把 JSON 文件转成文本 Document底层依赖jq库执行过滤。构造参数jq_schemajq 过滤表达式用于从嵌套 JSON 中提取数据不设置时使用整个 JSON 对象content_key指定提取对象中哪个键作为 Document 的contentextra_meta_fields字符串集合或字面量*。为集合时只把指定字段写入 meta缺失字段值为None为*时把过滤后对象中除content_key外的所有字段都存为元数据store_full_path。初始化规则参考文档明确列出源码同样强制执行两者都设置时在jq_schema提取结果内查找content_key提取结果不是 JSON 对象则跳过该条只设置jq_schema时提取结果必须是标量值对象或数组会被跳过只设置content_key时源 JSON 必须是 JSON 对象否则跳过两者都不设置时初始化直接失败。基础用法import json from haystack.components.converters import JSONConverter from haystack.dataclasses import ByteStream source ByteStream.from_string(json.dumps({text: This is the content of my document})) converter JSONConverter(content_keytext) results converter.run(sources[source]) print(results[documents][0].content) # This is the content of my document结合jq_schema与extra_meta_fields的完整示例参考文档原样保留import json from haystack.components.converters import JSONConverter from haystack.dataclasses import ByteStream data { laureates: [ { firstname: Enrico, surname: Fermi, motivation: for his demonstrations of the existence of new radioactive elements produced by neutron irradiation, and for his related discovery of nuclear reactions brought about by slow neutrons, }, { firstname: Rita, surname: Levi-Montalcini, motivation: for their discoveries of growth factors, }, ], } source ByteStream.from_string(json.dumps(data)) converter JSONConverter( jq_schema.laureates[], content_keymotivation, extra_meta_fields{firstname, surname} ) results converter.run(sources[source]) documents results[documents] print(documents[0].content) # for his demonstrations of the existence of new radioactive elements produced by # neutron irradiation, and for his related discovery of nuclear reactions brought # about by slow neutrons print(documents[0].meta) # {firstname: Enrico, surname: Fermi} print(documents[1].content) # for their discoveries of growth factors print(documents[1].meta) # {firstname: Rita, surname: Levi-Montalcini}可见一个 JSON 数组经.laureates[]展开后每个元素都生成独立 Document且extra_meta_fields指定的字段逐一落到meta中——这使得 JSON 数据源可以在入库前完成结构化的字段映射。七、网页、Markdown 与纯文本HTMLToDocumentHTMLToDocument使用 Trafilatura 库提取网页正文extraction_kwargs直接透传给 Trafilatura 的extract函数可控制输出格式、表格与链接保留等行为from haystack.components.converters import HTMLToDocument converter HTMLToDocument() results converter.run(sources[path/to/sample.html]) print(results[documents][0].content) # This is a text from the HTML file.构造参数extraction_kwargs可选字典与store_full_path默认Falserun()还额外接受一次性的extraction_kwargs覆盖参数。MarkdownToDocumentfrom haystack.components.converters import MarkdownToDocument converter MarkdownToDocument(table_to_single_lineTrue) results converter.run(sources[path/to/sample.md], meta{date_added: 2025-01-01T00:00:00})构造参数table_to_single_line默认False为True时把表格内容压缩成单行避免多行表格在分块/嵌入时被打散progress_bar默认True运行时显示进度条store_full_path默认False。TextFileToDocumentfrom haystack.components.converters.txt import TextFileToDocument converter TextFileToDocument(encodinggbk) results converter.run(sources[sample.txt])参数与 CSV 类似encoding默认utf-8可被ByteStream.meta中的encoding覆盖与store_full_path。它是处理.txt及MultiFileConverter中.md/.text路由的实际执行者。八、PDF 转换的三条路线参考文档 2.20 为 PDF 提供了三种互补方案可按“文本质量—版面还原—扫描件 OCR”三个维度选型。PyPDFToDocument轻量文本提取PyPDFToDocumenthaystack/components/converters/pypdf.py基于 PyPDF 库提供两种提取模式from haystack.components.converters.pypdf import PyPDFToDocument, PyPDFExtractionMode converter PyPDFToDocument(extraction_modePyPDFExtractionMode.PLAIN) results converter.run(sources[sample.pdf], meta{date_added: 2025-01-01T00:00:00})PyPDFExtractionMode枚举只有PLAIN和LAYOUT两个值from_str对未知模式抛ValueError。全部构造参数及默认值参数默认值说明extraction_modePLAIN提取模式LAYOUT 为实验性模式尽量还原 PDF 渲染版面plain_mode_orientations(0, 90, 180, 270)plain 模式尝试的文本朝向LAYOUT 模式下忽略plain_mode_space_width200.0无法从字体提取空格宽度时的强制默认值layout_mode_space_verticallyTrue是否根据 y 距离 字体高度插入空行layout_mode_scale_weight1.25加权平均字符宽度计算的字符串长度乘数layout_mode_strip_rotatedTrue检测到旋转文本时剔除否则版面降级并告警设为False可保留layout_mode_font_height_weight1.0空行高度计算中字体高度的乘数store_full_pathFalse元数据中存完整路径还是文件名PDFMinerToDocument版面分析可调的提取器PDFMinerToDocument基于 pdfminer.six把该库的版面分析参数全部开放为构造参数from haystack.components.converters.pdfminer import PDFMinerToDocument converter PDFMinerToDocument(line_overlap0.5, boxes_flow0.5) results converter.run(sources[sample.pdf], meta{date_added: 2025-01-01T00:00:00})参数语义参考文档原文整理line_overlap默认0.5两字符重叠度相对两者最小高度超过该值才视为同一行char_margin默认2.0字符间距小于该字符宽度倍数时视为同一行word_margin默认0.1同行两字符间距超过该宽度倍数时插入空格line_margin默认0.5两行间距小于该行高倍数时视为同一段落boxes_flow默认0.5文本框排序中水平/垂直位置权重取值 -1.0仅水平到 1.0仅垂直设None禁用高级版面分析按左下角坐标排序detect_vertical默认True版面分析时是否考虑竖排文本all_texts默认False是否分析图内文本store_full_path默认False。此外它还暴露detect_undecoded_cid_characters(text)静态方法检测文本中未正确解码的 CID 字符PDF 字体缺少 ToUnicode 映射时的典型症状用于判断“提取结果乱码”是否源于非标准字体——这为扫描件/特殊字体 PDF 该改用 OCR 路线提供了诊断依据。AzureOCRDocumentConverter云端 OCR 全格式转换AzureOCRDocumentConverter调用 Azure Document Intelligence 服务支持 PDF、JPEG、PNG、BMP、TIFF、DOCX、XLSX、PPTX 和 HTML是扫描件 PDF 的主力方案from haystack.components.converters import AzureOCRDocumentConverter from haystack.utils import Secret converter AzureOCRDocumentConverter(endpointurl, api_keySecret.from_token(your-api-key)) results converter.run(sources[path/to/doc_with_images.pdf], meta{date_added: 2025-01-01T00:00:00}) print(results[documents][0].content) # This is a text from the PDF file.构造参数endpointAzure 资源端点必填api_key默认从环境变量AZURE_AI_API_KEY读取Secret.from_env_varmodel_id默认prebuilt-readAzure 模型 ID可选列表见 Azure 官方文档preceding_context_len/following_context_len默认各3为表格提取前后若干行上下文写入表格元数据帮助 RAG 检索时理解表格语义merge_multiple_column_headers默认True把多行列表头合并为一行page_layout默认naturalnatural使用 Azure 判定的自然阅读顺序single_column按threshold_y阈值把同高度行分组成一行threshold_y默认0.05英寸single_column模式下判定两元素是否同行的空间阈值对章节标题、编号与正文在水平方向分离的场景很关键store_full_path默认False。与其他转换器不同的地方在于它的输出run()声明两个输出——documentslist[Document]和raw_azure_responselist[dict]保留 Azure 原始响应便于自定义后处理。TikaDocumentConverter借助 Tika 服务转换任意格式TikaDocumentConverter依赖外部运行的 Apache Tika 服务因此覆盖面最广参考文档示例输入同时包含.docx、.rtf、.zipfrom haystack.components.converters.tika import TikaDocumentConverter converter TikaDocumentConverter(tika_urlhttp://localhost:9998/tika) results converter.run(sources[sample.docx, my_document.rtf, archive.zip], meta{date_added: 2025-01-01T00:00:00})构造参数只有tika_url默认http://localhost:9998/tika与store_full_path。从源码结构看该模块内置一个XHTMLParser增量解析器通过handle_starttag/handle_endtag/handle_data识别 Tika 返回 XHTML 中的分页div从而把大文件按页切分成多个 Document——这正是它能输出多页 Document 的原因。九、MSGToDocument邮件正文与附件一次提取MSGToDocument处理 Microsoft Outlook 的.msg文件提取发件人、收件人、CC、BCC、主题等邮件元数据与正文内容并把附件抽取为ByteStream列表from haystack.components.converters.msg import MSGToDocument converter MSGToDocument() results converter.run(sources[sample.msg], meta{date_added: 2025-01-01T00:00:00}) documents results[documents] attachments results[attachments]它的run()输出声明为documentslist[Document]和attachmentslist[ByteStream]是文档中少数带“双输出”的文件转换器之一附件流可以直接接入其他转换器或存储组件。构造参数仅store_full_path。十、面向 Agent 与输出整形的转换器OpenAPIServiceToFunctions该组件把 OpenAPI 服务定义转换为 OpenAI function calling 格式要求定义符合 OpenAPI 3.0.0 及以上规范可以是 JSON 或 YAML。每个函数必须满足有唯一的operationId有description有requestBody和/或parameters为requestBody和/或parameters提供 schema。from haystack.components.converters import OpenAPIServiceToFunctions converter OpenAPIServiceToFunctions() result converter.run(sources[path/to/openapi_definition.yaml]) assert result[functions]run()输出两个键functionsOpenAI 函数调用格式的 JSON 对象列表与openapi_specs引用已解析的 OpenAPI 规范对象列表。异常约定定义无法下载或处理时抛RuntimeErrorsource 类型无法识别或未找到任何函数时抛ValueError。把它接在工具链前面可以快速把内部 REST 服务批量注册为 Agent 可调用的工具。OutputAdapterJinja 模板重塑组件输出OutputAdapter不属于文件转换而是用 Jinja 模板把任意组件输出重塑为目标类型在管线末端做“输出适配”from haystack import Document from haystack.components.converters import OutputAdapter adapter OutputAdapter(template{{ documents[0].content }}, output_typestr) documents [Document(contentTest content)] result adapter.run(documentsdocuments) assert result[output] Test content构造参数templateJinja 模板字符串模板中出现的变量名即为该组件的输入名如模板含{{ documents[0].content }}则输入为documentsoutput_type输出类型决定返回值的形态custom_filters模板可用的自定义 Jinja 过滤器字典unsafe默认False允许在模板中执行任意代码参考文档明确警告只应在完全信任模板来源时使用否则可能导致远程代码执行。run(**kwargs)要求 kwargs 覆盖模板中所有变量渲染失败抛OutputAdaptationException返回{output: ...}。十一、序列化to_dict / from_dict 与 Pipeline 持久化参考文档中每个持久化组件AzureOCRDocumentConverter、DOCXToDocument、HTMLToDocument、JSONConverter、OutputAdapter、PyPDFToDocument等都成对提供to_dict()与from_dict()这是 Haystack 把 Pipeline 保存为 YAML、跨环境部署的基础。结合源码可以看到典型实现模式以 docx.py 为例to_dict用default_to_dict把枚举转为字符串str(self.table_format)from_dict则先手动把init_parameters中的字符串字段经DOCXTableFormat.from_str/DOCXLinkFormat.from_str还原为枚举再交给default_from_dict。这种“字符串进出、枚举进出转换”的约定保证了table_formatmarkdown与table_formatDOCXTableFormat.MARKDOWN在序列化后完全等价。PyPDFToDocument、AzureOCRDocumentConverter等遵循相同套路Secret类参数如api_key则由序列化框架按安全规则处理不会把明文密钥直接落盘。十二、版本对照2.20 参考文档与当前仓库源码的差异需要说明适用前提本文依据的是 2.20 版 API 参考文档而仓库主体源码是后续演进版本。从 haystack/components/converters/init.py 当前的惰性导入结构看导出表包含CSVToDocument、DOCXToDocument、FileToFileContent、HTMLToDocument、JSONConverter、MarkdownToDocument、MSGToDocument、MultiFileConverter、OutputAdapter、PDFMinerToDocument、PPTXToDocument、PyPDFToDocument、TextFileToDocument、XLSXToDocument及image子包——2.20 文档中的azure、tika、openapi_functions三个模块已不在核心导出表中结合releasenotes/notes/目录下的deprecate-tika-document-converter-3b8e2a1f74cd059a.yaml、deprecate-azure-ocr-converter-146df0c8cf40902e.yaml、deprecate-openapi-components-e5f0f7470218fcc4.yaml等变更记录可以推断这三类依赖外部服务/特定云端的转换器在新版本中已被标记弃用并从主包迁移或移除。若你按 2.20 文档编写集成代码建议以pyproject.toml锁定的 Haystack 版本为准核对模块可用性核心的本地文件转换器CSV/DOCX/HTML/JSON/Markdown/MSG/PDF/PPTX/XLSX/TXT接口在两个版本间保持一致可直接复用本文的用法示例。小结Haystack 的 Converters 以统一的run(sources, meta) - {documents: ...}契约覆盖从 PDF、Office、网页到邮件、JSON、OpenAPI 定义的完整数据源谱系本地解析优先PyPDFToDocument/PDFMinerToDocument/DOCXToDocument等复杂扫描件走 Azure OCR杂项格式交给 Tika 或MultiFileConverter自动分发输出侧再用OutputAdapter按模板整形。选型时建议按“格式确定性 版面要求 是否可运行外部服务”三要素匹配组件并利用各组件的store_full_path、metazip 语义与to_dict/from_dict序列化能力把转换层无缝嵌入可持久化的 Pipeline。【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考