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 的 ETL（Extract-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 API	`https://api.unstructured.io/general/v0/general`	免费，但存在一定的使用限制
Unstructured Serverless API	付费开通后在 Unstructured 账户中获取专属 URL	完整功能的付费版本

⚠️ 免费版与付费版的 API Key不同，不能互换使用。

无论使用哪个层级，官方都推荐把 API Key 放在环境变量UNSTRUCTURED_API_KEY中：

export UNSTRUCTURED_API_KEY=your_api_key

环境变量方式也是UnstructuredFileConverter的默认行为——api_key参数默认从UNSTRUCTURED_API_KEY读取（strict=False，即未设置时不报错）。这样既避免了把密钥硬编码进代码，也方便在 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", 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 地址。默认指向托管版；本地部署时需显式指定，如`"http://localhost:8000/general/v0/general"`
`api_key`	`Secret \\| None`	读取`UNSTRUCTURED_API_KEY`（非严格）	API Key，可显式传入或通过环境变量提供（推荐）。本地部署时无需提供
`document_creation_mode`	`Literal`	`"one-doc-per-file"`	元素到 Document 的组装模式，见上文三种模式
`separator`	`str`	`"\n\n"`	拼接元素时使用的分隔符
`unstructured_kwargs`	`dict[str, Any] \\| None`	`None`	透传给 Unstructured API 的额外参数（如`strategy`、`languages`、`coordinates`等），可用参数以 Unstructured API 参数文档为准
`progress_bar`	`bool`	`True`	转换过程中是否显示进度条

值得注意的两点设计：

api_key使用Secret类型：与 Haystack 整体的密钥管理规范一致，支持Secret.from_env_var从环境变量惰性读取，避免密钥出现在序列化结果与日志中；
unstructured_kwargs是透传通道：它让组件保持精简的同时，把策略选择（如strategy="hi_res"处理复杂版面）、语言指定、坐标输出等 Unstructured 能力全部开放给使用者，无需为每个参数单独建模。

run()：输入输出契约与边界行为

@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：文件与目录的混合输入

paths接收文件路径或目录路径的列表，且文件与目录可以混合：

路径指向文件时，转换该文件；
路径指向目录时，转换目录下的所有文件，但忽略子目录（不递归）。

meta：元数据的两种注入方式

meta参数用于给生成的 Document 附加元数据，支持两种形态：

单个字典：该字典的内容会添加到所有生成 Document 的meta中，适用于批量文件共享同一批元数据（如来源、批次号）的场景；
字典列表：列表长度必须与paths长度一致，两者按顺序一一对应（zip）后分别注入对应文件产生的 Document。

边界约束：如果paths中包含目录，则meta只能是单个字典（所有文件共享同一元数据）。若此时传入列表，run()会抛出ValueError。这是因为目录会被展开为多个未知数量的文件，无法与固定长度的meta列表对齐。

返回值

run()返回包含单个键的字典：

documents：list[Document]，即转换产生的 Haystack Document 列表，可直接作为下游组件的输入。

从@component.output_types(documents=list[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 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

容器启动后，初始化组件时指定 localhost 地址即可（此时无需 API Key）：

from haystack_integrations.components.converters.unstructured import ( UnstructuredFileConverter, ) converter = UnstructuredFileConverter( api_url="http://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是覆盖面最广、接入成本最低的选择之一。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考