通用OCR大模型

1\. 通用OCR大模型描述
--------------

OCR大模型

2\. 接口说明
--------

### 2.1. 请求方法和URL

```
ws(s)://ltm-cn-huabei-1.xf-yun.com/v1/private/se75ocrbm
```

注：全链路请求会话时长不超过1分钟

### 2.2. 接口Demo
[通用OCR大模型 demo Java语言](/media/attachment/2024/06/%E9%80%9A%E7%94%A8OCR%E5%A4%A7%E6%A8%A1%E5%9E%8B_websocket_demo.zip)

通用OCR大模型 demo Python语言

demo 覆盖部分语言，其他语言参照下方接口文档进行开发。

### 2.3. 接口要求

接口类型：流式 \[ws(s)\]

接口鉴权：使用签名机制进行鉴权，签名详情参照 “[接口鉴权](https://in.iflyaicloud.com/aipaas-doc//docs/api%E6%8E%A5%E5%8F%A3%E9%89%B4%E6%9D%83.html)”

3\. 请求
------

### 3.1. 请求协议示例

```
{
    "header": {
        "app_id": "123456",
        "uid": "39769795890",
        "did": "SR082321940000200",
        "imei": "8664020318693660",
        "imsi": "4600264952729100",
        "mac": "6c:92:bf:65:c6:14",
        "net_type": "wifi",
        "net_isp": "CMCC",
        "status": 0,
        "request_id": null,
        "res_id": ""
    },
    "parameter": {
        "ocr": {
            "result_option": "normal",
            "result_format": "json",
            "output_type": "one_shot",
            "exif_option": "0",
            "json_element_option": "",
            "markdown_element_option": "watermark=0,page_header=0,page_footer=0,page_number=0,graph=0",
            "sed_element_option": "watermark=0,page_header=0,page_footer=0,page_number=0,graph=0",
            "alpha_option": "0",
            "rotation_min_angle": 5,
			"result": {
                "encoding": "utf8",
                "compress": "raw",
                "format": "plain"
            }
        }
    },
    "payload": {
        "image": {
            "encoding": "jpg",
            "image": "",
            "status": 0,
            "seq": 0
        }
    }
}
```

**协议结构说明**

| 字段      | 含义         | 类型   | 说明                                                         |
| --------- | ------------ | ------ | ------------------------------------------------------------ |
| header    | 协议头部     | Object | 协议头部，用于描述平台特性的参数，详见 3.2.1 平台参数。      |
| parameter | 能力参数     | Object | AI 特性参数，用于控制 AI 引擎特性的开关。                    |
| ocr       | 服务别名     | Object |                                                              |
| result    | 响应数据控制 | Object | 数据格式预期，用于描述返回结果的编码等相关约束，不同的数据类型，约束维度亦不相同，此 object 与响应结果存在对应关系。 |
| payload   | 输入数据段   | Object | 数据段，携带请求的数据。                                     |
| image     | 输入数据     | Object | 输入数据，详见 3.2.3 请求数据。                              |

### 3.2. 请求参数

#### 3.2.1. 平台参数

| 字段        | 含义                                                         | 类型   | 限制                    | 是否必传 |
| ----------- | ------------------------------------------------------------ | ------ | ----------------------- | -------- |
| app\_id     | 在平台申请的app id信息，[点击申请](https://in.iflyaicloud.com/console/home) | string | "maxLength":50          | 是       |
| uid         | 请求用户服务返回的uid，用户及设备级别个性化功能依赖此参数    | string | "maxLength":50          | 否       |
| did         | 请求方确保唯一的设备标志，设备级别个性化功能依赖此参数       | string | "maxLength":50          | 否       |
| imei        | 设备imei信息                                                 | string | "maxLength":50          | 否       |
| imsi        | 设备imsi信息                                                 | string | "maxLength":50          | 否       |
| mac         | 设备mac信息                                                  | string | "maxLength":50          | 否       |
| net\_type   | 网络类型，可选值为wifi、2G、3G、4G、5G                       | string | wifi、2G、3G、4G、5G    | 否       |
| net\_isp    | 运营商信息，可选值为CMCC、CUCC、CTCC、other                  | string | CMCC、CUCC、CTCC、other | 否       |
| request\_id | 客户端请求的会话唯一标识                                     | string | "maxLength":64          | 否       |
| res\_id     | 个性化资源ID                                                 | string | "maxLength":1024        | 否       |
| status      | 请求状态，可选值为：0-开始、1-继续、2-结束                   | int    | 0、1、2                 | 是       |

#### 3.2.2. 服务特性参数

**功能参数**

| 功能标识                  | 功能描述                                                     | 数据类型 | 取值范围                                                     | 必填 | 默认值                                                       |
| ------------------------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| result\_option            | 输出结果级别，以逗号分隔，默认为“normal”，取值范围可枚举     | string   | normal:输出OCR识别结果和行坐标, normal,char:输出OCR识别结果和字符单元（CharUnit）结果, normal,no\_line\_position:输出不带行坐标的OCR识别结果, normal,char,no\_line\_position:输出不带行坐标的OCR识别结果、字符单元（CharUnit）结果 | 否   | normal                                                       |
| result\_format            | 输出结果格式,默认为“json”，取值范围可枚举                    | string   | json:输出结果为JSON字符串格式, json,markdown:输出结果为json、markdown格式, json,sed:输出结果为json、简单要素文档（sed）格式, json,markdown,sed:输出结果为json、markdown、简单要素文档（sed）格式 | 否   | json                                                         |
| output\_type              | 结果输出方式，默认为”one\_shot”，取值范围可枚举，当前版本仅支持one\_shot | string   | one\_shot:一次性输出全量结果, streaming\_layout:流式输出两次，第一次输出版面信息，第二次输出全量结果 | 否   | one\_shot                                                    |
| exif\_option              | 是否解析图片exif头，默认为“0”，取值范围可枚举                | string   | 0:不解析, 1:解析                                             | 否   | 0                                                            |
| json\_element\_option     | (保留字段暂不支持)默认为空字符串，所有要素均输出；针对每个要素有特殊需求时可使用本参数进行设定 输入格式为: “element\_name1=value1,element\_name2=value2” | string   | 最小长度:0, 最大长度:1000                                    | 否   |                                                              |
| markdown\_element\_option | 默认为空字符串，所有要素均输出；针对每个要素有特殊需求时可使用本参数进行设定，输入格式为: “element\_name1=value1,element\_name2=value2”其中element\_name可选值有：seal:印章，information\_bar:信息栏，fingerprint:手印，qrcode:二维码，watermark:水印，barcode:条形码，page\_header:页眉 ，page\_footer:页脚，page\_number:页码，layout:版面，title:标题，region:区域，paragraph:段落，textline:文本行，table:表格，graph:插图，list:列表，pseudocode:伪代码，code:代码，footnote:脚注，formula:公式；value值可选值有：0:不输出，1:输出，默认值；说明：当element\_name为table时，1表示同时识别有线表和少线表，2表示只识别有线表。 | string   | 最小长度:0, 最大长度:1000                                    | 否   | watermark=0,page\_header=0,page\_footer=0,page\_number=0,graph=0 |
| sed\_element\_option      | 默认为空字符串，所有要素均输出；针对每个要素有特殊需求时可使用本参数进行设定，输入格式为:“element\_name1=value1,element\_name2=value2”其中element\_name可选值有：seal:印章，information\_bar:信息栏，fingerprint:手印，qrcode:二维码，watermark:水印，barcode:条形码，page\_header:页眉，page\_footer:页脚，page\_number:页码，layout:版面，title:标题，region:区域，paragraph:段落，textline:文本行，table:表格，graph:插图，list:列表，pseudocode:伪代码，code:代码，footnote:脚注，formula:公式；value值可选值有：0:不输出，1:输出，默认值；说明：当element\_name为table时，1表示同时识别有线表和少线表，2表示只识别有线表。 | string   | 最小长度:0, 最大长度:1000                                    | 否   | watermark=0,page\_header=0,page\_footer=0,page\_number=0,graph=0 |
| alpha_option              | 是否解析图片的alpha通道，默认为“0”，取值范围可枚举                | string   | 0:不解析图片的alpha通道，即仅读取图片的RGB通道。若alpha通道为透明（即alpha通道的值为0）的区域存在文字，该区域的文字不可见，但识别结果中会出现该区域的文字，即出现识别结果与看到的内容不一致的现象, 1:解析图片的alpha通道，若图片存在alpha通道，将alpha通道为透明（alpha通道的值为0）的像素的RGB值设为白色（#FFFFFF），若alpha通道为透明的区域存在文字，识别结果中不会出现透明区域的文字，即识别结果与看到的内容保持一致。                                              | 否   | 0                                                            |
| rotation_min_angle              | 图像的最小旋转角度阈值，当图像绕中心顺、逆时针旋转的角度绝对值超过该阈值时，对图像进行旋转，取值范围为[0,180]，其中： 0：有旋转角度的图像均进行旋转。 180：所有图像均不进行旋转。 默认值为“5”，即当图像旋转角度的绝对值超过5°时才进行旋转。                | float   | 最小值:0, 最大值:180                                             | 否   | 5                                                            |
| word_element_option              | 文档恢复针对每个要素有特殊需求时可使用本参数进行设定 输入格式为: “element_name1=value1,element_name2=value2” 其中element_name可选值有： seal:印章 information_bar:信息栏 qrcode:二维码 watermark:水印 barcode:条形码 page_header:页眉 page_footer:页脚 page_number:页码 title:标题 table:表格 graph:插图 pseudocode:伪代码 code:代码 footnote:脚注 formula:公式 value值可选值有： 0:不输出 1:输出，默认值； 默认值：“watermark=0” 说明： 1、当element_name为table时，0表示不识别表格，1表示同时识别有线表、少线表和无线表，2表示只识别有线表，3表示同时识别无线表、少线表。 2、页面、版面、区域、段落、文本行作为基本要素，默认输出                | string   | 最小值:0, 最大值:1000                                            | 否   | watermark=0                           
| table_mode              | （当前版本暂不支持取值0）两种表格方案，默认值为“1”。取值范围可枚举	                | string   | 0:(当前版本暂不支持）文字识别效果和结构识别效果较1稍好，但是单元格坐标不可用。, 1:文字识别效果和结构识别效果较0稍差，单元格坐标可用。                                            | 否   | 1
| color_postproc_option              | 颜色后处理插件开关，该插件输出颜色为整行文本的颜色，无法区分一行内的多种颜色，取值范围可枚举。颜色取值范围为：#FF0000：红色、#00FF00：绿色、#0000FF：蓝色、#FFFF00：黄色、#800080：紫色、#FFA500：橙色、#00FFFF：青色、#FFFFFF：白色、#A52A2A：棕色、#AAAAAA：灰色、#FFC0CB :粉色、#000000：黑色                | string   | 0:不生效，不影响result_option中color参数, 1:打开颜色后处理插件，参数result_option设置包含color时使用插件结果替换原始结果，颜色取值为任意RGB值十六进制字符串；                                             | 否   | 0
| markdown_format_option              | 用于控制markdown是否输出纯文本格式，纯文本格式定义为相较于原始markdown格式，无标题、列表的修饰字段（#、-、*等），文字的格式化信息（加粗、斜体等）、换行符从双\n修改为单\n，取值范围可枚举                | string   |normal:正常markdown格式, plain_text:纯文本格式                                            | 否   | normal

**响应数据参数**

result 段的参数（默认返回）

| 字段     | 含义         | 数据类型 | 取值范围          | 默认值 | 说明           | 必填 |
| -------- | ------------ | -------- | ----------------- | ------ | -------------- | ---- |
| encoding | 文本编码     | string   | utf8, gb2312, gbk | utf8   | 取值范围可枚举 | 否   |
| compress | 文本压缩格式 | string   | raw, gzip         | raw    | 取值范围可枚举 | 否   |
| format   | 文本格式     | string   | plain, json, xml  | plain  | 取值范围可枚举 | 否   |

#### 3.2.3. 请求数据

image（默认请求）

| 字段     | 含义     | 数据类型 | 取值范围                                             | 默认值 | 说明                          | 必填 |
| -------- | -------- | -------- | ---------------------------------------------------- | ------ | ----------------------------- | ---- |
| encoding | 图像编码 | string   | jpg:jpg格式, jpeg:jpeg格式, png:png格式, bmp:bmp格式 | jpg    | 图像编码                      | 否   |
| image    | 图像数据 | string   | 最小尺寸:1B, 最大尺寸:10485760B                      |        | 需base64编码，图片大小：0~10M | 是   |
| status   | 数据状态 | int      | 0:开始, 1:继续, 2:结束                               |        | 流式传输                      | 是   |
| seq      | 数据序号 | int      | 最小值:0, 最大值:9999999                             | 0      | 标明数据为第几块              | 否   |

4\. 响应
------

### 4.1. 响应协议示例

```
{
    "header": {
        "code": 0,
        "message": "success",
        "sid": "ase000704fa@dx16ade44e4d87a1c802",
        "status": 0
    },
    "payload": {
        "result": {
            "encoding": "utf8",
            "compress": "raw",
            "format": "plain",
            "status": 0,
            "seq": 0,
            "text": ""
        }
    }
}
```

**协议结构说明**

| 字段    | 含义       | 类型   | 说明                                                    |
| ------- | ---------- | ------ | ------------------------------------------------------- |
| header  | 协议头部   | Object | 协议头部，用于描述平台特性的参数，详见 4.2.1 平台参数。 |
| payload | 响应数据块 | Object | 数据段，携带响应的数据。                                |
| result  | 响应数据块 | Object | 输出数据，详见 4.2.2 响应数据参数。                     |

### 4.2. 响应参数

#### 4.2.1. 平台参数

| 字段    | 含义                            | 类型   | 是否必选 |
| ------- | ------------------------------- | ------ | -------- |
| code    | 返回码，0表示成功，其它表示异常 | int    | 是       |
| message | 错误描述                        | string | 是       |
| sid     | 本次会话的id                    | string | 是       |

#### 4.2.2. 响应数据参数

result（默认返回）

| 字段     | 含义         | 数据类型 | 取值范围                       | 默认值 | 说明                         | 必填 |
| -------- | ------------ | -------- | ------------------------------ | ------ | ---------------------------- | ---- |
| encoding | 文本编码     | string   | utf8, gb2312, gbk              | utf8   | 取值范围可枚举               | 否   |
| compress | 文本压缩格式 | string   | raw, gzip                      | raw    | 取值范围可枚举               | 否   |
| format   | 文本格式     | string   | plain, json, xml               | plain  | 取值范围可枚举               | 否   |
| status   | 数据状态     | int      | 0:开始, 1:继续, 2:结束         |        | 流式传输                     | 是   |
| seq      | 数据序号     | int      | 最小值:0, 最大值:9999999       |        | 数据序号                     | 是   |
| text     | 文本数据     | string   | 最小尺寸:1B, 最大尺寸:1048576B |        | 需base64编码，文本大小：0-1M | 是   |

5\. 错误码列表
---------

错误码示例：

```
{
    "code":10003, // 平台通用错误码，详细信息请参照 5.1 平台通用错误码
    "message":"WrapperInitErr;errno=101", // errno 为引擎错误码
    "sid":"ocr00088c7d@dx170194697e9a11d902"
}
```

### 5.1. 平台通用错误码

| 错误码        | 错误描述                                     | 说明                                         | 处理策略                                                     |
| ------------- | -------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------ |
| 10009         | input invalid data                           | 输入数据非法                                 | 检查输入数据                                                 |
| 10010         | service license not enough                   | 没有授权许可或授权数已满                     | 提交工单                                                     |
| 10019         | service read buffer timeout, session timeout | session超时                                  | 检查是否数据发送完毕但未关闭连接                             |
| 10043         | Syscall AudioCodingDecode error              | 音频解码失败                                 | 检查aue参数，如果为speex，请确保音频是speex音频并分段压缩且与帧大小一致 |
| 10114         | session timeout                              | session 超时                                 | 会话时间超时，检查是否发送数据时间超过了60s                  |
| 10139         | invalid param                                | 参数错误                                     | 检查参数是否正确                                             |
| 10160         | parse request json error                     | 请求数据格式非法                             | 检查请求数据是否是合法的json                                 |
| 10161         | parse base64 string error                    | base64解码失败                               | 检查发送的数据是否使用base64编码了                           |
| 10163         | param validate error:...                     | 参数校验失败                                 | 具体原因见详细的描述                                         |
| 10200         | read data timeout                            | 读取数据超时                                 | 检查是否累计10s未发送数据并且未关闭连接                      |
| 10222         | context deadline exceeded                    | 1.上传的数据超过了接口上限； 2.SSL证书无效； | 1.检查接口上传的数据（文本、音频、图片等）是否超越了接口的最大限制，可到相应的接口文档查询具体的上限； 2. 请将log导出发到工单：https://console.xfyun.cn/workorder/commit； |
| 10223         | RemoteLB: can't find valued addr             | lb 找不到节点                                | 提交工单                                                     |
| 10313         | invalid appid                                | appid和apikey不匹配                          | 检查appid是否合法                                            |
| 10317         | invalid version                              | 版本非法                                     | 请到控制台提交工单联系技术人员                               |
| 10700         | not authority                                | 引擎异常                                     | 按照报错原因的描述，对照开发文档检查输入输出，如果仍然无法排除问题，请提供sid以及接口返回的错误信息，到控制台提交工单联系技术人员排查。 |
| 11200         | auth no license                              | 功能未授权                                   | 请先检查appid是否正确，并且确保该appid下添加了相关服务。若没问题，则按照如下方法排查。 1. 确认总调用量是否已超越限制，或者总次数授权已到期，若已超限或者已过期请联系商务人员。 2. 查看是否使用了未授权的功能，或者授权已过期。 |
| 11201         | auth no enough license                       | 该APPID的每日交互次数超过限制                | 根据自身情况提交应用审核进行服务量提额，或者联系商务购买企业级正式接口，获得海量服务量权限以便商用。 |
| 11503         | server error :atmos return an error data     | 服务内部响应数据错误                         | 提交工单                                                     |
| 11502         | server error: too many datas in resp         | 服务配置错误                                 | 提交工单                                                     |
| 100001~100010 | WrapperInitErr                               | 调用引擎时出现错误                           | 请根据message中包含的errno前往 5.2引擎错误码 查看对应的说明及处理策略 |