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/haystackUnstructuredFileConverter是 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 URLhttps://api.unstructured.io/general/v0/general免费可用但存在一定的调用限制速率、并发与功能范围受免费额度约束。Unstructured Serverless APIServerless 付费版在 Unstructured 账号中开通付费版本后会获得专属的唯一 API URL。属于完整能力层的付费服务。⚠️ 免费版与付费版的 API Key 相互独立不能互换使用。无论选择哪个层级官方都推荐将 API Key 写入环境变量UNSTRUCTURED_API_KEY组件默认会从该环境变量读取密钥export UNSTRUCTURED_API_KEYyour_api_key这种做法的好处是密钥不会硬编码进代码或 YAML 配置也便于在容器、CI 等环境中统一注入。本地自托管Docker 方式如果你不希望数据离开本地环境、或想避免云服务的调用限制可以用 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启动后本地 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_urlhttp://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_urlhttp://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, 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_urlstrUNSTRUCTURED_HOSTED_API_URL托管版地址Unstructured API 的 URL。默认指向云端托管版本本地运行时需显式传入如http://localhost:8000/general/v0/general。api_keySecret \| None从环境变量UNSTRUCTURED_API_KEY读取非严格模式调用托管 API 所需的密钥。可显式传入也推荐通过环境变量注入本地运行时无需提供。document_creation_modeLiteral[one-doc-per-file, one-doc-per-page, one-doc-per-element]one-doc-per-file决定如何将 Unstructured 返回的元素重组为 HaystackDocument详见下文。separatorstr\n\n当多个元素被拼接进同一个文本字段时元素之间使用的分隔符。unstructured_kwargsdict[str, Any] \| NoneNone透传给 Unstructured API 的额外参数如策略、语言等具体可用参数参见 Unstructured API 参数文档。progress_barboolTrue转换过程中是否显示进度条。批量转换大量文件时建议保持开启便于观察进度。三种文档创建模式document_creation_mode是决定输出粒度的关键参数三种模式逐级细化one-doc-per-file默认每个文件生成一个HaystackDocument。Unstructured 返回的所有元素被按separator拼接进同一个文本字段。适合全文检索、整体嵌入等不需要细粒度拆分的场景。one-doc-per-page每个页面生成一个Document。同一页上的元素被拼接为一个文本字段。适合需要保留页码级出处、按页检索的场景。one-doc-per-element每个元素生成一个Document即 Unstructured 返回的最小文本单元如段落、表格、标题等各自独立成文档。适合需要对文档做最细粒度检索与引用的场景但文档数量会显著增多。关于separator与unstructured_kwargsseparator仅在拼接模式one-doc-per-file与one-doc-per-page下起作用默认\n\n空行分隔能让拼接后的文本保持段落可读性若希望元素之间以其他方式衔接可自定义该值。unstructured_kwargs提供了一条向 Unstructured API 透传参数的通道用于按需调整抽取行为例如指定处理策略、语言、坐标保留等。参数的具体名称与取值范围以 Unstructured API 的参数文档为准组件本身不做校验直接透传。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 一一对应每个路径的文档获得各自对应的元数据。边界情况若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_urlhttp://localhost:8000/general/v0/general此时无需 API Key。管道中的定位将UnstructuredFileConverter放在索引管道最前端PreProcessors 之前再连接 PreProcessors 进行清理切分、最后由 DocumentWriter 写入文档库即可构建一条完整的多格式文件索引链路。总结UnstructuredFileConverter把 Unstructured 强大的多格式 ETL 能力封装为 Haystack 标准组件让开发者以统一方式将 PDF、Office 文档、图片等非结构化文件接入 RAG 索引管道。理解其三个构造层面的决策点——API 服务形态托管/本地、文档创建模式文件/页/元素粒度、元数据附加方式单字典/列表——即可针对不同检索场景灵活配置。结合to_dict/from_dict序列化能力与 Pipeline 编排该组件能够无缝嵌入生产级的文档索引与检索系统。【免费下载链接】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），仅供参考
