密级	公开
版本	10D.2

AICP ASR 洗号服务开发手册

1. 洗号服务简介#

在电话外呼的场景中，客户需要对自动拨测的电话进行筛选，使用语音识别能力对铃音、忙音等进行识别并返回相关的匹配结果。能力平台提供专门的服务对上面的功能进行实现，此文档描述此服务的接口使用方式。

洗号服务接口分为两类：

短音频方式（short_audio），HTTP 接口形式，一次性传入整通音频，在响应里带着洗号结果。
流式短音频方式（short_stream），WebSocket 接口形式，通过分片的方式流式送入音频，在检测到洗号结果后即可返回。

2. 短音频接口#

2.1 请求 URI#

POST /v10/asr/ring/{property}/short_audio?appkey={appkey}

Query参数如下：

参数	类型	必选	说明
property	string	是	模型特征串，服务器端利用此值来调用不同的模型
appkey	string	是	分配给开发者的 appkey

本接口支持两种音频数据上传方式：

JSON方式上传音频，此时包体中是一个JSON串，配置项都放在JSON串中，而音频数据也需要进行BASE64编码后放在JSON串中。
二进制方式上传音频，此时包体中直接放置二进制形式的音频数据，而配置项都放置在 X-AICloud-Config 头中。

两种上传方式是通过Content-Type进行区分的，当Content-Type为 application/json时，采用JSON格式上传，为application/octet-stream时，则采用二进制方式上传。

2.2 JSON 模式#

2.2.1 HTTP Header#

参数	类型	必选	说明
Content-Type	string	是	application/json
X-Hci-Access-Token	string	是	从 `get-access-token` 接口获取的令牌

X-Hci-Access-Token 是开发者使用分配给开发者的 appkey 和 secret 访问系统服务接口 get-access-token 获取到的令牌，详细见《系统服务 HTTP 开发手册》。

2.2.2 包体#

其它参数都放在包体里，以json形式提供。

参数	类型	必选	缺省	说明
config	object	是	-	识别配置信息
audio	string	是	-	要识别的语音数据，base64编码要求base64编码后大小不超过4M，音频时长不超过1分钟。
audio	string	是	-	要识别的语音数据，base64编码要求base64编码后大小不超过4M，音频时长不超过1分钟。
extraInfo	string	否	空	客户端设置的信息串，服务器端只做记录，或将来作为定制版本的一些特殊信息
recordId	string	否	空	客户端设置的信息串，服务器端记录详细记录或者音频文件时会作为文件名的一部分，以便将来和客户端的信息关联。只能包括数字、大小写字母、下划线。其它字符在作为文件名时会被转为下划线，最长64字节，超过会被截断
recordId	string	否	空

注意：音频的时长限制由服务器端决定，缺省为120秒，但在私有云部署环境下可以由服务器端配置进行调整。

config 的结构如下:

参数	类型	必选	缺省	说明
audioFormat	string	否	AUTO	音频数据格式, 取值参见下面的audioFormat 取值表格。

audioFormat 取值：

audioFormat	备注
auto	自动判断格式（缺省）
pcm_s16le_8k	8K signed 16bit，小端字节序, 单声道
pcm_s16le_16k	16K signed 16bit，小端字节序, 单声道
alaw_8k	8K 8bit alaw, 单声道
alaw_16k	16K 8bit alaw, 单声道
ulaw_8k	8K 8bit ulaw, 单声道
ulaw_16k	16K 8bit ulaw, 单声道
wav	wav格式，采样率、编码格式、声道由wav头决定目前仅支持 pcm_s16le, alaw, ulaw三种编码格式，只支持单声道
wav
ogg	ogg容器格式，支持 speex/opus 编码格式，只支持单声道

2.2.3 示例#

json模式示例如下：

POST /v10/asr/ring/cn_16k_common/short_audio?appkey=xxxxxx HTTP/1.1
Content-Type: application/json
X-Hci-Access-Token: xxxxxxxxxxxxxxxxxxxx

