Haystack 2.19 Tika 集成参考TikaDocumentConverter 与 XHTMLParser 文档转换组件详解【免费下载链接】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 2.19 版本的 Tika 集成 API 参考文档完整解析TikaDocumentConverter组件的初始化参数、run()输入输出规范以及配套的内部解析器XHTMLParser的工作原理。读完后你将掌握如何在索引管线中借助 Apache Tika 服务器将 PDF、DOCX、RTF、ZIP 等各类文件批量转换为带元数据的 HaystackDocument对象并理解该组件从 Haystack 核心包迁移到独立tika-haystack包的来龙去脉。一、组件定位一个依赖 Tika 服务器的通用文档转换器TikaDocumentConverter用于把不同格式的文件PDF、DOCX、HTML、RTF、ZIP 等转换为 Haystack 的Document对象其底层解析工作完全委托给 Apache Tika。这意味着该组件自身不内置任何格式解析引擎必须有一个正在运行的 Tika 服务器组件通过 HTTP 调用该服务器完成转换。从组件在管线中的典型位置来看它最常被放在预处理组件之前或干脆位于索引管线indexing pipeline的最前端输入一批文件路径或ByteStream对象输出一批Document再交由清理、切分、写入等下游组件处理。该集成的包名为tika-haystack对应 API 参考即本文所依据的文档 docs-website/reference_versioned_docs/version-2.19/integrations-api/tika.md。在仓库的组件列表中它被描述为 “Converts various file types to documents using Apache Tika”见 converters.mdx更详细的组件使用文档位于 tikadocumentconverter.mdx。二、运行前提部署一个 Tika 3.x 服务器API 参考文档中有一条明确的版本约束必须重点注意请使用 Tika 3.x 版本的服务器tikaPython 客户端目前尚不支持 Tika Server 4.x。这是 2.19 时期该集成最关键的适用前提——盲目使用latest镜像一旦拉到了 4.x 版本就会不兼容。官方组件文档给出的最简部署方式是 Docker 一行命令docker run -d -p 127.0.0.1:9998:9998 apache/tika:latest组件文档同时提示关于在 Docker 中运行 Tika 的更多选项应查阅 Apache Tika 官方的 Docker 文档原文参考外链此处不重复给出 URL。三、TikaDocumentConverter 独立使用完整用法示例安装集成包后即可按如下方式使用导入路径体现了其独立集成包身份pip install tika-haystack文档给出的标准用法示例from haystack_integrations.components.converters.tika import TikaDocumentConverter from datetime import datetime converter TikaDocumentConverter() results converter.run( sources[sample.docx, my_document.rtf, archive.zip], meta{date_added: datetime.now().isoformat()} ) documents results[documents] print(documents[0].content) # This is a text from the docx file.这段示例覆盖了三个要点一次转换多个不同格式的文件docx、rtf、甚至 zip 归档通过meta为产出的所有Document统一附加元数据从返回字典的documents键取出结果列表。四、__init__参数详解构造函数签名与默认值如下__init__( tika_url: str http://localhost:9998/tika, store_full_path: bool False, ) - None参数类型默认值说明tika_urlstrhttp://localhost:9998/tikaTika 服务器地址。本地按 Docker 默认端口部署时可直接使用默认值部署到远程机器或换端口时必须显式指定store_full_pathboolFalse为True时文件的完整路径会写入产出文档的 metadata为False时只保存文件名store_full_path的取舍直接影响后续可追溯性与元数据隐私默认只存文件名适合来源路径包含本地绝对路径、不希望泄漏到索引中的场景需要精确定位原始文件时再打开该开关。仓库发布记录 add-store-full-path-param-to-converters-43b50812b1600eb2.yaml 记录了该参数向各转换器推广的过程。五、run()输入输出规范方法签名run( sources: list[str | Path | ByteStream], meta: dict[str, Any] | list[dict[str, Any]] | None None, ) - dict[str, list[Document]]5.1sources三种来源形态sources是一个列表每个元素可以是文件路径字符串str——如sample.docxPath对象——如Path(my_file.pdf)适合类型检查友好的写法ByteStream对象——内存中的字节流适合文件内容不落地磁盘的场景例如从网络抓取后直接送入转换器。5.2meta单字典与列表两种语义meta是可选参数允许三种形态语义差异是使用时最容易踩坑的地方单个字典其内容会被添加到本次运行产出的所有Document的 metadata 中即上文示例中{date_added: ...}的用法。字典列表长度必须与sources数量一致两个列表按顺序 zip逐条对应每个 source 产出的文档携带对应的 metadata。None不附加额外元数据。此外文档特别指出若sources中包含ByteStream对象这些ByteStream自带的meta会被合并到输出Document的 metadata 中——这是与ByteStream数据流协作时元数据不丢失的关键机制。单字典meta支持属于该组件的一次功能增强对应发布记录 single-meta-in-tikaconverter-89b454c451a2ed93.yamlAdds support for single metadata dictionary input inTikaDocumentConverter。5.3 返回值与页码信息run()返回dict[str, list[Document]]当前包含的键为documents即创建好的Document列表。一个值得了解的实现细节组件对 PDF 的处理会保留页分隔符——发布记录 fix-tika-page_number-2d600b2dc8a4faa7.yaml 明确说明 TikaDocumentConverternow returns page breaks (\f) in the output. This only works for PDF files.。也就是说 PDF 转换后的文本中以\fform feed标记页面边界下游若需要按页拆分或统计可以基于该字符处理。六、XHTMLParser从 Tika XHTML 输出中切分页面API 参考文档中并列给出了一个内部类XHTMLParser继承自 Python 标准库的HTMLParser职责是“从 Tika XHTML 内容中提取页面pages”。Tika 服务器返回的文档文本通常是 XHTML 包装形式XHTMLParser通过重写标准库HTMLParser的三个回调完成页面切分方法签名职责handle_starttaghandle_starttag(tag: str, attrs: list[tuple[str, str \| None]]) - None识别页面div的开始根据标签名与属性判断handle_endtaghandle_endtag(tag: str) - None识别页面div的结束handle_datahandle_data(data: str) - None填充当前页面节点中的文本内容三个方法协同工作遇到页面div的开始标签开启一个页面缓冲handle_data不断追加文本遇到结束标签收口——这正是第五节所述 PDF 文本中出现页分隔符的底层来源。它属于haystack_integrations.components.converters.tika.converter模块中的辅助解析器一般无需直接调用但理解它能帮助你在排查“转换结果分页异常”类问题时定位到正确的位置。七、在索引管线中的典型用法参考文档 tikadocumentconverter.mdx 给出了一个完整索引管线示例展示了该组件作为管线入口组件的接法from haystack import Pipeline from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack_integrations.components.converters.tika import TikaDocumentConverter from haystack.components.preprocessors import DocumentCleaner from haystack.components.preprocessors import DocumentSplitter from haystack.components.writers import DocumentWriter document_store InMemoryDocumentStore() pipeline Pipeline() pipeline.add_component(converter, TikaDocumentConverter()) pipeline.add_component(cleaner, DocumentCleaner()) pipeline.add_component( splitter, DocumentSplitter(split_bysentence, split_length5), ) pipeline.add_component(writer, DocumentWriter(document_storedocument_store)) pipeline.connect(converter, cleaner) pipeline.connect(cleaner, splitter) pipeline.connect(splitter, writer) pipeline.run({converter: {sources: file_paths}})组件的必填入参为sources文件路径列表输出为documents文档列表在pipeline.run()中以{converter: {sources: file_paths}}的形式传入输入字典。若文件来自上游抓取器等组件则以ByteStream列表经sources传入即可无需落盘。八、版本演进从核心包到 tika-haystack 独立集成包如果你维护的是较早版本的代码务必注意该组件的迁移历史这对升级排查非常有价值加入 2.0发布记录 add-tikaconverter-2.0-ef637f93114e6c96.yaml 记录了组件的初次引入preview弃用发布记录 deprecate-tika-document-converter-3b8e2a1f74cd059a.yaml 宣布TikaDocumentConverter弃用并计划随 3.0 移出 Haystack迁往tika-haystack包移除发布记录 remove-tika-document-converter-3f1f31d3ad16b73a.yaml 确认了迁移落地导入方式由from haystack.components.converters import TikaDocumentConverter改为from haystack_integrations.components.converters.tika import TikaDocumentConverter。这一点也与 migration.mdx 中的迁移对照表一致旧导入from haystack.components.converters import TikaDocumentConverter对应的新导入为from haystack_integrations.components.converters.tika import TikaDocumentConverter新包为tika-haystack。2.19 时期的本文档所呈现的即是迁移后的haystack_integrations命名空间形态。九、小结与检查清单使用前先确认 Tika 服务器为3.x且正在监听tika_url指向的地址默认http://localhost:9998/tika这是最常见的故障源run(sources, meta)中sources支持str/Path/ByteStream混合传入meta传单字典时作用于全部输出文档传列表时必须与sources等长关注store_full_path对元数据内容的影响按来源追溯需求二选一PDF 场景利用文本中的\f页分隔符实现按页逻辑排查分页异常时可结合XHTMLParser的页面div解析机制定位问题老代码升级时按第八节的导入路径映射完成迁移并安装tika-haystack包。本组件当前版本3.x的 API 参考与 2.19 文档结构一致可继续查阅 docs-website/reference/integrations-api/tika.md 确认签名是否有后续变化。【免费下载链接】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 2.19 Tika 集成参考：TikaDocumentConverter 与 XHTMLParser 文档转换组件详解
Haystack 2.19 Tika 集成参考TikaDocumentConverter 与 XHTMLParser 文档转换组件详解【免费下载链接】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 2.19 版本的 Tika 集成 API 参考文档完整解析TikaDocumentConverter组件的初始化参数、run()输入输出规范以及配套的内部解析器XHTMLParser的工作原理。读完后你将掌握如何在索引管线中借助 Apache Tika 服务器将 PDF、DOCX、RTF、ZIP 等各类文件批量转换为带元数据的 HaystackDocument对象并理解该组件从 Haystack 核心包迁移到独立tika-haystack包的来龙去脉。一、组件定位一个依赖 Tika 服务器的通用文档转换器TikaDocumentConverter用于把不同格式的文件PDF、DOCX、HTML、RTF、ZIP 等转换为 Haystack 的Document对象其底层解析工作完全委托给 Apache Tika。这意味着该组件自身不内置任何格式解析引擎必须有一个正在运行的 Tika 服务器组件通过 HTTP 调用该服务器完成转换。从组件在管线中的典型位置来看它最常被放在预处理组件之前或干脆位于索引管线indexing pipeline的最前端输入一批文件路径或ByteStream对象输出一批Document再交由清理、切分、写入等下游组件处理。该集成的包名为tika-haystack对应 API 参考即本文所依据的文档 docs-website/reference_versioned_docs/version-2.19/integrations-api/tika.md。在仓库的组件列表中它被描述为 “Converts various file types to documents using Apache Tika”见 converters.mdx更详细的组件使用文档位于 tikadocumentconverter.mdx。二、运行前提部署一个 Tika 3.x 服务器API 参考文档中有一条明确的版本约束必须重点注意请使用 Tika 3.x 版本的服务器tikaPython 客户端目前尚不支持 Tika Server 4.x。这是 2.19 时期该集成最关键的适用前提——盲目使用latest镜像一旦拉到了 4.x 版本就会不兼容。官方组件文档给出的最简部署方式是 Docker 一行命令docker run -d -p 127.0.0.1:9998:9998 apache/tika:latest组件文档同时提示关于在 Docker 中运行 Tika 的更多选项应查阅 Apache Tika 官方的 Docker 文档原文参考外链此处不重复给出 URL。三、TikaDocumentConverter 独立使用完整用法示例安装集成包后即可按如下方式使用导入路径体现了其独立集成包身份pip install tika-haystack文档给出的标准用法示例from haystack_integrations.components.converters.tika import TikaDocumentConverter from datetime import datetime converter TikaDocumentConverter() results converter.run( sources[sample.docx, my_document.rtf, archive.zip], meta{date_added: datetime.now().isoformat()} ) documents results[documents] print(documents[0].content) # This is a text from the docx file.这段示例覆盖了三个要点一次转换多个不同格式的文件docx、rtf、甚至 zip 归档通过meta为产出的所有Document统一附加元数据从返回字典的documents键取出结果列表。四、__init__参数详解构造函数签名与默认值如下__init__( tika_url: str http://localhost:9998/tika, store_full_path: bool False, ) - None参数类型默认值说明tika_urlstrhttp://localhost:9998/tikaTika 服务器地址。本地按 Docker 默认端口部署时可直接使用默认值部署到远程机器或换端口时必须显式指定store_full_pathboolFalse为True时文件的完整路径会写入产出文档的 metadata为False时只保存文件名store_full_path的取舍直接影响后续可追溯性与元数据隐私默认只存文件名适合来源路径包含本地绝对路径、不希望泄漏到索引中的场景需要精确定位原始文件时再打开该开关。仓库发布记录 add-store-full-path-param-to-converters-43b50812b1600eb2.yaml 记录了该参数向各转换器推广的过程。五、run()输入输出规范方法签名run( sources: list[str | Path | ByteStream], meta: dict[str, Any] | list[dict[str, Any]] | None None, ) - dict[str, list[Document]]5.1sources三种来源形态sources是一个列表每个元素可以是文件路径字符串str——如sample.docxPath对象——如Path(my_file.pdf)适合类型检查友好的写法ByteStream对象——内存中的字节流适合文件内容不落地磁盘的场景例如从网络抓取后直接送入转换器。5.2meta单字典与列表两种语义meta是可选参数允许三种形态语义差异是使用时最容易踩坑的地方单个字典其内容会被添加到本次运行产出的所有Document的 metadata 中即上文示例中{date_added: ...}的用法。字典列表长度必须与sources数量一致两个列表按顺序 zip逐条对应每个 source 产出的文档携带对应的 metadata。None不附加额外元数据。此外文档特别指出若sources中包含ByteStream对象这些ByteStream自带的meta会被合并到输出Document的 metadata 中——这是与ByteStream数据流协作时元数据不丢失的关键机制。单字典meta支持属于该组件的一次功能增强对应发布记录 single-meta-in-tikaconverter-89b454c451a2ed93.yamlAdds support for single metadata dictionary input inTikaDocumentConverter。5.3 返回值与页码信息run()返回dict[str, list[Document]]当前包含的键为documents即创建好的Document列表。一个值得了解的实现细节组件对 PDF 的处理会保留页分隔符——发布记录 fix-tika-page_number-2d600b2dc8a4faa7.yaml 明确说明 TikaDocumentConverternow returns page breaks (\f) in the output. This only works for PDF files.。也就是说 PDF 转换后的文本中以\fform feed标记页面边界下游若需要按页拆分或统计可以基于该字符处理。六、XHTMLParser从 Tika XHTML 输出中切分页面API 参考文档中并列给出了一个内部类XHTMLParser继承自 Python 标准库的HTMLParser职责是“从 Tika XHTML 内容中提取页面pages”。Tika 服务器返回的文档文本通常是 XHTML 包装形式XHTMLParser通过重写标准库HTMLParser的三个回调完成页面切分方法签名职责handle_starttaghandle_starttag(tag: str, attrs: list[tuple[str, str \| None]]) - None识别页面div的开始根据标签名与属性判断handle_endtaghandle_endtag(tag: str) - None识别页面div的结束handle_datahandle_data(data: str) - None填充当前页面节点中的文本内容三个方法协同工作遇到页面div的开始标签开启一个页面缓冲handle_data不断追加文本遇到结束标签收口——这正是第五节所述 PDF 文本中出现页分隔符的底层来源。它属于haystack_integrations.components.converters.tika.converter模块中的辅助解析器一般无需直接调用但理解它能帮助你在排查“转换结果分页异常”类问题时定位到正确的位置。七、在索引管线中的典型用法参考文档 tikadocumentconverter.mdx 给出了一个完整索引管线示例展示了该组件作为管线入口组件的接法from haystack import Pipeline from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack_integrations.components.converters.tika import TikaDocumentConverter from haystack.components.preprocessors import DocumentCleaner from haystack.components.preprocessors import DocumentSplitter from haystack.components.writers import DocumentWriter document_store InMemoryDocumentStore() pipeline Pipeline() pipeline.add_component(converter, TikaDocumentConverter()) pipeline.add_component(cleaner, DocumentCleaner()) pipeline.add_component( splitter, DocumentSplitter(split_bysentence, split_length5), ) pipeline.add_component(writer, DocumentWriter(document_storedocument_store)) pipeline.connect(converter, cleaner) pipeline.connect(cleaner, splitter) pipeline.connect(splitter, writer) pipeline.run({converter: {sources: file_paths}})组件的必填入参为sources文件路径列表输出为documents文档列表在pipeline.run()中以{converter: {sources: file_paths}}的形式传入输入字典。若文件来自上游抓取器等组件则以ByteStream列表经sources传入即可无需落盘。八、版本演进从核心包到 tika-haystack 独立集成包如果你维护的是较早版本的代码务必注意该组件的迁移历史这对升级排查非常有价值加入 2.0发布记录 add-tikaconverter-2.0-ef637f93114e6c96.yaml 记录了组件的初次引入preview弃用发布记录 deprecate-tika-document-converter-3b8e2a1f74cd059a.yaml 宣布TikaDocumentConverter弃用并计划随 3.0 移出 Haystack迁往tika-haystack包移除发布记录 remove-tika-document-converter-3f1f31d3ad16b73a.yaml 确认了迁移落地导入方式由from haystack.components.converters import TikaDocumentConverter改为from haystack_integrations.components.converters.tika import TikaDocumentConverter。这一点也与 migration.mdx 中的迁移对照表一致旧导入from haystack.components.converters import TikaDocumentConverter对应的新导入为from haystack_integrations.components.converters.tika import TikaDocumentConverter新包为tika-haystack。2.19 时期的本文档所呈现的即是迁移后的haystack_integrations命名空间形态。九、小结与检查清单使用前先确认 Tika 服务器为3.x且正在监听tika_url指向的地址默认http://localhost:9998/tika这是最常见的故障源run(sources, meta)中sources支持str/Path/ByteStream混合传入meta传单字典时作用于全部输出文档传列表时必须与sources等长关注store_full_path对元数据内容的影响按来源追溯需求二选一PDF 场景利用文本中的\f页分隔符实现按页逻辑排查分页异常时可结合XHTMLParser的页面div解析机制定位问题老代码升级时按第八节的导入路径映射完成迁移并安装tika-haystack包。本组件当前版本3.x的 API 参考与 2.19 文档结构一致可继续查阅 docs-website/reference/integrations-api/tika.md 确认签名是否有后续变化。【免费下载链接】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），仅供参考