全部产品
云市场

POP API创建泛热词表

更新时间:2019-10-16 10:02:56

使用POP API的方式,您可以在客户端自行操作训练泛热词,不需依赖管控台的设置。可执行的操作:

  • 创建词表,对应的POP API为 CreateAsrVocab
  • 获取词表,对应的POP API为 GetAsrVocab
  • 更新词表,对应的POP API为 UpdateAsrVocab
  • 删除词表,对应的POP API为 DeleteAsrVocab
  • 列举所有词表,对应的POP API为 ListAsrVocab

调用限制

  1. 默认最多可创建10个词表。
  2. 同一个词表中最多添加128个词,每个词语最长32个字,不能超出限制。
  3. 泛热词必须为UTF-8编码,不能包含标点、特殊字符。
  4. 泛热词对应的权重取值范围为[-6, 5]之间的整数,不能超出限制。大于0的权重用来增加该词语被识别的概率,小于0的权重用来减小该词语被识别的概率。权重-6表示尽量不要识别出这个词语;权重2是常用的值,如果效果不明显可以适当增加权重,但是当权重较大时可能会有一些负面效果,导致其他词语识别不准确。

创建词表

一个词表就是一类泛热词的组合。

输入参数

提交创建词表的请求时,需要设置输入参数到请求的Body中,如下表所示:

名称 类型 是否必需 说明
Name String 词表名称
Description String 词表描述信息
WordWeights String 词表里的词和对应的权重,JSON的Map格式字符串,例如:”{\”苹果\”: 3, \”西瓜\”: 3}”,key为String类型的泛热词,value为Int类型的泛热词对应的权重

泛热词和权重的使用查看调用限制。

输出参数

提交创建词表的请求,响应的输出参数为JSON格式的字符串。

正常返回:

  1. {
  2. "VocabId": "0074ac87db754e0fbd3465c60d86e118",
  3. "RequestId": "77C00AE4-A646-4A41-B6FF-F06C19FACE76"
  4. }

参数说明:

  • 返回HTTP状态:200表示成功,更多状态码请查阅HTTP状态码;
  • 返回JSON格式字符串参数:
名称 类型 说明
RequestId String 请求ID
VocabId String 词表ID,作为后续词表的获取、更新、删除使用

获取词表

根据词表的ID可以获取对应的词表信息。

输入参数

提交获取词表的请求时,需要设置输入参数到请求的Body中,如下表所示:

名称 类型 是否必需 说明
Id String 词表ID(创建词表时获取的VocabId)

输出参数

提交获取词表的请求,响应的输出参数为JSON格式的字符串。

正常响应:

  1. {
  2. "RequestId": "A590423E-FEBC-4AA0-A520-4DA772929E04",
  3. "Vocab": {
  4. "Name": "测试词表",
  5. "Md5": "58c732d3b31eb564c275371d46fcdfc0",
  6. "Description": "测试词表描述",
  7. "CreateTime": "2018-11-26 17:19:40",
  8. "UpdateTime": "2018-11-26 17:19:40",
  9. "Id": "6118b2a057d1440bb253382a76177ced",
  10. "WordWeights": {
  11. "西瓜": 3,
  12. "苹果": 3
  13. },
  14. "Size": 323
  15. }
  16. }

参数说明:

  • 返回HTTP状态:200表示成功,更多状态码请查阅HTTP状态码;
  • 返回JSON格式字符串参数:
名称 类型 说明
RequestId String 请求ID
Vocab Vocab对象 词表对象

其中,Vocab对象的参数描述:

名称 类型 说明
Id String 词表ID(与创建词表时获取的VocabId相同)
Name String 词表名称
Description String 词表描述信息
Size Int 词表编译后的大小
Md5 String 词表编译后的md5值
CreateTime String 词表创建时间
UpdateTime String 词表更新时间
WordWeights Map 词表中的泛热词和对应的权重

更新词表

根据词表的ID可以更新对应的词表信息,包括词表名称、词表描述信息、词表的词和权重。

输入参数

提交更新词表的请求时,需要设置输入参数到请求的Body中,如下表所示:

名称 类型 是否必须 说明
Id String 词表Id(创建词表时获取的VocabId)
Name String 更新后的词表名称
Description String 更新后的词表描述信息,可选
WordWeights String 更新后的词表里泛热词和对应的权重,JSON的Map格式字符串

输出参数

提交获取词表的请求,响应的输出参数为JSON格式的字符串。

正常响应:

  1. {
  2. "RequestId": "829E373C-9E23-4DEF-A979-002F140B2FCC"
  3. }