{
  "config":
  {
    "audioFormat": "ulaw_8k",
  },
  "audio": "/+MgxAAUeHpMAUkQAANhuRAC...",
  "extraInfo": "abcdefg"
}  

2.3 二进制模式#

2.3.1 HTTP Header#

参数	类型	必选	说明
Content-Type	string	是	application/octet-stream
X-Hci-Access-Token	string	是	从 `get-access-token` 接口获取的令牌
X-AICloud-Config	string	是	配置参数

X-Hci-Access-Token 是开发者使用分配给开发者的 appkey 和 secret 访问系统服务接口获取到的令牌，详细见《系统服务 HTTP 开发手册》。

X-AICloud-Config 是自定义的HTTP头，格式为逗号隔开的键值对，例如 name1=value1,name2=value2。允许的键如下：

参数	类型	必选	缺省
extraInfo	string	否	空
recordId	string	否	空
audioFormat	string	否	AUTO

各参数含义请参见JSON上传方式时候的参数列表。

注意：

当所有参数都使用默认配置时，也必须有 X-AICloud-Config头，值为空串。

2.3.2 包体#

在二进制格式上传方式下，包体中直接放置二进制的音频流，无需进行 BASE64 编码。包体大小不超过4M，音频时长不超过1分钟。

2.3.3 示例#

二进制方式上传的示例请求如下：

POST /v10/asr/ring/cn_16k_common/short_audio?appkey=xxxxxx HTTP/1.1
Content-Type: application/octet-stream
X-Hci-Access-Token: xxxxxxxxxxxxxxxxxxxx
X-AICloud-Config: audioFormat=ulaw_8k,addPunc=true,extraInfo=abcdefg

二进制音频数据...

2.4 响应#

发送识别的HTTP请求之后，会收到服务端的响应，识别的结果以JSON字符串的形式保存在该响应中。无论是JSON方式上传还是二进制方式上传音频数据，结果响应都是一样的。

请求是否成功通过HTTP 状态码来区分。

2.4.1 成功响应#

当 HTTP 状态码为 200 时，表示请求成功，识别结果在包体中。

2.4.1.1 响应字段说明#

参数	类型	说明
traceToken	string	服务内部的 token 字符串，可用于日志追溯。
result	object	调用成功表示识别结果，调用失败时将没有此字段, 多候选输出时，这里是第一候选结果

error 的结构如下：

参数	类型	说明
code	number	错误代码，参加下面的错误代码表
message	string	详细的错误信息

result 的结构如下：

参数	类型	说明
result	string	识别出的文本内容
keyword	string	识别出的洗号关键词内容
resultId	number	对应的洗号结果表中id
resultName	string	洗号结果的描述名称
confidence	number	识别的置信度, 介于 [0.0-1.0] 之间。注意，目前置信度不是很准确，不要过多依赖此值

2.4.1.2 响应示例#

{
  "traceToken": "token_abcd_12345",
  "result":
  {
   "result": "用户正在通话中",
   "keyword": "通话中",
   "resultId": 10,
   "resultName": "被叫忙",
   "confidence": 0.9
  }
}

2.4.2 失败响应#

如果HTTP 状态码不为 200 时，表示请求失败。

2.4.2.1 响应字段说明#

参数	类型	说明
traceToken	string	服务内部的 token 字符串，可用于日志追溯。在某些错误情况下可能没有此令牌字符串。
error	object	发生错误时可用，如果请求成功将没有此字段

error 的结构如下：

参数	类型	说明
code	number	错误代码，参加下面的错误代码表
message	string	详细的错误信息

响应的状态码及错误码，请参见《AICP 10 开发通用规范》

2.4.2.2 结果示例#

{
  "error":
  {
    "code": 3,
    "message": "10004: Parse Task Config Failed",
  }
}

3. 流式短音频接口#

