做桌面自动化的人迟早会遇到一个尴尬瞬间按键精灵自带的找字功能面对屏幕上那种“字体很普通、但每次内容都不同”的文字一点办法都没有。我在跑一个报表自动录入流程时被一列订单号卡了整整一天——想用OCR解决又不知道按键精灵该怎么调用OCR文字识别API。后来我把整个链路跑通才发现阻碍大家的根本不是原理而是几个技术衔接点图片转Base64、HTTP请求、JSON解析在按键精灵里都不像别的语言那么顺手。这篇文章就从0到1完整讲一遍整个链路给你一份能直接改改就用的可运行脚本。如果你正在用按键精灵做Windows桌面自动化面对的不是固定按钮而是“会变的文字内容”那你就是本文目标读者。我会以Windows端按键精灵2014版语法为例其他版本思路完全一致。读完你至少能掌握三件事按键精灵怎么发HTTPS请求、本地图片怎么转成Base64、云端OCR返回的JSON怎么解析成纯文本。这三件事拼起来就是一个可落地的文字识别能力。1. 那些“原生找字”搞不定的场景才是OCR真正的主战场1.1 原生找字为什么遇到复杂文字就失灵按键精灵自带的找字、找图本质上是像素模板匹配。你先用抓图工具截一张目标小图脚本再拿着这张小图去屏幕区域里逐个像素比对颜色分布。这种机制有个前提目标内容的样子必须“基本固定”。同一字号、同一字体、同一背景色时识别率很高一旦字体渲染变了、屏幕DPI缩放了、文字部分被底纹干扰比对相似度立刻下降。更关键的是找字功能只能匹配你“已经见过并截图存下来的文字形状”。比如你想读取每次都在变的订单号总不能给每一个数字组合都截一张图存起来吧这既不可能也没意义。原生找字解决的是“定位已知控件”不是“读懂陌生文字”。1.2 哪些桌面自动化场景确实需要OCR我实际用下来适合接入OCR文字识别API的场景主要有这几类从表格、报表截图里提取文字数据再自动录入到另一个系统或Excel中界面文字带有渐变色、底纹、水印传统找字全挂但人眼能读出来读取本地PDF或聊天记录截图里的段落内容按关键词自动分类存档需要把一段连续文本变成可搜索的变量之后参与匹配判断或流程分支。这些场景有一个共同特征文字内容是变化的、字体不固定、背景有干扰。只要占一条原生找字就很难受。OCR的本质是图像语义识别它学的是“字的形状和上下文”而不是拿像素死磕模板。1.3 先认清OCR接入的三个核心环节按键精灵调用OCR不需要理解深度学习模型怎么训练但必须搞清这三点第一图片怎么交出去。云端接口不认识本地文件路径它只认两种东西图片的Base64字符串或图片的公开URL。按键精灵里最稳的办法是把本地图片转成Base64字符串放进请求体。第二请求怎么发出去。按键精灵不是编程语言没有原生的requests库得通过调用Windows系统内置的COM组件来发HTTP请求。第三返回结果怎么解析。OCR返回的是JSON字符串按键精灵没有内置JSON解析器需要自己写解析函数或借助系统组件。把这三个环节理清了剩下的就是拼接代码的问题。这也是我写这篇文章希望帮你避开的弯路——大部分人在第一步“图片怎么转Base64”就卡住了。2. 一次云端OCR调用到底发生在哪些环节——协议、鉴权与返回结果2.1 从本地截图到最终文本的完整链路一次完整的OCR调用从按键精灵视角看是这样一串动作读取本地图片文件或在脚本里截图保存为文件把图片二进制数据编码成Base64字符串构造HTTP POST请求把Base64和参数塞进请求体发送请求到云平台OCR接口云平台对图片做预处理、文字检测、文字识别返回JSON格式的识别结果按键精灵解析JSON提取文字内容。第5步的“预处理、检测、识别”是云端模型做的事你不需要关心细节。但第2、3、7步是脚本里必须实现的也是最容易出错的三段逻辑。2.2 请求协议与关键参数绝大多数云OCR平台走的是标准HTTPS协议请求方式是POSTContent-Type一般是application/x-www-form-urlencoded或application/json; charsetutf-8。我在脚本里用前者因为按键精灵拼接键值对字符串最直接。请求体里通常包含这些参数参数名是否必填作用image必填图片的Base64编码内容api_key / access_token必填应用密钥用于鉴权language_type选填识别语言如CHN_ENG表示中英文混合detect_direction选填是否自动检测图像旋转角度paragraph选填是否输出段落信息不同云平台的密钥字段名不同有的用access_token有的用api_key secret_key签名后换取token。但核心思路一致你先在云平台控制台创建应用拿到一串密钥然后在请求里带上它。2.3 返回数据到底长什么样OCR返回的数据结构各家略有差异但最常见的是这种格式{ words_result: [ { words: 商品名称智能手环, location: { left: 65, top: 48, width: 210, height: 30 } }, { words: 订单号XD20240519001, location: { left: 65, top: 92, width: 240, height: 30 } } ], words_result_num: 2, log_id: 1234567890 }words_result是一个数组每个元素包含一行识别出的文字部分平台还会返回location字段给出这行字在图片中的坐标矩形。这个字段后面做“识别结果转屏幕坐标”时非常有用我在第7章会细讲。现在你只需要记住我们要拿的就是words_result数组里每个元素的words字段。解析思路可以非常简单不一定要做完整JSON对象解析。3. 环境准备按键精灵发HTTP请求的可行方案与选型理由3.1 三种实现方式的横向对比按键精灵没有内置的“一键发HTTP请求”指令但至少有三条路可以走方案实现方式优点缺点方案A网络命令插件使用第三方或老版本的URL插件代码简单开箱即用不同版本函数名差异大文档零散部分插件已停更方案BWinHttp COM组件调用Windows系统内置组件无需额外安装支持HTTPS超时可控需要理解COM组件调用方式方案C外部命令行工具按键精灵调用curl或Python等外部程序环境能力强解析方便依赖外部环境流程割裂传递变量麻烦我最终选了方案BWinHttp COM组件。原因是它在Windows系统里自带按键精灵2014可以直接通过CreateObject(WinHttp.WinHttpRequest.5.1)创建对象不需要安装任何第三方插件对HTTPS支持稳定还能设置超时时间。对于OCR这种“请求一发、等待返回”的同步操作WinHttp非常合适。3.2 为什么不用WebBrowser控件或直接用插件网上有些教程推荐用按键精灵的网页浏览器控件来发请求原理是让浏览器内核去加载一个带参数的URL然后读取网页内容。这种方式能跑通但非常笨重要创建浏览器窗口、等页面加载完、再抓取文档内容一轮操作可能好几秒。OCR接口是高频率调用的性能完全跟不上。至于第三方URL插件我在多个版本上试过函数签名不统一是最大的坑。有的插件叫Plugin.Url.Post有的叫Plugin.HTTP.Send换个版本脚本就直接报错。自己写WinHttp调用一次搞定以后换版本也不用改。3.3 在你自己的系统上验证组件可用按键精灵2014通常以32位进程运行在64位Windows上WinHttp组件在32位环境下是可用的。你可以先写一段最小验证脚本确认组件能正常创建并请求一个简单地址Dim http Set http CreateObject(WinHttp.WinHttpRequest.5.1) http.Open GET, https://www.baidu.com, False http.Send TracePrint 状态码 http.Status TracePrint 返回长度 Len(http.ResponseText)如果状态码返回200说明系统环境没问题可以进入下一步。如果创建对象就报错多半是系统组件被精简了这种情况可以改用“按键精灵调用本地Python脚本做OCR桥接”的备选方案我在第6章末尾会给思路。4. 核心代码拆解从一张本地图片到一段识别文本4.1 第一步图片转Base64字符串按键精灵没有内置的Base64编码函数但是Windows的MSXML2组件提供了二进制转Base64的能力。核心思路是先用ADODB.Stream读取图片文件的二进制数据再借助MSXML2.DOMDocument的nodeTypedValue把二进制转成Base64字符串。写成函数如下Function ImageToBase64(path) Dim fso, stream, xml, node, binaryData Set fso CreateObject(Scripting.FileSystemObject) If Not fso.FileExists(path) Then ImageToBase64 Exit Function End If Set stream CreateObject(ADODB.Stream) stream.Type 1 1表示二进制模式 stream.Open stream.LoadFromFile path binaryData stream.Read stream.Close Set xml CreateObject(MSXML2.DOMDocument.6.0) Set node xml.createElement(b64) node.DataType bin.base64 node.nodeTypedValue binaryData ImageToBase64 node.text End Function这段代码里stream.Type 1必须写否则ADODB.Stream会以文本模式读取遇到图片里的非文本字节直接损坏。node.DataType bin.base64是MSXML2组件内置的编码方式比手动写转换循环快得多也省代码。如果CreateObject(MSXML2.DOMDocument.6.0)在部分精简系统上报错可以退一级改用MSXML2.DOMDocument或MSXML.DOMDocument编码逻辑不变。4.2 第二步用WinHttp发出带鉴权的POST请求图片转成Base64后接下来就是发送请求。我封装了一个PostOcr函数把URL和图片Base64字符串作为参数传进去返回原始JSON文本Function PostOcr(url, imageBase64) Dim http, resp Set http CreateObject(WinHttp.WinHttpRequest.5.1) http.Open POST, url, False False表示同步请求 http.setTimeouts 10000, 10000, 30000, 30000 http.setRequestHeader Content-Type, application/x-www-form-urlencoded http.setRequestHeader Accept, application/json http.Send image imageBase64 language_typeCHN_ENGapi_key API_KEY PostOcr http.ResponseText End Function几个容易犯迷糊的点为什么要用同步请求按键精灵脚本必须等OCR结果返回后才能决定下一步动作。如果设置成异步脚本不会停在请求那行等待流程就会直接往下跑拿到的还是空字符串。OCR这种场景就是需要“等结果”同步请求是正确选择。为什么要先拼接参数再Send有的云平台要求API Key放在请求头里有的要求放在请求体里。我在示例里放请求体是为了少写一行setRequestHeader也方便你一眼看清参数结构。实际使用时以你申请的云平台文档为准通常都会写明鉴权参数放哪里。超时时间怎么设置setTimeouts四个参数分别对应连接超时、发送超时、接收超时、总超时。OCR接口一般1秒内返回网络差时可能需要5到10秒。给30秒总超时足够如果超过30秒还没返回基本可以判定请求有问题不必死等。4.3 第三步把返回的JSON解析成纯文本按键精灵没有JSON对象但我们可以用正则直接提取words字段。因为OCR返回的结构非常固定正则在这种场景下反而比通用JSON解析更快、更容易写对Function ParseOcrText(respText) Dim re, m, out Set re CreateObject(VBScript.RegExp) re.Global True re.IgnoreCase True re.Pattern \words\:\([^\]*)\ For Each m In re.Execute(respText) out out m.SubMatches(0) vbCrLf Next ParseOcrText out End Function这个正则的意思是寻找形如words:xxx的模式把xxx提取出来用换行分隔拼接。如果返回JSON里的中文是转义字符例如\u554a正则提取后还需要做一步Unicode反转义。不过多数云平台在application/x-www-form-urlencoded请求下直接返回UTF-8明文按键精灵的字符串能正常处理。如果后续需要解析更复杂的字段比如location坐标正则就有点吃力了。这时可以改用MSScriptControl.ScriptControl组件执行JavaScript的JSON.parse按键精灵调用代码会更冗长但能拿全整个JSON对象。本章先用正则解决80%的需求坐标解析我放在第7章讲。4.4 完整可运行脚本把上面三块拼起来就是一个完整的、可直接修改运行的按键精灵脚本。脚本开头是配置区你把云平台地址和密钥填进去再把要识别的图片路径改一下直接运行就能在“调试输出”里看到识别结果 配置区 Dim OCR_URL, API_KEY, IMG_PATH OCR_URL https://ocr.example.com/v1/general_basic API_KEY your_api_key IMG_PATH C:\test\sample.png 主流程 Dim b64, resp, result b64 ImageToBase64(IMG_PATH) If b64 Then TracePrint 图片路径不存在或读取失败 EndScript End If TracePrint Base64长度 Len(b64) resp PostOcr(OCR_URL, b64) TracePrint 原始返回 Left(resp, 300) result ParseOcrText(resp) TracePrint 识别结果如下 TracePrint result这个脚本的识别结果会逐行输出到按键精灵的调试窗口。到这里“按键精灵调用OCR文字识别API”的最小闭环已经跑通了。接下来我聊聊实际跑的时候会发生什么。5. 实测过程识别一张10行报表截图要多久瓶颈在哪5.1 测试样本设计我实际测试时截了一张带底纹的库存报表图包含商品名称、数量、单价三列一共10行。图片分辨率约900x600保存为PNG格式大小约180KB。画面上有浅蓝色底纹黑色文字字体是常见的中文黑体。为什么选这张图因为底纹会干扰传统找字也更能体现OCR模型的优势。测试方式是循环识别5次用按键精灵的系统时间函数记录每个环节的耗时。5.2 各环节耗时分布实测数据大致如下环节平均耗时说明图片转Base6415ms纯本地计算耗时极低HTTP请求云端识别550ms受网络环境影响波动±200msJSON解析2ms正则提取速度很快总计约570ms单张图片识别不到1秒可以看到瓶颈完全在HTTP请求和云端识别。如果你做的是每隔几秒轮询一次的场景这个耗时完全可接受但如果要高频识别100张图片算下来就是接近1分钟还要考虑云平台限流。所以“单张识别”和“批量识别”是两种节奏后者必须做缓存和频率控制。5.3 识别质量与常见干扰因素实际识别结果里中文商品名基本全对数字和英文混合的规格型号偶尔会出现“0/O”、“1/I”混淆。这不是接口不行而是图片本身分辨率不够。遇到这种情况我的经验是在截图时尽量把目标区域放大或者保存成更高分辨率的图片。把原图宽度放大1.5倍后数字混淆问题基本消失。另外如果截图区域里有水印或反色文字云平台的处理效果在边缘场景会有偏差。可以把图片转成灰度图或提升对比度再提交准确率会明显提升。按键精灵里可以用图像处理插件先做预处理但大多数场景直接提交原图就够了。6. 高频报错与排查链路我从报错信息反推问题根因的经验6.1 常见报错现象和排查路径第一次跑通后我把几个常见报错和排查链路总结成一张表。以后你再遇到报错按这张表反推根因会很快报错现象可能原因排查动作-214701286操作超时网络不通、接口地址错误、防火墙拦截先用浏览器手动打开URL看能否访问检查WinHttp是否被安全软件拦截返回空字符串请求被服务端拒绝或同步请求设置错误打印http.Status确认请求是否完成检查是否使用False同步模式返回JSON带error_code鉴权失败、密钥权限不足、图片格式不支持把原始返回完整打印出来对应云平台错误码表逐条比对中文乱码响应头未声明charset按键精灵按ANSI解析检查HTTP响应头是否有charsetutf-8必要时改用ResponseBody转码图片超过大小限制图片体积或分辨率超接口上限压缩或裁剪图片控制在平台限制内0x80072EFD连接失败系统根证书过期、HTTPS握手失败更新系统时间检查系统根证书把地址改成不带HTTPS的测试接口6.2 三个最典型的案例案例一中文乱码。有次我识别一个包含生僻字的截图返回的words字段在调试窗口里显示成乱码。排查后发现是按键精灵对响应文本的编码判断问题。解决方法有两种一种是在请求头加Accept: application/json; charsetutf-8让服务端明确返回编码另一种是解析时不直接取ResponseText而是把ResponseBody字节流用ADODB.Stream按UTF-8重新读。后一种写法更绕但能根治问题。案例二图片过大被拒。云平台通常对图片大小有硬性限制超限直接返回错误。我遇到过截取整屏后图片体积超过限制的情况。处理方式是缩小识别区域或者用图像处理命令把图片宽度缩到限制范围内。认清一点OCR识别的不是“整屏”而是“目标区域”截图范围越小识别越快准确率还越高。案例三密钥权限不足。申请完云服务后有些接口需要单独开通才可用否则返回“没有权限”的错误码。最容易被忽略的是密钥所属应用要绑定正确的服务类别。这个在控制台里检查一遍就好通常不是代码问题。6.3 定位问题的最佳方法断点日志法按键精灵脚本不像高级语言那样有完整的断点调试但TracePrint就是最好的调试工具。我的习惯是在每个环节打印一行日志TracePrint [步骤1] 图片转Base64完成耗时 cost1 TracePrint [步骤2] 请求发送完成状态码 http.Status TracePrint [步骤3] JSON解析完成提取到 lineCount 行每加一个日志就相当于给管道开一个观察窗。哪个环节没打印出来问题就出在哪。你可能觉得多加日志麻烦但排错时它能帮你省一个小时。所有临时日志在最终脚本里保留也行只要注意不要打印完整的密钥信息。6.4 实在调不通时的备选方案如果你的按键精灵版本对COM组件支持不好或者系统环境被安全软件限制得比较死还有一个更稳的方案用按键精灵调用本地Python脚本做OCR桥接。思路很简单用按键精灵的RunApp命令调用python ocr_bridge.py 图片路径Python脚本负责读取图片、调用云平台OCR、把结果写入一个txt文件按键精灵再用文件读取命令把txt内容读回来。痛点是要装Python环境好处是Python里处理Base64、JSON、编码问题都极其顺滑几乎不会踩坑。我个人的建议是优先用COM组件方案因为按键精灵脚本完全自包含拿到别的电脑上不需要额外环境只有COM方案被环境卡死时才切换Python桥接。7. 把识别结果接回自动化流程坐标回填、缓存与安全收尾7.1 识别文本如何变成屏幕坐标很多人的OCR需求不是“读出文字”就结束而是“读出文字后要定位它在屏幕上的位置然后点击或输入”。这时候就要用上返回数据里的location坐标。OCR返回的location是文字在你提交那张图片里的相对坐标。如果你截图时已经记录了截屏区域左上角的屏幕坐标那么文字的真实屏幕坐标就是屏幕X 截图区域左上角X location.left 屏幕Y 截图区域左上角Y location.top算出坐标后就可以用按键精灵标准的鼠标命令操作了MoveTo screenX, screenY LeftClick 1 Delay 100 Call Plugin.Sys.SendString(text)这套组合能让“识别点击输入”的完整自动化流程跑通。比如读取报表里的订单号识别后自动在另一个系统里点击输入框把订单号填进去。整个过程不需要写任何复杂坐标计算把偏移量加对就行。7.2 缓存与频率控制避免无谓的API消耗OCR接口是按调用次数计费的哪怕是免费额度也有每秒调用上限。我在批量处理场景里的做法是图片文件名 文件修改时间作为缓存键识别过一次的结果直接存在本地txt或内存变量里下次遇到同一张图片就直接读缓存结果不再发请求。脚本的大致逻辑可以这样理解如果 图片文件的修改时间没有变化 且 本地缓存文件存在 直接读取缓存结果 否则 调用OCR接口识别 把结果写入缓存文件这样处理之后重复运行同一个流程时大量图片根本不会触发HTTP请求不仅省钱还彻底规避了限流问题。如果必须连续识别多张图片脚本里在每次请求后加Delay 500或者更长给接口留出喘息空间。7.3 密钥安全与脚本分发注意事项OCR API密钥本质上是一串可以消耗费用的凭证而且很多平台是“凭密钥不限设备”的。这意味着密钥一旦泄露别人可以一直拿你的额度做识别。所以我强烈建议不要在脚本里直接写死密钥尤其是脚本要发给别人用的时候可以把密钥放在本地一个config.ini文件里脚本启动时读取别人拿到脚本也看不到密钥内容云平台控制台里如果发现异常调用记录立即重置密钥日志输出时过滤掉密钥字段防止调试时不小心把密钥打印出来。密钥管理看起来很不起眼但自动化脚本一旦规模化分发这往往是最早爆雷的地方。7.4 文本后处理让识别结果更好地参与后续逻辑OCR返回的文本往往带着多余空格、全角字符、换行符。直接拿去做字符串匹配很容易失败。我习惯在解析结果之后加一步清洗Function CleanText(t) CleanText Replace(Replace(t, , ), vbCrLf, ) CleanText Replace(CleanText, Chr(13), ) CleanText Replace(CleanText, Chr(10), ) End Function清洗后再根据业务需求做一次“规范化”比如把识别出的数字里的字母“O”统一替换成“0”把全角数字转半角。这些细节看着繁琐但在自动化流程里一行没清洗干净就可能导致后续判断全部走错分支。我自己的体会是OCR接入真正难的不是某个单独环节而是键精灵里这几个环节环环相扣任何一个点卡住都让人抓狂。把图片转Base64、WinHttp请求、正则解析这三件套写好再配一套日志定位问题和缓存策略这套方案就足够撑起绝大多数桌面级别的文字识别自动化。将来如果你的业务量变大、对识别速度要求变高再考虑把图片预处理和文本后处理做成独立模块整个链路会清晰很多。 
长河君 · 2026/10/21 15:20:40 · 阅读 1.2k 按键精灵调用OCR文字识别API：从Base64编码到JSON解析的完整实战
做桌面自动化的人迟早会遇到一个尴尬瞬间按键精灵自带的找字功能面对屏幕上那种“字体很普通、但每次内容都不同”的文字一点办法都没有。我在跑一个报表自动录入流程时被一列订单号卡了整整一天——想用OCR解决又不知道按键精灵该怎么调用OCR文字识别API。后来我把整个链路跑通才发现阻碍大家的根本不是原理而是几个技术衔接点图片转Base64、HTTP请求、JSON解析在按键精灵里都不像别的语言那么顺手。这篇文章就从0到1完整讲一遍整个链路给你一份能直接改改就用的可运行脚本。如果你正在用按键精灵做Windows桌面自动化面对的不是固定按钮而是“会变的文字内容”那你就是本文目标读者。我会以Windows端按键精灵2014版语法为例其他版本思路完全一致。读完你至少能掌握三件事按键精灵怎么发HTTPS请求、本地图片怎么转成Base64、云端OCR返回的JSON怎么解析成纯文本。这三件事拼起来就是一个可落地的文字识别能力。1. 那些“原生找字”搞不定的场景才是OCR真正的主战场1.1 原生找字为什么遇到复杂文字就失灵按键精灵自带的找字、找图本质上是像素模板匹配。你先用抓图工具截一张目标小图脚本再拿着这张小图去屏幕区域里逐个像素比对颜色分布。这种机制有个前提目标内容的样子必须“基本固定”。同一字号、同一字体、同一背景色时识别率很高一旦字体渲染变了、屏幕DPI缩放了、文字部分被底纹干扰比对相似度立刻下降。更关键的是找字功能只能匹配你“已经见过并截图存下来的文字形状”。比如你想读取每次都在变的订单号总不能给每一个数字组合都截一张图存起来吧这既不可能也没意义。原生找字解决的是“定位已知控件”不是“读懂陌生文字”。1.2 哪些桌面自动化场景确实需要OCR我实际用下来适合接入OCR文字识别API的场景主要有这几类从表格、报表截图里提取文字数据再自动录入到另一个系统或Excel中界面文字带有渐变色、底纹、水印传统找字全挂但人眼能读出来读取本地PDF或聊天记录截图里的段落内容按关键词自动分类存档需要把一段连续文本变成可搜索的变量之后参与匹配判断或流程分支。这些场景有一个共同特征文字内容是变化的、字体不固定、背景有干扰。只要占一条原生找字就很难受。OCR的本质是图像语义识别它学的是“字的形状和上下文”而不是拿像素死磕模板。1.3 先认清OCR接入的三个核心环节按键精灵调用OCR不需要理解深度学习模型怎么训练但必须搞清这三点第一图片怎么交出去。云端接口不认识本地文件路径它只认两种东西图片的Base64字符串或图片的公开URL。按键精灵里最稳的办法是把本地图片转成Base64字符串放进请求体。第二请求怎么发出去。按键精灵不是编程语言没有原生的requests库得通过调用Windows系统内置的COM组件来发HTTP请求。第三返回结果怎么解析。OCR返回的是JSON字符串按键精灵没有内置JSON解析器需要自己写解析函数或借助系统组件。把这三个环节理清了剩下的就是拼接代码的问题。这也是我写这篇文章希望帮你避开的弯路——大部分人在第一步“图片怎么转Base64”就卡住了。2. 一次云端OCR调用到底发生在哪些环节——协议、鉴权与返回结果2.1 从本地截图到最终文本的完整链路一次完整的OCR调用从按键精灵视角看是这样一串动作读取本地图片文件或在脚本里截图保存为文件把图片二进制数据编码成Base64字符串构造HTTP POST请求把Base64和参数塞进请求体发送请求到云平台OCR接口云平台对图片做预处理、文字检测、文字识别返回JSON格式的识别结果按键精灵解析JSON提取文字内容。第5步的“预处理、检测、识别”是云端模型做的事你不需要关心细节。但第2、3、7步是脚本里必须实现的也是最容易出错的三段逻辑。2.2 请求协议与关键参数绝大多数云OCR平台走的是标准HTTPS协议请求方式是POSTContent-Type一般是application/x-www-form-urlencoded或application/json; charsetutf-8。我在脚本里用前者因为按键精灵拼接键值对字符串最直接。请求体里通常包含这些参数参数名是否必填作用image必填图片的Base64编码内容api_key / access_token必填应用密钥用于鉴权language_type选填识别语言如CHN_ENG表示中英文混合detect_direction选填是否自动检测图像旋转角度paragraph选填是否输出段落信息不同云平台的密钥字段名不同有的用access_token有的用api_key secret_key签名后换取token。但核心思路一致你先在云平台控制台创建应用拿到一串密钥然后在请求里带上它。2.3 返回数据到底长什么样OCR返回的数据结构各家略有差异但最常见的是这种格式{ words_result: [ { words: 商品名称智能手环, location: { left: 65, top: 48, width: 210, height: 30 } }, { words: 订单号XD20240519001, location: { left: 65, top: 92, width: 240, height: 30 } } ], words_result_num: 2, log_id: 1234567890 }words_result是一个数组每个元素包含一行识别出的文字部分平台还会返回location字段给出这行字在图片中的坐标矩形。这个字段后面做“识别结果转屏幕坐标”时非常有用我在第7章会细讲。现在你只需要记住我们要拿的就是words_result数组里每个元素的words字段。解析思路可以非常简单不一定要做完整JSON对象解析。3. 环境准备按键精灵发HTTP请求的可行方案与选型理由3.1 三种实现方式的横向对比按键精灵没有内置的“一键发HTTP请求”指令但至少有三条路可以走方案实现方式优点缺点方案A网络命令插件使用第三方或老版本的URL插件代码简单开箱即用不同版本函数名差异大文档零散部分插件已停更方案BWinHttp COM组件调用Windows系统内置组件无需额外安装支持HTTPS超时可控需要理解COM组件调用方式方案C外部命令行工具按键精灵调用curl或Python等外部程序环境能力强解析方便依赖外部环境流程割裂传递变量麻烦我最终选了方案BWinHttp COM组件。原因是它在Windows系统里自带按键精灵2014可以直接通过CreateObject(WinHttp.WinHttpRequest.5.1)创建对象不需要安装任何第三方插件对HTTPS支持稳定还能设置超时时间。对于OCR这种“请求一发、等待返回”的同步操作WinHttp非常合适。3.2 为什么不用WebBrowser控件或直接用插件网上有些教程推荐用按键精灵的网页浏览器控件来发请求原理是让浏览器内核去加载一个带参数的URL然后读取网页内容。这种方式能跑通但非常笨重要创建浏览器窗口、等页面加载完、再抓取文档内容一轮操作可能好几秒。OCR接口是高频率调用的性能完全跟不上。至于第三方URL插件我在多个版本上试过函数签名不统一是最大的坑。有的插件叫Plugin.Url.Post有的叫Plugin.HTTP.Send换个版本脚本就直接报错。自己写WinHttp调用一次搞定以后换版本也不用改。3.3 在你自己的系统上验证组件可用按键精灵2014通常以32位进程运行在64位Windows上WinHttp组件在32位环境下是可用的。你可以先写一段最小验证脚本确认组件能正常创建并请求一个简单地址Dim http Set http CreateObject(WinHttp.WinHttpRequest.5.1) http.Open GET, https://www.baidu.com, False http.Send TracePrint 状态码 http.Status TracePrint 返回长度 Len(http.ResponseText)如果状态码返回200说明系统环境没问题可以进入下一步。如果创建对象就报错多半是系统组件被精简了这种情况可以改用“按键精灵调用本地Python脚本做OCR桥接”的备选方案我在第6章末尾会给思路。4. 核心代码拆解从一张本地图片到一段识别文本4.1 第一步图片转Base64字符串按键精灵没有内置的Base64编码函数但是Windows的MSXML2组件提供了二进制转Base64的能力。核心思路是先用ADODB.Stream读取图片文件的二进制数据再借助MSXML2.DOMDocument的nodeTypedValue把二进制转成Base64字符串。写成函数如下Function ImageToBase64(path) Dim fso, stream, xml, node, binaryData Set fso CreateObject(Scripting.FileSystemObject) If Not fso.FileExists(path) Then ImageToBase64 Exit Function End If Set stream CreateObject(ADODB.Stream) stream.Type 1 1表示二进制模式 stream.Open stream.LoadFromFile path binaryData stream.Read stream.Close Set xml CreateObject(MSXML2.DOMDocument.6.0) Set node xml.createElement(b64) node.DataType bin.base64 node.nodeTypedValue binaryData ImageToBase64 node.text End Function这段代码里stream.Type 1必须写否则ADODB.Stream会以文本模式读取遇到图片里的非文本字节直接损坏。node.DataType bin.base64是MSXML2组件内置的编码方式比手动写转换循环快得多也省代码。如果CreateObject(MSXML2.DOMDocument.6.0)在部分精简系统上报错可以退一级改用MSXML2.DOMDocument或MSXML.DOMDocument编码逻辑不变。4.2 第二步用WinHttp发出带鉴权的POST请求图片转成Base64后接下来就是发送请求。我封装了一个PostOcr函数把URL和图片Base64字符串作为参数传进去返回原始JSON文本Function PostOcr(url, imageBase64) Dim http, resp Set http CreateObject(WinHttp.WinHttpRequest.5.1) http.Open POST, url, False False表示同步请求 http.setTimeouts 10000, 10000, 30000, 30000 http.setRequestHeader Content-Type, application/x-www-form-urlencoded http.setRequestHeader Accept, application/json http.Send image imageBase64 language_typeCHN_ENGapi_key API_KEY PostOcr http.ResponseText End Function几个容易犯迷糊的点为什么要用同步请求按键精灵脚本必须等OCR结果返回后才能决定下一步动作。如果设置成异步脚本不会停在请求那行等待流程就会直接往下跑拿到的还是空字符串。OCR这种场景就是需要“等结果”同步请求是正确选择。为什么要先拼接参数再Send有的云平台要求API Key放在请求头里有的要求放在请求体里。我在示例里放请求体是为了少写一行setRequestHeader也方便你一眼看清参数结构。实际使用时以你申请的云平台文档为准通常都会写明鉴权参数放哪里。超时时间怎么设置setTimeouts四个参数分别对应连接超时、发送超时、接收超时、总超时。OCR接口一般1秒内返回网络差时可能需要5到10秒。给30秒总超时足够如果超过30秒还没返回基本可以判定请求有问题不必死等。4.3 第三步把返回的JSON解析成纯文本按键精灵没有JSON对象但我们可以用正则直接提取words字段。因为OCR返回的结构非常固定正则在这种场景下反而比通用JSON解析更快、更容易写对Function ParseOcrText(respText) Dim re, m, out Set re CreateObject(VBScript.RegExp) re.Global True re.IgnoreCase True re.Pattern \words\:\([^\]*)\ For Each m In re.Execute(respText) out out m.SubMatches(0) vbCrLf Next ParseOcrText out End Function这个正则的意思是寻找形如words:xxx的模式把xxx提取出来用换行分隔拼接。如果返回JSON里的中文是转义字符例如\u554a正则提取后还需要做一步Unicode反转义。不过多数云平台在application/x-www-form-urlencoded请求下直接返回UTF-8明文按键精灵的字符串能正常处理。如果后续需要解析更复杂的字段比如location坐标正则就有点吃力了。这时可以改用MSScriptControl.ScriptControl组件执行JavaScript的JSON.parse按键精灵调用代码会更冗长但能拿全整个JSON对象。本章先用正则解决80%的需求坐标解析我放在第7章讲。4.4 完整可运行脚本把上面三块拼起来就是一个完整的、可直接修改运行的按键精灵脚本。脚本开头是配置区你把云平台地址和密钥填进去再把要识别的图片路径改一下直接运行就能在“调试输出”里看到识别结果 配置区 Dim OCR_URL, API_KEY, IMG_PATH OCR_URL https://ocr.example.com/v1/general_basic API_KEY your_api_key IMG_PATH C:\test\sample.png 主流程 Dim b64, resp, result b64 ImageToBase64(IMG_PATH) If b64 Then TracePrint 图片路径不存在或读取失败 EndScript End If TracePrint Base64长度 Len(b64) resp PostOcr(OCR_URL, b64) TracePrint 原始返回 Left(resp, 300) result ParseOcrText(resp) TracePrint 识别结果如下 TracePrint result这个脚本的识别结果会逐行输出到按键精灵的调试窗口。到这里“按键精灵调用OCR文字识别API”的最小闭环已经跑通了。接下来我聊聊实际跑的时候会发生什么。5. 实测过程识别一张10行报表截图要多久瓶颈在哪5.1 测试样本设计我实际测试时截了一张带底纹的库存报表图包含商品名称、数量、单价三列一共10行。图片分辨率约900x600保存为PNG格式大小约180KB。画面上有浅蓝色底纹黑色文字字体是常见的中文黑体。为什么选这张图因为底纹会干扰传统找字也更能体现OCR模型的优势。测试方式是循环识别5次用按键精灵的系统时间函数记录每个环节的耗时。5.2 各环节耗时分布实测数据大致如下环节平均耗时说明图片转Base6415ms纯本地计算耗时极低HTTP请求云端识别550ms受网络环境影响波动±200msJSON解析2ms正则提取速度很快总计约570ms单张图片识别不到1秒可以看到瓶颈完全在HTTP请求和云端识别。如果你做的是每隔几秒轮询一次的场景这个耗时完全可接受但如果要高频识别100张图片算下来就是接近1分钟还要考虑云平台限流。所以“单张识别”和“批量识别”是两种节奏后者必须做缓存和频率控制。5.3 识别质量与常见干扰因素实际识别结果里中文商品名基本全对数字和英文混合的规格型号偶尔会出现“0/O”、“1/I”混淆。这不是接口不行而是图片本身分辨率不够。遇到这种情况我的经验是在截图时尽量把目标区域放大或者保存成更高分辨率的图片。把原图宽度放大1.5倍后数字混淆问题基本消失。另外如果截图区域里有水印或反色文字云平台的处理效果在边缘场景会有偏差。可以把图片转成灰度图或提升对比度再提交准确率会明显提升。按键精灵里可以用图像处理插件先做预处理但大多数场景直接提交原图就够了。6. 高频报错与排查链路我从报错信息反推问题根因的经验6.1 常见报错现象和排查路径第一次跑通后我把几个常见报错和排查链路总结成一张表。以后你再遇到报错按这张表反推根因会很快报错现象可能原因排查动作-214701286操作超时网络不通、接口地址错误、防火墙拦截先用浏览器手动打开URL看能否访问检查WinHttp是否被安全软件拦截返回空字符串请求被服务端拒绝或同步请求设置错误打印http.Status确认请求是否完成检查是否使用False同步模式返回JSON带error_code鉴权失败、密钥权限不足、图片格式不支持把原始返回完整打印出来对应云平台错误码表逐条比对中文乱码响应头未声明charset按键精灵按ANSI解析检查HTTP响应头是否有charsetutf-8必要时改用ResponseBody转码图片超过大小限制图片体积或分辨率超接口上限压缩或裁剪图片控制在平台限制内0x80072EFD连接失败系统根证书过期、HTTPS握手失败更新系统时间检查系统根证书把地址改成不带HTTPS的测试接口6.2 三个最典型的案例案例一中文乱码。有次我识别一个包含生僻字的截图返回的words字段在调试窗口里显示成乱码。排查后发现是按键精灵对响应文本的编码判断问题。解决方法有两种一种是在请求头加Accept: application/json; charsetutf-8让服务端明确返回编码另一种是解析时不直接取ResponseText而是把ResponseBody字节流用ADODB.Stream按UTF-8重新读。后一种写法更绕但能根治问题。案例二图片过大被拒。云平台通常对图片大小有硬性限制超限直接返回错误。我遇到过截取整屏后图片体积超过限制的情况。处理方式是缩小识别区域或者用图像处理命令把图片宽度缩到限制范围内。认清一点OCR识别的不是“整屏”而是“目标区域”截图范围越小识别越快准确率还越高。案例三密钥权限不足。申请完云服务后有些接口需要单独开通才可用否则返回“没有权限”的错误码。最容易被忽略的是密钥所属应用要绑定正确的服务类别。这个在控制台里检查一遍就好通常不是代码问题。6.3 定位问题的最佳方法断点日志法按键精灵脚本不像高级语言那样有完整的断点调试但TracePrint就是最好的调试工具。我的习惯是在每个环节打印一行日志TracePrint [步骤1] 图片转Base64完成耗时 cost1 TracePrint [步骤2] 请求发送完成状态码 http.Status TracePrint [步骤3] JSON解析完成提取到 lineCount 行每加一个日志就相当于给管道开一个观察窗。哪个环节没打印出来问题就出在哪。你可能觉得多加日志麻烦但排错时它能帮你省一个小时。所有临时日志在最终脚本里保留也行只要注意不要打印完整的密钥信息。6.4 实在调不通时的备选方案如果你的按键精灵版本对COM组件支持不好或者系统环境被安全软件限制得比较死还有一个更稳的方案用按键精灵调用本地Python脚本做OCR桥接。思路很简单用按键精灵的RunApp命令调用python ocr_bridge.py 图片路径Python脚本负责读取图片、调用云平台OCR、把结果写入一个txt文件按键精灵再用文件读取命令把txt内容读回来。痛点是要装Python环境好处是Python里处理Base64、JSON、编码问题都极其顺滑几乎不会踩坑。我个人的建议是优先用COM组件方案因为按键精灵脚本完全自包含拿到别的电脑上不需要额外环境只有COM方案被环境卡死时才切换Python桥接。7. 把识别结果接回自动化流程坐标回填、缓存与安全收尾7.1 识别文本如何变成屏幕坐标很多人的OCR需求不是“读出文字”就结束而是“读出文字后要定位它在屏幕上的位置然后点击或输入”。这时候就要用上返回数据里的location坐标。OCR返回的location是文字在你提交那张图片里的相对坐标。如果你截图时已经记录了截屏区域左上角的屏幕坐标那么文字的真实屏幕坐标就是屏幕X 截图区域左上角X location.left 屏幕Y 截图区域左上角Y location.top算出坐标后就可以用按键精灵标准的鼠标命令操作了MoveTo screenX, screenY LeftClick 1 Delay 100 Call Plugin.Sys.SendString(text)这套组合能让“识别点击输入”的完整自动化流程跑通。比如读取报表里的订单号识别后自动在另一个系统里点击输入框把订单号填进去。整个过程不需要写任何复杂坐标计算把偏移量加对就行。7.2 缓存与频率控制避免无谓的API消耗OCR接口是按调用次数计费的哪怕是免费额度也有每秒调用上限。我在批量处理场景里的做法是图片文件名 文件修改时间作为缓存键识别过一次的结果直接存在本地txt或内存变量里下次遇到同一张图片就直接读缓存结果不再发请求。脚本的大致逻辑可以这样理解如果 图片文件的修改时间没有变化 且 本地缓存文件存在 直接读取缓存结果 否则 调用OCR接口识别 把结果写入缓存文件这样处理之后重复运行同一个流程时大量图片根本不会触发HTTP请求不仅省钱还彻底规避了限流问题。如果必须连续识别多张图片脚本里在每次请求后加Delay 500或者更长给接口留出喘息空间。7.3 密钥安全与脚本分发注意事项OCR API密钥本质上是一串可以消耗费用的凭证而且很多平台是“凭密钥不限设备”的。这意味着密钥一旦泄露别人可以一直拿你的额度做识别。所以我强烈建议不要在脚本里直接写死密钥尤其是脚本要发给别人用的时候可以把密钥放在本地一个config.ini文件里脚本启动时读取别人拿到脚本也看不到密钥内容云平台控制台里如果发现异常调用记录立即重置密钥日志输出时过滤掉密钥字段防止调试时不小心把密钥打印出来。密钥管理看起来很不起眼但自动化脚本一旦规模化分发这往往是最早爆雷的地方。7.4 文本后处理让识别结果更好地参与后续逻辑OCR返回的文本往往带着多余空格、全角字符、换行符。直接拿去做字符串匹配很容易失败。我习惯在解析结果之后加一步清洗Function CleanText(t) CleanText Replace(Replace(t, , ), vbCrLf, ) CleanText Replace(CleanText, Chr(13), ) CleanText Replace(CleanText, Chr(10), ) End Function清洗后再根据业务需求做一次“规范化”比如把识别出的数字里的字母“O”统一替换成“0”把全角数字转半角。这些细节看着繁琐但在自动化流程里一行没清洗干净就可能导致后续判断全部走错分支。我自己的体会是OCR接入真正难的不是某个单独环节而是键精灵里这几个环节环环相扣任何一个点卡住都让人抓狂。把图片转Base64、WinHttp请求、正则解析这三件套写好再配一套日志定位问题和缓存策略这套方案就足够撑起绝大多数桌面级别的文字识别自动化。将来如果你的业务量变大、对识别速度要求变高再考虑把图片预处理和文本后处理做成独立模块整个链路会清晰很多。