密级	公开
版本	10D.2

AICP ASR热词词表管理 HTTP开发手册

warning

自 10D.1 起，此接口已废弃，请使用新的统一资源管理接口。

1. 简介#

AICP 10 ASR 能力支持热词优化功能，也即用户可以通过接口上传热词词表（也称作个性化词汇，例如通讯录中的人名等），在识别时指定热词词表，ASR识别引擎在识别时，就会优先选取热词词表中的热词词汇。

目前用户热词分为三类：

权重修正类热词，对于热词在解码网络中建立新的路径或者修正其权重
文本替换类热词，检查结果文本，相同的就进行替换
音素替换类热词，检查音素序列，相同的就进行替换

权重修正类热词，会在解码过程中直接使用，遇到发音和热词词表中词汇的拼音差不多的时候，就会加强热词的权重，使得对应的词语识别为热词的几率就会大大提高，这些词汇更容易被识别出来。

而文本替换类和音素替换类热词都是在获取到解码结果之后，再根据原始结果是否匹配某些规则来进行替换的，因此只要匹配上总能输出结果。如果有多个替换类热词，那么文本替换类的热词优先于音素替换类热词，出现在词表前面的热词优先于词表后面的热词，不会优先选择长度更长的热词。

本文档描述了AICP 10 平台中的热词管理接口。通过这里提供的 HTTP 接口，用户可以对热词词表进行增、删、改、查的操作，同时这里获得的热词词表ID，可以用于在识别时指定ASR服务所使用的热词词表。

2. 热词词表描述#

2.1 热词词表格式#

热词词表的内容中为 UTF-8 编码，有无 BOM 头均可。整体内容不能超过100K。

内容中包括多行，每行代表一个热词，每行内容不能超过 256 字节。如果行首为 '#'，表示注释，不会进行解析。

2.2 每条热词格式#

每行定义的热词按照上述分类分别有自己的格式。不同类别的热词可以放在一个词表中，引擎会自动根据格式判断是哪一类热词。

2.2.1 权重调整类热词#

格式为：

热词 [标音] 权重

热词、标音、权重部分以空格或TAB字符隔开，标音内部也有空格，因此前后需要有[]和其他部分区分开。

2.2.1.1 热词#

热词可以是中文、英文或者中英文混、甚至可以有其它符号，但不能出现空格和 TAB 字符。

2.2.1.2 标音#

标音部分是可选的，如果没有标音，系统将会进行自动标音。如果出现一些多音字读法或者英文、符号等读法和系统自动标音不一致的情况，可以使用手动标音。

在手动标音时，中文的标音直接使用小写拼音+声调的方式，声调以1-5表示（1阴平 2阳平 3上声 4去声 5轻声）。英文可以用近似的中文拼音进行标注。（目前也可以用大写的英文音素进行标注，但由于比较复杂，并不推荐，将来会支持国际音标标注）。

同一个热词可以有多个标音，写成多行即可。

2.2.1.3 权重#

权重部分是可选的，表示热词概率修改的幅度。权重为整形值，范围是[-5,5]。大于等于0的权重用来增加该词语被识别的概率，小于0的权重用来减小该词语被识别的概率。缺省为0，一般使用缺省值即可，如果效果不明显可以适当增加权重，但是当权重较大时会影响其他词汇的识别，导致整体识别率反而降低。

对于一些不希望出现的词，可以考虑使用小于0的权重，但这些词需要在原始模型的词表中。在这种情况下，如果有手动标音会被忽略。

对于不在原始模型中的词，本来出现的概率就不大，因此目前并不支持降低这些词权重。

2.2.1.4 示例#

# 系统自动标音
成都

# 一般的多音字，系统也能自动标对拼音，如果不确认，可以手动标音
重庆 [chong2 qing4]

# 英文用拼音标音
json [jie1 sen4]

# 符号等需要手工标音
长江➆号 [chang2 jiang1 qi1 hao4]

# 中英数字混合
k8s [kei4 ba1 ai1 si4]
陈sir [chen4 se4 er5]

# 增加权重
测试 1

# 标音+增加权重
莱昂纳多 [lai2 ang2 na4 duo1] 2

# 降低权重
吗 -1

2.2.2 文本替换类热词#

格式为：

热词 (原始识别词汇)

当原始识别结果文本中有定义的词汇时，就会被替换成热词。原始词汇中有空格是不支持的，热词中有空格是支持的，但总是会按照原样输出，也即会把空格也作为最终输出热词的一部分。

文本的比较是不区分大小写的。

注意：这可用于替代之前版本的 map.list。但这里的原始识别词汇并不像以前的 map.list 那样，需要在分词边界并且以空格隔开，原始词汇和热词也不需要分词数相等。

2.2.2.1 示例#

# 中央舞台 会被 替换为 中央五台
中央五台 (中央舞台)

# 英文符号的替换
I ♥ U (I love you)

2.2.3 音素替换类热词#

格式为:

热词 ([标音])