实时短音频洗号识别支持用户将一整段语音分段，以流式输入，最后得到识别结果。语音识别引擎在获得分段的输入语音的同时，就可以同步地对这段数据进行特征提取和解码工作，而不用等到所有数据都获得后再开始工作。随着洗号音频的送入，根据实时识别结果进行结果匹配。识别结果分为两种场景：

识别结果中，能够匹配到洗号数据，服务端返回洗号结果，然后主动结束会话，并且忽略在此会话上接下来的音频流数据，主要交互流程如下：

识别过程中，未能匹配到洗号数据，用户发送END或者达到用户设置的最大时长，返回最终的识别结果，结束会话，主要交互流程如下：

会话停止条件有如下几种：

中间匹配到洗号结果
用户主动结束
音频长度超过最大长度限制

3.1 握手阶段#

3.1.1 请求 URI#

ws(s)://ip:port/v10/asr/ring/{property}/short_stream?appkey={appkey}[&access-token={token}]

3.1.2 Query参数#

参数	类型	必选	说明
property	string	是	模型特征串，服务器端利用此值来调用不同的模型
appkey	string	是	分配给开发者的 appkey
access-token	string	否	通过 `get-access-token` 获取到的令牌

3.1.3 HTTP Header参数#

参数	类型	必选	说明
X-Hci-Access-Token	string	是	从 `get-access-token` 接口获取的令牌

X-Hci-Access-Token 是开发者使用分配给开发者的 appkey 和 secret 访问系统服务接口 get-access-token 获取到的令牌，详细见《系统服务 HTTP 开发手册》。

注意： 在 HTML5 中，由于 Javascript 中在创建 WebScoket 对象时，无法设置HTTP 头域，因此无法传入 get-access-token 获取的令牌，此时可以通过URL中的 access-token 参数来传入。

3.1.4 握手阶段响应#

正常协议升级，HTTP 状态码为 101 Switching Protocols，此时没有其它响应。

如果没有给出令牌或者令牌无效、过期，则会返回 UNAUTHENTICATED 错误（HTTP Response Code 401: Unauthorized）。

其它响应的状态码及错误码，请参见《AICP 10 开发通用规范》

3.1.5 握手阶段示例#

以HTTP方式进行握手和协议升级

客户端发送请求：

GET /v10/asr/ring/cn_16k_common/short_stream?appkey=xxxxxx HTTP/1.1
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Version: 13
X-Hci-Access-Token: xxxxxxxx

服务器响应，完成握手和协议升级：

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

3.2 连接阶段#

3.2.1 连接阶段请求#

3.2.1.1 开始识别#

客户端发送"开始识别"请求，使用文本类型的数据帧(text message)发送，命令和本次会话的参数以json字符串的形式提供。

参数	类型	必选	缺省	说明
command	string	是	-	为 `START`，表示开始识别请求
extraInfo	string	否	空	客户端设置的信息串，服务器端只做记录，或将来作为定制版本的一些特殊信息
recordId	string	否	空	客户端设置的信息串，服务器端记录详细记录或者音频文件时会作为文件名的一部分，以便将来和客户端的信息关联。只能包括数字、大小写字母、下划线。其它字符在作为文件名时会被转为下划线，最长64字节，超过会被截断
recordId	string	否	空
config	object	是	-	配置信息

config 结构如下：

参数	类型	必选	缺省	说明
audioFormat	string	是	-	支持语音的格式, 取值参见下面的audioFormat 取值表格。
encParams	string	否	空串	编码参数，在裸音频格式 (pcm_xxx, alaw_xxx, ulaw_xxx) 下面无效，在其它压缩音频下需要根据不同的格式进行设置，格式为 `param1:value1;param2:value2`。不同格式可能有不同的参数值，但一般都会定义 `ar` 和 `ac` 两个参数，表示原始音频采样率和声道数。具体格式的参数值请参见 ASR WebSocket 开发手册中的附录文档。



audioMax	number	否	90	音频达到此时长后即便未能匹配到洗号结果，也不再进行识别，范围[10-300]，单位秒

