Haystack UnstructuredFileConverter 实战指南借助 Unstructured API 完成多格式文件的文档化转换【免费下载链接】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 生态中的UnstructuredFileConverter组件展开讲解如何借助 Unstructured 提供的 ETL 服务托管版或本地 Docker 部署版将 PDF、Office、HTML、邮件等大量异构格式的文件批量转换为 HaystackDocument。读完本文你将掌握该组件的安装、初始化参数、三种文档切分模式、独立运行与管道集成方式以及元数据meta注入的完整规则可直接用于搭建 RAG 或语义搜索的索引管道。组件概览UnstructuredFileConverter 是什么UnstructuredFileConverter是 Haystack 集成生态中用于把文件和目录转换为 HaystackDocument的转换组件。它本身不直接解析文件而是把解析工作交给 Unstructured API 完成输入文件路径或目录路径paths输出documentslist[Document]。从 组件用户指南 中的位置说明可以看到它在索引管道中最常见的位置是预处理PreProcessors之前、索引管道的最开头负责把原始文件统一成结构化的Document为后续的清洗、切分、嵌入与写入环节铺路。Unstructured 本身定位为“面向 LLM 的 ETL”工具官方文档强调它能从极其广泛的文件格式中抽取文本与附加信息。因此与只能处理单一格式的TextFileToDocument、PyPDFToDocument等转换器不同UnstructuredFileConverter的核心价值在于一份代码统一处理多种格式尤其适合格式繁杂、难以逐一编写解析逻辑的批量文件场景。需要说明该组件由独立的unstructured-fileconverter-haystack集成包提供源码托管在 deepset-ai 的 haystack-core-integrations 仓库不在当前 haystack 主仓库内安装后以haystack_integrations.components.converters.unstructured命名空间导入。安装与 API 接入方式安装集成包使用UnstructuredFileConverter前需要先安装对应的集成包pip install unstructured-fileconverter-haystack安装完成后即可从haystack_integrations.components.converters.unstructured导入组件。两种 API 服务层级Unstructured API 分为免费版与付费版两种Free Unstructured APIAPI URLhttps://api.unstructured.io/general/v0/general免费使用但带有一定的调用限制限流、功能裁剪等。Unstructured Serverless API付费完整版注册后可在 Unstructured 账号中获取专属的 API URL。❗️ 注意免费版与付费版的 API Key互不通用不能混用。环境变量配置 API Key无论选择哪个层级官方都推荐把 API Key 放到环境变量UNSTRUCTURED_API_KEY中export UNSTRUCTURED_API_KEYyour_api_key组件初始化时默认会从这个环境变量读取密钥见下方构造参数中api_key的默认值这样既能避免把密钥硬编码进代码也便于在不同环境间复用配置。构造参数详解API 引用层面根据 version-2.22 集成 API 参考组件的完整构造签名如下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 的地址。默认使用托管版本若本地运行 API则改为本地地址如http://localhost:8000/general/v0/general。api_keySecret \| None默认从环境变量UNSTRUCTURED_API_KEY读取strictFalseUnstructured API 密钥。可显式传入也可推荐通过环境变量读取本地运行时无需提供。document_creation_modeLiteral默认one-doc-per-file决定如何由 Unstructured 返回的 elements 生成 Haystack Document详见下文“三种文档创建模式”。separatorstr默认\n\n将多个 element 拼接进同一文本字段时使用的分隔符。unstructured_kwargsdict[str, Any] \| None透传给 Unstructured API 的额外参数如strategy、languages、coordinates等完整参数清单见 Unstructured 官方 API 参数文档。progress_barbool默认True转换过程中是否显示进度条。值得关注的是api_key的默认实现Secret.from_env_var(UNSTRUCTURED_API_KEY, strictFalse)意味着即使环境变量未设置也不会报错——因为本地 API 场景本就不需要密钥。这与当前 Haystack 主仓库中其他组件“优先从环境变量读取密钥、必要时再显式注入”的安全实践一致例如 TextFileToDocument 的做法。三种文档创建模式document_creation_mode是决定输出粒度的关键参数共三种取值one-doc-per-file默认每个文件生成一个 HaystackDocument文件内所有 elements 被拼接进同一个文本字段one-doc-per-page每个页面生成一个Document同一页的所有 elements 拼接为一个文本字段one-doc-per-element每个 element 生成一个DocumentUnstructured 返回的每一个元素段落、标题、表格等都独立成文。选择建议one-doc-per-file适合整体性较强的文档如整篇报告one-doc-per-page适合后续按页检索的场景如论文、书籍扫描件one-doc-per-element则保留了最细粒度的结构化信息便于下游按元素级别定位引用。三种模式配合separator控制拼接分隔符默认\n\n可以灵活平衡文档粒度与检索单元大小。run 方法与元数据注入规则run方法是组件的执行入口其签名如下来自 集成 API 参考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待转换的路径列表元素可以是文件也可以是目录。若传入目录则目录下的所有文件都会被转换但子目录会被忽略不会递归深入。meta可选附加到Document的元数据。取值分两种情况单个字典其内容会附加到本次生成的所有Document上字典列表列表长度必须与paths数量一致二者按位置一一对应zip绑定。限制如果paths中包含目录meta只能传单个字典因为目录展开后的文件数量不确定无法与列表一一对应。异常当meta是列表而paths中含有目录时抛出ValueError。返回结果返回值是一个字典仅含一个键documents转换得到的 HaystackDocument列表。元数据规则与源码印证meta的“单个字典复制给所有文档、列表按位置 zip、长度不匹配报错”这套行为在 Haystack 主仓库的转换器基础设施中有对应的实现佐证normalize_metadata 会把meta统一规范化为与来源数量等长的字典列表——None时生成等长的空字典列表、单个字典时对每个来源做深拷贝避免下游修改互相污染、列表时校验长度并原样返回。UnstructuredFileConverter 作为转换器家族的一员遵循同样的元数据约定这保证了它在管道中的行为与其它转换器一致、可预期。实战用法独立使用最简单的用法是直接构造组件并调用run此时需已设置UNSTRUCTURED_API_KEY环境变量from haystack_integrations.components.converters.unstructured import UnstructuredFileConverter converter UnstructuredFileConverter() documents converter.run(paths[a/file/path.pdf, a/directory/path])[documents]这里paths同时传入了单个 PDF 文件与一个目录目录内所有文件都会被一并转换。若在本地运行 Unstructured API则显式指定本地地址参考 用户指南from haystack_integrations.components.converters.unstructured import UnstructuredFileConverter converter UnstructuredFileConverter( api_urlhttp://localhost:8000/general/v0/general, )此时无需 API Key。在索引管道中使用更常见的做法是把转换器接进索引管道转换结果直接交给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]}})管道中转换器的输出documents直接连到writer的输入完成“文件 → Document → 文档存储”的索引闭环。如果需要进一步清洗与切分可以在 converter 与 writer 之间插入 PreProcessor 组件——这正是用户指南所标注的“位于 PreProcessors 之前”的典型位置。本地 Docker 部署不想把文件内容发送到云端、或有数据合规要求时可以本地启动 Unstructured API 容器docker run -p 8000:8000 -d --rm --name unstructured-api quay.io/unstructured-io/unstructured-api:latest --port 8000 --host 0.0.0.0容器启动后组件指向本地端点即可from haystack_integrations.components.converters.unstructured import ( UnstructuredFileConverter, ) converter UnstructuredFileConverter( api_urlhttp://localhost:8000/general/v0/general, )本地模式免去了 API Key 配置文件数据不出本机适合对隐私敏感的内部文档处理场景。使用建议与注意事项密钥管理优先通过环境变量UNSTRUCTURED_API_KEY提供密钥并注意免费/付费 Key 不可混用本地 Docker 模式无需密钥。目录转换行为传入目录时只转换顶层文件、忽略子目录需要递归处理嵌套目录时请自行展开路径列表。元数据绑定多文件批量转换时若需逐文件差异化元数据务必让meta列表长度与paths一致一旦路径列表里混入目录meta只能退化为单个字典否则会触发ValueError。参数透传Unstructured 的解析策略如strategy、语言languages等通过unstructured_kwargs透传不必等待组件升级即可使用 Unstructured 的新能力。输出粒度根据下游检索与切分需求在one-doc-per-file、one-doc-per-page、one-doc-per-element之间选择避免过度切碎导致上下文割裂或粒度过粗导致检索单元过大。延伸阅读组件用户指南docs-website/docs/pipeline-components/converters/unstructuredfileconverter.mdx完整 API 参考version-2.22docs-website/reference_versioned_docs/version-2.22/integrations-api/unstructured.md转换器总览docs-website/docs/pipeline-components/converters.mdx元数据规范化基础设施源码haystack/components/converters/utils.py同为转换器家族的TextFileToDocument实现haystack/components/converters/txt.py【免费下载链接】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），仅供参考 Haystack UnstructuredFileConverter 实战指南：借助 Unstructured API 完成多格式文件的文档化转换
Haystack UnstructuredFileConverter 实战指南借助 Unstructured API 完成多格式文件的文档化转换【免费下载链接】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 生态中的UnstructuredFileConverter组件展开讲解如何借助 Unstructured 提供的 ETL 服务托管版或本地 Docker 部署版将 PDF、Office、HTML、邮件等大量异构格式的文件批量转换为 HaystackDocument。读完本文你将掌握该组件的安装、初始化参数、三种文档切分模式、独立运行与管道集成方式以及元数据meta注入的完整规则可直接用于搭建 RAG 或语义搜索的索引管道。组件概览UnstructuredFileConverter 是什么UnstructuredFileConverter是 Haystack 集成生态中用于把文件和目录转换为 HaystackDocument的转换组件。它本身不直接解析文件而是把解析工作交给 Unstructured API 完成输入文件路径或目录路径paths输出documentslist[Document]。从 组件用户指南 中的位置说明可以看到它在索引管道中最常见的位置是预处理PreProcessors之前、索引管道的最开头负责把原始文件统一成结构化的Document为后续的清洗、切分、嵌入与写入环节铺路。Unstructured 本身定位为“面向 LLM 的 ETL”工具官方文档强调它能从极其广泛的文件格式中抽取文本与附加信息。因此与只能处理单一格式的TextFileToDocument、PyPDFToDocument等转换器不同UnstructuredFileConverter的核心价值在于一份代码统一处理多种格式尤其适合格式繁杂、难以逐一编写解析逻辑的批量文件场景。需要说明该组件由独立的unstructured-fileconverter-haystack集成包提供源码托管在 deepset-ai 的 haystack-core-integrations 仓库不在当前 haystack 主仓库内安装后以haystack_integrations.components.converters.unstructured命名空间导入。安装与 API 接入方式安装集成包使用UnstructuredFileConverter前需要先安装对应的集成包pip install unstructured-fileconverter-haystack安装完成后即可从haystack_integrations.components.converters.unstructured导入组件。两种 API 服务层级Unstructured API 分为免费版与付费版两种Free Unstructured APIAPI URLhttps://api.unstructured.io/general/v0/general免费使用但带有一定的调用限制限流、功能裁剪等。Unstructured Serverless API付费完整版注册后可在 Unstructured 账号中获取专属的 API URL。❗️ 注意免费版与付费版的 API Key互不通用不能混用。环境变量配置 API Key无论选择哪个层级官方都推荐把 API Key 放到环境变量UNSTRUCTURED_API_KEY中export UNSTRUCTURED_API_KEYyour_api_key组件初始化时默认会从这个环境变量读取密钥见下方构造参数中api_key的默认值这样既能避免把密钥硬编码进代码也便于在不同环境间复用配置。构造参数详解API 引用层面根据 version-2.22 集成 API 参考组件的完整构造签名如下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 的地址。默认使用托管版本若本地运行 API则改为本地地址如http://localhost:8000/general/v0/general。api_keySecret \| None默认从环境变量UNSTRUCTURED_API_KEY读取strictFalseUnstructured API 密钥。可显式传入也可推荐通过环境变量读取本地运行时无需提供。document_creation_modeLiteral默认one-doc-per-file决定如何由 Unstructured 返回的 elements 生成 Haystack Document详见下文“三种文档创建模式”。separatorstr默认\n\n将多个 element 拼接进同一文本字段时使用的分隔符。unstructured_kwargsdict[str, Any] \| None透传给 Unstructured API 的额外参数如strategy、languages、coordinates等完整参数清单见 Unstructured 官方 API 参数文档。progress_barbool默认True转换过程中是否显示进度条。值得关注的是api_key的默认实现Secret.from_env_var(UNSTRUCTURED_API_KEY, strictFalse)意味着即使环境变量未设置也不会报错——因为本地 API 场景本就不需要密钥。这与当前 Haystack 主仓库中其他组件“优先从环境变量读取密钥、必要时再显式注入”的安全实践一致例如 TextFileToDocument 的做法。三种文档创建模式document_creation_mode是决定输出粒度的关键参数共三种取值one-doc-per-file默认每个文件生成一个 HaystackDocument文件内所有 elements 被拼接进同一个文本字段one-doc-per-page每个页面生成一个Document同一页的所有 elements 拼接为一个文本字段one-doc-per-element每个 element 生成一个DocumentUnstructured 返回的每一个元素段落、标题、表格等都独立成文。选择建议one-doc-per-file适合整体性较强的文档如整篇报告one-doc-per-page适合后续按页检索的场景如论文、书籍扫描件one-doc-per-element则保留了最细粒度的结构化信息便于下游按元素级别定位引用。三种模式配合separator控制拼接分隔符默认\n\n可以灵活平衡文档粒度与检索单元大小。run 方法与元数据注入规则run方法是组件的执行入口其签名如下来自 集成 API 参考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待转换的路径列表元素可以是文件也可以是目录。若传入目录则目录下的所有文件都会被转换但子目录会被忽略不会递归深入。meta可选附加到Document的元数据。取值分两种情况单个字典其内容会附加到本次生成的所有Document上字典列表列表长度必须与paths数量一致二者按位置一一对应zip绑定。限制如果paths中包含目录meta只能传单个字典因为目录展开后的文件数量不确定无法与列表一一对应。异常当meta是列表而paths中含有目录时抛出ValueError。返回结果返回值是一个字典仅含一个键documents转换得到的 HaystackDocument列表。元数据规则与源码印证meta的“单个字典复制给所有文档、列表按位置 zip、长度不匹配报错”这套行为在 Haystack 主仓库的转换器基础设施中有对应的实现佐证normalize_metadata 会把meta统一规范化为与来源数量等长的字典列表——None时生成等长的空字典列表、单个字典时对每个来源做深拷贝避免下游修改互相污染、列表时校验长度并原样返回。UnstructuredFileConverter 作为转换器家族的一员遵循同样的元数据约定这保证了它在管道中的行为与其它转换器一致、可预期。实战用法独立使用最简单的用法是直接构造组件并调用run此时需已设置UNSTRUCTURED_API_KEY环境变量from haystack_integrations.components.converters.unstructured import UnstructuredFileConverter converter UnstructuredFileConverter() documents converter.run(paths[a/file/path.pdf, a/directory/path])[documents]这里paths同时传入了单个 PDF 文件与一个目录目录内所有文件都会被一并转换。若在本地运行 Unstructured API则显式指定本地地址参考 用户指南from haystack_integrations.components.converters.unstructured import UnstructuredFileConverter converter UnstructuredFileConverter( api_urlhttp://localhost:8000/general/v0/general, )此时无需 API Key。在索引管道中使用更常见的做法是把转换器接进索引管道转换结果直接交给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]}})管道中转换器的输出documents直接连到writer的输入完成“文件 → Document → 文档存储”的索引闭环。如果需要进一步清洗与切分可以在 converter 与 writer 之间插入 PreProcessor 组件——这正是用户指南所标注的“位于 PreProcessors 之前”的典型位置。本地 Docker 部署不想把文件内容发送到云端、或有数据合规要求时可以本地启动 Unstructured API 容器docker run -p 8000:8000 -d --rm --name unstructured-api quay.io/unstructured-io/unstructured-api:latest --port 8000 --host 0.0.0.0容器启动后组件指向本地端点即可from haystack_integrations.components.converters.unstructured import ( UnstructuredFileConverter, ) converter UnstructuredFileConverter( api_urlhttp://localhost:8000/general/v0/general, )本地模式免去了 API Key 配置文件数据不出本机适合对隐私敏感的内部文档处理场景。使用建议与注意事项密钥管理优先通过环境变量UNSTRUCTURED_API_KEY提供密钥并注意免费/付费 Key 不可混用本地 Docker 模式无需密钥。目录转换行为传入目录时只转换顶层文件、忽略子目录需要递归处理嵌套目录时请自行展开路径列表。元数据绑定多文件批量转换时若需逐文件差异化元数据务必让meta列表长度与paths一致一旦路径列表里混入目录meta只能退化为单个字典否则会触发ValueError。参数透传Unstructured 的解析策略如strategy、语言languages等通过unstructured_kwargs透传不必等待组件升级即可使用 Unstructured 的新能力。输出粒度根据下游检索与切分需求在one-doc-per-file、one-doc-per-page、one-doc-per-element之间选择避免过度切碎导致上下文割裂或粒度过粗导致检索单元过大。延伸阅读组件用户指南docs-website/docs/pipeline-components/converters/unstructuredfileconverter.mdx完整 API 参考version-2.22docs-website/reference_versioned_docs/version-2.22/integrations-api/unstructured.md转换器总览docs-website/docs/pipeline-components/converters.mdx元数据规范化基础设施源码haystack/components/converters/utils.py同为转换器家族的TextFileToDocument实现haystack/components/converters/txt.py【免费下载链接】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），仅供参考