Haystack DoclingServeConverter 接入指南：基于 DoclingServe 的远程文档解析组件

Haystack DoclingServeConverter 接入指南：基于 DoclingServe 的远程文档解析组件

【免费下载链接】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

DoclingServeConverter是 Haystack 官方集成docling-serve-haystack提供的文档转换组件：它通过 HTTP 调用远程 DoclingServe 服务，将 PDF、Office 文档、HTML 等多种格式解析为 HaystackDocument，本地无需任何重型机器学习依赖。本文基于 Docling Serve 集成 API 参考 与 DoclingServeConverter 组件指南，完整讲解其枚举、错误类型、构造参数、run/run_async用法，并给出从 Docker 启动服务到接入索引管线的可直接运行的实战示例。

组件定位：与本地 DoclingConverter 的关键区别

Docling 是文档智能解析库，擅长把复杂版式（表格、公式、多栏、扫描件）还原为结构化内容。Haystack 提供两种接入方式：

• 本地DoclingConverter：在应用进程内直接运行 Docling，所有解析、OCR、分块都在本地完成，依赖较重，参考 Docling 集成 API 参考；
• 远程DoclingServeConverter：把解析任务交给一个独立的 DoclingServe HTTP 服务器，本地进程只负责上传文件与接收结果，没有任何重型 ML 依赖，处理完全在远程进行。

从源码结构看（模块位于haystack_integrations.components.converters.docling_serve.converter），DoclingServeConverter 本身是一个标准的 Haystack@component装饰器组件，可像普通组件一样被加入Pipeline。其典型位置是索引管线最前端、预处理（PreProcessors）之前：先完成格式解析，再交给DocumentSplitter等后续环节。

组件整体能力如下：

快速上手：安装、启动服务并完成首次转换

DoclingServeConverter 位于独立的集成包中，需单独安装：

pip install docling-serve-haystack

转换需要有一个运行中的 DoclingServe 实例。本地可借助 Docker 一键启动 CPU 版本（默认监听 5001 端口）：

docker run -p 5001:5001 ghcr.io/docling-project/docling-serve-cpu:latest

随后即可像使用任何 Haystack 组件一样调用它。最简单的单组件用法：

from haystack_integrations.components.converters.docling_serve import DoclingServeConverter converter = DoclingServeConverter(base_url="http://localhost:5001") result = converter.run(sources=["report.pdf", "notes.docx"]) documents = result["documents"] print(documents[0].content[:200])

也可以直接传入远程 URL 字符串，由服务端抓取并解析，无需先在本地下载：

from haystack_integrations.components.converters.docling_serve import DoclingServeConverter converter = DoclingServeConverter(base_url="http://localhost:5001") result = converter.run(sources=["https://arxiv.org/pdf/2206.01062"]) print(result["documents"][0].content[:200])

核心枚举与异常类型

API 参考文档定义了组件使用的两个枚举与两个异常，理解它们有助于正确配置组件与处理失败场景。

ExportType：三种导出格式

ExportType继承自str与Enum，描述 DoclingServe 支持的导出格式：

• MARKDOWN（默认）：将文档转换为 Markdown 字符串，保留标题、列表、表格等结构信息，适合需要"带格式结构化文本"的场景；
• TEXT：仅提取纯文本，得到干净、无格式的文本内容；
• JSON：返回完整的 Docling 文档表示（JSON 字符串），适合需要访问完整结构化表示、自行做二次加工的场景。

ConversionMode：同步与异步执行

ConversionMode同样基于str与Enum，控制转换的执行方式：

• SYNC：使用 DoclingServe 的同步转换端点，一次 HTTP 请求返回结果；
• ASYNC：提交转换任务到 DoclingServe 的异步任务端点，随后轮询直到任务完成，适合耗时较长的转换。

异常类型

• DoclingServeConversionError（继承Exception）：当 DoclingServe 报告异步任务失败或转换失败时抛出；
• DoclingServeTimeoutError（继承DoclingServeConversionError）：当异步任务超过job_timeout上限仍未完成时抛出。

从异常继承关系可以推断，组件把"超时"视为"转换失败"的一种特例，捕获DoclingServeConversionError即可同时覆盖两类失败。

构造参数详解

DoclingServeConverter.__init__的全部参数均为关键字参数，签名如下：

__init__( *, base_url: str = "http://localhost:5001", export_type: ExportType = ExportType.MARKDOWN, convert_options: dict[str, Any] | None = None, timeout: float = 120.0, api_key: Secret | None = Secret.from_env_var( "DOCLING_SERVE_API_KEY", strict=False ), mode: ConversionMode | str = ConversionMode.SYNC, poll_interval: float = 2.0, job_timeout: float = 600.0 ) -> None

各参数含义与取值建议如下：

关于认证，组件默认的密钥来源是环境变量，这与 Haystack 生态中Secret的统一约定一致：既可以在进程环境里预先导出DOCLING_SERVE_API_KEY，也可以在部署时注入。若 DoclingServe 未开启认证，将api_key=None传入即可。

一个带 OCR 与异步模式的构造示例：

from haystack import Secret from haystack_integrations.components.converters.docling_serve import ( DoclingServeConverter, ConversionMode, ExportType, ) converter = DoclingServeConverter( base_url="http://localhost:5001", export_type=ExportType.MARKDOWN, convert_options={"do_ocr": True, "ocr_engine": "tesseract"}, api_key=Secret.from_env_var("DOCLING_SERVE_API_KEY", strict=False), mode=ConversionMode.ASYNC, poll_interval=2.0, job_timeout=600.0, )

