Haystack 集成 KreuzbergConverter本地化多格式文档转 Document 的完整实战指南【免费下载链接】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/haystackKreuzbergConverter是 Haystack 生态中一个以 Rust 为核心的文档智能转换组件它通过kreuzberg-haystack集成包将 PDF、Office 文档、图片及 91 种文件格式在本地转换为 HaystackDocument全程不发起任何外部 API 调用。本文将基于版本化 API 参考docs-website/reference_versioned_docs/version-2.20/integrations-api/kreuzberg.md与官方组件指南docs-website/docs/pipeline-components/converters/kreuzbergconverter.mdx系统讲解其安装、独立使用、Pipeline 集成、ExtractionConfig深度定制与序列化接口并对照 Haystack 核心转换器源码揭示其与生态其余 Converter 的设计异同。为什么选择 Kreuzberg本地化、高覆盖的文档智能抽取KreuzbergConverter的定位非常清晰把「任意常见文档」变成「可供检索与喂给 LLM 的干净文本」。它的底层是 Kreuzberg——一个文档智能框架核心处理逻辑由 Rust 实现支持从 PDF、Office 文档、图片以及 75 其他格式中提取文本。所有处理均在本地完成不依赖任何外部 API这意味着数据不出域、无网络依赖、成本可控非常适合对数据隐私和延迟敏感的企业级索引管线。需要特别说明的是官方组件指南中描述其格式覆盖为 91 种而版本 2.20 的 API 参考写作 75 种两者都是同一组件的不同版本措辞。从当前仓库可见docs-website/docs/pipeline-components/converters/kreuzbergconverter.mdx 与各版本化文档如 version-3.1 版本均采用 91 的描述读者应以官方最新指南为准并将其理解为「随版本持续增长的格式矩阵」。从组件目录结构看该集成属于 Haystack 生态的外置集成包kreuzberg-haystack与 Haystack 核心内置的 pypdf.py、docx.py、pdfminer.py 等单格式转换器形成互补核心包提供「一种格式一个组件」的精细控制而 Kreuzberg 集成以单个组件覆盖海量格式显著降低索引管线的组件数量与维护成本。支持的格式类别总览官方指南将 Kreuzberg 的格式覆盖划分为六类文档类PDF、DOCX、DOC、PPTX、PPT、XLSX、XLS、ODT、ODS、ODP、RTF、Pages、Keynote、Numbers 等图片类经 OCRPNG、JPEG、TIFF、GIF、BMP、WebP、JPEG 2000、SVG文本/标记类Markdown、HTML、XML、LaTeX、Typst、JSON、YAML、reStructuredText、Jupyter Notebook邮件类EML、MSG支持附件提取压缩包类ZIP、TAR、GZIP、7Z递归解压并处理内部内容电子书与学术类EPUB、BibTeX、DocBook、JATS。默认情况下每个源文件生成一个 HaystackDocument当开启按页提取per-page extraction或分块chunking后会改为每页/每块一个Document。生成结果携带丰富的元数据包括质量评分quality scores、检测到的语言、抽取的关键词、表格数据以及 PDF 注解等。快速上手安装与独立使用安装集成包通过 PyPI 分发包名为kreuzberg-haystackpip install kreuzberg-haystack安装完成后即可从haystack_integrations.components.converters.kreuzberg导入组件。独立使用最简单的调用方式与 Haystack 核心转换器保持一致——构造组件后直接调用run()from haystack_integrations.components.converters.kreuzberg import ( KreuzbergConverter, ) converter KreuzbergConverter() result converter.run(sources[document.pdf, report.docx]) documents result[documents]API 参考给出的run签名如下run( sources: list[str | Path | ByteStream], meta: dict[str, Any] | list[dict[str, Any]] | None None, ) - dict[str, list[Document]]几个关键行为sources支持三种类型文件路径字符串、Path对象以及 Haystack 的ByteStream二进制对象定义见 byte_stream.py包含data、meta、mime_type三个字段。这一点与核心转换器一致以 txt.py 为代表的run同样接收sources: list[str | Path | ByteStream]并通过get_bytestream_from_sourceutils.py将路径统一包装成带file_path元数据的ByteStream。目录路径会自动展开当sources中出现目录时会展开为其直接文件子项非递归、按字母序排序。meta的两种形态传单个字典时该字典内容会合并进所有产出Document的元数据传字典列表时其长度必须与sources数量一致两者按位置 zip。若sources中包含ByteStream对象则其自身携带的meta也会被合并进输出Document。目录与列表型meta的冲突当sources中存在目录时由于目录内文件数量在运行前不可知meta必须是单个字典而不能是列表。这一meta归一化机制在核心代码中有完整对应实现utils.py 的normalize_metadata会将None、单字典、字典列表统一为与源数量等长的独立字典列表并对单字典逐源deepcopy避免下游对元数据的原地修改污染其他文档。理解这一点有助于排查「为什么所有文档共享同一份元数据引用」之类的隐性坑。在 Pipeline 中使用KreuzbergConverter最常见的管道位置是索引管线的开头、PreProcessors 之前官方指南给出的完整索引管线示例如下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.kreuzberg import KreuzbergConverter document_store InMemoryDocumentStore() pipeline Pipeline() pipeline.add_component(converter, KreuzbergConverter()) pipeline.add_component( splitter, DocumentSplitter(split_bysentence, split_length5), ) pipeline.add_component(writer, DocumentWriter(document_storedocument_store)) pipeline.connect(converter, splitter) pipeline.connect(splitter, writer) pipeline.run({converter: {sources: [report.pdf, presentation.pptx]}})该链路完整呈现了 RAG 索引的标准三步转换 → 切分 → 写入文档库。KreuzbergConverter输出documents: list[Document]其下游可直接对接 DocumentSplitter按句子切分、每 5 句一块再经 DocumentWriter 写入InMemoryDocumentStore。得益于 Haystack 统一的documents输出约定Kreuzberg 可以无缝替换/并存于任何内置 Converter 所在的索引管线位置。构造参数详解KreuzbergConverter的__init__签名如下__init__( *, config: ExtractionConfig | None None, config_path: str | Path | None None, store_full_path: bool False, batch: bool True, easyocr_kwargs: dict[str, Any] | None None ) - None参数类型默认值作用configExtractionConfig \| NoneNone直接传入kreuzberg.ExtractionConfig对象用于定制输出格式、OCR 后端与语言、强制 OCR 模式、按页提取、分块、关键词抽取等行为不传时使用 Kreuzberg 默认配置config_pathstr \| Path \| NoneNone指向 Kreuzberg 配置文件.toml、.yaml或.json的路径不能与config同时使用store_full_pathboolFalse为True时在Document元数据中保存完整文件路径为False时只保存文件名batchboolTrue为True时使用 Kreuzberg 的批量提取 API借助 Rust rayon 线程池并行处理为False时逐个串行提取easyocr_kwargsdict[str, Any] \| NoneNone使用easyocrOCR 后端时透传给 EasyOCR 的关键字参数支持 GPU、beam width、模型存储位置等 EasyOCR 专属选项几个值得展开的细节config与config_path二选一两者都用于注入提取配置API 参考明确标注二者不可同时使用。config_path的适用场景是把提取策略沉淀为团队共享的配置文件TOML/YAML/JSON便于版本管理与跨环境复用详见下文「配置文件驱动」小节。store_full_path的语义与核心组件一致Haystack 内置转换器如 txt.py在store_full_pathFalse时会通过os.path.basename(file_path)将元数据中的file_path降级为纯文件名Kreuzberg 集成遵循同一约定。建议在需要追溯文档来源绝对位置如审计、去重、重新抓取时开启。batch是性能关键开关默认True意味着多文件场景下由 Kreuzberg 的 Rust 侧 rayon 线程池并行抽取吞吐远高于逐文件串行仅在内存受限或需要严格顺序输出的场景才关闭。easyocr_kwargs仅影响easyocr后端当config中 OCR 后端选择 EasyOCR 时此参数可将 GPU 设备、beam width、模型缓存目录等选项透传参考 EasyOCR 官方文档的参数清单。深度定制ExtractionConfig 的三大实用场景ExtractionConfig是 Kreuzberg 提取行为的统一入口。API 参考与组件指南共同展示了三种最常用的定制模式。场景一Markdown 输出 Tesseract OCR扫描件处理from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter from kreuzberg import ExtractionConfig, OcrConfig converter KreuzbergConverter( configExtractionConfig( output_formatmarkdown, ocrOcrConfig(backendtesseract, languageeng), ), ) result converter.run(sources[scanned_document.pdf]) documents result[documents]该配置把输出格式设为markdown保留标题层级、列表等结构信息对下游分块与 LLM 上下文构建更友好并让 OCR 走 Tesseract 后端、语言限定为英语。对于扫描件 PDF无文本层ExtractionConfig还支持强制 OCR 模式确保纯图片型文档也能抽取文本。场景二按页提取每页一个 Documentfrom haystack_integrations.components.converters.kreuzberg import KreuzbergConverter from kreuzberg import ExtractionConfig, PageConfig converter KreuzbergConverter( configExtractionConfig( pagePageConfig(extract_pagesTrue), ), ) result converter.run(sources[multipage.pdf]) # One Document per page, each with page_number in metadata开启PageConfig(extract_pagesTrue)后多页 PDF 会拆成每页一个Document且每个文档的元数据中带有page_number。这一粒度对「引用页码的 RAG」与「按页审核」场景极有价值配合 Haystack 的Document元数据字段见 document.py可直接作为后续 Ranker 或生成器的引用依据。场景三Token Reduction 压缩输出from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter from kreuzberg import ExtractionConfig, TokenReductionConfig converter KreuzbergConverter( configExtractionConfig( token_reductionTokenReductionConfig(modemoderate), ), )Token 缩减面向 LLM 消费场景采用基于 TF-IDF 的抽取式摘要识别并保留最重要的术语与短语逐步剔除多余空白、填充词与冗余表述。共分五档官方指南给出了每档的近似压缩比例模式近似压缩比例off不缩减light约 15%moderate约 30%aggressive约 50%maximum超过 50%缩减后的文本直接体现在Document.content中无需额外后处理即可喂给下游可有效控制长文档索引时的 token 成本与上下文占用。场景四OCR 图像预处理调优对于 OCR 质量敏感的场景API 参考还给出了图像预处理的调优入口OcrConfig( tesseract_configTesseractConfig( preprocessingImagePreprocessingConfig(...) ) )ImagePreprocessingConfig支持目标 DPI、自动旋转auto-rotate、纠偏deskew、去噪denoise、对比度增强与二值化方法等选项。低质量扫描件歪斜、噪点多、光照不均可借此显著提升 OCR 准确率——这是把「能抽」变成「抽得准」的关键旋钮。配置文件驱动config_path当提取策略需要团队级复用或按环境切换时把配置写入独立文件更合适from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter converter KreuzbergConverter(config_pathextraction_config.toml)config_path支持.toml、.yaml、.json三种格式。一个典型的extraction_config.toml可同时表达输出格式、OCR 与 token 缩减策略output_format markdown [ocr] backend tesseract language eng [token_reduction] mode moderate注意config与config_path互斥二者只能择一。完整配置项清单与格式支持矩阵可查阅 Kreuzberg 官方文档docs.kreuzberg.dev。序列化支持to_dict / from_dict作为 Haystack 组件KreuzbergConverter实现了标准的组件序列化协议这对 Pipeline 的 YAML 持久化与反序列化至关重要Haystack 的Pipeline.dumps()/loads()依赖各组件此协议。to_dict() - dict[str, Any]to_dict将组件序列化为字典其中包含组件类型与构造参数。反序列化方法from_dict(data: dict[str, Any]) - KreuzbergConverterfrom_dict接收一个字典通常来自Pipeline.loads()的 YAML/JSON 内容返回一个等价的KreuzbergConverter实例。序列化往返保证了索引管线可以「定义即配置」——例如将包含config_path的组件定义写入 YAML在不同环境中重建完全一致的提取行为。与 Haystack 核心转换器家族的关系把KreuzbergConverter放在 Haystack 转换器生态中看它的定位与核心内置转换器互为补充核心单格式转换器haystack/components/converters/目录下按格式拆分如 txt.py文本、docx.pyWord、pypdf.pyPDF、pptx.pyPPT、xlsx.pyExcel、html.py、markdown.py、json.py 等。它们各自小而专依赖轻。KreuzbergConverter以单一组件覆盖 91 格式内置 Rust 加速与批量并行且在元数据丰富度质量评分、语言检测、关键词、表格数据、PDF 注解与 OCR/图像预处理能力上明显更强。两者共享同一套接口契约run(sources, meta) - {documents: [...]}输入都接受str | Path | ByteStream元数据归一化遵循 utils.py 中normalize_metadata的统一逻辑输出都是带content与meta的Documentdocument.py。这意味着切换到 KreuzbergConverter 不需要改动下游任何组件只需替换索引管线的首节点即可获得格式覆盖与性能的双重提升而当项目只需要极轻量的单格式转换时核心转换器仍是更低依赖的选择。实战建议与注意事项扫描件务必显式配置 OCR纯图片型 PDF 不会自动走 OCR需按「场景一」设置OcrConfig多语言文档记得按需配置language或扩展语言列表。长文档索引优先开 Token Reduction结合「场景三」的五档模式可先用moderate起步再根据检索质量回调。缩减后的文本直接进入Document.content不会额外占用下游字段。需要页码溯源时开启按页提取「场景二」的PageConfig让每个Document携带page_number配合store_full_pathTrue可获得「文件 页码」的完整溯源能力。多文件批量索引保持batchTruerayon 线程池并行抽取是吞吐优势所在仅当内存或顺序敏感时才置为False。配置策略交给文件团队共享提取策略时优先config_pathTOML/YAML/JSON并牢记与config互斥。元数据合并规则meta传列表时长度必须等于sources数量且sources含目录时只能传单个字典ByteStream自带的meta会自动并入输出。小结KreuzbergConverter把「本地化、多格式、高性能」三个诉求收敛到一个组件里Rust 核心负责格式解析与批量并行ExtractionConfig体系提供输出格式、OCR、按页、分块、Token 缩减、图像预处理的精细控制config_path让策略可配置化to_dict/from_dict则保证它无缝融入 Haystack 的 Pipeline 序列化体系。无论你是要搭建企业级 RAG 索引管线、处理历史扫描件还是为 LLM 应用做上下文工程它都是一个值得优先评估的文档入口组件。【免费下载链接】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 集成 KreuzbergConverter：本地化多格式文档转 Document 的完整实战指南
Haystack 集成 KreuzbergConverter本地化多格式文档转 Document 的完整实战指南【免费下载链接】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/haystackKreuzbergConverter是 Haystack 生态中一个以 Rust 为核心的文档智能转换组件它通过kreuzberg-haystack集成包将 PDF、Office 文档、图片及 91 种文件格式在本地转换为 HaystackDocument全程不发起任何外部 API 调用。本文将基于版本化 API 参考docs-website/reference_versioned_docs/version-2.20/integrations-api/kreuzberg.md与官方组件指南docs-website/docs/pipeline-components/converters/kreuzbergconverter.mdx系统讲解其安装、独立使用、Pipeline 集成、ExtractionConfig深度定制与序列化接口并对照 Haystack 核心转换器源码揭示其与生态其余 Converter 的设计异同。为什么选择 Kreuzberg本地化、高覆盖的文档智能抽取KreuzbergConverter的定位非常清晰把「任意常见文档」变成「可供检索与喂给 LLM 的干净文本」。它的底层是 Kreuzberg——一个文档智能框架核心处理逻辑由 Rust 实现支持从 PDF、Office 文档、图片以及 75 其他格式中提取文本。所有处理均在本地完成不依赖任何外部 API这意味着数据不出域、无网络依赖、成本可控非常适合对数据隐私和延迟敏感的企业级索引管线。需要特别说明的是官方组件指南中描述其格式覆盖为 91 种而版本 2.20 的 API 参考写作 75 种两者都是同一组件的不同版本措辞。从当前仓库可见docs-website/docs/pipeline-components/converters/kreuzbergconverter.mdx 与各版本化文档如 version-3.1 版本均采用 91 的描述读者应以官方最新指南为准并将其理解为「随版本持续增长的格式矩阵」。从组件目录结构看该集成属于 Haystack 生态的外置集成包kreuzberg-haystack与 Haystack 核心内置的 pypdf.py、docx.py、pdfminer.py 等单格式转换器形成互补核心包提供「一种格式一个组件」的精细控制而 Kreuzberg 集成以单个组件覆盖海量格式显著降低索引管线的组件数量与维护成本。支持的格式类别总览官方指南将 Kreuzberg 的格式覆盖划分为六类文档类PDF、DOCX、DOC、PPTX、PPT、XLSX、XLS、ODT、ODS、ODP、RTF、Pages、Keynote、Numbers 等图片类经 OCRPNG、JPEG、TIFF、GIF、BMP、WebP、JPEG 2000、SVG文本/标记类Markdown、HTML、XML、LaTeX、Typst、JSON、YAML、reStructuredText、Jupyter Notebook邮件类EML、MSG支持附件提取压缩包类ZIP、TAR、GZIP、7Z递归解压并处理内部内容电子书与学术类EPUB、BibTeX、DocBook、JATS。默认情况下每个源文件生成一个 HaystackDocument当开启按页提取per-page extraction或分块chunking后会改为每页/每块一个Document。生成结果携带丰富的元数据包括质量评分quality scores、检测到的语言、抽取的关键词、表格数据以及 PDF 注解等。快速上手安装与独立使用安装集成包通过 PyPI 分发包名为kreuzberg-haystackpip install kreuzberg-haystack安装完成后即可从haystack_integrations.components.converters.kreuzberg导入组件。独立使用最简单的调用方式与 Haystack 核心转换器保持一致——构造组件后直接调用run()from haystack_integrations.components.converters.kreuzberg import ( KreuzbergConverter, ) converter KreuzbergConverter() result converter.run(sources[document.pdf, report.docx]) documents result[documents]API 参考给出的run签名如下run( sources: list[str | Path | ByteStream], meta: dict[str, Any] | list[dict[str, Any]] | None None, ) - dict[str, list[Document]]几个关键行为sources支持三种类型文件路径字符串、Path对象以及 Haystack 的ByteStream二进制对象定义见 byte_stream.py包含data、meta、mime_type三个字段。这一点与核心转换器一致以 txt.py 为代表的run同样接收sources: list[str | Path | ByteStream]并通过get_bytestream_from_sourceutils.py将路径统一包装成带file_path元数据的ByteStream。目录路径会自动展开当sources中出现目录时会展开为其直接文件子项非递归、按字母序排序。meta的两种形态传单个字典时该字典内容会合并进所有产出Document的元数据传字典列表时其长度必须与sources数量一致两者按位置 zip。若sources中包含ByteStream对象则其自身携带的meta也会被合并进输出Document。目录与列表型meta的冲突当sources中存在目录时由于目录内文件数量在运行前不可知meta必须是单个字典而不能是列表。这一meta归一化机制在核心代码中有完整对应实现utils.py 的normalize_metadata会将None、单字典、字典列表统一为与源数量等长的独立字典列表并对单字典逐源deepcopy避免下游对元数据的原地修改污染其他文档。理解这一点有助于排查「为什么所有文档共享同一份元数据引用」之类的隐性坑。在 Pipeline 中使用KreuzbergConverter最常见的管道位置是索引管线的开头、PreProcessors 之前官方指南给出的完整索引管线示例如下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.kreuzberg import KreuzbergConverter document_store InMemoryDocumentStore() pipeline Pipeline() pipeline.add_component(converter, KreuzbergConverter()) pipeline.add_component( splitter, DocumentSplitter(split_bysentence, split_length5), ) pipeline.add_component(writer, DocumentWriter(document_storedocument_store)) pipeline.connect(converter, splitter) pipeline.connect(splitter, writer) pipeline.run({converter: {sources: [report.pdf, presentation.pptx]}})该链路完整呈现了 RAG 索引的标准三步转换 → 切分 → 写入文档库。KreuzbergConverter输出documents: list[Document]其下游可直接对接 DocumentSplitter按句子切分、每 5 句一块再经 DocumentWriter 写入InMemoryDocumentStore。得益于 Haystack 统一的documents输出约定Kreuzberg 可以无缝替换/并存于任何内置 Converter 所在的索引管线位置。构造参数详解KreuzbergConverter的__init__签名如下__init__( *, config: ExtractionConfig | None None, config_path: str | Path | None None, store_full_path: bool False, batch: bool True, easyocr_kwargs: dict[str, Any] | None None ) - None参数类型默认值作用configExtractionConfig \| NoneNone直接传入kreuzberg.ExtractionConfig对象用于定制输出格式、OCR 后端与语言、强制 OCR 模式、按页提取、分块、关键词抽取等行为不传时使用 Kreuzberg 默认配置config_pathstr \| Path \| NoneNone指向 Kreuzberg 配置文件.toml、.yaml或.json的路径不能与config同时使用store_full_pathboolFalse为True时在Document元数据中保存完整文件路径为False时只保存文件名batchboolTrue为True时使用 Kreuzberg 的批量提取 API借助 Rust rayon 线程池并行处理为False时逐个串行提取easyocr_kwargsdict[str, Any] \| NoneNone使用easyocrOCR 后端时透传给 EasyOCR 的关键字参数支持 GPU、beam width、模型存储位置等 EasyOCR 专属选项几个值得展开的细节config与config_path二选一两者都用于注入提取配置API 参考明确标注二者不可同时使用。config_path的适用场景是把提取策略沉淀为团队共享的配置文件TOML/YAML/JSON便于版本管理与跨环境复用详见下文「配置文件驱动」小节。store_full_path的语义与核心组件一致Haystack 内置转换器如 txt.py在store_full_pathFalse时会通过os.path.basename(file_path)将元数据中的file_path降级为纯文件名Kreuzberg 集成遵循同一约定。建议在需要追溯文档来源绝对位置如审计、去重、重新抓取时开启。batch是性能关键开关默认True意味着多文件场景下由 Kreuzberg 的 Rust 侧 rayon 线程池并行抽取吞吐远高于逐文件串行仅在内存受限或需要严格顺序输出的场景才关闭。easyocr_kwargs仅影响easyocr后端当config中 OCR 后端选择 EasyOCR 时此参数可将 GPU 设备、beam width、模型缓存目录等选项透传参考 EasyOCR 官方文档的参数清单。深度定制ExtractionConfig 的三大实用场景ExtractionConfig是 Kreuzberg 提取行为的统一入口。API 参考与组件指南共同展示了三种最常用的定制模式。场景一Markdown 输出 Tesseract OCR扫描件处理from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter from kreuzberg import ExtractionConfig, OcrConfig converter KreuzbergConverter( configExtractionConfig( output_formatmarkdown, ocrOcrConfig(backendtesseract, languageeng), ), ) result converter.run(sources[scanned_document.pdf]) documents result[documents]该配置把输出格式设为markdown保留标题层级、列表等结构信息对下游分块与 LLM 上下文构建更友好并让 OCR 走 Tesseract 后端、语言限定为英语。对于扫描件 PDF无文本层ExtractionConfig还支持强制 OCR 模式确保纯图片型文档也能抽取文本。场景二按页提取每页一个 Documentfrom haystack_integrations.components.converters.kreuzberg import KreuzbergConverter from kreuzberg import ExtractionConfig, PageConfig converter KreuzbergConverter( configExtractionConfig( pagePageConfig(extract_pagesTrue), ), ) result converter.run(sources[multipage.pdf]) # One Document per page, each with page_number in metadata开启PageConfig(extract_pagesTrue)后多页 PDF 会拆成每页一个Document且每个文档的元数据中带有page_number。这一粒度对「引用页码的 RAG」与「按页审核」场景极有价值配合 Haystack 的Document元数据字段见 document.py可直接作为后续 Ranker 或生成器的引用依据。场景三Token Reduction 压缩输出from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter from kreuzberg import ExtractionConfig, TokenReductionConfig converter KreuzbergConverter( configExtractionConfig( token_reductionTokenReductionConfig(modemoderate), ), )Token 缩减面向 LLM 消费场景采用基于 TF-IDF 的抽取式摘要识别并保留最重要的术语与短语逐步剔除多余空白、填充词与冗余表述。共分五档官方指南给出了每档的近似压缩比例模式近似压缩比例off不缩减light约 15%moderate约 30%aggressive约 50%maximum超过 50%缩减后的文本直接体现在Document.content中无需额外后处理即可喂给下游可有效控制长文档索引时的 token 成本与上下文占用。场景四OCR 图像预处理调优对于 OCR 质量敏感的场景API 参考还给出了图像预处理的调优入口OcrConfig( tesseract_configTesseractConfig( preprocessingImagePreprocessingConfig(...) ) )ImagePreprocessingConfig支持目标 DPI、自动旋转auto-rotate、纠偏deskew、去噪denoise、对比度增强与二值化方法等选项。低质量扫描件歪斜、噪点多、光照不均可借此显著提升 OCR 准确率——这是把「能抽」变成「抽得准」的关键旋钮。配置文件驱动config_path当提取策略需要团队级复用或按环境切换时把配置写入独立文件更合适from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter converter KreuzbergConverter(config_pathextraction_config.toml)config_path支持.toml、.yaml、.json三种格式。一个典型的extraction_config.toml可同时表达输出格式、OCR 与 token 缩减策略output_format markdown [ocr] backend tesseract language eng [token_reduction] mode moderate注意config与config_path互斥二者只能择一。完整配置项清单与格式支持矩阵可查阅 Kreuzberg 官方文档docs.kreuzberg.dev。序列化支持to_dict / from_dict作为 Haystack 组件KreuzbergConverter实现了标准的组件序列化协议这对 Pipeline 的 YAML 持久化与反序列化至关重要Haystack 的Pipeline.dumps()/loads()依赖各组件此协议。to_dict() - dict[str, Any]to_dict将组件序列化为字典其中包含组件类型与构造参数。反序列化方法from_dict(data: dict[str, Any]) - KreuzbergConverterfrom_dict接收一个字典通常来自Pipeline.loads()的 YAML/JSON 内容返回一个等价的KreuzbergConverter实例。序列化往返保证了索引管线可以「定义即配置」——例如将包含config_path的组件定义写入 YAML在不同环境中重建完全一致的提取行为。与 Haystack 核心转换器家族的关系把KreuzbergConverter放在 Haystack 转换器生态中看它的定位与核心内置转换器互为补充核心单格式转换器haystack/components/converters/目录下按格式拆分如 txt.py文本、docx.pyWord、pypdf.pyPDF、pptx.pyPPT、xlsx.pyExcel、html.py、markdown.py、json.py 等。它们各自小而专依赖轻。KreuzbergConverter以单一组件覆盖 91 格式内置 Rust 加速与批量并行且在元数据丰富度质量评分、语言检测、关键词、表格数据、PDF 注解与 OCR/图像预处理能力上明显更强。两者共享同一套接口契约run(sources, meta) - {documents: [...]}输入都接受str | Path | ByteStream元数据归一化遵循 utils.py 中normalize_metadata的统一逻辑输出都是带content与meta的Documentdocument.py。这意味着切换到 KreuzbergConverter 不需要改动下游任何组件只需替换索引管线的首节点即可获得格式覆盖与性能的双重提升而当项目只需要极轻量的单格式转换时核心转换器仍是更低依赖的选择。实战建议与注意事项扫描件务必显式配置 OCR纯图片型 PDF 不会自动走 OCR需按「场景一」设置OcrConfig多语言文档记得按需配置language或扩展语言列表。长文档索引优先开 Token Reduction结合「场景三」的五档模式可先用moderate起步再根据检索质量回调。缩减后的文本直接进入Document.content不会额外占用下游字段。需要页码溯源时开启按页提取「场景二」的PageConfig让每个Document携带page_number配合store_full_pathTrue可获得「文件 页码」的完整溯源能力。多文件批量索引保持batchTruerayon 线程池并行抽取是吞吐优势所在仅当内存或顺序敏感时才置为False。配置策略交给文件团队共享提取策略时优先config_pathTOML/YAML/JSON并牢记与config互斥。元数据合并规则meta传列表时长度必须等于sources数量且sources含目录时只能传单个字典ByteStream自带的meta会自动并入输出。小结KreuzbergConverter把「本地化、多格式、高性能」三个诉求收敛到一个组件里Rust 核心负责格式解析与批量并行ExtractionConfig体系提供输出格式、OCR、按页、分块、Token 缩减、图像预处理的精细控制config_path让策略可配置化to_dict/from_dict则保证它无缝融入 Haystack 的 Pipeline 序列化体系。无论你是要搭建企业级 RAG 索引管线、处理历史扫描件还是为 LLM 应用做上下文工程它都是一个值得优先评估的文档入口组件。【免费下载链接】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），仅供参考