参数说明:

  • 返回HTTP状态:200表示成功,更多状态码请查阅HTTP状态码;
  • 返回JSON格式字符串参数:
名称 类型 说明
RequestId String 请求ID

删除词表

根据词表的ID可以删除对应的词表。

输入参数

提交删除词表请求时,需要设置输入参数到请求的Body中,如下表所示:

名称 类型 是否必须 说明
Id String 词表Id(创建词表时获取的VocabId)

输出参数

提交删除词表的请求,响应的输出参数为JSON格式的字符串。

正常响应:

  1. {
  2. "RequestId": "75CCBD40-BC19-4227-9140-0F42806BBF6F"
  3. }

参数说明:

  • 返回HTTP状态:200表示成功,更多状态码请查阅HTTP状态码;
  • 返回JSON格式字符串参数:
名称 类型 说明
RequestId String 请求ID

列举词表

列举指定页的词表信息。

说明:为了防止响应的Body过大,列举请求获取的词表信息不包含具体的泛热词和对应的权重信息。

输入参数

提交列举词表请求时,需要设置输入参数到请求的Body中,如下表所示:

名称 类型 是否必需 说明
PageNumber Int 可选 页号,默认值为1,页号需大于0
PageSize Int 可选 每页包含的词表数量,默认值为10,取值范围[10, 100]

说明:服务端根据词表的修改时间降序排列,如果词表过多,一次获取全部的词表,导致HTTP请求的Body过大,可能会被中间的网关或者代理节点拦截,因此需要采用分页的方式,每次获取指定的一页词表。PageSize指定了每页的词表数量,不足一页按一页处理,PageNumber指定了要获取第几页的词表。

输出参数

提交列举词表的请求,响应的输出参数为JSON格式的字符串。

正常响应:

  1. {
  2. "Page": {
  3. "PageNumber": 1,
  4. "PageSize": 10,
  5. "TotalItems": 5,
  6. "TotalPages": 1,
  7. "Content": [{
  8. "Name": "测试词表_1",
  9. "Md5": "eafaaf1d73b17c9d35c64d600e0793d9",
  10. "Description": "测试词表描述_1",
  11. "CreateTime": "2018-11-26 17:51:41",
  12. "UpdateTime": "2018-11-26 17:51:41",
  13. "Id": "266df2819a9d4d96a07c5c5d39b6430e",
  14. "Size": 323
  15. }, {
  16. "Name": "测试词表_2",
  17. "Md5": "f32c10fd8569cb3712576a0ea988d469",
  18. "Description": "测试词表描述_2",
  19. "CreateTime": "2018-11-26 17:51:41",
  20. "UpdateTime": "2018-11-26 17:51:41",
  21. "Id": "0fa718759c034f67bb3e394d2fd9866b",
  22. "Size": 323
  23. }]
  24. },
  25. "RequestId": "CB7B4AB4-5C16-4617-8B91-519A130E8991"
  26. }

参数说明:

  • 返回HTTP状态:200表示成功,更多状态码请查阅HTTP状态码;
  • 返回JSON格式字符串参数:
名称 类型 说明
RequestId String 请求ID
Page Page对象 输入参数中指定获取的页,没有指定默认获取第一页

其中Page对象的参数描述:

名称 类型 说明
Content List< Vocab > 词表数组,参考获取词表的输出参数Vocab,不包含WordWeights参数
PageNumber Int 页号,与输入参数相同
PageSize Int 页包含的词表数量,与输入参数相同
TotalPages Int 总页数
TotalItems Int 总词表数量

错误码

在提交创建词表、获取词表、更新词表、删除词表、列举词表的请求时,获取的HTTP响应状态码如果不是200,则表示请求失败,失败信息以JSON格式字符串包含在HTTP响应的Body中,具体的错误码如下表所示:

错误码 说明 解决方案
SLP.PAGE_NUMBER_INVALID 调用列举接口是设置了无效的页号 请检查列举的页号是否在有效取值范围:[1, ∞)
SLP.PAGE_SIZE_INVALID 调用列举接口时设置了无效的页大小 请检查列举的页大小是否在有效取值范围:[10, 100]
SLP.NOT_FOUND 词表ID不存在 请检查使用的词表ID是否正确
SLP.PARAMETER_ERROR 请求参数设置错误 请参考返回的具体错误消息提示,检查参数设置
SLP.EXCEED_LIMIT 创建词表数量超过上限 请确认现有的词表数量限制,默认每个用户允许创建10个泛热词表
SLP.ASR_VOCAB_ERROR 其他错误 与词表相关的其他错误,请看考错误消息提示

