服务开通与鉴权：网关签名是第一道门槛

通用OCR不是匿名接口。接入前要在控制台购买通用型OCR、创建应用并开通能力，拿到两样东西：平台应用的标识，以及账号中心的密钥对。前者标识哪个应用调用，后者用于网关签名计算，证明调用方身份合法。

签名流程按规范走：把待签请求头、排序后的请求头组合、换行符、排序的查询参数、换行符、请求体哈希值拼成待签字符串，再用哈希算法算出签名，塞进认证头。请求头里还要带请求标识、时间戳、主机地址、内容类型。时间偏差过大或签名算错，网关直接拒绝，不会进到OCR引擎。

这一步最常见的踩坑是密钥放前端。密钥对必须只在服务端使用，前端最多拿一个短期换发的业务令牌。另一个坑是时间戳用了本地时区没转成统一标准时间，或者请求标识每次写死，后者会让网关防重放逻辑误伤。签名计算的细节一定要严格按照官方文档来，多一个换行符或少一个冒号都会导致签名校验失败。

请求构造与图片约束：边界比想象中严格

接口地址指向统一的AI网关，用POST方法发送，请求体是标准的JSON格式，核心字段是一个数组，里面放一张或多张图片的编码文本。单次建议不超过几张，整个请求体不超过一定大小，单张图片不超过一定大小，像素边长在一定范围内，格式限定几种常见图片类型。

这些约束不是文档里的摆设。图片太大网关会拒收；像素太小会被判无效；批量塞太多张虽然接口允许，但超时风险和费用都会上去。工程上建议在客户端或服务端做一道预处理：太大的先压缩到可接受范围，太小的先放大再做增强处理，倾斜明显的先做旋转矫正。通用OCR不支持手写体，但印刷体倾斜在合理角度内模型能纠，过分倾斜还是前端预处理好。

编码时注意字符集统一，二进制读出来直接编码，不要先转字符串再编码，否则会引入编码损伤。多图批量场景里，数组里每张图独立识别，返回结果按数组顺序对应，不要靠大概顺序去猜。

响应结构与位置信息：拿到文字只是开始

成功响应里最外层有状态码表示成功与否，真正的文字在结果数组里，每条识别行带识别出的文本内容、置信度、以及该文本块在图中的位置坐标。通用OCR不返回表格单元格关系，也不返回段落逻辑，只告诉你这段字在图的哪个位置、写了什么、可信度多高。

位置信息的价值常被初次接入的工程师忽略。做文本转数字时，位置坐标能帮你区分金额栏的数字和备注栏里碰巧出现的数字。按纵坐标聚类可以把同一行的字段聚到一起，按横坐标排序能还原字段名和值的左右结构。比如发票上价税合计和具体金额，它们的纵坐标接近、横坐标分列，单靠字符串匹配容易把其他位置的数字误吸进来，靠坐标过滤能大幅降低误抽。

置信度是另一道滤网。印刷体正常场景置信度很高，但遇到盖章压字、底色花纹、低分辨率扫描，数字位的置信度可能明显下降。后处理时不要把低置信度数字直接转数值，应先挑出来走人工复核或二次识别。

文本转数字的后处理：从字符串到数值的最后一公里

OCR返回的是字符串，不是数值。带千分位逗号的、带货币符号的、法式分隔的、中文大写的，都是可能的形态。把字符串安全变成程序里的数值类型，是接入里最容易被低估的环节。

第一步是清洗：去千分位逗号、去货币符号、去首尾空格、把全角数字转半角、把字母和数字按上下文纠错。第二步是格式判定：提取数值片段，若原串含中文大写相关词汇，走大写转小写专用映射，不要试图用简单规则硬吃。第三步是校验：金额类字段用小数位数约束，数量类字段用整数约束，日期单独走日期解析；匹配不上约束的，标记为低置信结果，不强制入库。第四步是上下文绑定：用位置坐标和字段名把识别出的数字绑到具体的业务语义上，避免把运费数字写进商品单价。

一个典型健壮做法是：OCR出原文，按位置坐标聚类出行，每行用规则抽字段名和值，值串清洗，尝试转数值，转失败或越界则挂原文字段交人工。直接做类型转换而不做清洗的写法，上线后一定会遇到千分位逗号导致数值截断的事故。

异常处理与重试：不同类型的错误分开处理

接口错误分几类。鉴权类是请求本身有问题，重试多少次都不会成功，必须改配置。参数类同样不该重试，要改调用前校验。限流类和临时服务类才适合退避重试。

OCR类接口默认请求频率有限制，突发批处理容易触限。正确做法是客户端加限速控制，失败返回限流码时按指数退避重试，且重试时重新计算签名和时间戳。因为时间戳和请求标识每次请求都应新鲜，拿上次签名原样重发会被防重放拦下。

图片偶尔传输损坏导致识别空结果，不属于接口错误，属于业务空结果，处理方式是留原文、标空值、进人工队列，而不是疯狂重试同一张图。

排障视角：从识别错了倒推哪层出问题

接入后常见三类投诉。其一是图片传上去报鉴权错，查密钥是否泄露后被重置、时间戳时区、签名串里请求体的哈希值是否用了原始字节而不是格式化后的字符串。其二是返回成功但文字全是乱的，查图片是不是实际是其他格式截图但存成了常见图片格式、是不是底图带水印导致模型被带偏、是不是把通用OCR用在手写票据上。其三是数字转出来不对，查后处理规则有没有吃千分位、中文大写有没有映射漏、位置坐标聚类有没有把两行数字并成一行。

监控上要把接口错误率、平均识别耗时、空结果率、转数值失败率拆开看。接口错误率是网关和健康问题，空结果率是图片质量问题，转数值失败率是后处理规则问题，三件事混在一起看会误诊。

结语

天翼云通用OCR接口的接入，前半段是网关鉴权和请求约束的体力活，后半段是把识别字符串可靠地变成业务数值的脑力活。开发工程师最容易把精力全花在怎么把图发出去，却轻视各种格式的数值怎么变成程序里能计算的数字这一环，而上线的数据错乱往往就出在后一环。把鉴权签名、图片边界、位置坐标聚类、字符串清洗、数值校验、异常分类这六件事按顺序钉牢，通用OCR才真正从能识别出字变成能让系统用数字做计算。官网那句返回检测到的文字内容及位置信息，分量就在位置二字——没有位置坐标，文本转数字只是盲猜；有了位置坐标，印刷体里的数字才有机会被安静地、准确地请进数据库。