使用POP API创建业务专属热词 - 智能语音交互

本文为您介绍如何使用POP API，在客户端自行操作训练业务专属热词，而无需依赖控制台的设置。

操作概览

您可通过POP API执行如下操作：

创建词表： CreateAsrVocab
获取词表： GetAsrVocab
更新词表： UpdateAsrVocab
删除词表：DeleteAsrVocab
列举所有词表： ListAsrVocab

调用限制

默认最多创建10个词表。
每个词表最多添加128个词，每个词语最长10个字。
业务专属热词必须为UTF-8编码，不能包含标点、特殊字符。
业务专属词对应的权重取值范围为[-6,5]之间的整数。
说明
- 取值大于0增大该词语被识别的概率，小于0减小该词语被识别的概率。
- 取值为-6：表示尽量不要识别出该词语。
- 取值为2：常用值。
- 如果效果不明显可以适当增加权重，但是当权重较大时可能会引起负面效果，导致其他词语识别不准确。

创建词表

一个词表就是一类业务专属热词的组合。

请求参数：

提交创建词表的请求时，需要设置请求参数到请求的Body中，如下表所示。

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

返回数据：

返回数据为JSON格式的字符串。

{
        "VocabId": "0074ac87db754e0fbd3465c60d86****",
        "RequestId": "77C00AE4-A646-4A41-B6FF-F06C19FA****"
}

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

获取词表

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

请求参数：

提交获取词表的请求时，需要设置请求参数到请求的Body中，如下表所示。

名称	类型	是否必选	说明
Id	String	是	词表ID（创建词表时获取的VocabId）。

返回数据：

返回数据为JSON格式的字符串。

{
        "RequestId": "A590423E-FEBC-4AA0-A520-4DA77292****",
        "Vocab": {
                "Name": "测试词表",
                "Md5": "58c732d3b31eb564c275371d46fc****",
                "Description": "测试词表描述",
                "CreateTime": "2018-11-26 17:19:40",
                "UpdateTime": "2018-11-26 17:19:40",
                "Id": "6118b2a057d1440bb253382a7617****",
                "WordWeights": {
                        "西瓜": 3,
                        "苹果": 3
                },
                "Size": 323
        }
}

返回HTTP状态：200表示成功，更多状态码请查阅错误码。

返回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	是	更新后的词表名称。
WordWeights	String	是	更新后的词表里业务专属热词和对应的权重，为JSON的Map格式字符串。
Description	String	否	更新后的词表描述信息。

返回数据：

返回数据为JSON格式的字符串。

{
        "RequestId": "829E373C-9E23-4DEF-A979-002F140B****"
}

返回HTTP状态：200表示成功，更多状态码请查阅错误码。
返回JSON格式字符串参数：
名称
类型
说明
RequestId
String
请求ID。

删除词表

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

请求参数：

提交删除词表请求时，需要设置请求参数到请求的Body中，如下表所示。

名称	类型	是否必选	说明
Id	String	是	词表Id（创建词表时获取的VocabId）。

返回数据：

返回数据为JSON格式的字符串。

{
        "RequestId": "75CCBD40-BC19-4227-9140-0F42806B****"
}

返回HTTP状态：200表示成功，更多状态码请查阅错误码。
返回JSON格式字符串参数：
名称
类型
说明
RequestId
String
请求ID。

列举词表

列举指定页的词表信息。

说明

为了防止响应Body过大，获取的词表信息不包含具体的专属热词和对应的权重信息。

请求参数：

提交列举词表请求时，需要设置请求参数到请求的Body中，如下表所示。

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

说明

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

返回数据：

返回数据为JSON格式的字符串。

