Haystack 2.21 KreuzbergConverter 完整指南本地化多格式文档转换组件的 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本文基于 Haystack 官方文档站 2.21 版本的集成 API 参考页kreuzberg.md完整解读KreuzbergConverter这一文档转换组件它如何将 PDF、Office 文档、图片等 75 种格式的文件在本地提取为 HaystackDocument对象。读完后你可以掌握该组件的全部构造参数config、config_path、store_full_path、batch、easyocr_kwargs、ExtractionConfig的 OCR 与 Token 缩减定制方式以及run方法在sources/meta上的输入输出契约并将其正确接入自己的索引 Pipeline。1. 组件定位Kreuzberg 是什么它属于哪一层KreuzbergConverter的完整导入路径为haystack_integrations.components.converters.kreuzberg.converter根据 API 参考文档Kreuzberg 是一个文档智能document intelligence框架能从 PDF、Office 文档、图片以及 75 种以上其他格式中提取文本所有处理均在本地完成不发起任何外部 API 调用——这使得它适合对数据隐私有要求、或无法依赖云端 OCR 服务的部署场景。需要注意其在 Haystack 生态中的层次关系。本文档所属仓库的核心组件目录haystack/components/converters/下内置了 CSV、DOCX、HTML、JSON、Markdown、PPTX、PDFMiner、PyPDF、TXT、XLSX 等转换器见 converters 目录而 Kreuzberg 属于外部第三方集成通过独立的 PyPI 包kreuzberg-haystack安装代码位于独立的 haystack-core-integrations 集成仓库中。在 2.21 版本文档站的转换器导航页converters.mdx中Kreuzberg 也归入 “External Integrations” 一类。换言之本文描述的是官方 API 参考对第三方集成的收录快照该集成的实现源码不在本仓库内但其输入输出契约完全遵循本仓库定义的Documentdocument.py与ByteStreambyte_stream.py数据类因此可以无缝嵌入任何标准 Haystack Pipeline。2. 安装与最简用法按集成包的包名安装pip install kreuzberg-haystack最简用法——两个文件转成Document列表from haystack_integrations.components.converters.kreuzberg import ( KreuzbergConverter, ) converter KreuzbergConverter() result converter.run(sources[document.pdf, report.docx]) documents result[documents]run返回一个字典唯一的键是documents值为生成的Document列表。默认情况下每个源文件对应一个 Document若启用了按页提取或分块见第 4 节则会变为每页/每块一个 Document。3.__init__构造参数逐项解析KreuzbergConverter的构造函数签名为__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注意第一个*表示所有参数均为关键字参数keyword-only调用时不能按位置传参。各参数含义如下参数类型 / 默认值说明configExtractionConfig \| None默认None可选的kreuzberg.ExtractionConfig对象用于定制提取行为输出格式、OCR 后端与语言、强制 OCR 模式、按页提取、分块、关键词提取等。不提供时使用 kreuzberg 的默认配置config_pathstr \| Path \| None默认Nonekreuzberg 配置文件路径支持.toml、.yaml、.json三种格式。不能与config同时使用二选一store_full_pathbool默认False为True时Document 元数据中保存文件的完整路径为False时只保存文件名batchbool默认True为True时使用 kreuzberg 的批量提取 API利用 Rust 的 rayon 线程池并行处理为False时逐个源文件顺序提取easyocr_kwargsdict[str, Any] \| None默认None当使用easyocrOCR 后端时透传给 EasyOCR 的关键字参数支持 GPU、beam width、模型存储位置等 EasyOCR 专属选项几个实践要点batchTrue是默认行为批量场景下可借助 rayon 线程池获得并行加速在需要严格控制单文件处理顺序或排查单个文件错误时可显式设为False顺序执行。config与config_path互斥设计意图是两种配置风格并存程序化定制直接传ExtractionConfig对象把配置沉淀为 TOML/YAML/JSON 文件、由部署环境管理时则用config_path。easyocr_kwargs仅在 easyocr 后端下有意义例如需要占用 GPU 时可在这里传入 EasyOCR 的对应参数使用 tesseract 后端时该参数不起作用。4. 用ExtractionConfig定制提取行为这是本组件最灵活的扩展面所有高级能力都通过传入 kreuzberg 的ExtractionConfig打开。4.1 指定输出格式与 OCR 后端API 参考给出的标准示例——输出 Markdown 并用 Tesseract 做 OCRfrom kreuzberg import ExtractionConfig, OcrConfig converter KreuzbergConverter( configExtractionConfig( output_formatmarkdown, ocrOcrConfig(backendtesseract, languageeng), ), )output_formatmarkdown让提取结果以 Markdown 结构输出保留了标题、列表等结构信息对下游 LLM 消费更友好OcrConfig(backendtesseract, languageeng)指定 OCR 后端与识别语言切换到backendeasyocr时即可通过构造参数easyocr_kwargs进一步透传 EasyOCR 选项。4.2 Token 缩减为 LLM 消费裁剪文本体积ExtractionConfig支持token_reduction配置用于缩减输出体积、降低 LLM 上下文开销from kreuzberg import ExtractionConfig, TokenReductionConfig converter KreuzbergConverter( configExtractionConfig( token_reductionTokenReductionConfig(modemoderate), ), )共有五个档位off、light、moderate、aggressive、maximum。API 参考页指出缩减后的文本会直接出现在Document.content中——也就是说它影响的是最终产出的文档内容本身而非仅影响某个中间表示。根据当前版本文档站的组件说明kreuzbergconverter.mdx其原理是基于 TF-IDF 的抽取式摘要识别并保留最重要的词与短语逐步去掉额外空白、填充词、冗余表述各档位的参考压缩幅度大致为light约 15%、moderate约 30%、aggressive约 50%、maximum超过 50%off表示不缩减。这一机制对长文档入库做 RAG 时控制嵌入/生成阶段的 token 成本非常实用。4.3 OCR 前的图像预处理对扫描件质量不佳的场景可调整 OCR 前的图像预处理from kreuzberg import ( ExtractionConfig, ImagePreprocessingConfig, OcrConfig, TesseractConfig, ) converter KreuzbergConverter( configExtractionConfig( ocrOcrConfig( backendtesseract, tesseract_configTesseractConfig( preprocessingImagePreprocessingConfig(...) ), ), ), )ImagePreprocessingConfig可调节的选项包括目标 DPI、自动旋转auto-rotate、纠偏deskew、去噪denoise、对比度增强以及二值化方法binarization method。这些参数决定了 Tesseract 拿到的是否是“干净”的输入图对扫描件 OCR 准确率影响直接。4.4 按页提取与其他常用子配置API 参考中列出了config可定制的全部维度“输出格式、OCR 后端与语言、强制 OCR 模式、按页提取、分块、关键词提取以及其他 kreuzberg 选项”。其中按页提取PageConfig在组件文档中有明确示例from kreuzberg import ExtractionConfig, PageConfig converter KreuzbergConverter( configExtractionConfig( pagePageConfig(extract_pagesTrue), ), ) result converter.run(sources[multipage.pdf]) # 每页一个 Document且元数据中含 page_number另外config_path方式等价于把上述配置写进文件后加载converter KreuzbergConverter(config_pathextraction_config.toml)4.5 产出的 Document 携带丰富元数据组件文档指出除默认的整文件 Document 外Kreuzberg 产出的 Document 会附带丰富的元数据例如质量分数、检测到的语言、提取的关键词、表格数据以及 PDF 注解annotations等。这与本仓库Document数据类开放的自由meta字典设计一致见 document.py下游过滤器和检索器都可以直接基于这些元字段做二次加工。5.run方法的输入输出契约run( sources: list[str | Path | ByteStream], meta: dict[str, Any] | list[dict[str, Any]] | None None, ) - dict[str, list[Document]]sources必填文件路径、目录路径或ByteStream对象的列表。当传入的是目录路径时会展开为该目录的直接文件子项——注意是非递归展开且按字母序排序。这也意味着在 Pipeline 中该组件可对接任何能产出ByteStream的上游如文件抓取类组件与 byte_stream.py 定义的数据结构直接互通。meta可选要附加到产出 Document 上的元数据支持两种形态单个字典其内容会加到所有产出 Document 的元数据上字典列表列表长度必须与 sources 数量一致两份列表将按位置一一 zip 配对。若sources中含ByteStream对象它们自身的meta也会被合并进对应输出 Document。目录 meta 的组合限制容易踩坑当sources中存在目录时meta必须是单个字典而不能是列表——因为目录里到底有多少文件事先无法确定无法与列表 zip 对齐。批量入库时如果按目录整批投喂记住这一条约束即可避免运行期报错。返回值dict[str, list[Document]]其中documents键为创建的 Document 列表。6. 序列化to_dict/from_dictto_dict() - dict[str, Any] from_dict(data: dict[str, Any]) - KreuzbergConverter这一对方法遵循 Haystack 组件的通用序列化协议to_dict返回组件的可序列化字典from_dict从字典还原组件实例。其工程价值在于 Pipeline 的 YAML/JSON 持久化——把整个索引 Pipeline 序列化部署时转换器及其配置会随 Pipeline 一起落盘反序列化后恢复相同的运行行为。从本仓库的序列化实现serialization.py可以看到Haystack 核心对组件的to_dict/from_dict做了统一的注册与校验机制第三方集成组件正是通过实现这一对方法接入该体系的。7. 在 Pipeline 中的落位KreuzbergConverter最典型的位点是索引 Pipeline 的入口处位于 Preprocessor / DocumentWriter 之前文件进来 → Kreuzberg 提取为 Document → 切分 → 写入文档库。以本仓库自带的组件为例一个最小可用的接入形态是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]}})其中DocumentSplitter、DocumentWriter、InMemoryDocumentStore均来自本仓库核心切分器见haystack/components/preprocessors/写入器见haystack/components/writers/内存文档库见 in_memory 目录替换成其他文档库与切分策略即可得到生产形态的索引流水线。8. 小结与适用边界适用场景需要本地、离线、免 API 地批量解析 PDF/Office/图片/邮件/压缩包等多种格式并直接产出带丰富元数据Document的索引前置环节关键调优点ExtractionConfig的输出格式与 OCR 配置、TokenReductionConfig的五个档位、OCR 图像预处理参数、batch并行开关注意边界config与config_path互斥sources含目录时meta只能传单字典目录展开为非递归的直接子文件该组件为外部集成包kreuzberg-haystack提供实现不在本仓库haystack/核心代码中但其接口契约与本仓库的Document/ByteStream数据类完全兼容版本提示本文以 2.21 版 API 参考kreuzberg.md为基准当前文档站converters.mdx 中的 kreuzbergconverter.mdx已将支持格式数更新为 91并补充了按页提取、Token 缩减比例等更细的说明升级使用时建议以对应版本文档为准。【免费下载链接】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.21 KreuzbergConverter 完整指南：本地化多格式文档转换组件的 API 与实战
Haystack 2.21 KreuzbergConverter 完整指南本地化多格式文档转换组件的 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本文基于 Haystack 官方文档站 2.21 版本的集成 API 参考页kreuzberg.md完整解读KreuzbergConverter这一文档转换组件它如何将 PDF、Office 文档、图片等 75 种格式的文件在本地提取为 HaystackDocument对象。读完后你可以掌握该组件的全部构造参数config、config_path、store_full_path、batch、easyocr_kwargs、ExtractionConfig的 OCR 与 Token 缩减定制方式以及run方法在sources/meta上的输入输出契约并将其正确接入自己的索引 Pipeline。1. 组件定位Kreuzberg 是什么它属于哪一层KreuzbergConverter的完整导入路径为haystack_integrations.components.converters.kreuzberg.converter根据 API 参考文档Kreuzberg 是一个文档智能document intelligence框架能从 PDF、Office 文档、图片以及 75 种以上其他格式中提取文本所有处理均在本地完成不发起任何外部 API 调用——这使得它适合对数据隐私有要求、或无法依赖云端 OCR 服务的部署场景。需要注意其在 Haystack 生态中的层次关系。本文档所属仓库的核心组件目录haystack/components/converters/下内置了 CSV、DOCX、HTML、JSON、Markdown、PPTX、PDFMiner、PyPDF、TXT、XLSX 等转换器见 converters 目录而 Kreuzberg 属于外部第三方集成通过独立的 PyPI 包kreuzberg-haystack安装代码位于独立的 haystack-core-integrations 集成仓库中。在 2.21 版本文档站的转换器导航页converters.mdx中Kreuzberg 也归入 “External Integrations” 一类。换言之本文描述的是官方 API 参考对第三方集成的收录快照该集成的实现源码不在本仓库内但其输入输出契约完全遵循本仓库定义的Documentdocument.py与ByteStreambyte_stream.py数据类因此可以无缝嵌入任何标准 Haystack Pipeline。2. 安装与最简用法按集成包的包名安装pip install kreuzberg-haystack最简用法——两个文件转成Document列表from haystack_integrations.components.converters.kreuzberg import ( KreuzbergConverter, ) converter KreuzbergConverter() result converter.run(sources[document.pdf, report.docx]) documents result[documents]run返回一个字典唯一的键是documents值为生成的Document列表。默认情况下每个源文件对应一个 Document若启用了按页提取或分块见第 4 节则会变为每页/每块一个 Document。3.__init__构造参数逐项解析KreuzbergConverter的构造函数签名为__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注意第一个*表示所有参数均为关键字参数keyword-only调用时不能按位置传参。各参数含义如下参数类型 / 默认值说明configExtractionConfig \| None默认None可选的kreuzberg.ExtractionConfig对象用于定制提取行为输出格式、OCR 后端与语言、强制 OCR 模式、按页提取、分块、关键词提取等。不提供时使用 kreuzberg 的默认配置config_pathstr \| Path \| None默认Nonekreuzberg 配置文件路径支持.toml、.yaml、.json三种格式。不能与config同时使用二选一store_full_pathbool默认False为True时Document 元数据中保存文件的完整路径为False时只保存文件名batchbool默认True为True时使用 kreuzberg 的批量提取 API利用 Rust 的 rayon 线程池并行处理为False时逐个源文件顺序提取easyocr_kwargsdict[str, Any] \| None默认None当使用easyocrOCR 后端时透传给 EasyOCR 的关键字参数支持 GPU、beam width、模型存储位置等 EasyOCR 专属选项几个实践要点batchTrue是默认行为批量场景下可借助 rayon 线程池获得并行加速在需要严格控制单文件处理顺序或排查单个文件错误时可显式设为False顺序执行。config与config_path互斥设计意图是两种配置风格并存程序化定制直接传ExtractionConfig对象把配置沉淀为 TOML/YAML/JSON 文件、由部署环境管理时则用config_path。easyocr_kwargs仅在 easyocr 后端下有意义例如需要占用 GPU 时可在这里传入 EasyOCR 的对应参数使用 tesseract 后端时该参数不起作用。4. 用ExtractionConfig定制提取行为这是本组件最灵活的扩展面所有高级能力都通过传入 kreuzberg 的ExtractionConfig打开。4.1 指定输出格式与 OCR 后端API 参考给出的标准示例——输出 Markdown 并用 Tesseract 做 OCRfrom kreuzberg import ExtractionConfig, OcrConfig converter KreuzbergConverter( configExtractionConfig( output_formatmarkdown, ocrOcrConfig(backendtesseract, languageeng), ), )output_formatmarkdown让提取结果以 Markdown 结构输出保留了标题、列表等结构信息对下游 LLM 消费更友好OcrConfig(backendtesseract, languageeng)指定 OCR 后端与识别语言切换到backendeasyocr时即可通过构造参数easyocr_kwargs进一步透传 EasyOCR 选项。4.2 Token 缩减为 LLM 消费裁剪文本体积ExtractionConfig支持token_reduction配置用于缩减输出体积、降低 LLM 上下文开销from kreuzberg import ExtractionConfig, TokenReductionConfig converter KreuzbergConverter( configExtractionConfig( token_reductionTokenReductionConfig(modemoderate), ), )共有五个档位off、light、moderate、aggressive、maximum。API 参考页指出缩减后的文本会直接出现在Document.content中——也就是说它影响的是最终产出的文档内容本身而非仅影响某个中间表示。根据当前版本文档站的组件说明kreuzbergconverter.mdx其原理是基于 TF-IDF 的抽取式摘要识别并保留最重要的词与短语逐步去掉额外空白、填充词、冗余表述各档位的参考压缩幅度大致为light约 15%、moderate约 30%、aggressive约 50%、maximum超过 50%off表示不缩减。这一机制对长文档入库做 RAG 时控制嵌入/生成阶段的 token 成本非常实用。4.3 OCR 前的图像预处理对扫描件质量不佳的场景可调整 OCR 前的图像预处理from kreuzberg import ( ExtractionConfig, ImagePreprocessingConfig, OcrConfig, TesseractConfig, ) converter KreuzbergConverter( configExtractionConfig( ocrOcrConfig( backendtesseract, tesseract_configTesseractConfig( preprocessingImagePreprocessingConfig(...) ), ), ), )ImagePreprocessingConfig可调节的选项包括目标 DPI、自动旋转auto-rotate、纠偏deskew、去噪denoise、对比度增强以及二值化方法binarization method。这些参数决定了 Tesseract 拿到的是否是“干净”的输入图对扫描件 OCR 准确率影响直接。4.4 按页提取与其他常用子配置API 参考中列出了config可定制的全部维度“输出格式、OCR 后端与语言、强制 OCR 模式、按页提取、分块、关键词提取以及其他 kreuzberg 选项”。其中按页提取PageConfig在组件文档中有明确示例from kreuzberg import ExtractionConfig, PageConfig converter KreuzbergConverter( configExtractionConfig( pagePageConfig(extract_pagesTrue), ), ) result converter.run(sources[multipage.pdf]) # 每页一个 Document且元数据中含 page_number另外config_path方式等价于把上述配置写进文件后加载converter KreuzbergConverter(config_pathextraction_config.toml)4.5 产出的 Document 携带丰富元数据组件文档指出除默认的整文件 Document 外Kreuzberg 产出的 Document 会附带丰富的元数据例如质量分数、检测到的语言、提取的关键词、表格数据以及 PDF 注解annotations等。这与本仓库Document数据类开放的自由meta字典设计一致见 document.py下游过滤器和检索器都可以直接基于这些元字段做二次加工。5.run方法的输入输出契约run( sources: list[str | Path | ByteStream], meta: dict[str, Any] | list[dict[str, Any]] | None None, ) - dict[str, list[Document]]sources必填文件路径、目录路径或ByteStream对象的列表。当传入的是目录路径时会展开为该目录的直接文件子项——注意是非递归展开且按字母序排序。这也意味着在 Pipeline 中该组件可对接任何能产出ByteStream的上游如文件抓取类组件与 byte_stream.py 定义的数据结构直接互通。meta可选要附加到产出 Document 上的元数据支持两种形态单个字典其内容会加到所有产出 Document 的元数据上字典列表列表长度必须与 sources 数量一致两份列表将按位置一一 zip 配对。若sources中含ByteStream对象它们自身的meta也会被合并进对应输出 Document。目录 meta 的组合限制容易踩坑当sources中存在目录时meta必须是单个字典而不能是列表——因为目录里到底有多少文件事先无法确定无法与列表 zip 对齐。批量入库时如果按目录整批投喂记住这一条约束即可避免运行期报错。返回值dict[str, list[Document]]其中documents键为创建的 Document 列表。6. 序列化to_dict/from_dictto_dict() - dict[str, Any] from_dict(data: dict[str, Any]) - KreuzbergConverter这一对方法遵循 Haystack 组件的通用序列化协议to_dict返回组件的可序列化字典from_dict从字典还原组件实例。其工程价值在于 Pipeline 的 YAML/JSON 持久化——把整个索引 Pipeline 序列化部署时转换器及其配置会随 Pipeline 一起落盘反序列化后恢复相同的运行行为。从本仓库的序列化实现serialization.py可以看到Haystack 核心对组件的to_dict/from_dict做了统一的注册与校验机制第三方集成组件正是通过实现这一对方法接入该体系的。7. 在 Pipeline 中的落位KreuzbergConverter最典型的位点是索引 Pipeline 的入口处位于 Preprocessor / DocumentWriter 之前文件进来 → Kreuzberg 提取为 Document → 切分 → 写入文档库。以本仓库自带的组件为例一个最小可用的接入形态是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]}})其中DocumentSplitter、DocumentWriter、InMemoryDocumentStore均来自本仓库核心切分器见haystack/components/preprocessors/写入器见haystack/components/writers/内存文档库见 in_memory 目录替换成其他文档库与切分策略即可得到生产形态的索引流水线。8. 小结与适用边界适用场景需要本地、离线、免 API 地批量解析 PDF/Office/图片/邮件/压缩包等多种格式并直接产出带丰富元数据Document的索引前置环节关键调优点ExtractionConfig的输出格式与 OCR 配置、TokenReductionConfig的五个档位、OCR 图像预处理参数、batch并行开关注意边界config与config_path互斥sources含目录时meta只能传单字典目录展开为非递归的直接子文件该组件为外部集成包kreuzberg-haystack提供实现不在本仓库haystack/核心代码中但其接口契约与本仓库的Document/ByteStream数据类完全兼容版本提示本文以 2.21 版 API 参考kreuzberg.md为基准当前文档站converters.mdx 中的 kreuzbergconverter.mdx已将支持格式数更新为 91并补充了按页提取、Token 缩减比例等更细的说明升级使用时建议以对应版本文档为准。【免费下载链接】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），仅供参考