audioformat 取值：

audioFormat	备注
pcm_s16le_8k	8K signed 16bit，小端字节序, 单声道
pcm_s16le_16k	16K signed 16bit，小端字节序, 单声道
alaw_8k	8K 8bit alaw, 单声道
alaw_16k	16K 8bit alaw, 单声道
ulaw_8k	8K 8bit ulaw, 单声道
ulaw_16k	16K 8bit ulaw, 单声道
jtx_speex	speex 压缩格式，使用捷通定义的封包格式，具体封包格式见附录
jtx_opus	opus 压缩格式，使用捷通定义的封包格式，具体封包格式见附录

注意： 在流式实时识别时，可以在传输音频之前先进行压缩，可以减少网络传输的流量。一些简单的压缩方法（alaw, ulaw）引入的压缩解压时间很短，但压缩比率也不高。某些复杂一些的压缩算法（speex/opus）压缩比率较大，但需要额外的时间消耗，因此需要根据实际情况决定是否使用压缩音频传输。

3.2.1.2 发送音频数据#

在收到“开始识别”的响应之后，可以开始发送音频数据。为节省流量，音频以二进制数据帧形式（binary message）的方式发送。

音频数据将分片发送，也即在获得一定量音频数据的同时就可以发送一个binary message，每个分片必须在40ms~1000ms之间，建议在需要实时反馈的情况下100ms，不需要实时反馈的情况下500ms。

3.2.1.3 结束识别#

对于识别中的对话，需要在Websocket上发送“结束识别”的请求来取消或结束识别。 "结束识别"请求使用文本类型的数据帧 (text message)发送，命令和参数以json字符串的形式提供。

参数	类型	必选	说明
command	string	是	为 `END`，表示结束识别请求
cancel	boolen	否	为 `true`时表示取消识别，也即丢弃识别中和未识别的语音数据并结束，不返回剩余的识别结果。为`false`则表示继续处理识别中和未识别的语音数据直到处理完所有之前发送的数据。
cancel	boolen	否

3.2.2 连接阶段响应#

由于WebSocket是全双工的，因此所谓响应就是从服务器端发送给客户端的消息，而且，也并不是所有的请求信息都有一条对应的响应。

3.2.2.1 开始识别请求响应#

服务器端收到“开始识别”请求时，会给出如下响应消息，以json字符串形式放置在text message中。

参数	类型	必选	说明
respType	string	是	为 `START`，表示开始识别响应
traceToken	string	是	服务内部的跟踪令牌，可用于在日志中追溯具体流程。
warning	array	否	可能的警告信息

warning 是一个数组，每一项的结构如下：

参数	类型	必选	说明
code	number	是	警告代码，具体的警告错误码见后
message	string	是	警告的详细信息

warning 字段说明有正常流程之外的情况发生，但可以继续识别下去。其 code 包括：

警告代码	说明
100	输入引擎的采样率和模型的采样率不一致，自动进行了升采样或降采样

3.2.2.2 识别结果响应#

参数	类型	必选	说明
respType	string	是	为 `RESULT`，表示识别结果的响应
traceToken	string	是	服务内部的跟踪令牌，可用于在日志中追溯具体流程。
sentence	object	是	一句话的结果

sentence 元素是一个json object，其结构如下：

参数	类型	必选	说明
startTime	number	是	一句的起始时间戳，单位ms
endTime	number	是	一句的结束时间戳，单位ms
isFinal	boolean	是	`true`表示是根据根据最终识别的洗号结果， `false`表示为中间结果的洗号结果
result	string	是	识别出的文本内容
keyword	string	是	匹配到的洗号keyword内容
resultId	number	是	对应的洗号结果表中id
resultName	string	是	洗号结果的描述名称
confidence	number	是	识别的置信度, 介于 [0.0-1.0] 之间。注意，目前置信度不是很准确，不要过多依赖此值
exceededAudio	boolean	是	是否因为达到audioMax结束的识别

