全部产品
云市场
云游戏

使用POP API创建业务专属热词

更新时间:2020-08-11 18:42:54

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

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

  • 创建词表: CreateAsrVocab

  • 获取词表: GetAsrVocab

  • 更新词表: UpdateAsrVocab

  • 删除词表 :DeleteAsrVocab

  • 列举所有词表: ListAsrVocab

调用限制

  • 默认最多创建10个词表。

  • 每个词表最多添加128个词,每个词语最长10个字。

  • 业务专属热词必须为UTF-8编码,不能包含标点、特殊字符。

  • 业务专属词对应的权重取值范围为[-6,5]之间的整数。

    说明

    取值大于0增大该词语被识别的概率,小于0减小该词语被识别的概率。

    取值为-6:表示尽量不要识别出该词语。

    取值为2:常用值。

    如果效果不明显可以适当增加权重,但是当权重较大时可能会起到负面效果,导致其他词语识别不准确。

创建词表

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

输入参数:

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

名称类型是否必选说明
NameString词表名称。

WordWeights

String

词表里的词和对应的权重,为JSON的Map格式字符串。例如:

{
    "苹果":3,
    "西瓜":3
}

key为String类型的热词,value为Int类型的热词对应的权重。

Description

String

词表描述信息。

输出参数:

返回的输出参数为JSON格式的字符串。

{
	"VocabId": "0074ac87db754e0fbd3465c60d86e118",
	"RequestId": "77C00AE4-A646-4A41-B6FF-F06C19FACE76"
}
  • 返回HTTP状态:200表示成功,更多状态码请查阅HTTP状态码。

  • 返回JSON格式字符串参数:

    名称类型说明
    RequestIdString请求ID。
    VocabIdString词表ID,作为后续词表的获取、更新、删除使用。

获取词表

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

输入参数:

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

名称类型是否必选说明
IdString词表ID(创建词表时获取的VocabId)。

输出参数:

返回的输出参数为JSON格式的字符串。

{
	"RequestId": "A590423E-FEBC-4AA0-A520-4DA772929E04",
	"Vocab": {
		"Name": "测试词表",
		"Md5": "58c732d3b31eb564c275371d46fcdfc0",
		"Description": "测试词表描述",
		"CreateTime": "2018-11-26 17:19:40",
		"UpdateTime": "2018-11-26 17:19:40",
		"Id": "6118b2a057d1440bb253382a76177ced",
		"WordWeights": {
			"西瓜": 3,
			"苹果": 3
		},
		"Size": 323
	}
}
  • 返回HTTP状态:200表示成功,更多状态码请查阅HTTP状态码。

  • 返回JSON格式字符串参数:

    名称类型说明
    RequestIdString请求ID。
    VocabVocab对象词表对象。

    其中,Vocab对象的参数描述如下表所示。

    名称类型说明
    IdString词表ID(与创建词表时获取的VocabId相同)。
    NameString词表名称。
    DescriptionString词表描述信息。
    SizeInt词表编译后的大小。
    Md5String词表编译后的md5值。
    CreateTimeString词表创建时间。
    UpdateTimeString词表更新时间。
    WordWeightsMap词表中的业务专属热词和对应的权重。

更新词表

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

输入参数:

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

名称类型是否必选说明
IdString词表Id(创建词表时获取的VocabId)。
NameString更新后的词表名称。
WordWeightsString更新后的词表里业务专属热词和对应的权重,为JSON的Map格式字符串。

Description

String

更新后的词表描述信息。

输出参数:

返回的输出参数为JSON格式的字符串。

{
	"RequestId": "829E373C-9E23-4DEF-A979-002F140B2FCC"
}
  • 返回HTTP状态:200表示成功,更多状态码请查阅HTTP状态码。

  • 返回JSON格式字符串参数:

    名称类型说明
    RequestIdString请求ID。

删除词表

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

输入参数:

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

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

输出参数:

返回的输出参数为JSON格式的字符串。

{
	"RequestId": "75CCBD40-BC19-4227-9140-0F42806BBF6F"
}
  • 返回HTTP状态:200表示成功,更多状态码请查阅HTTP状态码。

  • 返回JSON格式字符串参数:

    名称类型说明
    RequestIdString请求ID。

列举词表

列举指定页的词表信息。

说明

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

输入参数:

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

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

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

输出参数:

返回的输出参数为JSON格式的字符串。

{
	"Page": {
		"PageNumber": 1,
		"PageSize": 10,
		"TotalItems": 5,
		"TotalPages": 1,
		"Content": [{
			"Name": "测试词表_1",
			"Md5": "eafaaf1d73b17c9d35c64d600e0793d9",
			"Description": "测试词表描述_1",
			"CreateTime": "2018-11-26 17:51:41",
			"UpdateTime": "2018-11-26 17:51:41",
			"Id": "266df2819a9d4d96a07c5c5d39b6430e",
			"Size": 323
		}, {
			"Name": "测试词表_2",
			"Md5": "f32c10fd8569cb3712576a0ea988d469",
			"Description": "测试词表描述_2",
			"CreateTime": "2018-11-26 17:51:41",
			"UpdateTime": "2018-11-26 17:51:41",
			"Id": "0fa718759c034f67bb3e394d2fd9866b",
			"Size": 323
		}]
	},
	"RequestId": "CB7B4AB4-5C16-4617-8B91-519A130E8991"
}
  • 返回HTTP状态:200表示成功,更多状态码请查阅HTTP状态码。

  • 返回JSON格式字符串参数:

    名称类型说明
    RequestIdString请求ID。
    PagePage对象输入参数中指定获取页,没有指定默认获取第一页。

    其中Page对象的参数描述如下表所示。

    名称类型说明
    ContentList< Vocab >词表数组,参见获取词表中输出参数Vocab,不包含WordWeights参数。
    PageNumberInt页号,与输入参数相同。
    PageSizeInt页包含的词表数量,与输入参数相同。
    TotalPagesInt总页数。
    TotalItemsInt总词表数量。

错误码

在提交创建词表、获取词表、更新词表、删除词表、列举词表的请求时,获取的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-B78576C6388A",
	"HostId": "nls-slp.cn-shanghai.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.49</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 = "cn-shanghai";
    private static final String DOMAIN = "nls-slp.cn-shanghai.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));
        }
    }
}