音素替换类热词，表示当查找到识别结果中的音素序列和定义的热词音素序列相同时，就将原来的识别结果替换为热词。

当后面的小括号内如果没有内容，或者括住的内容又是方括号括住的标音，表示音素替换类热词。

当小括号中没有内容时，表示自动标音，否则表示手动标音。标音概念同前面的建网类热词。

音素比较时，受到 conf 文件中 ignore_tone 配置的影响。当ignore_tone 是 true 时，比较的时候将忽略拼音音素的声调。

2.2.3.1 示例#

# 系统自动标音
成都 ()

# 一般的多音字，系统也能自动标对拼音，如果不确认，可以手动标音
重庆 ([chong2 qing4])

# 英文用拼音标音
json ([jie1 sen4])

# 符号等需要手工标音
长江➆号 ([chang2 jiang1 qi1 hao4])

# 中英数字混合
k8s ([kei4 ba1 ai1 si4])
陈sir ([chen4 se4 er5])

3. 接口描述#

3.1 请求URI#

添加热词词表
POST http://ip:port/v10/asr/userword/create?appkey={appkey}
修改热词词表
POST http://ip:port/v10/asr/userword/update?appkey={appkey}
查找热词词表
POST http://ip:port/v10/asr/userword/list?appkey={appkey}
查看热词词表
POST http://ip:port/v10/asr/userword/get?appkey={appkey}
删除热词词表
POST http://ip:port/v10/asr/userword/delete?appkey={appkey}

上述接口均支持 https 形式。

URL中的参数如下：

参数	类型	必选	说明
appkey	string	是	分配给开发者的 appkey

上述接口都使用JSON串作为包体，因此在HTTP Header中需要加上如下头：

参数	类型	必选	说明
Content-Type	string	是	application/json

上述接口暂时不需要先通过 get-access-token 接口获取 token，再将 token 放在 X-Hci-Access-Token 头中加以访问。

3.2 添加热词词表#

该接口支持用户添加热词词表。

3.2.1 请求消息#

参数	类型	必选	缺省	说明
userId	string	是		用户ID
vocab	object	是		热词词表信息

注意：

目前每个 userId 下面最多只能存储 10 套热词词表。
定义 "*" 为特殊的 userId，此 userId 下面存储的热词词表数量不受限制。主要为了非ToC场景，无需将热词词表和 userId 相关联。
userId 由开发者自行定义，不超过64字节。
不同的开发者下面的 userId 是独立的，即使名称相同，其热词词表也是不同的。
同一个开发者下面，userId 是在多个 appKey 下面共享的。如果希望不同 app 下的 userId 独立，请自行在 userId 上加入标识进行区分。

vocab 的结构如下：

参数	类型	必选	缺省	说明
name	string	是		热词词表的命名
lang	string	是		热词词表的语种 (参考`property`的第一部分)
desc	string	否	空串	热词词表描述
content	string	是		经过BASE64编码后的热词词表内容

注意：

目前在识别时，不会判断热词词表的 lang 是否和当前模型一致，但未来版本可能会加入判断。

3.2.2 响应消息#

参数	类型	说明
error	object	发生错误时可用，如果请求成功将没有此字段
created	object	调用成功表示添加的热词词表信息，调用失败时将没有此字段

error 的结构如下：

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

created 的结构如下：

参数	类型	说明
id	string	词表ID
ver	string	当前版本信息

3.2.3 示例#

请求示例

{
  "userId": "jths-2019",
  "vocab":
  {
    "name": "telepower",
    "lang": "cn",
    "content": "5Zub5bedIFtzaTQgY2h1YW4xXQ=="
  }
}

上述 content 内容是 "四川 [si4 chuan1]" 经过BASE64编码之后的串。

成功响应示例

{
  "created":
  {
      "id" : "CFD08A32-6176-4ad7-92F9-11ED015C8109",
      "ver": "1",
  }
}

失败响应示例

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

3.3 修改热词词表#

该接口支持用户更新热词词表。

3.3.1 请求消息#

参数	类型	必选	说明
userId	string	是	用户ID，必须和创建vocabId词表时候的用户一致
vocabId	string	是	热词词表Id，从添加接口中获取
vocab	object	是	热词词表信息

vocab 的结构和“添加接口”的输入参数一样，结构如下：

参数	类型	必选	缺省	说明
name	string	是		热词词表的命名
lang	string	是		热词词表的语种
desc	string	否	空串	热词词表描述
content	string	是		经过BASE64编码后的热词词表内容

3.3.2 响应消息#

参数	类型	说明
error	object	发生错误时可用，如果请求成功将没有此字段
updated	object	调用成功表示修改后的热词词表信息，调用失败时将没有此字段

updated 的结构如下：

参数	类型	说明
id	string	词表ID
ver	string	当前版本信息

其中 id 肯定和输入的 vocabId 一致， ver 为修改后的最新版本号。

注意： 目前版本只能更新 vocab 中的 content，也即词表内容本身，无法更新 name, lang, desc 等元信息。

3.3.3 示例#