以创建词表超出数量限制的错误响应为例:

  1. {
  2. "RequestId": "848C33E3-5A74-4BF8-9BE6-B78576C6388A",
  3. "HostId": "nls-slp.cn-shanghai.aliyuncs.com",
  4. "Code": "SLP.EXCEED_LIMIT",
  5. "Message": "Vocab count has reached the limit! (max: 10)"
  6. }

Demo示例

说明:Demo示例为Java语言的示例,使用了阿里云Java SDK的CommonRequest用来提交请求,采用的是RPC风格的POP API调用。阿里云SDK的详细介绍请阅读 集成开发最佳实践,Java SDK CommonRequest的使用方法请阅读 使用CommonRequest进行调用

添加Java依赖您只需要依赖阿里云Java SDK的核心库与阿里开源库fastjson即可。阿里云Java SDK的核心库版本支持3.5.0及以上(如果版本在4.0.0及以上,需要增加其对应的第三方依赖,根据错误提示补充即可)。

  1. <dependency>
  2. <groupId>com.aliyun</groupId>
  3. <artifactId>aliyun-java-sdk-core</artifactId>
  4. <version>3.7.1</version>
  5. </dependency>
  6. <dependency>
  7. <groupId>com.alibaba</groupId>
  8. <artifactId>fastjson</artifactId>
  9. <version>1.2.49</version>
  10. </dependency>

