Haystack Azure 集成实战：使用 AzureOCRDocumentConverter 调用 Azure 文档智能服务进行 OCR 文档转换

Haystack Azure 集成实战使用 AzureOCRDocumentConverter 调用 Azure 文档智能服务进行 OCR 文档转换【免费下载链接】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/haystackAzureOCRDocumentConverter是 Haystack 生态中对接 Azure 文档智能Document Intelligence服务的文档转换组件用于将 PDF、JPEG、PNG 等十余种格式的文件批量转换为 HaystackDocument对象。本文以该组件的 API 参考为骨架完整讲解其安装迁移、构造参数、运行方式、表格处理细节与生命周期方法并结合当前仓库的官方组件指南与发布说明release notes补充源码级演进依据帮助你在一套 RAG / 语义检索索引流水线中正确、高效地接入 Azure OCR。组件定位与适用场景AzureOCRDocumentConverter位于haystack_integrations.components.converters.azure_form_recognizer模块其核心职责是输入文件路径或ByteStream调用 Azure 云端服务完成 OCR 识别与版面分析输出一批可直接进入后续预处理与索引环节的Document。该组件适用于以下典型场景索引图像型 PDF扫描件、拍照件与纯图片文件借助 Azure 云端 OCR 能力抽取文字处理结构化复杂版面多栏、表格、页眉页脚、编号与章节标题并在抽取结果中保留版面上下文信息在统一索引流水线中将可搜索 PDF 与图像型 PDF 混合的文件批次交给同一组件处理。组件支持的文件格式包括PDF含可搜索 PDF 与纯图像 PDF、JPEG、PNG、BMP、TIFF、DOCX、XLSX、PPTX、HTML。要使用它你需要一个有效的 Azure 账号以及一个 Document Intelligence文档智能或 Cognitive Services认知服务资源并按 Azure 官方快速入门文档完成资源创建与密钥获取。从组件在流水线中的位置看它通常被放置在整个索引流水线的最前端、各类 PreProcessor如 DocumentCleaner、DocumentSplitter之前负责把原始文件统一转换成后续组件可消费的Document列表。安装与导入路径AzureOCRDocumentConverter在 Haystack 2.x 中曾被内置于核心包随后被移出并独立成集成包。自该组件被标记为弃用deprecated起使用方式变为先安装独立包再从haystack_integrations命名空间导入pip install azure-form-recognizer-haystackfrom haystack_integrations.components.converters.azure_form_recognizer import ( AzureOCRDocumentConverter, )迁移依据可参考仓库根目录的 MIGRATION.md 中的导入路径映射表旧的from haystack.components.converters import AzureOCRDocumentConverter已迁移至上述新路径对应的发布说明 deprecate-azure-ocr-converter-146df0c8cf40902e.yaml 明确指出该组件将随 Haystack 3.0 从核心代码中移除继续使用者需安装azure-form-recognizer-haystack包并更新导入语句。提示如果你从零开始新建 OCR 转换需求建议优先评估官方推荐的继任组件AzureDocumentIntelligenceConverter详见文末「迁移到 AzureDocumentIntelligenceConverter」一节它基于更新的azure-ai-documentintelligenceSDK输出更利于 LLM / RAG 消费的 GitHub Flavored Markdown。构造函数参数详解组件初始化签名__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 资源的端点地址Resource Endpoint形如https://your-resource.cognitiveservices.azure.com/api_keySecretSecret.from_env_var(AZURE_AI_API_KEY)Azure 资源的 API 密钥默认从环境变量AZURE_AI_API_KEY读取也可用Secret.from_token(...)显式传入model_idstrprebuilt-read使用的模型 ID默认走快速 OCR 的prebuilt-read可用模型列表参见 Azure 文档智能「选择模型」官方文档preceding_context_lenint3表格前纳入上下文的行数上下文会被写入表格Document的 metadatafollowing_context_lenint3表格后纳入上下文的行数同样写入 metadatamerge_multiple_column_headersboolTrue为True时将多行表头合并为单行便于后续按表头对齐数据page_layoutLiteral[natural, single_column]natural阅读顺序natural采用 Azure 决定的自然阅读顺序single_column按threshold_y阈值将页面上高度相同的行聚合为单行threshold_yfloat \| None0.05仅当page_layoutsingle_column时生效。以英寸为单位的阈值用于判断两个识别出的 PDF 元素是否应归入同一行对横向轴上与其余文本空间分离的章节标题、编号等元素尤为关键store_full_pathboolFalse为True时在输出Document的 metadata 中保存文件的完整路径为False时只保存文件名两个需要特别说明的参数api_key与 Secret 机制组件使用 Haystack 的Secret类型管理凭据避免在代码、序列化产物中明文暴露密钥。发布说明 update-secret-handling-in-components-925d4f3c3c9530db.yaml 记录了对该组件 Secret 处理的统一调整默认初始化参数改为优先从环境变量读取并移除了 Azure 组件的azure_ad_token_provider参数。store_full_path的隐私取向该参数于后续版本加入用于控制文件完整路径是否写入 metadata。从 add-store-full-path-param-to-converters-5bd32a7561abfe78.yaml 可以看到其默认值经历了一次面向隐私的收紧由默认存完整路径改为默认仅存文件名与本 API 参考中False的默认值一致。若你的业务需要追溯文件来源可显式开启。运行转换run 方法run是组件的核心入口签名如下run( sources: list[str | Path | ByteStream], meta: dict[str, Any] | list[dict[str, Any]] | None None, ) - dict[str, Any]输入参数sources文件路径字符串、pathlib.Path或ByteStream对象的列表。ByteStream支持直接以内存字节流形式传入文件内容便于与上游下载器、抓取器联动。meta可选元数据支持两种形态单个字典该字典内容会合并到本次所有输出Document的 metadata 中适合给整批文件统一打标如数据来源、导入批次、日期字典列表列表长度必须与sources数量一致两者按位置 zip 对应为每个文件分别附加各自的 metadata。若sources中包含ByteStream对象则这些对象自带的meta也会合并进对应输出Document的 metadata。返回值run返回一个字典包含两个键documents本次转换生成的Document列表raw_azure_response用于生成这些Document的 Azure 原始响应列表便于排查识别质量、做后续二次加工或调试。表格的特殊处理方式AzureOCRDocumentConverter对表格有一套专门的处理逻辑表格不会以内联形式留在页面正文文本中而是每个表格被抽取为独立的Document其content为表格内容的CSV 渲染文本metadata 中附加preceding_context表格前文、following_context表格后文以及page页码字段。这一行为由多项发布说明印证azure-ocr-converter-enhancements-c882456cad9a5efc.yaml 记录了本组件的表格与文本增强提取表格上下文、合并多列表头、支持单栏页面布局remove-df-doc-from-azure-ocr-4d65509235a5fd9d.yaml 说明输出Document不再携带已弃用的dataframe字段表格统一以 CSV 文本写入content若业务需要 DataFrame 形态可用pandas.read_csv()将 CSV 文本还原。因此下游若想利用表格上下文做增强检索可以直接读取表格Document的 metadata 中的preceding_context/following_context字段无需自行实现版面上下文截取。完整使用示例单独使用以下示例从环境变量读取端点与密钥转换一份 PDF 并为结果附加导入时间元数据示例中test/test_files/pdf/react_paper.pdf为集成包测试样例路径实际使用时替换为你的文件即可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.更简洁的写法是直接用Path对象并让组件走默认的AZURE_AI_API_KEY环境变量from pathlib import Path from haystack_integrations.components.converters.azure_form_recognizer import AzureOCRDocumentConverter from haystack.utils import Secret converter AzureOCRDocumentConverter( endpointazure_resource_url, api_keySecret.from_token(your-api-key), ) converter.run(sources[Path(my_file.pdf)])在流水线中使用AzureOCRDocumentConverter输出的是结构完整的Document列表可无缝接入 Haystack 索引流水线。官方组件指南 azureocrdocumentconverter.mdx 给出了一个「转换 → 清洗 → 切分 → 写入文档库」的完整示例from haystack import Pipeline from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack_integrations.components.converters.azure_form_recognizer import ( AzureOCRDocumentConverter, ) from haystack.components.preprocessors import DocumentCleaner from haystack.components.preprocessors import 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}})运行后OCR 抽取出的正文与表格Document会依次经过清洗、切分并写入InMemoryDocumentStore形成可被检索器消费的索引数据。若你的文档以表格为主请留意切分与清洗策略避免破坏表格 CSV 的结构完整性。生命周期方法warm_up 与 closewarm_up() - None创建 Azure 文档分析客户端Document Analysis client。Haystack 会在流水线正式运行前自动调用各组件含此组件的warm_up将网络客户端初始化集中到预热阶段避免首次运行时的冷启动延迟。close() - None关闭 Azure 文档分析客户端释放底层连接资源。在长生命周期服务中可通过显式调用close及时回收资源。序列化to_dict 与 from_dict作为标准的 Haystack 组件AzureOCRDocumentConverter实现了序列化协议to_dict() - dict[str, Any]将组件配置序列化为字典便于 YAML 化保存、版本化管理与跨环境复现。from_dict(data: dict[str, Any]) - AzureOCRDocumentConverter从字典反序列化重建组件实例返回新的AzureOCRDocumentConverter。需要注意的是由于api_key使用Secret类型管理序列化产物不会包含明文密钥凭据仍须在运行环境中以环境变量或Secret提供这符合组件库对凭据安全处理的统一约定。源码级演进与设计要点虽然AzureOCRDocumentConverter的实现在独立的azure-form-recognizer-haystack集成仓库中但当前仓库的发布说明完整记录了它的设计演进可据此把握其行为细节表格增强azure-ocr-converter-enhancements-c882456cad9a5efc.yaml引入表格前后文提取、多列表头合并、单栏版面阅读顺序支撑复杂版面的准确抽取CSV 化表格remove-df-doc-from-azure-ocr-4d65509235a5fd9d.yaml移除过时的dataframe字段表格统一以 CSV 文本承载单字典 meta 支持single-meta-in-azureconverter-ce1cc196a9b161f3.yaml当输入源数量未知时仍可通过单个 metadata 字典为整批文档统一打标路径隐私add-store-full-path-param-to-converters-5bd32a7561abfe78.yamlstore_full_path默认值向False收紧减少敏感路径信息外泄凭据安全update-secret-handling-in-components-925d4f3c3c9530db.yaml统一改用Secret与环境变量移除azure_ad_token_provider参数。这些演进共同决定了你在 API 参考中看到的参数默认值与行为约定理解它们有助于在升级 Haystack 版本时评估兼容性影响。迁移到 AzureDocumentIntelligenceConverterAzureOCRDocumentConverter基于较旧的azure-ai-formrecognizerSDK官方已将其标记为弃用并推荐使用新的 AzureDocumentIntelligenceConverter。两者对比如下维度AzureOCRDocumentConverterAzureDocumentIntelligenceConverter集成包azure-form-recognizer-haystackazure-doc-intelligence-haystack底层 SDKazure-ai-formrecognizerazure-ai-documentintelligencev1.0.0默认密钥环境变量AZURE_AI_API_KEYAZURE_DI_API_KEY输出格式纯文本表格独立成 CSV DocumentGitHub Flavored Markdown表格以内联 Markdown 表格呈现默认模型prebuilt-readprebuilt-document也支持prebuilt-read、prebuilt-layout及自定义模型定位已弃用官方继任者迁移时的注意点将依赖从azure-form-recognizer-haystack切换为azure-doc-intelligence-haystack并把导入语句改为from haystack_integrations.components.converters.azure_doc_intelligence import AzureDocumentIntelligenceConverter输出由纯文本变为 Markdown 后不要用默认配置的DocumentCleaner直接清洗因为其默认开启的remove_extra_whitespacesTrue、remove_empty_linesTrue会折叠换行、压平标题/表格/列表建议直接连接下一组件或按需关闭这些选项后再清洗详见 azuredocumentintelligenceconverter.mdx原依赖表格Document的preceding_context/following_context元数据的处理逻辑需要按新的 Markdown 内联表格输出重新设计。小结AzureOCRDocumentConverter是 Haystack 对接 Azure 文档智能服务的高性价比 OCR 入口构造参数覆盖了识别模型、版面阅读顺序、表格上下文与路径隐私等关键诉求run的meta双形态设计与表格独立成Document的行为使其能自然嵌入标准索引流水线warm_up/close/to_dict/from_dict则保证了它与 Haystack 组件生命周期与序列化协议的无缝协同。在新项目中建议优先评估其继任组件AzureDocumentIntelligenceConverter的 Markdown 输出能力而在维护存量流水线时可按本文的迁移对照完成平滑升级。【免费下载链接】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），仅供参考