Parsr 接入 Microsoft Cognitive Services OCR：凭据配置、端点到结构化文档的完整流程

后端数据工程【免费下载链接】ParsrTransforms PDF, Documents and Images into Enriched Structured Data项目地址https://gitcode.com/gh_mirrors/pa/Parsr点击查看免费下载本篇技术指南讲解 Parsr 开源项目中 Microsoft Cognitive Services 输入模块ms-cognitive-services的完整用法从 Azure 上申请 API Key、在 Parsr 配置文件中正确填写凭据与区域端点到该模块如何调用 Azure 认知服务的 Read API 完成 OCR并把识别结果转换为 Parsr 内部统一的Document结构化数据模型供后续清理、结构化处理与导出使用。读完本文你将能够在自己的 Parsr 配置中无缝启用这一云端 OCR 方案并理解其底层调用链路与数据处理细节。模块定位Parsr 输入层中的云端 OCR 方案Parsr 的处理管线分为输入提取 → 清洗结构化 → 导出三大阶段。在输入阶段输入模块总览 将各提取器统一抽象为输入模块Input Modules它们负责把原始文件解析为统一的Document对象——包含每个Page上的Word数组等结构化元素供后续 Cleaner 中的各处理模块标题检测、表格检测、阅读顺序等继续加工。Microsoft Cognitive Services 模块源码位于 MicrosoftCognitiveServices.ts正是一个 OCR 输入模块它的职责是对图片类文件进行云端 OCR 识别即文档描述中所说的 Extractor module for OCRing image files。在 Config 类型定义 中ExtractorConfig.ocr字段明确支持五种取值其中之一就是ms-cognitive-servicestesseract本地开源 OCRabbyygoogle-visionamazon-textractms-cognitive-services本模块从源码结构与官方模块列表看该模块主要面向扫描图片TIFF/PNG/JPEG 等格式的 OCR 场景而 PDF 文件则由extractor.pdf字段指定的提取器如pdfminer、pdfjs处理。输入模块的支持格式矩阵 也印证了这一点MS Cognitive Services 一列对.pdf、.docx、.eml标记为不支持而对.tiff、.png、.jpeg标记为支持。前置条件获取 Azure 认知服务 API Key使用该模块的前提是拥有一个 Microsoft Cognitive Services 的 API KeyOCP_APIM_SUBSCRIPTION_KEY。你可以免费生成一个在 Azure 门户中进入 Cognitive Services 账户创建页面portal.azure.com→ Cognitive Services accounts 资源类型按提示创建认知服务资源后即可获得订阅密钥。拿到密钥后务必将其写入 Parsr 配置文件的extractor.credentials键中详见下一节。若密钥缺失或配置有误模块会在初始化阶段直接抛出异常并给出明确的报错提示——这是由基类 Extractor.checkCredentials() 实现的它遍历必填凭据列表对缺失项拼接出一段示例 JSON 后抛出Required credentials not found: ...错误。配置详解credentials 与区域端点模块要求两项凭据缺一不可源码中通过this.checkCredentials([OCP_APIM_SUBSCRIPTION_KEY, OCP_APIM_ENDPOINT])校验见 MicrosoftCognitiveServices.ts配置键含义是否必填OCP_APIM_SUBSCRIPTION_KEYAzure 认知服务订阅密钥必填OCP_APIM_ENDPOINT认知服务区域端点 URL可选有默认值在 Parsr 配置文件中将extractor.ocr设为ms-cognitive-services并按如下格式配置凭据原文示例已保留完整extractor: { pdf: ..., ocr: ms-cognitive-services, credentials: { OCP_APIM_SUBSCRIPTION_KEY: ..., OCP_APIM_ENDPOINT: } },几点实操细节端点可省略OCP_APIM_ENDPOINT为可选项。若省略或留空模块会使用默认值https://westeurope.api.cognitive.microsoft.com/。该默认值同时固化在模块目录下的 credentials.json 中——这正是基类构造器的默认凭据注入机制Extractor构造器会将credentials.json中的键值填入配置中缺失的对应项见 Extractor.ts因此即使配置里未写端点也会落到西欧区域。端点必须是合法 URL源码构造器中调用this.checkCredentialAsURL(OCP_APIM_ENDPOINT)通过new URL(...)校验其合法性非法值会抛出OCP_APIM_ENDPOINT must be a valid URL见 Extractor.ts。区域选择你可以把端点换成任意可用区域。不同区域对应不同的服务 URL 前缀如westus、westeurope等Azure 官方文档中提供了全部可用端点区域的列表可按业务所在地就近选择以降低延迟。从源码看实际请求目标配置的端点并不直接用于识别请求而是作为 axios 客户端的baseURL见 MicrosoftCognitiveServices.ts。实际发起 OCR 请求的路径为/vision/v2.0/read/core/asyncBatchAnalyze即 Azure Computer Vision v2.0 的 Read API。也就是说完整请求 URL 为OCP_APIM_ENDPOINT /vision/v2.0/read/core/asyncBatchAnalyze。运行时行为异步识别、轮询与结果映射1. 基类调度旋转校正与尺寸回填MicrosoftCognitiveExtractor继承自 OcrExtractorFactory后者又继承自抽象类OcrExtractor。基类的run()流程为若输入不是 PDF 且开启了旋转校正fixRotation默认true先调用 ImageMagick 脚本对图片做旋转校正CommandExecuter.imageCorrection得到旋转角度、原点与平移量信息校正失败时降级使用原图并记录 warn 日志调用子类实现的scanFile(inputFile)执行真正的 OCR对非 PDF 输入通过 set-page-dimensions.ts 用原始图片的真实尺寸回填页面宽高避免 OCR 返回的缩放坐标与原始图片尺寸不一致若执行过旋转校正将RotationCorrection信息挂到doc.pages[0].pageRotation上。2. 提交识别任务asyncBatchAnalyzescanFile()见 MicrosoftCognitiveServices.ts将输入文件以二进制流readFileSyncPOST 到 Read API 的异步端点请求头包含Content-Type: application/octet-stream原始字节流上传Ocp-Apim-Subscription-Key: 你的订阅密钥Azure 认证头axios 客户端超时时间为 20000ms20 秒Azure 的 Read API 采用异步两段式设计POST 提交任务后服务端在响应头operation-location中返回一个查询识别进度的 URL。3. 轮询等待awaitForCompletionawaitForCompletion()见 MicrosoftCognitiveServices.ts对该 URL 发起 GET 查询并按响应状态处理NotStarted/Running每 1 秒1000ms重试轮询直至任务完成Succeeded返回完整识别结果Failed或其他状态reject 并返回该状态字符串。整体即提交 → 每秒轮询 → 成功取回结果的异步闭环。4. 结果映射msResponseToParsrPagesAzure 返回的 JSON 结构源码中以MSCognitiveServicesResponse类型定义见 MicrosoftCognitiveServices.ts包含status、recognitionResults数组每页一个对象页内包含page、clockwiseOrientation顺时针旋转角度、width、height、unit以及lines行数组每行又含boundingBox8 个数字构成的四边形顶点、text与words词数组。msResponseToParsrPages()见 MicrosoftCognitiveServices.ts将其逐层转换为 Parsr 内部模型每个词 →Word含BoundingBox与Font.undefinedFont每行 →Line由词组成附行级BoundingBox每页 →Page页码、行集合以及以页宽高构造的BoundingBox。最终打包成一个Document返回即 输入模块总览 中约定的统一结构可直接进入清洗与结构化阶段。5. 关键细节四边形边界框的矩形化转换Azure Read API 返回的boundingBox是一个 8 元数组[x1,y1,x2,y2,x3,y3,x4,y4]表示四边形的四个顶点坐标顺时针。由于扫描图片可能旋转或倾斜该四边形往往不是标准的水平矩形。msBBToParsrBB()见 MicrosoftCognitiveServices.ts的处理策略是取四个顶点的x、y最小值为左上角取x、y最大值与最小值的差作为宽高从而生成一个能完整包含原四边形的轴对齐矩形。也就是说Parsr 得到的边界框会比 Azure 原始检测结果略大包含旋转造成的空白区域这是为了保证后续模块拿到的一定是规则的矩形框。如何启用配置文件与切换器启用该模块只需在 Parsr 配置文件的extractor段设置ocr: ms-cognitive-services并补全凭据。完整的配置文件结构可参考仓库根部的 server/defaultConfig.json默认ocr为tesseract替换即可配置中还包含version、cleaner清洗模块链与output输出格式等段落。在代码层面模块的接入点在 server/src/utils.ts 的getOcrExtractor()工厂函数它读取config.extractor.ocr的值当为ms-cognitive-services时返回new MicrosoftCognitiveExtractor(config)。该工厂函数被两类场景调用OCR 提取主流程由 Orchestrator 持有的Extractor实例执行run()先提取后清洗Orchestrator 的构造器接收通过工厂选出的提取器日志会打印实际使用的提取器类名Using extractor: MicrosoftCognitiveExtractor。图片内嵌 OCRImageDetectionModule 在检测到文档内嵌图片需要 OCR 时也会调用utils.getOcrExtractor(config)复用同一配置其中ocrImages开关控制是否对图片执行 OCR。适用前提与注意事项输入格式本模块面向图片 OCRTIFF/PNG/JPEG不处理 PDF/DOCX/EML请勿在 PDF 场景下选择它作为ocr提取器PDF 场景应通过extractor.pdf选择pdfminer、pdfjs、tesseract或abbyy。网络与异步识别依赖 Azure 云服务属于外部异步 API需要网络连通且任务耗时取决于服务端队列与图片复杂度源码层面轮询间隔固定为 1 秒。凭据安全订阅密钥属于敏感凭据请避免将其硬编码进公开仓库仓库中的 credentials.json 为占位默认值密钥为空、端点为西欧区域默认值实际使用应在 Parsr 配置文件中覆盖填写。边界框语义经msBBToParsrBB()转换后的边界框是包容旋转四边形的轴对齐矩形与 Azure 原始四边形坐标存在细微差异做像素级后处理时需注意这一语义。版本说明源码调用的识别端点为/vision/v2.0/read/core/asyncBatchAnalyze属于 Azure Computer Vision v2.0 时代的接口若你的 Azure 账户/服务已迁移到更新的 API 版本需自行确认兼容性。总结Microsoft Cognitive Services 输入模块为 Parsr 提供了一条开箱即用的云端 OCR 通路配置上只需两项凭据订阅密钥 可选区域端点运行时则完整封装了异步提交 → 秒级轮询 → 结果转换的调用链并把 Azure 的页面/行/词级识别结果统一映射为 Parsr 的Document/Page/Line/Word结构化模型。通过 Config 类型、提取器工厂、基类调度 与 Orchestrator 的串联你可以快速在 Parsr 中接入该云端 OCR并在此基础上继续使用项目内置的表格检测、标题检测、阅读顺序等清洗模块完成文档结构化。赞分享后端数据工程【免费下载链接】ParsrTransforms PDF, Documents and Images into Enriched Structured Data项目地址https://gitcode.com/gh_mirrors/pa/Parsr点击查看免费下载相关推荐Parsr完整指南如何将PDF文档转换为结构化数据Parsr完整指南如何将PDF文档转换为结构化数据 Parsr是一款强大的开源文档解析工具专门用于将PDF、文档和图像转换为丰富的结构化数据。无论您是数据分后端数据工程VoltAgent 接入 Azure Cognitive Services 完整指南配置、鉴权与 90 个模型速查VoltAgent 接入 Azure Cognitive Services 完整指南配置、鉴权与 90 个模型速查 Azure Cognitive Servi人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音Parsr Simple JSON 导出从结构化文档到有序轻量 JSON 的完整指南Parsr Simple JSON 导出从结构化文档到有序轻量 JSON 的完整指南 导读 Parsr 的 Simple JSON 输出模块 SimpleJ后端数据工程上一篇TV Bro电视浏览器基于Android系统的遥控器优化网页浏览解决方案下一篇揭秘ImageToSTL如何用一张图片重塑3D打印世界创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考