3.2.2.3 结束识别请求响应#

参数	类型	必选	说明
respType	string	是	为 `END`，表示结束识别响应
traceToken	string	是	服务内部的令牌，可用于在日志中追溯具体流程。
reason	string	是	结束原因，参见下表

reason 的可能取值：

结束原因	说明
NORMAL	正常结束
CANCEL	用户取消，也即客户端发送”结束识别“指令时`cancel`参数为`true`
ERROR	识别过程中发生错误

3.2.2.4 错误响应#

参数	类型	必选	说明
respType	string	是	为 `ERROR`，表示错误响应
traceToken	string	否	服务内部的跟踪令牌，可用于在日志中追溯具体流程。
errCode	number	是	错误码，请参见《AICP 10 开发通用规范》
errMessage	string	是	处理结果的详细描述，主要是错误状态

这里的错误响应，通常是指不影响流程，但当前会话无法再进行下去的错误，包括如下情况：

配置串错误，包括存在不识别的配置串，或者配置串值的范围不合法
时序不正确，比如没有发“开始识别”指令，就发送了“结束识别”指令
音频分片大小不合理 (每个分片必须在40ms~1000ms之间)
识别过程中发生错误，比如音频解码发生错误

出现错误响应时，如果已经在一个会话中了，会再发送一个"结束识别”的响应，表示识别会话结束。如果会话还没有开始，那么发送此错误响应后不做其它操作。此后的音频数据都被忽略，直到收到下一个“开始识别”请求。

返回错误响应后，连接不会关闭，只是会关闭当前会话。客户端仍然可以在同一连接上启动新的会话。但如果在一定时间内出现错误响应的次数超过一定阈值时，服务器端也会发送“严重错误”响应，然后主动关闭连接。

3.2.2.5 严重错误响应#

参数	类型	必选	说明
respType	string	是	为 `FATAL_ERROR`，表示严重错误响应
traceToken	string	否	服务内部的跟踪令牌，可用于在日志中追溯具体流程。
errCode	number	是	错误码，请参见《AICP 10 开发通用规范》
errMessage	string	是	处理结果的详细描述，主要是错误状态

严重错误，通常指流程无法继续的情况。比如当出现以下情况：

服务端收到“开始识别”请求，等待音频数据超时，或者收到分片音频后，等待下一个分片超时，目前超时时间缺省均为20s
连接空闲时间（也即连接上没有任何有效会话）超过一定阈值，目前连接空闲超时时间缺省为2min
在没有任何有效会话的时候超过一定时间还收到音频流
在一段时间内连续出现错误情况超过一定次数

出现严重错误响应时，流程不再继续，服务器端会主动断连。

3.2.3 连接阶段示例#

客户端发送"开始识别"请求

{
  "command": "START",
  "config":
  {
    "audioFormat": "ulaw_8k",
    "audioMax":90,
  },
  "extraInfo": "abcdefgh"
}  

服务器端发送“开始识别”响应

{
  "respType": "START",
  "traceToken": "token_abcd_12345"
}

服务器端发送“开始识别”响应，但是带警告信息

{
  "respType": "START",
  "traceToken": "token_abcd_12345",
  "warning":
  [
    {
      "code": 100,
      "message": "speech sample rate automatically changed from 44100 to 16000"
    }
  ]
}

客户端开始分片发送音频数据

通过Binary Frame发送语音数据

服务器端匹配到洗号结果

{
  "respType": "RESULT",
  "traceToken": "token_abcd_12345",
  "sentence":
  {
    "startTime": 100,
    "endTime": 1500,
    "isFinal": true,
    "result": "用户正在通话中,请您稍后再拨。",
    "keyword": "通话中",
    "resultId": 10,
    "resultName": "被叫忙"
    "confidence": 95.2,
    "exceededAudio":false,
  }
}

客户端发送“结束识别”指令

{
  "command": "END",
  "token": "token_abcd_12345",
  "cancel": false
}

