尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

Haystack DoclingConverter 集成指南:用 Docling 将 PDF/DOCX 转换为布局感知的 Haystack Documents

Haystack DoclingConverter 集成指南:用 Docling 将 PDF/DOCX 转换为布局感知的 Haystack Documents Haystack DoclingConverter 集成指南用 Docling 将 PDF/DOCX 转换为布局感知的 Haystack Documents【免费下载链接】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/haystackDoclingConverter是 Haystack 生态中基于 Docling 文档解析库的转换组件负责把 PDF、DOCX、HTML 等格式的文件解析为保留布局、表格、标题等结构信息的 HaystackDocument并支持 Markdown、按块导出和 JSON 三种导出模式。阅读本文后你将掌握该组件的完整初始化参数、三种导出模式的适用场景、元数据抽取机制以及如何单独运行它或将其接入 RAG 索引管道进行实战部署。本文以 Docling 集成 API 参考 为核心骨架结合 DoclingConverter 用户指南 与仓库内数据类源码展开确保每个参数与行为都有文档或源码依据。一、Docling 集成在 Haystack 中的定位Docling 是一个理解文档结构的解析库能够识别布局、表格、标题等元素。DoclingConverter接收文件路径、URL 或ByteStream对象列表交给 Docling 解析成富文档表示再转成 HaystackDocument输出。在索引管道中它通常位于 PreProcessors 之前也就是整个管道的起始位置。按官方用户指南的定位它是“最常出现在管道中的位置”——处于索引管道的开头负责把原始文件变成结构化的Document流。其核心属性如下属性说明管道中的常见位置索引管道起始处PreProcessors 之前必填运行参数sources文件路径、URL 或ByteStream对象列表输出变量documentsHaystackDocument列表集成包名docling-haystack说明DoclingConverter本身并不在本仓库的haystack/目录内而是由独立的docling-haystack集成包提供源码位于 deepset-ai/haystack-core-integrations 仓库的 integrations/docling 目录。本仓库中的 API 参考文档 与 用户指南 完整记录了它的接口与用法。二、安装与包结构安装 Docling 集成pip install docling-haystack安装后相关组件从haystack_integrations.components.converters.docling导入模块路径为haystack_integrations.components.converters.docling.converter。API 参考文档在该模块下定义了四个公开类型ExportType导出类型枚举BaseMetaExtractor元数据抽取器抽象基类MetaExtractor默认的元数据抽取器实现DoclingConverter核心转换组件。三、ExportType三种导出模式ExportType继承自str和Enum是可用的导出类型枚举。它是决定DoclingConverter输出形态的核心开关取值行为典型场景ExportType.MARKDOWN默认每个输入文档导出为单个 Markdown 字符串封装进一个Document需要保留完整格式化内容的场景ExportType.DOC_CHUNKS先用 Docling 的HybridChunker对每个文档分块每个块返回一个Document块元数据携带 Docling 的结构上下文索引管道下游检索需要语义连贯的块ExportType.JSON将完整 Docling 文档序列化为 JSON 字符串封装进一个Document需要访问完整结构化表示的场景对应关系可以直接从参考文档的__init__参数说明中确认MARKDOWN将每个输入文档捕获为单个 markdownDocumentDOC_CHUNKS先分块再按块返回JSON将完整 Docling 文档序列化为 JSON 字符串。from haystack_integrations.components.converters.docling import ( DoclingConverter, ExportType, ) # 默认整份文档输出为一个 Markdown Document converter DoclingConverter() # 按块输出一个块对应一个 Document converter DoclingConverter(export_typeExportType.DOC_CHUNKS) # JSON 模式完整结构序列化为 JSON 字符串 converter DoclingConverter(export_typeExportType.JSON)当选择ExportType.DOC_CHUNKS时DoclingConverter已经完成了分块管道中通常不再需要单独的DocumentSplitter。四、DoclingConverter 构造参数详解DoclingConverter.__init__的完整签名如下__init__( converter: DocumentConverter | None None, convert_kwargs: dict[str, Any] | None None, export_type: ExportType ExportType.MARKDOWN, md_export_kwargs: dict[str, Any] | None None, chunker: BaseChunker | None None, meta_extractor: BaseMetaExtractor | None None, ) - None各参数的语义依据 API 参考文档参数类型默认行为说明converterDocumentConverter \| None系统默认传入预先配置好的 DoclingDocumentConverter实例以定制解析行为convert_kwargsdict[str, Any] \| None系统默认传给 Docling 转换步骤的任意关键字参数export_typeExportTypeExportType.MARKDOWN导出模式见上文三种取值md_export_kwargsdict[str, Any] \| None无传给 Markdown 导出的参数仅在ExportType.MARKDOWN下生效例如控制图片占位文本chunkerBaseChunker \| None系统默认自定义 Docling 分块器实例仅在ExportType.DOC_CHUNKS下生效meta_extractorBaseMetaExtractor \| None系统默认用于填充输出文档元数据的抽取器实例定制解析行为的典型组合是通过converter传入预配置的DocumentConverter以改变 Docling 的解析选项通过convert_kwargs向转换步骤追加参数通过md_export_kwargs控制 Markdown 渲染如图片占位文本通过chunker提供自定义分块器。五、方法行为详解API 参考文档为DoclingConverter定义了四个方法这里逐一展开。5.1 warm_up延迟构建默认 HybridChunkerwarm_up() - None该方法在未于初始化时传入chunker的情况下为ExportType.DOC_CHUNKS构建默认的HybridChunker。参考文档明确指出构建默认 chunker 会下载一个 Hugging Face tokenizer因此被延迟到 warm-up 阶段执行——这正是 Haystack 将模型/资源加载统一推迟到warm_up阶段的设计动机。5.2 to_dict 与 from_dict序列化与反序列化to_dict() - dict[str, Any]将组件序列化为字典产生带type和init_parameters键的字典供管道 YAML 序列化使用。from_dict(data: dict[str, Any]) - DoclingConverter从to_dict产生的字典恢复组件实例。关键限制converter和chunker参数不可序列化反序列化时总是被忽略——恢复出的实例会分别使用默认的DocumentConverter和HybridChunker。这意味着序列化后自定义的 Docling 解析配置与分块器不会保留需要反序列化后手动重新注入。5.3 run执行转换run( paths: list[str | Path] | None None, sources: list[str | Path | ByteStream] | None None, meta: dict[str, Any] | list[dict[str, Any]] | None None, ) - dict[str, list[Document]]参数语义paths已弃用请改用sources。sources要转换的文件路径、URL 或ByteStream对象列表。meta附加到输出Document上的元数据可为单个字典或字典列表传单个字典时其内容被添加到所有产出的Document的元数据中传列表时列表长度必须与sources数量一致两者按位置 zip 对应当某个来源是ByteStream时ByteStream自身的元数据也会被合并进输出。返回值包含键documents的字典值为输出的 HaystackDocument列表。异常ValueErrormeta是列表但长度与sources数量不匹配时抛出RuntimeError遇到未知的export_type时抛出。六、元数据体系BaseMetaExtractor 与 MetaExtractor输出文档的元数据由MetaExtractor实例填充。API 参考定义了抽象基类BaseMetaExtractor继承自ABC其方法契约如下extract_chunk_meta(chunk: BaseChunk) - dict[str, Any] # 抽取分块元数据 extract_dl_doc_meta(dl_doc: DoclingDocument) - dict[str, Any] # 抽取 Docling 文档元数据 to_dict() - dict[str, Any] # 序列化为字典 from_dict(data: dict[str, Any]) - BaseMetaExtractor # 从字典反序列化MetaExtractor继承BaseMetaExtractor实现extract_chunk_meta与extract_dl_doc_meta两个方法。默认MetaExtractor会将 Docling 特有的元数据分块结构或文档来源信息写入dl_meta键下。参考文档将这两个方法抽象到基类层面说明元数据抽取是可插拔的你可以通过meta_extractor参数传入自定义的BaseMetaExtractor实现控制输出文档的元数据内容。两类元数据的叠加方式组件层MetaExtractor默认写dl_meta键——由 Docling 解析结果自动生成运行层run的meta参数——手动附加业务元数据见下文实战。七、实战单独使用 DoclingConverter7.1 基础用法Markdown 默认模式from haystack_integrations.components.converters.docling import ( DoclingConverter, ExportType, ) # 默认整份文档作为 Markdown 输出 converter DoclingConverter() result converter.run(sources[report.pdf, notes.docx]) documents result[documents] print(documents[0].content) # 按块输出一个 Document 对应一个 chunk converter DoclingConverter(export_typeExportType.DOC_CHUNKS) result converter.run(sources[report.pdf]) documents result[documents]7.2 接入索引管道DoclingConverter作为Pipeline组件接入输出documents直接连接到DocumentWriterfrom haystack import Pipeline from haystack.components.writers import DocumentWriter from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack_integrations.components.converters.docling import DoclingConverter document_store InMemoryDocumentStore() pipeline Pipeline() pipeline.add_component(converter, DoclingConverter()) pipeline.add_component(writer, DocumentWriter(document_storedocument_store)) pipeline.connect(converter, writer) pipeline.run({converter: {sources: [report.pdf, manual.docx]}})管道运行时sources通过{converter: {sources: [...]}}传入。若设置export_typeExportType.DOC_CHUNKS分块已在转换器内完成通常无需再挂DocumentSplitter。7.3 自定义分块器chunker参数仅在ExportType.DOC_CHUNKS下生效。可传入自定义的 DoclingHybridChunker控制分块粒度from docling.chunking import HybridChunker from haystack_integrations.components.converters.docling import ( DoclingConverter, ExportType, ) chunker HybridChunker(tokenizerBAAI/bge-small-en-v1.5, max_tokens256) converter DoclingConverter(export_typeExportType.DOC_CHUNKS, chunkerchunker) result converter.run(sources[report.pdf])需要留意的是构造HybridChunker涉及加载 tokenizer可能需联网下载这也是默认 chunker 被推迟到warm_up阶段构建的原因自定义chunker实例不会在from_dict反序列化时被恢复。7.4 附加元数据全量或按来源from haystack_integrations.components.converters.docling import DoclingConverter converter DoclingConverter() # 同一份元数据附加到所有输出 Document result converter.run( sources[a.pdf, b.pdf], meta{project: research}, ) # 按来源分别附加元数据列表长度必须与 sources 一致 result converter.run( sources[a.pdf, b.pdf], meta[{title: Report A}, {title: Report B}], )7.5 处理内存中的文件ByteStream文件已读入内存时可直接传ByteStream对象。关键点在于须在ByteStream的元数据中设置file_pathDocling 才能识别文件格式。这与仓库内ByteStream数据类的设计一致——它持有data二进制内容、meta附加元数据字典与mime_type字段且run方法在来源为ByteStream时会将其自身元数据一并合并进输出Document。from haystack.dataclasses import ByteStream from haystack_integrations.components.converters.docling import DoclingConverter with open(report.pdf, rb) as f: data f.read() source ByteStream(datadata, meta{file_path: report.pdf}) converter DoclingConverter() result converter.run(sources[source])ByteStream还提供from_file_path、from_string、to_file、to_string等便捷方法定义于 byte_stream.py可灵活地在文件、字符串与字节流之间转换便于在爬虫、下载器等内存管道中直接喂给 DoclingConverter。八、源码级佐证与事实核对以下关键结论均可在当前仓库中找到依据导出模式语义ExportType三种取值的完整行为见 API 参考 中__init__的参数说明与 用户指南 的 Overview 一致。ByteStream数据类data、meta、mime_type字段及文件/字符串互转方法定义于 haystack/dataclasses/byte_stream.py。输出数据类型Document转换结果中的每个元素都是 HaystackDocument数据类其结构定义见 haystack/dataclasses/document.py 与 数据类概念文档。集成包归属DoclingConverter属于外部docling-haystack包本仓库承载其 API 参考、用户指南与示例。九、延伸阅读DoclingConverter 用户指南本文实战示例的完整来源包含更多管道组合方式。DoclingServe 集成API 参考若不想在本地承担 Docling 的机器学习依赖可用DoclingServeConverter将转换卸载到远程 DoclingServe HTTP 服务支持同步与异步执行。PreProcessors 文档DOC_CHUNKS之外需要更细粒度清洗时可在转换器之后串联预处理组件。ByteStream 数据类理解内存文件在管道中的数据载体。【免费下载链接】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),仅供参考
返回列表