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）；
输出：documents（list[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 API
- API URL：https://api.unstructured.io/general/v0/general
- 免费使用，但带有一定的调用限制（限流、功能裁剪等）。
Unstructured Serverless API
- 付费完整版，注册后可在 Unstructured 账号中获取专属的 API URL。

❗️ 注意：免费版与付费版的 API Key互不通用，不能混用。

环境变量配置 API Key

无论选择哪个层级，官方都推荐把 API Key 放到环境变量UNSTRUCTURED_API_KEY中：

export UNSTRUCTURED_API_KEY=your_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", strict=False), 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_url`	`str`，默认指向托管版 URL	Unstructured API 的地址。默认使用托管版本；若本地运行 API，则改为本地地址（如`http://localhost:8000/general/v0/general`）。
`api_key`	`Secret \\| None`，默认从环境变量`UNSTRUCTURED_API_KEY`读取（`strict=False`）	Unstructured API 密钥。可显式传入，也可（推荐）通过环境变量读取；本地运行时无需提供。
`document_creation_mode`	`Literal`，默认`"one-doc-per-file"`	决定如何由 Unstructured 返回的 elements 生成 Haystack Document，详见下文“三种文档创建模式”。
`separator`	`str`，默认`"\n\n"`	将多个 element 拼接进同一文本字段时使用的分隔符。
`unstructured_kwargs`	`dict[str, Any] \\| None`	透传给 Unstructured API 的额外参数（如`strategy`、`languages`、`coordinates`等），完整参数清单见 Unstructured 官方 API 参数文档。
`progress_bar`	`bool`，默认`True`	转换过程中是否显示进度条。

值得关注的是api_key的默认实现：Secret.from_env_var("UNSTRUCTURED_API_KEY", strict=False)意味着即使环境变量未设置也不会报错——因为本地 API 场景本就不需要密钥。这与当前 Haystack 主仓库中其他组件“优先从环境变量读取密钥、必要时再显式注入”的安全实践一致，例如 TextFileToDocument 的做法。

三种文档创建模式

document_creation_mode是决定输出粒度的关键参数，共三种取值：

"one-doc-per-file"（默认）：每个文件生成一个 HaystackDocument，文件内所有 elements 被拼接进同一个文本字段；
"one-doc-per-page"：每个页面生成一个Document，同一页的所有 elements 拼接为一个文本字段；
"one-doc-per-element"：每个 element 生成一个Document，Unstructured 返回的每一个元素（段落、标题、表格等）都独立成文。

选择建议：one-doc-per-file适合整体性较强的文档（如整篇报告），one-doc-per-page适合后续按页检索的场景（如论文、书籍扫描件），one-doc-per-element则保留了最细粒度的结构化信息，便于下游按元素级别定位引用。三种模式配合separator控制拼接分隔符（默认\n\n），可以灵活平衡文档粒度与检索单元大小。

run 方法与元数据注入规则

run方法是组件的执行入口，其签名如下（来自集成 API 参考）：

@component.output_types(documents=list[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_url="http://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_url="http://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之间选择，避免过度切碎导致上下文割裂，或粒度过粗导致检索单元过大。

企业官网建设流程全解析