Haystack 集成指南使用 UnstructuredFileConverter 将多格式文档转换为 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 官方 Unstructured 集成的核心组件UnstructuredFileConverter展开讲解如何借助 Unstructured API托管版或本地 Docker 部署把 PDF、Word、PPT、Excel 等海量格式的文件统一转换为 Haystack Document从而接入 RAG 与 Agent 应用的索引管道。读完本文你将掌握该组件的安装方式、三种文档创建模式、全部构造参数与run()输入输出契约并能独立完成从原始文件到可直接写入 Document Store 的文档的完整链路搭建。组件定位为什么需要 UnstructuredFileConverter在 Haystack 中Converters 负责把各种格式的文件抽取为统一的 Document 结构是索引管道的起点。UnstructuredFileConverter是其中覆盖面最广的转换器之一它并不在本地解析每种格式而是把文件交给 Unstructured API 处理。Unstructured 提供了一套面向 LLM 的 ETLExtract-Transform-Load工具链能够从数量庞大的文件格式中抽取文本及结构化信息。UnstructuredFileConverter以 API 调用的方式接入这套能力因此不需要在本地为每种格式安装解析依赖——只需维护一个 API 端点即可获得统一的多格式解析结果。该集成组件在 平台组件总览 中被标记为 ✅ Available用户指南与 API 参考分别位于 UnstructuredFileConverter 用户指南 与 Unstructured API 参考。从管道编排上看它最常见的放置位置是索引管道的最开头位于 PreProcessors 之前。这样后面接DocumentSplitter、DocumentWriter等组件即可形成完整的数据入库流水线。该组件的包名为unstructured-fileconverter-haystack属于 Haystack 官方维护的 core-integrations 生态。安装与 API 准备安装集成包pip install unstructured-fileconverter-haystack安装后即可从haystack_integrations.components.converters.unstructured导入组件from haystack_integrations.components.converters.unstructured import UnstructuredFileConverter两种托管服务模式Unstructured API 分为免费版与付费版两个层级层级API URL说明Free Unstructured APIhttps://api.unstructured.io/general/v0/general免费但存在一定的使用限制Unstructured Serverless API付费开通后在 Unstructured 账户中获取专属 URL完整功能的付费版本⚠️ 免费版与付费版的 API Key不同不能互换使用。无论使用哪个层级官方都推荐把 API Key 放在环境变量UNSTRUCTURED_API_KEY中export UNSTRUCTURED_API_KEYyour_api_key环境变量方式也是UnstructuredFileConverter的默认行为——api_key参数默认从UNSTRUCTURED_API_KEY读取strictFalse即未设置时不报错。这样既避免了把密钥硬编码进代码也方便在 CI/CD 或容器环境中统一注入。三种文档创建模式元素到 Document 的映射策略Unstructured API 的解析结果是一组元素elements。UnstructuredFileConverter通过document_creation_mode参数控制这些元素如何被组装成 Haystack Document共三种模式one-doc-per-file默认每个文件生成一个 Document文件内的所有元素按顺序拼接进同一个text字段one-doc-per-page每页生成一个 Document同一页上的所有元素拼接进该页 Document 的text字段one-doc-per-element每个元素单独生成一个 Document元素与 Document 一一对应。模式的选择直接影响下游切分与检索的粒度文件内容较短、希望保持整篇完整语义时默认的one-doc-per-file最省事文件较长、需要按页做粗粒度切分或对齐页码信息时one-doc-per-page更合适需要按标题、段落、表格等元素级粒度分别处理例如后续做元素级检索或结构化重建时one-doc-per-element提供最大灵活性。拼接多个元素时各元素之间使用separator参数分隔默认值为\n\n空行以保证拼接后的文本保留元素间的自然段落边界。构造参数详解UnstructuredFileConverter.__init__的完整签名如下def __init__(api_url: str UNSTRUCTURED_HOSTED_API_URL, api_key: Secret | None Secret.from_env_var( UNSTRUCTURED_API_KEY, strictFalse), document_creation_mode: Literal[ one-doc-per-file, one-doc-per-page, one-doc-per-element] one-doc-per-file, separator: str \n\n, unstructured_kwargs: dict[str, Any] | None None, progress_bar: bool True)各参数含义与使用要点参数类型默认值说明api_urlstr托管版 URLUnstructured API 地址。默认指向托管版本地部署时需显式指定如http://localhost:8000/general/v0/generalapi_keySecret \| None读取UNSTRUCTURED_API_KEY非严格API Key可显式传入或通过环境变量提供推荐。本地部署时无需提供document_creation_modeLiteralone-doc-per-file元素到 Document 的组装模式见上文三种模式separatorstr\n\n拼接元素时使用的分隔符unstructured_kwargsdict[str, Any] \| NoneNone透传给 Unstructured API 的额外参数如strategy、languages、coordinates等可用参数以 Unstructured API 参数文档为准progress_barboolTrue转换过程中是否显示进度条值得注意的两点设计api_key使用Secret类型与 Haystack 整体的密钥管理规范一致支持Secret.from_env_var从环境变量惰性读取避免密钥出现在序列化结果与日志中unstructured_kwargs是透传通道它让组件保持精简的同时把策略选择如strategyhi_res处理复杂版面、语言指定、坐标输出等 Unstructured 能力全部开放给使用者无需为每个参数单独建模。run()输入输出契约与边界行为component.output_types(documentslist[Document]) def run( paths: list[str] | list[os.PathLike], meta: dict[str, Any] | list[dict[str, Any]] | None None ) - dict[str, list[Document]]paths文件与目录的混合输入paths接收文件路径或目录路径的列表且文件与目录可以混合路径指向文件时转换该文件路径指向目录时转换目录下的所有文件但忽略子目录不递归。meta元数据的两种注入方式meta参数用于给生成的 Document 附加元数据支持两种形态单个字典该字典的内容会添加到所有生成 Document 的meta中适用于批量文件共享同一批元数据如来源、批次号的场景字典列表列表长度必须与paths长度一致两者按顺序一一对应zip后分别注入对应文件产生的 Document。边界约束如果paths中包含目录则meta只能是单个字典所有文件共享同一元数据。若此时传入列表run()会抛出ValueError。这是因为目录会被展开为多个未知数量的文件无法与固定长度的meta列表对齐。返回值run()返回包含单个键的字典documentslist[Document]即转换产生的 Haystack Document 列表可直接作为下游组件的输入。从component.output_types(documentslist[Document])装饰器可以看出该组件严格遵守 Haystack 的组件协议Component Protocol声明式输出类型、统一的run()入口因此可以无缝接入Pipeline的add_component/connect机制被其他组件或 Agent 工具调用。实战用法独立使用import os from haystack_integrations.components.converters.unstructured import ( UnstructuredFileConverter, ) # 确保已设置环境变量 UNSTRUCTURED_API_KEY converter UnstructuredFileConverter() documents converter.run(paths[a/file/path.pdf, a/directory/path])[documents]在索引管道中使用将转换器与DocumentWriter组合即可完成从文件到文档存储的完整入库import os from haystack import Pipeline from haystack.components.writers import DocumentWriter from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack_integrations.components.converters.unstructured import ( UnstructuredFileConverter, ) document_store InMemoryDocumentStore() indexing Pipeline() indexing.add_component(converter, UnstructuredFileConverter()) indexing.add_component(writer, DocumentWriter(document_store)) indexing.connect(converter, writer) indexing.run({converter: {paths: [a/file/path.pdf, a/directory/path]}})管道将converter输出的documents自动送入writer写入文档存储之后即可衔接 Embedder 与 Retriever 构建检索链路。在真实索引管道中通常还会在转换器与 Writer 之间插入切分器如DocumentSplitter与嵌入组件而UnstructuredFileConverter始终位于最前端的文件→文本阶段。通过 Docker 本地部署如果希望文件内容完全不出本地环境、或需要避免托管版的使用限制可以本地运行 Unstructured APIdocker run -p 8000:8000 -d --rm --name unstructured-api quay.io/unstructured-io/unstructured-api:latest --port 8000 --host 0.0.0.0容器启动后初始化组件时指定 localhost 地址即可此时无需 API Keyfrom haystack_integrations.components.converters.unstructured import ( UnstructuredFileConverter, ) converter UnstructuredFileConverter( api_urlhttp://localhost:8000/general/v0/general, )同样地也可以把本地 API 与document_creation_mode、unstructured_kwargs组合使用获得完全可控的本地 ETL 能力。序列化支持to_dict 与 from_dict与 Haystack 所有组件一样UnstructuredFileConverter实现了标准的序列化接口使管道可以被保存为 YAML/JSON 并在其他环境中重建to_dict() - dict[str, Any]把组件序列化为字典。序列化时会保留api_url、document_creation_mode、separator、unstructured_kwargs、progress_bar等配置api_key作为Secret类型以环境变量引用方式处理不会把明文密钥写入序列化结果from_dict(cls, data) - UnstructuredFileConverter类方法从字典反序列化重建组件实例。这意味着你可以把包含该转换器的整个索引管道导出为 YAML 文件通过 Haystack 的 Pipeline 反序列化机制在 CI、生产环境或其他团队成员的机器上复现同一套配置保证不同环境间的解析行为一致。注意事项与最佳实践API Key 严格区分层级免费版与付费版的 Key 不能互换配置前先确认自己所属的层级并对应填写正确的 API URL。目录输入与meta列表互斥只要paths中包含目录meta就必须是单个字典否则run()抛ValueError。需要按文件注入不同元数据时请使用文件路径列表。模式选择决定下游粒度默认one-doc-per-file适合短文档长文档建议one-doc-per-page以便与页码对齐元素级处理需求选用one-doc-per-element。三种模式配合separator可以精细控制拼接后的文本形态。本地部署免除密钥与网络依赖Docker 一条命令即可启动本地 Unstructured API适合数据敏感或需要离线解析的场景本地模式下api_key无需设置。unstructured_kwargs是能力扩展口复杂版面、多语言、坐标信息等高级解析需求通过该参数透传保持组件 API 简洁的同时不损失 Unstructured 的完整功能。放在索引管道最前端该转换器输出的是未切分、未嵌入的原始 Document最佳位置是管道开头、PreProcessors 之前让后续组件按统一节奏处理。结合 Converters 总览 可以看到Haystack 还提供了 PyPDFToDocument、DOCXToDocument、CSVToDocument 等单格式本地转换器以及 AzureDocumentIntelligenceConverter、DoclingConverter 等云端/服务化方案。当你的数据源横跨多种格式、又希望以统一 API 方式维护解析能力时UnstructuredFileConverter是覆盖面最广、接入成本最低的选择之一。【免费下载链接】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），仅供参考 
长河君 · 2026/9/12 18:29:28 · 阅读 1.2k Haystack 集成指南：使用 UnstructuredFileConverter 将多格式文档转换为 Document
Haystack 集成指南使用 UnstructuredFileConverter 将多格式文档转换为 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 官方 Unstructured 集成的核心组件UnstructuredFileConverter展开讲解如何借助 Unstructured API托管版或本地 Docker 部署把 PDF、Word、PPT、Excel 等海量格式的文件统一转换为 Haystack Document从而接入 RAG 与 Agent 应用的索引管道。读完本文你将掌握该组件的安装方式、三种文档创建模式、全部构造参数与run()输入输出契约并能独立完成从原始文件到可直接写入 Document Store 的文档的完整链路搭建。组件定位为什么需要 UnstructuredFileConverter在 Haystack 中Converters 负责把各种格式的文件抽取为统一的 Document 结构是索引管道的起点。UnstructuredFileConverter是其中覆盖面最广的转换器之一它并不在本地解析每种格式而是把文件交给 Unstructured API 处理。Unstructured 提供了一套面向 LLM 的 ETLExtract-Transform-Load工具链能够从数量庞大的文件格式中抽取文本及结构化信息。UnstructuredFileConverter以 API 调用的方式接入这套能力因此不需要在本地为每种格式安装解析依赖——只需维护一个 API 端点即可获得统一的多格式解析结果。该集成组件在 平台组件总览 中被标记为 ✅ Available用户指南与 API 参考分别位于 UnstructuredFileConverter 用户指南 与 Unstructured API 参考。从管道编排上看它最常见的放置位置是索引管道的最开头位于 PreProcessors 之前。这样后面接DocumentSplitter、DocumentWriter等组件即可形成完整的数据入库流水线。该组件的包名为unstructured-fileconverter-haystack属于 Haystack 官方维护的 core-integrations 生态。安装与 API 准备安装集成包pip install unstructured-fileconverter-haystack安装后即可从haystack_integrations.components.converters.unstructured导入组件from haystack_integrations.components.converters.unstructured import UnstructuredFileConverter两种托管服务模式Unstructured API 分为免费版与付费版两个层级层级API URL说明Free Unstructured APIhttps://api.unstructured.io/general/v0/general免费但存在一定的使用限制Unstructured Serverless API付费开通后在 Unstructured 账户中获取专属 URL完整功能的付费版本⚠️ 免费版与付费版的 API Key不同不能互换使用。无论使用哪个层级官方都推荐把 API Key 放在环境变量UNSTRUCTURED_API_KEY中export UNSTRUCTURED_API_KEYyour_api_key环境变量方式也是UnstructuredFileConverter的默认行为——api_key参数默认从UNSTRUCTURED_API_KEY读取strictFalse即未设置时不报错。这样既避免了把密钥硬编码进代码也方便在 CI/CD 或容器环境中统一注入。三种文档创建模式元素到 Document 的映射策略Unstructured API 的解析结果是一组元素elements。UnstructuredFileConverter通过document_creation_mode参数控制这些元素如何被组装成 Haystack Document共三种模式one-doc-per-file默认每个文件生成一个 Document文件内的所有元素按顺序拼接进同一个text字段one-doc-per-page每页生成一个 Document同一页上的所有元素拼接进该页 Document 的text字段one-doc-per-element每个元素单独生成一个 Document元素与 Document 一一对应。模式的选择直接影响下游切分与检索的粒度文件内容较短、希望保持整篇完整语义时默认的one-doc-per-file最省事文件较长、需要按页做粗粒度切分或对齐页码信息时one-doc-per-page更合适需要按标题、段落、表格等元素级粒度分别处理例如后续做元素级检索或结构化重建时one-doc-per-element提供最大灵活性。拼接多个元素时各元素之间使用separator参数分隔默认值为\n\n空行以保证拼接后的文本保留元素间的自然段落边界。构造参数详解UnstructuredFileConverter.__init__的完整签名如下def __init__(api_url: str UNSTRUCTURED_HOSTED_API_URL, api_key: Secret | None Secret.from_env_var( UNSTRUCTURED_API_KEY, strictFalse), document_creation_mode: Literal[ one-doc-per-file, one-doc-per-page, one-doc-per-element] one-doc-per-file, separator: str \n\n, unstructured_kwargs: dict[str, Any] | None None, progress_bar: bool True)各参数含义与使用要点参数类型默认值说明api_urlstr托管版 URLUnstructured API 地址。默认指向托管版本地部署时需显式指定如http://localhost:8000/general/v0/generalapi_keySecret \| None读取UNSTRUCTURED_API_KEY非严格API Key可显式传入或通过环境变量提供推荐。本地部署时无需提供document_creation_modeLiteralone-doc-per-file元素到 Document 的组装模式见上文三种模式separatorstr\n\n拼接元素时使用的分隔符unstructured_kwargsdict[str, Any] \| NoneNone透传给 Unstructured API 的额外参数如strategy、languages、coordinates等可用参数以 Unstructured API 参数文档为准progress_barboolTrue转换过程中是否显示进度条值得注意的两点设计api_key使用Secret类型与 Haystack 整体的密钥管理规范一致支持Secret.from_env_var从环境变量惰性读取避免密钥出现在序列化结果与日志中unstructured_kwargs是透传通道它让组件保持精简的同时把策略选择如strategyhi_res处理复杂版面、语言指定、坐标输出等 Unstructured 能力全部开放给使用者无需为每个参数单独建模。run()输入输出契约与边界行为component.output_types(documentslist[Document]) def run( paths: list[str] | list[os.PathLike], meta: dict[str, Any] | list[dict[str, Any]] | None None ) - dict[str, list[Document]]paths文件与目录的混合输入paths接收文件路径或目录路径的列表且文件与目录可以混合路径指向文件时转换该文件路径指向目录时转换目录下的所有文件但忽略子目录不递归。meta元数据的两种注入方式meta参数用于给生成的 Document 附加元数据支持两种形态单个字典该字典的内容会添加到所有生成 Document 的meta中适用于批量文件共享同一批元数据如来源、批次号的场景字典列表列表长度必须与paths长度一致两者按顺序一一对应zip后分别注入对应文件产生的 Document。边界约束如果paths中包含目录则meta只能是单个字典所有文件共享同一元数据。若此时传入列表run()会抛出ValueError。这是因为目录会被展开为多个未知数量的文件无法与固定长度的meta列表对齐。返回值run()返回包含单个键的字典documentslist[Document]即转换产生的 Haystack Document 列表可直接作为下游组件的输入。从component.output_types(documentslist[Document])装饰器可以看出该组件严格遵守 Haystack 的组件协议Component Protocol声明式输出类型、统一的run()入口因此可以无缝接入Pipeline的add_component/connect机制被其他组件或 Agent 工具调用。实战用法独立使用import os from haystack_integrations.components.converters.unstructured import ( UnstructuredFileConverter, ) # 确保已设置环境变量 UNSTRUCTURED_API_KEY converter UnstructuredFileConverter() documents converter.run(paths[a/file/path.pdf, a/directory/path])[documents]在索引管道中使用将转换器与DocumentWriter组合即可完成从文件到文档存储的完整入库import os from haystack import Pipeline from haystack.components.writers import DocumentWriter from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack_integrations.components.converters.unstructured import ( UnstructuredFileConverter, ) document_store InMemoryDocumentStore() indexing Pipeline() indexing.add_component(converter, UnstructuredFileConverter()) indexing.add_component(writer, DocumentWriter(document_store)) indexing.connect(converter, writer) indexing.run({converter: {paths: [a/file/path.pdf, a/directory/path]}})管道将converter输出的documents自动送入writer写入文档存储之后即可衔接 Embedder 与 Retriever 构建检索链路。在真实索引管道中通常还会在转换器与 Writer 之间插入切分器如DocumentSplitter与嵌入组件而UnstructuredFileConverter始终位于最前端的文件→文本阶段。通过 Docker 本地部署如果希望文件内容完全不出本地环境、或需要避免托管版的使用限制可以本地运行 Unstructured APIdocker run -p 8000:8000 -d --rm --name unstructured-api quay.io/unstructured-io/unstructured-api:latest --port 8000 --host 0.0.0.0容器启动后初始化组件时指定 localhost 地址即可此时无需 API Keyfrom haystack_integrations.components.converters.unstructured import ( UnstructuredFileConverter, ) converter UnstructuredFileConverter( api_urlhttp://localhost:8000/general/v0/general, )同样地也可以把本地 API 与document_creation_mode、unstructured_kwargs组合使用获得完全可控的本地 ETL 能力。序列化支持to_dict 与 from_dict与 Haystack 所有组件一样UnstructuredFileConverter实现了标准的序列化接口使管道可以被保存为 YAML/JSON 并在其他环境中重建to_dict() - dict[str, Any]把组件序列化为字典。序列化时会保留api_url、document_creation_mode、separator、unstructured_kwargs、progress_bar等配置api_key作为Secret类型以环境变量引用方式处理不会把明文密钥写入序列化结果from_dict(cls, data) - UnstructuredFileConverter类方法从字典反序列化重建组件实例。这意味着你可以把包含该转换器的整个索引管道导出为 YAML 文件通过 Haystack 的 Pipeline 反序列化机制在 CI、生产环境或其他团队成员的机器上复现同一套配置保证不同环境间的解析行为一致。注意事项与最佳实践API Key 严格区分层级免费版与付费版的 Key 不能互换配置前先确认自己所属的层级并对应填写正确的 API URL。目录输入与meta列表互斥只要paths中包含目录meta就必须是单个字典否则run()抛ValueError。需要按文件注入不同元数据时请使用文件路径列表。模式选择决定下游粒度默认one-doc-per-file适合短文档长文档建议one-doc-per-page以便与页码对齐元素级处理需求选用one-doc-per-element。三种模式配合separator可以精细控制拼接后的文本形态。本地部署免除密钥与网络依赖Docker 一条命令即可启动本地 Unstructured API适合数据敏感或需要离线解析的场景本地模式下api_key无需设置。unstructured_kwargs是能力扩展口复杂版面、多语言、坐标信息等高级解析需求通过该参数透传保持组件 API 简洁的同时不损失 Unstructured 的完整功能。放在索引管道最前端该转换器输出的是未切分、未嵌入的原始 Document最佳位置是管道开头、PreProcessors 之前让后续组件按统一节奏处理。结合 Converters 总览 可以看到Haystack 还提供了 PyPDFToDocument、DOCXToDocument、CSVToDocument 等单格式本地转换器以及 AzureDocumentIntelligenceConverter、DoclingConverter 等云端/服务化方案。当你的数据源横跨多种格式、又希望以统一 API 方式维护解析能力时UnstructuredFileConverter是覆盖面最广、接入成本最低的选择之一。【免费下载链接】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），仅供参考