示例代码

  1. import com.alibaba.fastjson.JSONObject;
  2. import com.aliyuncs.CommonRequest;
  3. import com.aliyuncs.CommonResponse;
  4. import com.aliyuncs.DefaultAcsClient;
  5. import com.aliyuncs.IAcsClient;
  6. import com.aliyuncs.exceptions.ClientException;
  7. import com.aliyuncs.http.MethodType;
  8. import com.aliyuncs.http.ProtocolType;
  9. import com.aliyuncs.profile.DefaultProfile;
  10. import java.util.ArrayList;
  11. import java.util.HashMap;
  12. import java.util.List;
  13. import java.util.Map;
  14. public class AsrVocabPopApiDemo {
  15. /**
  16. * 地域信息
  17. * 常量内容,请勿改变
  18. */
  19. private static final String REGION_ID = "cn-shanghai";
  20. private static final String DOMAIN = "nls-slp.cn-shanghai.aliyuncs.com";
  21. private static final ProtocolType PROTOCOL_TYPE = ProtocolType.HTTPS;
  22. /**
  23. * POP API信息
  24. * 常量内容,请勿改变
  25. */
  26. private static final String API_VERSION = "2018-11-20";
  27. private static final String ACTION_CREATE_ASR = "CreateAsrVocab";
  28. private static final String ACTION_GET_ASR_VOCAB = "GetAsrVocab";
  29. private static final String ACTION_LIST_ASR_VOCAB = "ListAsrVocab";
  30. private static final String ACTION_UPDATE_ASR_VOCAB = "UpdateAsrVocab";
  31. private static final String ACTION_DELETE_ASR_VOCAB = "DeleteAsrVocab";
  32. /**
  33. * 参数设置key
  34. * 常量内容,请勿改变
  35. */
  36. private static final String KEY_VOCAB_ID = "VocabId";
  37. private static final String KEY_ID = "Id";
  38. private static final String KEY_NAME = "Name";
  39. private static final String KEY_DESCRIPTION = "Description";
  40. private static final String KEY_WORD_WEIGHTS = "WordWeights";
  41. private static final String KEY_VOCAB = "Vocab";
  42. private static final String KEY_PAGE = "Page";
  43. private static final String KEY_PAGE_NUMBER = "PageNumber";
  44. private static final String KEY_PAGE_SIZE = "PageSize";
  45. // 阿里云鉴权client
  46. private static IAcsClient client;
  47. static class Vocab {
  48. public String Id;
  49. public String Name;
  50. public String Description;
  51. public int Size;
  52. public String Md5;
  53. public String CreateTime;
  54. public String UpdateTime;
  55. public Map<String, Integer> WordWeights = new HashMap<String, Integer>();
  56. }
  57. static class Page {
  58. class VocabContent {
  59. public String Id;
  60. public String Name;
  61. public String Description;
  62. public int Size;
  63. public String Md5;
  64. public String CreateTime;
  65. public String UpdateTime;
  66. }
  67. public int PageNumber;
  68. public int PageSize;
  69. public int TotalItems;
  70. public int TotalPages;
  71. public List<VocabContent> Content = new ArrayList<VocabContent>();
  72. }
  73. public AsrVocabPopApiDemo(String akId, String akSecret) {
  74. DefaultProfile profile = DefaultProfile.getProfile(REGION_ID, akId, akSecret);
  75. client = new DefaultAcsClient(profile);
  76. }
  77. private CommonRequest newRequest(String action) {
  78. CommonRequest request = new CommonRequest();
  79. request.setDomain(DOMAIN);
  80. request.setProtocol(PROTOCOL_TYPE);
  81. request.setVersion(API_VERSION);
  82. request.setMethod(MethodType.POST);
  83. request.setAction(action);
  84. return request;
  85. }
  86. /**
  87. * 创建词表
  88. *
  89. * @param name 词表名称,必填
  90. * @param description 词表描述信息,可选
  91. * @param wordWeights 词表里的词和对应的权重,JSON的Map格式,必填
  92. *
  93. * @return String 创建的词表Id
  94. */
  95. String createAsrVocab(String name, String description, String wordWeights) {
  96. CommonRequest request = newRequest(ACTION_CREATE_ASR);
  97. request.putBodyParameter(KEY_NAME, name);
  98. request.putBodyParameter(KEY_DESCRIPTION, description);
  99. request.putBodyParameter(KEY_WORD_WEIGHTS, wordWeights);
  100. CommonResponse response = null;
  101. try {
  102. response = client.getCommonResponse(request);
  103. } catch (ClientException e) {
  104. e.printStackTrace();
  105. }
  106. if (response.getHttpStatus() != 200) {
  107. System.out.println(response.getData());
  108. System.out.println("创建词表失败,HTTP错误码:" + response.getHttpStatus());
  109. return null;
  110. }
  111. JSONObject result = JSONObject.parseObject(response.getData());
  112. String vocabId = result.getString(KEY_VOCAB_ID);
  113. return vocabId;
  114. }
  115. /**
  116. * 获取词表
  117. *
  118. * @param vocabId 词表Id
  119. *
  120. * @return Vocab 获取的词表对象
  121. */
  122. Vocab getAsrVocab(String vocabId) {
  123. CommonRequest request = newRequest(ACTION_GET_ASR_VOCAB);
  124. request.putBodyParameter(KEY_ID, vocabId);
  125. CommonResponse response = null;
  126. try {
  127. response = client.getCommonResponse(request);
  128. } catch (ClientException e) {
  129. e.printStackTrace();
  130. }
  131. if (response.getHttpStatus() != 200) {
  132. System.out.println(response.getData());
  133. System.out.println("获取词表失败,HTTP错误码:" + response.getHttpStatus());
  134. return null;
  135. }
  136. JSONObject result = JSONObject.parseObject(response.getData());
  137. String vocabJson = result.getString(KEY_VOCAB);
  138. Vocab vocab = JSONObject.parseObject(vocabJson, Vocab.class);
  139. return vocab;
  140. }
  141. /**
  142. * 更新词表
  143. *
  144. * @param vocabId 待更新的词表Id
  145. * @param name 更新后的词表名称
  146. * @param description 更新后的词表描述
  147. * @param wordWeights 更新后的热词和权重
  148. *
  149. * @return boolean 更新词表是否成功
  150. */
  151. boolean updateAsrVocab(String vocabId, String name, String description, String wordWeights) {
  152. CommonRequest request = newRequest(ACTION_UPDATE_ASR_VOCAB);
  153. request.putBodyParameter(KEY_ID, vocabId);
  154. request.putBodyParameter(KEY_NAME, name);
  155. request.putBodyParameter(KEY_DESCRIPTION, description);
  156. request.putBodyParameter(KEY_WORD_WEIGHTS, wordWeights);
  157. CommonResponse response = null;
  158. try {
  159. response = client.getCommonResponse(request);
  160. } catch (ClientException e) {
  161. e.printStackTrace();
  162. }
  163. if (response.getHttpStatus() != 200) {
  164. System.out.println(response.getData());
  165. System.out.println("更新词表失败,HTTP错误码:" + response.getHttpStatus());
  166. return false;
  167. }
  168. return true;
  169. }
  170. /**
  171. * 删除词表
  172. *
  173. * @param vocabId 词表Id
  174. *
  175. * @return boolean 删除词表是否成功
  176. * */
  177. boolean deleteAsrVocab(String vocabId) {
  178. CommonRequest request = newRequest(ACTION_DELETE_ASR_VOCAB);
  179. request.putBodyParameter(KEY_ID, vocabId);
  180. CommonResponse response = null;
  181. try {
  182. response = client.getCommonResponse(request);
  183. } catch (ClientException e) {
  184. e.printStackTrace();
  185. }
  186. if (response.getHttpStatus() != 200) {
  187. System.out.println(response.getData());
  188. System.out.println("删除词表失败, HTTP错误码:" + response.getHttpStatus());
  189. return false;
  190. }
  191. return true;
  192. }
  193. /**
  194. * 列举词表
  195. * 如果不指定获取的页号,默认获取第1页
  196. * 如果不指定每页的词表数量,默认每页10个词表
  197. *
  198. * @return Page 所有词表信息
  199. */
  200. Page listAsrVocab() {
  201. CommonRequest request = newRequest(ACTION_LIST_ASR_VOCAB);
  202. request.putBodyParameter(KEY_PAGE_NUMBER, 1);
  203. request.putBodyParameter(KEY_PAGE_SIZE, 10);
  204. CommonResponse response = null;
  205. try {
  206. response = client.getCommonResponse(request);
  207. } catch (ClientException e) {
  208. e.printStackTrace();
  209. }
  210. if (response.getHttpStatus() != 200) {
  211. System.out.println(response.getData());
  212. System.out.println("列举词表失败,HTTP错误码:" + response.getHttpStatus());
  213. return null;
  214. }
  215. JSONObject result = JSONObject.parseObject(response.getData());
  216. String pageJson = result.getString(KEY_PAGE);
  217. Page page = JSONObject.parseObject(pageJson, Page.class);
  218. return page;
  219. }
  220. public static void main(String[] args) {
  221. if (args.length < 2) {
  222. System.err.println("FileASRDemo need params: <AccessKey Id> <AccessKey Secret>");
  223. return;
  224. }
  225. String accessKeyId = args[0];
  226. String accessKeySecret = args[1];
  227. AsrVocabPopApiDemo demo = new AsrVocabPopApiDemo(accessKeyId, accessKeySecret);
  228. // 词表ID
  229. String vocabId = null;
  230. /**
  231. * 创建词表
  232. */
  233. String name = "测试词表";
  234. String description = "测试词表描述";
  235. String wordWeights = "{\"苹果\": 3, \"西瓜\": 3}";
  236. vocabId = demo.createAsrVocab(name, description, wordWeights);
  237. if (vocabId != null) {
  238. System.out.println("创建词表成功,词表Id:" + vocabId);
  239. }
  240. else {
  241. System.out.println("创建词表失败!");
  242. return;
  243. }
  244. /**
  245. * 获取词表
  246. */
  247. Vocab vocab = demo.getAsrVocab(vocabId);
  248. if (vocab != null) {
  249. System.out.println("获取词表成功:" + JSONObject.toJSONString(vocab));
  250. }
  251. else {
  252. System.out.println("获取词表失败!");
  253. }
  254. /**
  255. * 更新词表
  256. */
  257. name = "测试词表2";
  258. description = "测试词表描述2";
  259. wordWeights = "{\"苹果\": 2, \"西瓜\": 2}";
  260. boolean isUpdated = demo.updateAsrVocab(vocabId, name, description, wordWeights);
  261. if (isUpdated) {
  262. System.out.println("更新词表成功:" + JSONObject.toJSONString(demo.getAsrVocab(vocabId)));
  263. }
  264. else {
  265. System.out.println("更新词表失败!");
  266. }
  267. /**
  268. * 删除词表
  269. */
  270. boolean isDeleted = demo.deleteAsrVocab(vocabId);
  271. if (isDeleted) {
  272. System.out.println("删除词表成功!");
  273. }
  274. else {
  275. System.out.println("删除词表失败!");
  276. }
  277. /**
  278. * 列举所有词表
  279. */
  280. // 创建多个词表
  281. for (int i = 0; i < 10; i++) {
  282. name = "测试词表_" + String.valueOf(i);
  283. description = "测试词表描述_" + String.valueOf(i);
  284. JSONObject jsonObject = new JSONObject();
  285. jsonObject.put("苹果", 2);
  286. jsonObject.put("西瓜", 2);
  287. wordWeights = jsonObject.toJSONString();
  288. demo.createAsrVocab(name, description, wordWeights);
  289. }
  290. // 列举创建的词表
  291. Page page = demo.listAsrVocab();
  292. if (page != null) {
  293. System.out.println("列举词表成功:" + JSONObject.toJSONString(page));
  294. }
  295. else {
  296. System.out.println("列举词表失败!");
  297. return;
  298. }
  299. // 删除所有的词表
  300. for (int i = 0; i < page.Content.size(); i++) {
  301. demo.deleteAsrVocab(page.Content.get(i).Id);
  302. }
  303. page = demo.listAsrVocab();
  304. if (page != null) {
  305. System.out.println("删除所有词表:" + JSONObject.toJSONString(page));
  306. }
  307. }
  308. }