Haystack 2.21 AzureOCRDocumentConverter 集成指南基于 Azure Document Intelligence 的复杂文档转换【免费下载链接】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 版本中AzureOCRDocumentConverter集成组件的 API 参考展开系统讲解该组件如何调用 Azure Document Intelligence原 Form Recognizer服务将 PDF、扫描件、Office 文档与 HTML 等 9 种格式的文件批量转换为 HaystackDocument对象读完你将掌握其全部初始化参数表格上下文、阅读顺序、路径存储策略、run方法的输入输出契约、序列化行为以及在索引流水线中接入该组件的完整方式。组件定位与适用场景AzureOCRDocumentConverter属于 Haystack 的转换器Converter类组件位于数据索引流水线的最前端最典型的位置是在 PreProcessors 之前或干脆作为索引管线的第一个组件。它负责把原始文件文件路径或ByteStream对象交给 Azure 云端服务做 OCR 与版面分析再转换回 Haystack 内存中的Document列表。按 2.21 版组件文档 与 本 API 参考文档 的说明该组件支持的文件格式包括PDF含可搜索与纯扫描版、JPEG、PNG、BMP、TIFF、DOCX、XLSX、PPTX 以及 HTML。使用它需要一个活跃的 Azure 账户以及一个 Document Intelligence 或 Cognitive Services 资源资源创建流程请参考 Azure 官方文档API 参考 中的 Azure documentation 链接指向的快速入门页。与纯本地转换器相比它的核心优势在于处理复杂版面组件不会把表格压平成纯文本而是为表格生成独立的Document对象并标记为table类型从而保留表格的二维结构——这一点在处理含大量报表、账单的语料库时非常关键。安装与环境准备使用本组件涉及两层依赖集成包。该组件的正式 API 参考路径为haystack_integrations.components.converters.azure_form_recognizer即由外部集成包azure-form-recognizer-haystack提供安装方式为pip install azure-form-recognizer-haystack其底层依赖 Azure SDK 的表单识别客户端azure-ai-formrecognizer2.21 版组件文档要求3.2.0b2。Azure 资源凭据。组件默认从环境变量AZURE_AI_API_KEY读取 API Key也可用Secret.from_env_var(CORE_AZURE_CS_API_KEY)等方式指向自定义变量资源端点 URL 必须显式传入endpoint参数。需要注意的演进背景该组件早期直接内置于 Haystack 核心包haystack.components.converters后来被标记为弃用并迁移至独立的集成包。仓库中的发布说明 deprecate-azure-ocr-converter-146df0c8cf40902e.yaml 明确记录了迁移路径继续使用者应安装azure-form-recognizer-haystack并改用haystack_integrations.components.converters.azure_form_recognizer的导入路径。因此在 2.21 版本上两套导入路径都可能见到新代码建议统一采用集成包路径。快速上手独立调用示例API 参考文档给出的标准用法如下import os from datetime import datetime from haystack_integrations.components.converters.azure_form_recognizer import AzureOCRDocumentConverter from haystack.utils import Secret converter AzureOCRDocumentConverter( endpointos.environ[CORE_AZURE_CS_ENDPOINT], api_keySecret.from_env_var(CORE_AZURE_CS_API_KEY), ) results converter.run( sources[test/test_files/pdf/react_paper.pdf], meta{date_added: datetime.now().isoformat()}, ) documents results[documents] print(documents[0].content) # This is a text from the PDF file.要点说明api_key通过Secret封装传入支持环境变量或明文 tokenSecret.from_token(your-api-key)两种构造方式避免密钥硬编码meta传入单个字典时会附加到该次调用产出的所有Document上run的返回值是字典除documents外还包含raw_azure_response即 Azure 的原始响应便于做二次解析或问题排查。初始化参数详解init组件构造签名为__init__( endpoint: str, api_key: Secret Secret.from_env_var(AZURE_AI_API_KEY), model_id: str prebuilt-read, preceding_context_len: int 3, following_context_len: int 3, merge_multiple_column_headers: bool True, page_layout: Literal[natural, single_column] natural, threshold_y: float | None 0.05, store_full_path: bool False, ) - None各参数的作用与默认值如下表参数类型 / 默认值说明endpointstr必填Azure 资源的服务端点 URLapi_keySecret默认Secret.from_env_var(AZURE_AI_API_KEY)Azure 资源的 API Key从环境变量AZURE_AI_API_KEY读取model_idstr默认prebuilt-read指定 Azure 分析模型可用模型列表以 Azure 官方文档choose-model-feature 页为准preceding_context_lenint默认3提取表格时向前附带的前置文本行数写入元数据following_context_lenint默认3提取表格时向后附带的后置文本行数写入元数据merge_multiple_column_headersbool默认True为True时把多行表头合并为单行表头page_layoutLiteral[natural, single_column]默认natural阅读顺序策略见下文详解threshold_yfloat \| None默认0.05仅当page_layoutsingle_column时生效单位英寸store_full_pathbool默认False为True时在文档元数据中存储文件完整路径否则只存文件名表格上下文参数preceding / following_context_len这两个参数解决了表格脱离正文后语义不完整的问题当组件为表格生成独立Document时会把表格前后各n行文本一并写入该表格文档的元数据供下游检索与生成环节恢复上下文。这两个能力由发布说明 azure-ocr-converter-enhancements-c882456cad9a5efc.yaml 佐证是后来为提升复杂版面转换准确性而增强加入的特性。阅读顺序参数page_layout 与 threshold_ypage_layoutnatural直接采用 Azure 识别出的自然阅读顺序适合绝大多数文档page_layoutsingle_column按单栏处理把页面上高度相近的行归并为同一行。归并的判定阈值由threshold_y英寸控制。threshold_y的实际意义在于处理横向空间上分离的元素例如章节标题与编号、跨栏的标题与正文它们在竖直方向高度接近但水平方向分开若按自然顺序容易被拆断。调大threshold_y会让更多元素被合并到同一行适合多栏报纸式版面调小则更保守。从参数设计看该值只对single_column模式生效。元数据路径策略store_full_pathstore_full_path控制输出文档元数据中记录的路径粒度True时记录完整路径False时只记录文件名。仓库发布说明 add-store-full-path-param-to-converters-5bd32a7561abfe78.yaml 显示该参数最初默认值为True之后出于隐私考虑在后续版本调整为False——2.21 版 API 参考中该默认值已是False。在多租户或跨环境部署时建议保持False避免把宿主机绝对路径泄漏到语料库元数据中。生命周期管理warm_up 与 close组件提供显式的客户端生命周期方法def warm_up(self) - None: Create the Azure Document Analysis client. def close(self) - None: Close the Azure Document Analysis client.warm_up()负责创建 Azure Document Analysis 客户端实例。在 Haystack 流水线中组件的warm_up会在管线启动阶段被统一调用因此通常无需手动触发close()用于关闭该客户端并释放连接资源适合长驻服务在退出前显式调用避免悬挂连接。这一初始化时不建立连接、运行时惰性创建客户端的设计也与 Haystack 组件统一的资源生命周期约定一致。run 方法输入契约与输出结构def run( self, sources: list[str | Path | ByteStream], meta: dict[str, Any] | list[dict[str, Any]] | None None, ) - dict[str, Any]输入sources 与 meta 的三种匹配规则sources文件路径str或Path或ByteStream对象列表。传入ByteStream时适合与上游的文件抓取组件如 LinkContentFetcher 类串联无需落盘meta支持三种形态规则如下单个字典其内容会合并附加到本次调用产出的所有Document上。仓库发布说明 single-meta-in-azureconverter-ce1cc196a9b161f3.yaml 明确记录了这一增强允许在源文件数量未知时为全部文件统一附加元数据如{date_added: ...}字典列表列表长度必须与sources一一对应两者按位置 zip 配对实现逐文件的差异化元数据None不附加额外元数据若sources中的项为ByteStream其自带meta会自动并入输出Document的元数据。输出documents 与 raw_azure_response返回字典包含两个键documents转换生成的Document列表。其中正文为文本型文档表格为独立的table型文档表格文档的元数据中携带前后上下文行raw_azure_responseAzure 返回的原始响应列表。保留原始响应的价值在于当需要对版面块region、置信度或表格单元格做自定义二次解析时不必重新发起云端请求。序列化to_dict / from_dictdef to_dict(self) - dict[str, Any]: Serializes the component to a dictionary. def from_dict(self, data: dict[str, Any]) - AzureOCRDocumentConverter: Deserializes the component from a dictionary.这两个方法使组件能够随 Haystack 流水线一起被序列化、存储与重建例如通过Pipeline.dumps()保存 YAML 再加载。有一个值得注意的安全设计从源码发布说明 remove-api-key-from-serialization-2474a1539b86e233.yaml 可以看到api_key被刻意排除在序列化输出之外——反序列化后组件会重新从环境变量AZURE_AI_API_KEY读取密钥。这意味着把管线 YAML 提交到版本库或共享给他人时不会意外泄露 Azure 凭据但也意味着部署环境必须配置好同名环境变量。在索引流水线中的完整用法2.21 版组件文档给出了典型的转换 → 清洗 → 切分 → 写入索引管线from haystack import Pipeline from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack.components.converters import AzureOCRDocumentConverter from haystack.components.preprocessors import DocumentCleaner, DocumentSplitter from haystack.components.writers import DocumentWriter from haystack.utils import Secret document_store InMemoryDocumentStore() pipeline Pipeline() pipeline.add_component( converter, AzureOCRDocumentConverter( endpointazure_resource_url, api_keySecret.from_token(your-api-key), ), ) pipeline.add_component(cleaner, DocumentCleaner()) pipeline.add_component(splitter, DocumentSplitter(split_bysentence, split_length5)) pipeline.add_component(writer, DocumentWriter(document_storedocument_store)) pipeline.connect(converter, cleaner) pipeline.connect(cleaner, splitter) pipeline.connect(splitter, writer) file_names [my_file.pdf] pipeline.run({converter: {sources: file_names}})使用时的实操要点该示例使用haystack.components.converters导入2.21 时期核心包仍内置该组件且已弃用迁移到 3.x 后请改用haystack_integrations.components.converters.azure_form_recognizerDocumentCleaner承接转换器输出时需要注意表格类文档的特殊性——DocumentCleaner 文档 中提到其对表格文本的支持范围串联前建议先用小样本验证表格文档经过清洗与切分后的形态是否符合预期由于转换发生在云端管线对 Azure 资源有网络依赖与配额消耗生产环境应关注请求批量与限流行为并利用raw_azure_response排查单文件转换异常。版本演进小结从仓库发布说明可以还原该组件的能力演进脉络便于判断你所在版本支持哪些参数组件引入add-azure_ocr_doc_converter-935130b3b243d236.yaml最初以预览特性加入表格与文本高级处理增强前后上下文、表头合并、单栏版面azure-ocr-converter-enhancements-c882456cad9a5efc.yaml单一 meta 字典支持single-meta-in-azureconverter-ce1cc196a9b161f3.yamlstore_full_path参数引入及默认值隐私化调整add-store-full-path-param-to-converters-5bd32a7561abfe78.yamlapi_key移出序列化remove-api-key-from-serialization-2474a1539b86e233.yaml弃用并迁移至独立集成包deprecate-azure-ocr-converter-146df0c8cf40902e.yaml。在 2.21 版本上AzureOCRDocumentConverter提供了以云端 OCR 换取高质量复杂版面解析的完整方案表格保留二维结构、支持阅读顺序定制与表格上下文元数据、序列化安全且可嵌入任意索引管线。若你处理的是扫描件 PDF、多栏报表或 Office 导出文档它值得作为转换器层的备选若文档均为结构规整的文本型 PDF则本地转换器在延迟与成本上通常更具优势。【免费下载链接】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 AzureOCRDocumentConverter 集成指南：基于 Azure Document Intelligence 的复杂文档转换
Haystack 2.21 AzureOCRDocumentConverter 集成指南基于 Azure Document Intelligence 的复杂文档转换【免费下载链接】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 版本中AzureOCRDocumentConverter集成组件的 API 参考展开系统讲解该组件如何调用 Azure Document Intelligence原 Form Recognizer服务将 PDF、扫描件、Office 文档与 HTML 等 9 种格式的文件批量转换为 HaystackDocument对象读完你将掌握其全部初始化参数表格上下文、阅读顺序、路径存储策略、run方法的输入输出契约、序列化行为以及在索引流水线中接入该组件的完整方式。组件定位与适用场景AzureOCRDocumentConverter属于 Haystack 的转换器Converter类组件位于数据索引流水线的最前端最典型的位置是在 PreProcessors 之前或干脆作为索引管线的第一个组件。它负责把原始文件文件路径或ByteStream对象交给 Azure 云端服务做 OCR 与版面分析再转换回 Haystack 内存中的Document列表。按 2.21 版组件文档 与 本 API 参考文档 的说明该组件支持的文件格式包括PDF含可搜索与纯扫描版、JPEG、PNG、BMP、TIFF、DOCX、XLSX、PPTX 以及 HTML。使用它需要一个活跃的 Azure 账户以及一个 Document Intelligence 或 Cognitive Services 资源资源创建流程请参考 Azure 官方文档API 参考 中的 Azure documentation 链接指向的快速入门页。与纯本地转换器相比它的核心优势在于处理复杂版面组件不会把表格压平成纯文本而是为表格生成独立的Document对象并标记为table类型从而保留表格的二维结构——这一点在处理含大量报表、账单的语料库时非常关键。安装与环境准备使用本组件涉及两层依赖集成包。该组件的正式 API 参考路径为haystack_integrations.components.converters.azure_form_recognizer即由外部集成包azure-form-recognizer-haystack提供安装方式为pip install azure-form-recognizer-haystack其底层依赖 Azure SDK 的表单识别客户端azure-ai-formrecognizer2.21 版组件文档要求3.2.0b2。Azure 资源凭据。组件默认从环境变量AZURE_AI_API_KEY读取 API Key也可用Secret.from_env_var(CORE_AZURE_CS_API_KEY)等方式指向自定义变量资源端点 URL 必须显式传入endpoint参数。需要注意的演进背景该组件早期直接内置于 Haystack 核心包haystack.components.converters后来被标记为弃用并迁移至独立的集成包。仓库中的发布说明 deprecate-azure-ocr-converter-146df0c8cf40902e.yaml 明确记录了迁移路径继续使用者应安装azure-form-recognizer-haystack并改用haystack_integrations.components.converters.azure_form_recognizer的导入路径。因此在 2.21 版本上两套导入路径都可能见到新代码建议统一采用集成包路径。快速上手独立调用示例API 参考文档给出的标准用法如下import os from datetime import datetime from haystack_integrations.components.converters.azure_form_recognizer import AzureOCRDocumentConverter from haystack.utils import Secret converter AzureOCRDocumentConverter( endpointos.environ[CORE_AZURE_CS_ENDPOINT], api_keySecret.from_env_var(CORE_AZURE_CS_API_KEY), ) results converter.run( sources[test/test_files/pdf/react_paper.pdf], meta{date_added: datetime.now().isoformat()}, ) documents results[documents] print(documents[0].content) # This is a text from the PDF file.要点说明api_key通过Secret封装传入支持环境变量或明文 tokenSecret.from_token(your-api-key)两种构造方式避免密钥硬编码meta传入单个字典时会附加到该次调用产出的所有Document上run的返回值是字典除documents外还包含raw_azure_response即 Azure 的原始响应便于做二次解析或问题排查。初始化参数详解init组件构造签名为__init__( endpoint: str, api_key: Secret Secret.from_env_var(AZURE_AI_API_KEY), model_id: str prebuilt-read, preceding_context_len: int 3, following_context_len: int 3, merge_multiple_column_headers: bool True, page_layout: Literal[natural, single_column] natural, threshold_y: float | None 0.05, store_full_path: bool False, ) - None各参数的作用与默认值如下表参数类型 / 默认值说明endpointstr必填Azure 资源的服务端点 URLapi_keySecret默认Secret.from_env_var(AZURE_AI_API_KEY)Azure 资源的 API Key从环境变量AZURE_AI_API_KEY读取model_idstr默认prebuilt-read指定 Azure 分析模型可用模型列表以 Azure 官方文档choose-model-feature 页为准preceding_context_lenint默认3提取表格时向前附带的前置文本行数写入元数据following_context_lenint默认3提取表格时向后附带的后置文本行数写入元数据merge_multiple_column_headersbool默认True为True时把多行表头合并为单行表头page_layoutLiteral[natural, single_column]默认natural阅读顺序策略见下文详解threshold_yfloat \| None默认0.05仅当page_layoutsingle_column时生效单位英寸store_full_pathbool默认False为True时在文档元数据中存储文件完整路径否则只存文件名表格上下文参数preceding / following_context_len这两个参数解决了表格脱离正文后语义不完整的问题当组件为表格生成独立Document时会把表格前后各n行文本一并写入该表格文档的元数据供下游检索与生成环节恢复上下文。这两个能力由发布说明 azure-ocr-converter-enhancements-c882456cad9a5efc.yaml 佐证是后来为提升复杂版面转换准确性而增强加入的特性。阅读顺序参数page_layout 与 threshold_ypage_layoutnatural直接采用 Azure 识别出的自然阅读顺序适合绝大多数文档page_layoutsingle_column按单栏处理把页面上高度相近的行归并为同一行。归并的判定阈值由threshold_y英寸控制。threshold_y的实际意义在于处理横向空间上分离的元素例如章节标题与编号、跨栏的标题与正文它们在竖直方向高度接近但水平方向分开若按自然顺序容易被拆断。调大threshold_y会让更多元素被合并到同一行适合多栏报纸式版面调小则更保守。从参数设计看该值只对single_column模式生效。元数据路径策略store_full_pathstore_full_path控制输出文档元数据中记录的路径粒度True时记录完整路径False时只记录文件名。仓库发布说明 add-store-full-path-param-to-converters-5bd32a7561abfe78.yaml 显示该参数最初默认值为True之后出于隐私考虑在后续版本调整为False——2.21 版 API 参考中该默认值已是False。在多租户或跨环境部署时建议保持False避免把宿主机绝对路径泄漏到语料库元数据中。生命周期管理warm_up 与 close组件提供显式的客户端生命周期方法def warm_up(self) - None: Create the Azure Document Analysis client. def close(self) - None: Close the Azure Document Analysis client.warm_up()负责创建 Azure Document Analysis 客户端实例。在 Haystack 流水线中组件的warm_up会在管线启动阶段被统一调用因此通常无需手动触发close()用于关闭该客户端并释放连接资源适合长驻服务在退出前显式调用避免悬挂连接。这一初始化时不建立连接、运行时惰性创建客户端的设计也与 Haystack 组件统一的资源生命周期约定一致。run 方法输入契约与输出结构def run( self, sources: list[str | Path | ByteStream], meta: dict[str, Any] | list[dict[str, Any]] | None None, ) - dict[str, Any]输入sources 与 meta 的三种匹配规则sources文件路径str或Path或ByteStream对象列表。传入ByteStream时适合与上游的文件抓取组件如 LinkContentFetcher 类串联无需落盘meta支持三种形态规则如下单个字典其内容会合并附加到本次调用产出的所有Document上。仓库发布说明 single-meta-in-azureconverter-ce1cc196a9b161f3.yaml 明确记录了这一增强允许在源文件数量未知时为全部文件统一附加元数据如{date_added: ...}字典列表列表长度必须与sources一一对应两者按位置 zip 配对实现逐文件的差异化元数据None不附加额外元数据若sources中的项为ByteStream其自带meta会自动并入输出Document的元数据。输出documents 与 raw_azure_response返回字典包含两个键documents转换生成的Document列表。其中正文为文本型文档表格为独立的table型文档表格文档的元数据中携带前后上下文行raw_azure_responseAzure 返回的原始响应列表。保留原始响应的价值在于当需要对版面块region、置信度或表格单元格做自定义二次解析时不必重新发起云端请求。序列化to_dict / from_dictdef to_dict(self) - dict[str, Any]: Serializes the component to a dictionary. def from_dict(self, data: dict[str, Any]) - AzureOCRDocumentConverter: Deserializes the component from a dictionary.这两个方法使组件能够随 Haystack 流水线一起被序列化、存储与重建例如通过Pipeline.dumps()保存 YAML 再加载。有一个值得注意的安全设计从源码发布说明 remove-api-key-from-serialization-2474a1539b86e233.yaml 可以看到api_key被刻意排除在序列化输出之外——反序列化后组件会重新从环境变量AZURE_AI_API_KEY读取密钥。这意味着把管线 YAML 提交到版本库或共享给他人时不会意外泄露 Azure 凭据但也意味着部署环境必须配置好同名环境变量。在索引流水线中的完整用法2.21 版组件文档给出了典型的转换 → 清洗 → 切分 → 写入索引管线from haystack import Pipeline from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack.components.converters import AzureOCRDocumentConverter from haystack.components.preprocessors import DocumentCleaner, DocumentSplitter from haystack.components.writers import DocumentWriter from haystack.utils import Secret document_store InMemoryDocumentStore() pipeline Pipeline() pipeline.add_component( converter, AzureOCRDocumentConverter( endpointazure_resource_url, api_keySecret.from_token(your-api-key), ), ) pipeline.add_component(cleaner, DocumentCleaner()) pipeline.add_component(splitter, DocumentSplitter(split_bysentence, split_length5)) pipeline.add_component(writer, DocumentWriter(document_storedocument_store)) pipeline.connect(converter, cleaner) pipeline.connect(cleaner, splitter) pipeline.connect(splitter, writer) file_names [my_file.pdf] pipeline.run({converter: {sources: file_names}})使用时的实操要点该示例使用haystack.components.converters导入2.21 时期核心包仍内置该组件且已弃用迁移到 3.x 后请改用haystack_integrations.components.converters.azure_form_recognizerDocumentCleaner承接转换器输出时需要注意表格类文档的特殊性——DocumentCleaner 文档 中提到其对表格文本的支持范围串联前建议先用小样本验证表格文档经过清洗与切分后的形态是否符合预期由于转换发生在云端管线对 Azure 资源有网络依赖与配额消耗生产环境应关注请求批量与限流行为并利用raw_azure_response排查单文件转换异常。版本演进小结从仓库发布说明可以还原该组件的能力演进脉络便于判断你所在版本支持哪些参数组件引入add-azure_ocr_doc_converter-935130b3b243d236.yaml最初以预览特性加入表格与文本高级处理增强前后上下文、表头合并、单栏版面azure-ocr-converter-enhancements-c882456cad9a5efc.yaml单一 meta 字典支持single-meta-in-azureconverter-ce1cc196a9b161f3.yamlstore_full_path参数引入及默认值隐私化调整add-store-full-path-param-to-converters-5bd32a7561abfe78.yamlapi_key移出序列化remove-api-key-from-serialization-2474a1539b86e233.yaml弃用并迁移至独立集成包deprecate-azure-ocr-converter-146df0c8cf40902e.yaml。在 2.21 版本上AzureOCRDocumentConverter提供了以云端 OCR 换取高质量复杂版面解析的完整方案表格保留二维结构、支持阅读顺序定制与表格上下文元数据、序列化安全且可嵌入任意索引管线。若你处理的是扫描件 PDF、多栏报表或 Office 导出文档它值得作为转换器层的备选若文档均为结构规整的文本型 PDF则本地转换器在延迟与成本上通常更具优势。【免费下载链接】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），仅供参考