run 与 run_async：输入输出契约

run（同步转换）

run( sources: list[str | Path | ByteStream], meta: dict[str, Any] | list[dict[str, Any]] | None = None, ) -> dict[str, list[Document]]

run将来源列表发送给 DoclingServe 并返回 HaystackDocument列表。参数规则：

• sources：待转换来源列表。每个元素可以是 URL 字符串、本地文件路径（str/Path）或ByteStream。URL 字符串会被发送到/v1/convert/source端点；其余所有来源（本地文件与 ByteStream）会上传到/v1/convert/file端点；
• meta：附加到输出Document的可选元数据。可以传单个字典（应用到所有输出文档），也可以传字典列表（与sources一一对应，按顺序 zip 到每个来源）。

返回值为{"documents": [Document, ...]}形式的字典。每个来源产生一个Document；转换失败的单条来源会被跳过并记录一条 warning，而不是让整个run失败。

run_async（异步转换）

run_async( sources: list[str | Path | ByteStream], meta: dict[str, Any] | list[dict[str, Any]] | None = None, ) -> dict[str, list[Document]]

run_async是run的异步等价物，签名与返回结构完全一致。当 DoclingServe 请求不应阻塞事件循环（例如运行在异步 Web 服务或异步应用中）时，应使用run_async。注意它对应的是 Python 协程层面的异步执行，与上文ConversionMode.ASYNC（服务端任务轮询模式）是两个不同维度，可以组合使用。

附加元数据：单字典与列表两种模式

from haystack_integrations.components.converters.docling_serve import ( DoclingServeConverter, ) converter = DoclingServeConverter(base_url="http://localhost:5001") # 模式一：所有来源共享同一份元数据 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"}], )

处理内存中的文件（ByteStream）

当文件已加载进内存（例如来自网络下载、数据库或流式读取）时，可以直接传ByteStream对象。务必在ByteStream的元数据中设置file_path，DoclingServe 依赖它来识别文件格式：

from haystack.dataclasses import ByteStream from haystack_integrations.components.converters.docling_serve import ( DoclingServeConverter, ) with open("report.pdf", "rb") as f: data = f.read() source = ByteStream(data=data, meta={"file_path": "report.pdf"}) converter = DoclingServeConverter(base_url="http://localhost:5001") result = converter.run(sources=[source])

序列化：to_dict 与 from_dict

与 Haystack 其他组件一致，DoclingServeConverter支持完整的序列化/反序列化，便于通过 YAML 或 JSON 描述管线：

• to_dict() -> dict[str, Any]：将组件序列化为字典，包含组件类型与全部初始化参数；
• from_dict(data: dict[str, Any]) -> DoclingServeConverter：从to_dict产生的字典重建组件实例，返回一个新的DoclingServeConverter。

这意味着包含该组件的管线可以被整体序列化保存，并在其他进程中恢复，配合 Haystack 的Pipeline序列化机制使用（可参考 pipeline 序列化文档 中关于 YAML/JSON 管线的说明）。值得注意的是，api_key这类敏感参数在序列化时会按 HaystackSecret的约定处理，不会把明文密钥写入序列化结果。

实战：接入完整索引管线

将 DoclingServeConverter 与DocumentSplitter、DocumentWriter串联，即可构成一条完整的 RAG 索引管线：

from haystack import Pipeline from haystack.components.preprocessors import DocumentSplitter from haystack.components.writers import DocumentWriter from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack_integrations.components.converters.docling_serve import ( DoclingServeConverter, ) document_store = InMemoryDocumentStore() pipeline = Pipeline() pipeline.add_component( "converter", DoclingServeConverter(base_url="http://localhost:5001"), ) pipeline.add_component("splitter", DocumentSplitter()) pipeline.add_component("writer", DocumentWriter(document_store=document_store)) pipeline.connect("converter", "splitter") pipeline.connect("splitter", "writer") pipeline.run({"converter": {"sources": ["report.pdf", "manual.docx"]}})

从源码结构看，DoclingServeConverter输出的Document.content内容取决于export_type：MARKDOWN模式下 content 为带格式的 Markdown 文本，TEXT为纯文本，JSON则为 Docling 文档的 JSON 字符串表示。下游的DocumentSplitter等预处理组件可直接消费这些文本内容。

使用要点与注意事项

1. to_formats勿手动指定：组件会根据export_type自动向 DoclingServe API 设置to_formats，在convert_options中重复传入可能导致冲突。
2. file_path对 ByteStream 是必需的：内存文件的格式识别依赖该元数据，缺失时可能无法正确解析。
3. 失败来源会被跳过：run对单个来源的转换失败采用"跳过 + warning"策略，适合批量索引场景；如需严格失败语义，可在调用方对返回文档数量与输入来源数量做校验。
4. 两种"异步"不要混淆：ConversionMode.ASYNC是服务端任务轮询；run_async是 Python 协程异步调用，二者独立、可组合。
5. 认证方式：默认读取DOCLING_SERVE_API_KEY环境变量，未配置时不强制（strict=False）；公开实例可传api_key=None。

DoclingServe 本身支持 PDF、Office 文档、HTML 及多种其他格式，且以 HTTP 服务形式提供可水平扩展的解析能力，适合对解析吞吐、资源隔离有要求的生产环境。相关更多示例与字段说明，可继续阅读 DoclingServeConverter 组件指南 与 Docling 集成（本地版）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