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/haystackDoclingServeConverter是 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.converterDoclingServeConverter 本身是一个标准的 Haystackcomponent装饰器组件可像普通组件一样被加入Pipeline。其典型位置是索引管线最前端、预处理PreProcessors之前先完成格式解析再交给DocumentSplitter等后续环节。组件整体能力如下项目说明管线上最常见位置预处理组件之前或索引管线起始处必填运行参数sources文件路径、URL 字符串或ByteStream的列表输出变量documents转换后的 Haystack 文档列表集成包名docling-serve-haystack服务端接口/v1/convert/file本地上传、/v1/convert/sourceURL 提交快速上手安装、启动服务并完成首次转换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_urlhttp://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_urlhttp://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, strictFalse ), mode: ConversionMode | str ConversionMode.SYNC, poll_interval: float 2.0, job_timeout: float 600.0 ) - None各参数含义与取值建议如下参数默认值说明base_urlhttp://localhost:5001DoclingServe 实例的基础 URL。远程部署时需改为实际地址例如http://your-host:5001export_typeExportType.MARKDOWN输出格式三选一ExportType.MARKDOWN、ExportType.TEXT、ExportType.JSONconvert_optionsNone直接透传给 DoclingServe API 的转换选项字典例如{do_ocr: True, ocr_engine: tesseract}可启用 OCR。注意to_formats会由组件根据export_type自动设置不应出现在此字典中timeout120.0HTTP 请求超时时间秒适用于单次请求的收发api_key读取DOCLING_SERVE_API_KEY环境变量访问受保护 DoclingServe 实例的 API 密钥。默认从DOCLING_SERVE_API_KEY环境变量读取strictFalse表示未设置时不报错显式传None可关闭认证modeConversionMode.SYNC转换模式sync走同步端点async提交异步任务并轮询poll_interval2.0异步模式下同时控制服务端 long-poll 等待参数?wait与本地两次轮询之间的最大休眠时间。调大可减少往返次数调小则提高轮询频率、更快感知任务完成job_timeout600.0每个异步转换任务的最大等待时间秒超时抛出DoclingServeTimeoutError关于认证组件默认的密钥来源是环境变量这与 Haystack 生态中Secret的统一约定一致既可以在进程环境里预先导出DOCLING_SERVE_API_KEY也可以在部署时注入。若 DoclingServe 未开启认证将api_keyNone传入即可。一个带 OCR 与异步模式的构造示例from haystack import Secret from haystack_integrations.components.converters.docling_serve import ( DoclingServeConverter, ConversionMode, ExportType, ) converter DoclingServeConverter( base_urlhttp://localhost:5001, export_typeExportType.MARKDOWN, convert_options{do_ocr: True, ocr_engine: tesseract}, api_keySecret.from_env_var(DOCLING_SERVE_API_KEY, strictFalse), modeConversionMode.ASYNC, poll_interval2.0, job_timeout600.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_urlhttp://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_pathDoclingServe 依赖它来识别文件格式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(datadata, meta{file_path: report.pdf}) converter DoclingServeConverter(base_urlhttp://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_urlhttp://localhost:5001), ) pipeline.add_component(splitter, DocumentSplitter()) pipeline.add_component(writer, DocumentWriter(document_storedocument_store)) pipeline.connect(converter, splitter) pipeline.connect(splitter, writer) pipeline.run({converter: {sources: [report.pdf, manual.docx]}})从源码结构看DoclingServeConverter输出的Document.content内容取决于export_typeMARKDOWN模式下 content 为带格式的 Markdown 文本TEXT为纯文本JSON则为 Docling 文档的 JSON 字符串表示。下游的DocumentSplitter等预处理组件可直接消费这些文本内容。使用要点与注意事项to_formats勿手动指定组件会根据export_type自动向 DoclingServe API 设置to_formats在convert_options中重复传入可能导致冲突。file_path对 ByteStream 是必需的内存文件的格式识别依赖该元数据缺失时可能无法正确解析。失败来源会被跳过run对单个来源的转换失败采用跳过 warning策略适合批量索引场景如需严格失败语义可在调用方对返回文档数量与输入来源数量做校验。两种异步不要混淆ConversionMode.ASYNC是服务端任务轮询run_async是 Python 协程异步调用二者独立、可组合。认证方式默认读取DOCLING_SERVE_API_KEY环境变量未配置时不强制strictFalse公开实例可传api_keyNone。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考