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

UnstructuredFileConverter是 Haystack 生态中用于接入 Unstructured ETL 服务的文档转换组件，它把 PDF、DOCX、PPTX、图片等非结构化文件统一转换为 Haystack 的Document对象，是构建 RAG 索引管道（Indexing Pipeline）的常用入口。读完本文，你将掌握该组件的安装方式、三种文档创建模式、全部构造参数与run()输入输出语义，并能在独立脚本和完整 Pipeline 两种场景中落地使用。

组件定位：索引管道中的“文件进、文档出”转换器

UnstructuredFileConverter是 Haystack 集成生态中位于haystack_integrations.components.converters.unstructured模块的转换器组件。在管道中，它最常见的放置位置是索引管道的最前端，或在 PreProcessors 之前——先由它把磁盘上的原始文件批量抽取为Document，再交给后续的文档清理、切分与写入环节。

它的核心工作方式是调用 Unstructured API（云托管版或本地自托管版）完成文本抽取。Unstructured 提供了一系列面向 LLM 的 ETL 工具，能够从海量文件格式中提取文本与结构化信息，而该组件将 API 返回的“元素（elements）”重组为 Haystack 的Document对象，使下游组件（切分器、嵌入器、文档写入器等）无需关心源文件格式差异。

该组件在 Haystack 中对应的 API 参考与使用指南分别位于：

API 参考：Unstructured
使用指南：UnstructuredFileConverter

说明：UnstructuredFileConverter属于独立维护的集成包（安装包名为unstructured-fileconverter-haystack），其实现代码不在本仓库内；本文以本仓库中的 API 参考文档与使用指南为事实主体，并辅以仓库内核心类进行佐证。

安装与运行环境准备

安装集成包

使用pip安装集成包即可获得该组件：

pip install unstructured-fileconverter-haystack

安装完成后，即可从以下路径导入组件：

from haystack_integrations.components.converters.unstructured import UnstructuredFileConverter

选择 API 服务形态

Unstructured API 存在免费与付费两个层级，二者的访问地址与 API Key 均不同，不能混用：

Free Unstructured API（免费版）
- API URL：https://api.unstructured.io/general/v0/general
- 免费可用，但存在一定的调用限制（速率、并发与功能范围受免费额度约束）。
Unstructured Serverless API（Serverless 付费版）
- 在 Unstructured 账号中开通付费版本后，会获得专属的唯一 API URL。
- 属于完整能力层的付费服务。

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

无论选择哪个层级，官方都推荐将 API Key 写入环境变量UNSTRUCTURED_API_KEY，组件默认会从该环境变量读取密钥：

export UNSTRUCTURED_API_KEY=your_api_key

这种做法的好处是密钥不会硬编码进代码或 YAML 配置，也便于在容器、CI 等环境中统一注入。

本地自托管：Docker 方式

如果你不希望数据离开本地环境、或想避免云服务的调用限制，可以用 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

启动后，本地 API 的通用端点地址为http://localhost:8000/general/v0/general。本地运行时不需要 API Key，只需在初始化组件时显式指定本地地址。

基础用法：三种运行场景

1. 独立使用（Standalone）

最小可用示例——不传任何参数时，组件默认访问 Unstructured 托管 API（此时需已配置UNSTRUCTURED_API_KEY环境变量）：

import os from haystack_integrations.components.converters.unstructured import ( UnstructuredFileConverter, ) converter = UnstructuredFileConverter() documents = converter.run(paths=["a/file/path.pdf", "a/directory/path"])["documents"]

paths既可以是单个文件路径，也可以是目录路径；传入目录时，该目录下的所有文件都会被转换。

对应 API 参考中的最短示例（含本地端点注释）：

from haystack_integrations.components.converters.unstructured import UnstructuredFileConverter # 两种准备方式任选其一： # 1) 设置环境变量 UNSTRUCTURED_API_KEY； # 2) 本地运行 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 converter = UnstructuredFileConverter( # api_url="http://localhost:8000/general/v0/general" # <-- 本地运行时取消注释 ) documents = converter.run(paths=["a/file/path.pdf", "a/directory/path"])["documents"]

2. 在 Pipeline 中使用

把转换器接入完整索引管道，转换结果直接流向文档写入器。下面示例构建了一个converter → writer的最小索引管道，将转换后的文档持久化到内存文档库：

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"]}})

这里接入的DocumentWriter是 Haystack 核心库中的标准组件（见 document_writer.py），其run(documents, ...)方法接收list[Document]，与UnstructuredFileConverter输出的documents键正好对接。这也是组件位于索引管道前端的典型原因：转换器的输出类型与下游组件输入完全兼容。

3. 本地 API 模式（With Docker）

若使用本地 Docker 部署的 Unstructured API，只需在初始化时指定本地端点：

from haystack_integrations.components.converters.unstructured import ( UnstructuredFileConverter, ) converter = UnstructuredFileConverter( api_url="http://localhost:8000/general/v0/general", )

构造参数详解