{
        "Page": {
                "PageNumber": 1,
                "PageSize": 10,
                "TotalItems": 5,
                "TotalPages": 1,
                "Content": [{
                        "Name": "测试词表_1",
                        "Md5": "eafaaf1d73b17c9d35c64d600e07****",
                        "Description": "测试词表描述_1",
                        "CreateTime": "2018-11-26 17:51:41",
                        "UpdateTime": "2018-11-26 17:51:41",
                        "Id": "266df2819a9d4d96a07c5c5d39b6****",
                        "Size": 323
                }, {
                        "Name": "测试词表_2",
                        "Md5": "f32c10fd8569cb3712576a0ea988****",
                        "Description": "测试词表描述_2",
                        "CreateTime": "2018-11-26 17:51:41",
                        "UpdateTime": "2018-11-26 17:51:41",
                        "Id": "0fa718759c034f67bb3e394d2fd9****",
                        "Size": 323
                }]
        },
        "RequestId": "CB7B4AB4-5C16-4617-8B91-519A130E****"
}

返回HTTP状态：200表示成功，更多状态码请查阅错误码。

返回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	其他错误。	与词表相关的其他错误，请参考错误消息提示。

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

{
        "RequestId": "848C33E3-5A74-4BF8-9BE6-B78576C6****",
        "HostId": "nls-slp.ap-southeast-1.aliyuncs.com",
        "Code": "SLP.EXCEED_LIMIT",
        "Message": "Vocab count has reached the limit! (max: 10)"
}

示例代码

说明

示例使用了阿里云Java SDK的CommonRequest提交请求，采用的是RPC风格的POP API调用方式。
阿里云SDK的详细介绍请参见安装及使用Java SDK。
Java SDK CommonRequest的使用方法请参见使用CommonRequest进行调用。

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

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <version>3.7.1</version>
</dependency>
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>1.2.83</version>
</dependency>