识别结束响应

如果上面“结束识别”指令中的cancel为false，会继续识别并先返回剩余的结果，然后返回“结束识别”响应；如果为true，则直接返回“结束识别”响应。

{
  "respType": "END",
  "traceToken": "token_abcd_12345",
  "reason": "NORMAL"
}

错误响应示例

{
  "respType": "ERROR",
  "errCode": 3,
  "errMessage": "Parse Task Config Failed",
}

严重错误响应示例

{
  "respType": "FATAL_ERROR",
  "errCode": 10,
  "errMessage": "Too many errors",
}

4. 洗号结果映射#

ASR 洗号引擎的输出结果通常为 振铃音检测结果 + 提示音识别结果。洗号过程则是在此输出结果上进行振铃音和识别结果关键词的检测和映射，得到最终的洗号结果。

4.1 振铃音检测结果#

振铃音检测结果有如下可能：

类别	含义	信号脉冲特征
#BUSY#	忙音	450Hz 0.35S(H)/0.35S(L)
#WAIT#	回铃音	450Hz 1S(H)/4S(L)
#RING#	其它	其它有规律的振铃音
#MUSIC#	彩铃
#FAX#	传真

#RING#、#FAX# 在新的洗号模型中，暂不支持。

4.2 洗号结果映射表#

ASR 洗号服务中会自带缺省的 识别结果关键词和洗号结果映射表，和 振铃音和洗号结果映射表。这两个映射表在服务端以文本方式存放，一般存放在 asr_ring 服务的 resource 路径下，文件名分别为：resource/OutbountWordFile.txt， resource/ZhenlingyinFile.txt。

在洗号过程中，会优先使用提示音识别结果进行关键词提取和洗号结果映射，在 识别结果关键词和洗号结果映射表 中定义了当识别结果中带有关键词(KEYWORD) 时返回的内容(RESULTID 和 RESULTNAME)，RESULTID 越大优先级越高。

当没有提示音识别结果或者在识别结果中无法提取到关键词时，才使用振铃音检测结果进行洗号结果映射。在 振铃音和洗号结果映射表 中定义了检测到某种振铃音(KEYWORD) 时返回的内容(RESULTID 和 RESULTNAME)，同样 RESULTID 越大优先级越高。

如果上述情况都无法命中，则会返回：RESULTID=0， RESULTNAME=其它情况。

用户可以自定义这两个映射表的内容，以便更好地适配不同区域或不同运营商的提示音话术。

下表为缺省的 识别结果关键词和洗号结果映射表 内容：

KEYWORD	RESULTID	RESULTNAME
通话中	10	被叫忙
暂时无法接通	10	被叫忙
正在通话	10	被叫忙
暂时无法接听	10	被叫忙
在拨	10	被叫忙
再拨	10	被叫忙
忙	10	被叫忙
手机转移	11	无应答
用户不存在	12	用户不存在
号码不存在	12	用户不存在
没有这个电话号码	12	用户不存在
空号	12	用户不存在
加拨零	12	用户不存在
加零	12	用户不存在
未开通语音通话功能	13	路由失败/用户不可达
通话已经被限制	13	路由失败/用户不可达
无权接受呼叫	13	路由失败/用户不可达
呼叫受限	13	路由失败/用户不可达
用户线故障	13	路由失败/用户不可达
关机	14	关机
来电提醒	14	关机
传真音	16	传真
暂停服务	17	停机
号码已过期	17	停机
停机	17	停机
保号	17	停机

下表为缺省的 振铃音和洗号结果映射表 内容：

KEYWORD	RESULTID	RESULTNAME
#BUSY#	10	被叫忙
#WAIT#	11	无应答
#RING#	11	无应答
#MUSIC#	11	无应答
#FAX#	16	传真

5. 版本记录#

接口版本	平台支持版本	组件及支持版本	修改内容
10.0.0	10C.0	aicp_asr_ring 10.0.0	初始版本