组件构造函数签名如下（取自 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`	`UNSTRUCTURED_HOSTED_API_URL`（托管版地址）	Unstructured API 的 URL。默认指向云端托管版本；本地运行时需显式传入如`"http://localhost:8000/general/v0/general"`。
`api_key`	`Secret \\| None`	从环境变量`UNSTRUCTURED_API_KEY`读取（非严格模式）	调用托管 API 所需的密钥。可显式传入，也推荐通过环境变量注入；本地运行时无需提供。
`document_creation_mode`	`Literal["one-doc-per-file", "one-doc-per-page", "one-doc-per-element"]`	`"one-doc-per-file"`	决定如何将 Unstructured 返回的元素重组为 Haystack`Document`（详见下文）。
`separator`	`str`	`"\n\n"`	当多个元素被拼接进同一个文本字段时，元素之间使用的分隔符。
`unstructured_kwargs`	`dict[str, Any] \\| None`	`None`	透传给 Unstructured API 的额外参数（如策略、语言等），具体可用参数参见 Unstructured API 参数文档。
`progress_bar`	`bool`	`True`	转换过程中是否显示进度条。批量转换大量文件时建议保持开启，便于观察进度。

三种文档创建模式

document_creation_mode是决定输出粒度的关键参数，三种模式逐级细化：

"one-doc-per-file"（默认）：每个文件生成一个HaystackDocument。Unstructured 返回的所有元素被按separator拼接进同一个文本字段。适合全文检索、整体嵌入等不需要细粒度拆分的场景。
"one-doc-per-page"：每个页面生成一个Document。同一页上的元素被拼接为一个文本字段。适合需要保留页码级出处、按页检索的场景。
"one-doc-per-element"：每个元素生成一个Document，即 Unstructured 返回的最小文本单元（如段落、表格、标题等）各自独立成文档。适合需要对文档做最细粒度检索与引用的场景，但文档数量会显著增多。

关于`separator`与`unstructured_kwargs`

separator仅在拼接模式（one-doc-per-file与one-doc-per-page）下起作用，默认"\n\n"（空行分隔）能让拼接后的文本保持段落可读性；若希望元素之间以其他方式衔接，可自定义该值。
unstructured_kwargs提供了一条向 Unstructured API 透传参数的通道，用于按需调整抽取行为（例如指定处理策略、语言、坐标保留等）。参数的具体名称与取值范围以 Unstructured API 的参数文档为准，组件本身不做校验，直接透传。

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 一一对应，每个路径的文档获得各自对应的元数据。

边界情况：若paths中包含目录，则meta只能是单个字典（目录下文件数量事先未知，无法与列表一一对应）。

返回与异常

返回：包含唯一键documents的字典，值为list[Document]——即由 API 返回元素重组而成的 Haystack 文档列表。
异常：当meta为列表而paths包含目录时，抛出ValueError。

产出对象的形态

组件产出的Document即 Haystack 核心库中的文档数据类（见 document.py）：文本内容存于content字段，附加元数据存于meta字段（必须是 JSON 可序列化的字典）。这意味着组件输出可直接被下游的切分器、嵌入器与DocumentWriter消费，无需额外适配。

序列化支持：to_dict 与 from_dict

组件实现了 Haystack 组件标准序列化接口，便于在 YAML/JSON 管道定义中保存与恢复：

def to_dict() -> dict[str, Any]

将组件序列化为字典，包含类名、初始化参数（api_key以 Secret 形式安全序列化，不会明文落盘）等完整信息。

@classmethod def from_dict(cls, data: dict[str, Any]) -> "UnstructuredFileConverter"

从字典反序列化重建组件实例，data为待反序列化的字典，返回重建后的UnstructuredFileConverter对象。

借助这两个方法，包含该组件的管道可以被保存为 YAML 定义并在其他环境复现，实现配置的版本化管理。

实战建议与注意事项

密钥管理：始终优先通过环境变量UNSTRUCTURED_API_KEY提供密钥，避免把密钥硬编码进脚本或管道配置文件。
免费版与付费版分离：两者的 API URL 与 Key 不同，切换服务层级时需同步更新api_url与api_key，否则会认证失败。
输出粒度按检索需求选型：做粗粒度全文检索选one-doc-per-file；需要页码出处选one-doc-per-page；需要精确到段落/表格的细粒度引用选one-doc-per-element。粒度越细，文档数量越多，后续嵌入与存储成本也越高。
目录批量转换时慎用列表形式meta：只要paths里混入目录，meta就必须退回单个字典形式，否则会触发ValueError。
本地部署以数据合规为先：对敏感数据或不满足云服务合规要求的场景，优先使用 Docker 本地部署并指定api_url="http://localhost:8000/general/v0/general"，此时无需 API Key。
管道中的定位：将UnstructuredFileConverter放在索引管道最前端（PreProcessors 之前），再连接 PreProcessors 进行清理切分、最后由 DocumentWriter 写入文档库，即可构建一条完整的多格式文件索引链路。

总结

UnstructuredFileConverter把 Unstructured 强大的多格式 ETL 能力封装为 Haystack 标准组件，让开发者以统一方式将 PDF、Office 文档、图片等非结构化文件接入 RAG 索引管道。理解其三个构造层面的决策点——API 服务形态（托管/本地）、文档创建模式（文件/页/元素粒度）、元数据附加方式（单字典/列表）——即可针对不同检索场景灵活配置。结合to_dict/from_dict序列化能力与 Pipeline 编排，该组件能够无缝嵌入生产级的文档索引与检索系统。

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

Haystack UnstructuredFileConverter 指南：借助 Unstructured API 将多格式文件转换为结构化文档