请求示例

{
  "userId": "jths-2019",
  "vocabId": "CFD08A32-6176-4ad7-92F9-11ED015C8109",
  "vocab":
  {
    "name": "telepower",
    "lang": "cn",
    "content": "5rGf6IuPIFtqaWFuZzEgc3UxXQ=="
  }
}

成功响应示例

{
  "updated":
  {
      "id": "CFD08A32-6176-4ad7-92F9-11ED015C8109",
      "ver": "2"
  }
}

3.4 查找热词词表#

该接口支持用户查找其名下所有的热词词表。对于每个词表，都会返回其最新的版本。

3.4.1 请求消息#

参数	类型	必选	缺省	说明
userId	string	是		用户ID
skip	number	否	0	查询时前面跳过的数量
limit	number	否	100	每次查询返回的最大数量，范围 [1-10000]

3.4.2 响应消息#

参数	类型	说明
error	object	发生错误时可用，如果请求成功将没有此字段
totalCount	number	用户名下的热词词表的总数，调用失败时将没有此字段
vocabList	array	用户名下的指定分页中的热词词表信息，调用失败时将没有此字段

vocabList 中的每一项结构如下：

参数	类型	说明
id	string	热词词表Id
ver	string	热词词表的最新版本号
name	string	热词词表的名字
lang	string	热词词表的语种信息
desc	string	热词词表描述，如果为空，可能没有

注意：

此接口只返回词表的ID和元信息，不返回词表的具体内容。要查看词表的具体内容，请使用“查看热词词表”接口通过每个词表ID进行查看。
找不到userId的热词词表时返回错误，如果是skip大于总的数目了，则正常返回总数和空数组([])

3.4.3 示例#

请求示例

{
  "userId": "jths-2019"
}

请求示例，带页码信息

{
  "userId": "jths-2019",
  "skip": 10,
  "limit": 10,
}

成功响应示例

{
  "totalCount": 13,
  "vocabList": [
    {
      "id": "5F85A74C-BED9-4a15-B66E-039251D877D6",
      "ver": "1",
      "lang": "cn",
      "name": "weather",
    },
    {
      "id": "692602B7-3C4C-486a-954E-3256A0B9CE55",
      "ver": "2",
      "lang": "cn",
      "name": "arm",
    },
    {
      "id": "50875954-7328-42ab-B236-B3EC6E22207A",
      "ver": "1",
      "lang": "en",
      "name": "war",
      "desc": "some description"
    }
  ]
}

3.5 查看热词词表#

该接口支持用户获取热词词表内容。该接口会返回此热词词表的最新版本内容。

3.5.1 请求消息#

参数	类型	必选	缺省	说明
userId	string	是		用户ID，必须和创建vocabId词表时候的用户一致
vocabId	string	是		热词词表Id，从添加接口中获取

3.5.2 响应消息#

参数	类型	说明
error	object	发生错误时可用，如果请求成功将没有此字段
vocab	object	调用成功表示热词词表内容，调用失败时将没有此字段

vocab 的结构如下：

参数	类型	说明
id	string	热词词表ID
ver	string	热词词表的最新版本号
name	string	热词词表的名字
lang	string	热词词表的语种信息
desc	string	热词词表描述，如果为空，可能没有
content	string	BASE64编码后的热词词表内容

3.5.3 示例#

请求示例

{
  "userId": "jths-2019",
  "vocabId": "110C84A7-D2AF-4f49-9D9C-7FCBEE4DA9AE"
}

响应示例

{
  "vocab": {
    "id": "110C84A7-D2AF-4f49-9D9C-7FCBEE4DA9AE",
    "ver": "3",
    "name": "telepower",
    "lang": "cn",
    "desc": "no desc",
    "content": "W+aIkOmDvSBjaGVuZzFkdTFdIg=="
  }
}

3.6 删除热词词表#

该接口支持用户删除一个指定的热词词表。该接口将删除此词表的所有版本。

3.6.1 请求消息#

参数	类型	必选	缺省	说明
userId	string	是		用户ID，必须和创建vocabId词表时候的用户一致
vocabId	string	是		热词词表Id，从添加接口中获取

3.6.2 响应消息#

参数	类型	说明
error	object	发生错误时可用，如果请求成功将没有此字段
deleted	object	调用成功表示删除的热词词表内容，调用失败时将没有此字段

deleted 结构如下：

参数	类型	说明
id	strin	被删除的热词词表ID

3.6.3 示例#

请求示例

{
  "userId": "jths-2019",
  "vocabId": "6A522D0A-AAD6-428b-AAB8-E225EABEBC94"
}

成功响应示例

{
  "deleted":
  {
    "id": "6A522D0A-AAD6-428b-AAB8-E225EABEBC94",
  }
}

4. 版本记录#

接口版本	平台支持版本	组件及支持版本	修改内容
10.1.0	10D.0	aicp_asr_ft 10.5.0	支持替换类热词
10.0.0	10A.1	aicp_asr_ft 10.1.0	初始版本