import com.alibaba.fastjson.JSONObject;
import com.aliyuncs.CommonRequest;
import com.aliyuncs.CommonResponse;
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.http.MethodType;
import com.aliyuncs.http.ProtocolType;
import com.aliyuncs.profile.DefaultProfile;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
public class AsrVocabPopApiDemo {
    /**
     * 地域信息
     * 常量内容，固定值。
     */
    private static final String REGION_ID = "ap-southeast-1";
    private static final String DOMAIN = "nls-slp.ap-southeast-1.aliyuncs.com";
    private static final ProtocolType PROTOCOL_TYPE = ProtocolType.HTTPS;
    /**
     * POP API信息
     * 常量内容，固定值。
     */
    private static final String API_VERSION = "2018-11-20";
    private static final String ACTION_CREATE_ASR = "CreateAsrVocab";
    private static final String ACTION_GET_ASR_VOCAB = "GetAsrVocab";
    private static final String ACTION_LIST_ASR_VOCAB = "ListAsrVocab";
    private static final String ACTION_UPDATE_ASR_VOCAB = "UpdateAsrVocab";
    private static final String ACTION_DELETE_ASR_VOCAB = "DeleteAsrVocab";
    /**
     * 参数设置key
     * 常量内容，固定值。
     */
    private static final String KEY_VOCAB_ID = "VocabId";
    private static final String KEY_ID = "Id";
    private static final String KEY_NAME = "Name";
    private static final String KEY_DESCRIPTION = "Description";
    private static final String KEY_WORD_WEIGHTS = "WordWeights";
    private static final String KEY_VOCAB = "Vocab";
    private static final String KEY_PAGE = "Page";
    private static final String KEY_PAGE_NUMBER = "PageNumber";
    private static final String KEY_PAGE_SIZE = "PageSize";
    // 阿里云鉴权client
    private static IAcsClient client;
    static class Vocab {
        public String Id;
        public String Name;
        public String Description;
        public int Size;
        public String Md5;
        public String CreateTime;
        public String UpdateTime;
        public Map<String, Integer> WordWeights = new HashMap<String, Integer>();
    }
    static class Page {
        class VocabContent {
            public String Id;
            public String Name;
            public String Description;
            public int Size;
            public String Md5;
            public String CreateTime;
            public String UpdateTime;
        }
        public int PageNumber;
        public int PageSize;
        public int TotalItems;
        public int TotalPages;
        public List<VocabContent> Content = new ArrayList<VocabContent>();
    }
    public AsrVocabPopApiDemo(String akId, String akSecret) {
        DefaultProfile profile = DefaultProfile.getProfile(REGION_ID, akId, akSecret);
        client = new DefaultAcsClient(profile);
    }
    private CommonRequest newRequest(String action) {
        CommonRequest request = new CommonRequest();
        request.setDomain(DOMAIN);
        request.setProtocol(PROTOCOL_TYPE);
        request.setVersion(API_VERSION);
        request.setMethod(MethodType.POST);
        request.setAction(action);
        return request;
    }
    /**
     * 创建词表
     *
     * @param name 词表名称，必填。
     * @param description 词表描述信息，可选。
     * @param wordWeights 词表里的词和对应的权重，JSON的Map格式，必填。
     *
     * @return String 创建的词表Id。
     */
    String createAsrVocab(String name, String description, String wordWeights) {
        CommonRequest request = newRequest(ACTION_CREATE_ASR);
        request.putBodyParameter(KEY_NAME, name);
        request.putBodyParameter(KEY_DESCRIPTION, description);
        request.putBodyParameter(KEY_WORD_WEIGHTS, wordWeights);
        CommonResponse response = null;
        try {
            response = client.getCommonResponse(request);
        } catch (ClientException e) {
            e.printStackTrace();
        }
        if (response.getHttpStatus() != 200) {
            System.out.println(response.getData());
            System.out.println("创建词表失败，HTTP错误码：" + response.getHttpStatus());
            return null;
        }
        JSONObject result = JSONObject.parseObject(response.getData());
        String vocabId = result.getString(KEY_VOCAB_ID);
        return vocabId;
    }
    /**
     * 获取词表
     *
     * @param vocabId 词表Id。
     *
     * @return Vocab 获取的词表对象。
     */
    Vocab getAsrVocab(String vocabId) {
        CommonRequest request = newRequest(ACTION_GET_ASR_VOCAB);
        request.putBodyParameter(KEY_ID, vocabId);
        CommonResponse response = null;
        try {
            response = client.getCommonResponse(request);
        } catch (ClientException e) {
            e.printStackTrace();
        }
        if (response.getHttpStatus() != 200) {
            System.out.println(response.getData());
            System.out.println("获取词表失败，HTTP错误码：" + response.getHttpStatus());
            return null;
        }
        JSONObject result = JSONObject.parseObject(response.getData());
        String vocabJson = result.getString(KEY_VOCAB);
        Vocab vocab = JSONObject.parseObject(vocabJson, Vocab.class);
        return vocab;
    }
    /**
     * 更新词表
     *
     * @param vocabId 待更新的词表Id。
     * @param name 更新后的词表名称。
     * @param description 更新后的词表描述。
     * @param wordWeights 更新后的热词和权重。
     *
     * @return boolean 更新词表是否成功。
     */
    boolean updateAsrVocab(String vocabId, String name, String description, String wordWeights) {
        CommonRequest request = newRequest(ACTION_UPDATE_ASR_VOCAB);
        request.putBodyParameter(KEY_ID, vocabId);
        request.putBodyParameter(KEY_NAME, name);
        request.putBodyParameter(KEY_DESCRIPTION, description);
        request.putBodyParameter(KEY_WORD_WEIGHTS, wordWeights);
        CommonResponse response = null;
        try {
            response = client.getCommonResponse(request);
        } catch (ClientException e) {
            e.printStackTrace();
        }
        if (response.getHttpStatus() != 200) {
            System.out.println(response.getData());
            System.out.println("更新词表失败，HTTP错误码：" + response.getHttpStatus());
            return false;
        }
        return true;
    }
    /**
     * 删除词表
     *
     * @param vocabId 词表Id。
     *
     * @return boolean 删除词表是否成功。
     * */
    boolean deleteAsrVocab(String vocabId) {
        CommonRequest request = newRequest(ACTION_DELETE_ASR_VOCAB);
        request.putBodyParameter(KEY_ID, vocabId);
        CommonResponse response = null;
        try {
            response = client.getCommonResponse(request);
        } catch (ClientException e) {
            e.printStackTrace();
        }
        if (response.getHttpStatus() != 200) {
            System.out.println(response.getData());
            System.out.println("删除词表失败, HTTP错误码：" + response.getHttpStatus());
            return false;
        }
        return true;
    }
    /**
     * 列举词表
     * 如果不指定获取的页号，默认获取第1页。
     * 如果不指定每页的词表数量，默认每页10个词表。
     *
     * @return Page 所有词表信息。
     */
    Page listAsrVocab() {
        CommonRequest request = newRequest(ACTION_LIST_ASR_VOCAB);
        request.putBodyParameter(KEY_PAGE_NUMBER, 1);
        request.putBodyParameter(KEY_PAGE_SIZE, 10);
        CommonResponse response = null;
        try {
            response = client.getCommonResponse(request);
        } catch (ClientException e) {
            e.printStackTrace();
        }
        if (response.getHttpStatus() != 200) {
            System.out.println(response.getData());
            System.out.println("列举词表失败，HTTP错误码：" + response.getHttpStatus());
            return null;
        }
        JSONObject result = JSONObject.parseObject(response.getData());
        String pageJson = result.getString(KEY_PAGE);
        Page page = JSONObject.parseObject(pageJson, Page.class);
        return page;
    }
    public static void main(String[] args) {
        if (args.length < 2) {
            System.err.println("FileASRDemo need params: <AccessKey Id> <AccessKey Secret>");
            return;
        }
        String accessKeyId = args[0];
        String accessKeySecret = args[1];
        AsrVocabPopApiDemo demo = new AsrVocabPopApiDemo(accessKeyId, accessKeySecret);
        // 词表ID
        String vocabId = null;
        /**
         * 创建词表
         */
        String name = "测试词表";
        String description = "测试词表描述";
        String wordWeights = "{\"苹果\": 3, \"西瓜\": 3}";
        vocabId = demo.createAsrVocab(name, description, wordWeights);
        if (vocabId != null) {
            System.out.println("创建词表成功，词表Id：" + vocabId);
        }
        else {
            System.out.println("创建词表失败！");
            return;
        }
        /**
         * 获取词表
         */
        Vocab vocab = demo.getAsrVocab(vocabId);
        if (vocab != null) {
            System.out.println("获取词表成功：" + JSONObject.toJSONString(vocab));
        }
        else {
            System.out.println("获取词表失败！");
        }
        /**
         * 更新词表
         */
        name = "测试词表2";
        description = "测试词表描述2";
        wordWeights = "{\"苹果\": 2, \"西瓜\": 2}";
        boolean isUpdated = demo.updateAsrVocab(vocabId, name, description, wordWeights);
        if (isUpdated) {
            System.out.println("更新词表成功：" + JSONObject.toJSONString(demo.getAsrVocab(vocabId)));
        }
        else {
            System.out.println("更新词表失败！");
        }
        /**
         * 删除词表
         */
        boolean isDeleted = demo.deleteAsrVocab(vocabId);
        if (isDeleted) {
            System.out.println("删除词表成功！");
        }
        else {
            System.out.println("删除词表失败！");
        }
        /**
         * 列举所有词表
         */
        // 创建多个词表
        for (int i = 0; i < 10; i++) {
            name = "测试词表_" + String.valueOf(i);
            description = "测试词表描述_" + String.valueOf(i);
            JSONObject jsonObject = new JSONObject();
            jsonObject.put("苹果", 2);
            jsonObject.put("西瓜", 2);
            wordWeights = jsonObject.toJSONString();
            demo.createAsrVocab(name, description, wordWeights);
        }
        // 列举创建的词表
        Page page = demo.listAsrVocab();
        if (page != null) {
            System.out.println("列举词表成功：" + JSONObject.toJSONString(page));
        }
        else {
            System.out.println("列举词表失败！");
            return;
        }
        // 删除所有的词表
        for (int i = 0; i < page.Content.size(); i++) {
            demo.deleteAsrVocab(page.Content.get(i).Id);
        }
        page = demo.listAsrVocab();
        if (page != null) {
            System.out.println("删除所有词表：" + JSONObject.toJSONString(page));
        }
    }
}