All Products
Search
Document Center

Intelligent Speech Interaction:Call the POP API to manage business-specific hotwords

Last Updated:Sep 09, 2022

This topic describes how to call the Alibaba Cloud pctowap open platform (POP) API in a client to manage business-specific hotwords.

The POP API provides the following operations for you to manage business-specific hotwords:

  • CreateAsrVocab: creates a hotword vocabulary.

  • GetAsrVocab: queries a single hotword vocabulary.

  • UpdateAsrVocab: updates a hotword vocabulary.

  • DeleteAsrVocab: deletes a hotword vocabulary.

  • ListAsrVocab: queries hotword vocabularies.

Call limits

  • You can create a maximum of 10 vocabularies of business-specific hotwords.

  • You can add a maximum of 128 hotwords to each vocabulary. Each hotword can contain up to 10 Chinese characters in length.

  • Business-specific hotwords must be encoded in UTF-8 and cannot contain punctuation marks or special characters.

  • The weight of each business-specific hotword must be an integer in the range of [-6,5].

    Note

    If the weight of a hotword is positive, the greater the weight, the greater the probability of the hotword being recognized. If the weight of a hotword is negative, the smaller the weight, the higher the probability of the hotword not being recognized.

    If the weight of a hotword is -6, the hotword is not recognized if possible.

    Generally, the weight is set to 2.

    If the recognition result of a hotword is not as expected, you can increase the weight of the hotword. However, this may lead to inaccurate recognition of other hotwords.

Create a hotword vocabulary

You can call the CreateAsrVocab operation to create a hotword vocabulary. A hotword vocabulary is a combination of business-specific hotwords.

Request parameters:

When you submit a request to create a hotword vocabulary, you must specify the request parameters in the request body. The following table describes the request parameters.

Parameter

Type

Required

Description

Name

String

Yes

The name of the hotword vocabulary.

WordWeights

String

Yes

The JSON map of the business-specific hotwords in the hotword vocabulary and their weights. Example:

{
    "Apple":3,
    "Watermelon":3
}

In each key-value pair, the key indicates a hotword of the STRING type, and the value indicates the weight of the hotword. The weight is of the INT type.

Description

String

No

The description of the hotword vocabulary.

Response parameters:

The response parameters are returned in JSON format.

{
        "VocabId": "0074ac87db754e0fbd3465c60d86****",
        "RequestId": "77C00AE4-A646-4A41-B6FF-F06C19FA****"
}
  • The HTTP status code 200 indicates that the operation is successful. For more information about error codes, see the "Error codes" section.

  • The following table describes the response parameters returned in JSON format.

    Parameter

    Type

    Description

    RequestId

    String

    The ID of the request.

    VocabId

    String

    The ID of the hotword vocabulary that was created. You can use the ID to query, update, or delete the hotword vocabulary.

Query a single hotword vocabulary

You can call the GetAsrVocab operation to query information about a specified hotword vocabulary based on the vocabulary ID.

Request parameters:

When you submit a request to query a single hotword vocabulary, you must specify the request parameters in the request body. The following table describes the request parameters.

Parameter

Type

Required

Description

Id

String

Yes

The ID of the hotword vocabulary. The ID is generated when the hotword vocabulary is created.

Response parameters:

The response parameters are returned in JSON format.

{
        "RequestId": "A590423E-FEBC-4AA0-A520-4DA77292****",
        "Vocab": {
                "Name": "Test vocabulary",
                "Md5": "58c732d3b31eb564c275371d46fc****",
                "Description": "Test description",
                "CreateTime": "2018-11-26 17:19:40",
                "UpdateTime": "2018-11-26 17:19:40",
                "Id": "6118b2a057d1440bb253382a7617****",
                "WordWeights": {
                        "Watermelon": 3,
                        "Apple": 3
                },
                "Size": 323
        }
}
  • The HTTP status code 200 indicates that the operation is successful. For more information about error codes, see the "Error codes" section.

  • The following table describes the response parameters returned in JSON format.

    Parameter

    Type

    Description

    RequestId

    String

    The ID of the request.

    Vocab

    Vocab object

    The vocabulary object.

    The following table describes the parameters of a Vocab object.

    Parameter

    Type

    Description

    Id

    String

    The ID of the hotword vocabulary. The ID is generated when the hotword vocabulary is created.

    Name

    String

    The name of the hotword vocabulary.

    Description

    String

    The description of the hotword vocabulary.

    Size

    Int

    The size of the hotword vocabulary after compilation.

    Md5

    String

    The MD5 value of the hotword vocabulary after compilation.

    CreateTime

    String

    The time when the hotword vocabulary was created.

    UpdateTime

    String

    The time when the hotword vocabulary was updated.

    WordWeights

    Map

    The business-specific hotwords in the hotword vocabulary and their weights.

Update a hotword vocabulary

You can call the UpdateAsrVocab operation to update a specified hotword vocabulary based on the vocabulary ID. You can change the vocabulary name, the vocabulary description, the hotwords in the vocabulary, and the weights of the hotwords.

Request parameters:

When you submit a request to update a hotword vocabulary, you must specify the request parameters in the request body. The following table describes the request parameters.

Parameter

Type

Required

Description

Id

String

Yes

The ID of the hotword vocabulary. The ID is generated when the hotword vocabulary is created.

Name

String

Yes

The new name of the hotword vocabulary.

WordWeights

String

Yes

The JSON map of the business-specific hotwords in the new hotword vocabulary and their weights.

Description

String

No

The new description of the hotword vocabulary.

Response parameters:

The response parameters are returned in JSON format.

{
        "RequestId": "829E373C-9E23-4DEF-A979-002F140B****"
}
  • The HTTP status code 200 indicates that the operation is successful. For more information about error codes, see the "Error codes" section.

  • The following table describes the response parameters returned in JSON format.

    Parameter

    Type

    Description

    RequestId

    String

    The ID of the request.


Delete a hotword vocabulary

You can call the DeleteAsrVocab operation to delete a specified hotword vocabulary based on the vocabulary ID.

Request parameters:

When you submit a request to delete a hotword vocabulary, you must specify the request parameters in the request body. The following table describes the request parameters.

Parameter

Type

Required

Description

Id

String

Yes

The ID of the hotword vocabulary. The ID is generated when the hotword vocabulary is created.

Response parameters:

The response parameters are returned in JSON format.

{
        "RequestId": "75CCBD40-BC19-4227-9140-0F42806BBF6F"
}
  • The HTTP status code 200 indicates that the operation is successful. For more information about error codes, see the "Error codes" section.

  • The following table describes the response parameters returned in JSON format.

    Parameter

    Type

    Description

    RequestId

    String

    The ID of the request.


Query hotword vocabularies

You can call the ListAsrVocab operation to query information about hotword vocabularies by page.

Note

The vocabulary information returned when you call the ListAsrVocab operation does not include business-specific hotwords and their weights. This prevents the generation of an oversized response body.

Request parameters:

When you submit a request to query hotword vocabularies, you must specify the request parameters in the request body. The following table describes the request parameters.

Parameter

Type

Required

Description

PageNumber

Int

No

The number of the page to return. The value is an integer greater than 0. Default value: 1.

PageSize

Int

No

The number of hotword vocabularies to return on each page. Valid values: 10 to 100. Default value: 10.

Note

The server sorts hotword vocabularies in descending order based on their last update time. If excessive hotword vocabularies are obtained at the same time, the HTTP response body is so large that it may be intercepted by the gateway or proxy. To avoid this issue, you can request for only one page of hotword vocabularies in each request. The PageSize parameter specifies the number of hotword vocabularies on each page. If the number of hotword vocabularies on the specified page is smaller than the value of PageSize, all hotword vocabularies on the page are returned. The PageNumber parameter specifies the number of the page to return.

Response parameters:

The response parameters are returned in JSON format.

{
        "Page": {
                "PageNumber": 1,
                "PageSize": 10,
                "TotalItems": 5,
                "TotalPages": 1,
                "Content": [{
                        "Name": "Test vocabulary_1",
                        "Md5": "eafaaf1d73b17c9d35c64d600e07****",
                        "Description": "Test description_1",
                        "CreateTime": "2018-11-26 17:51:41",
                        "UpdateTime": "2018-11-26 17:51:41",
                        "Id": "266df2819a9d4d96a07c5c5d39b6****",
                        "Size": 323
                }, {
                        "Name": "Test vocabulary_2",
                        "Md5": "f32c10fd8569cb3712576a0ea988****",
                        "Description": "Test 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****"
}
  • The HTTP status code 200 indicates that the operation is successful. For more information about error codes, see the "Error codes" section.

  • The following table describes the response parameters returned in JSON format.

    Parameter

    Type

    Description

    RequestId

    String

    The ID of the request.

    Page

    Page object

    The information about hotword vocabularies on the specified page. If you do not specify the page number in the request, information about the hotword vocabularies on the first page is returned.

    The following table describes the parameters of a Page object.

    Parameter

    Type

    Description

    Content

    List< Vocab >

    The list of hotword vocabularies. The parameters returned are the same as those contained in a Vocab object, excluding the WordWeights parameter. For more information, see the parameter description of the Vocab object in the Query a single hotword vocabulary.

    PageNumber

    Int

    The page number of the returned page. The value is the same as the value of the PageNumber parameter in request parameters.

    PageSize

    Int

    The number of hotword vocabularies returned per page. The value is the same as the value of the PageSize parameter in request parameters.

    TotalPages

    Int

    The total number of pages.

    TotalItems

    Int

    The total number of hotword vocabularies.


Error codes

After you submit a request to create, query, update, or delete a specified hotword vocabulary or query hotword vocabularies, if the returned HTTP status code is not 200, the request failed. The failure information is contained in a JSON string in the HTTP response body. The following table describes the specific error codes.

Error code

Description

Solution

SLP.PAGE_NUMBER_INVALID

The error code returned because the value of the PageNumber parameter is invalid when you call the ListAsrVocab operation.

Verify that the value of the PageNumber parameter is an integer greater than or equal to 1.

SLP.PAGE_SIZE_INVALID

The error code returned because the value of the PageSize parameter is invalid when you call the ListAsrVocab operation.

Verify that the value of the PageSize parameter is an integer in the value range [10, 100].

SLP.NOT_FOUND

The error code returned because the specified vocabulary ID does not exist.

Verify that the vocabulary ID is valid.

SLP.PARAMETER_ERROR

The error code returned because the request parameters are invalid.

Check parameter settings based on the specific error message.

SLP.EXCEED_LIMIT

The error code returned because the number of existing hotword vocabularies has reached the upper limit.

Make sure that the current number of hotword vocabularies has not reached the upper limit. By default, each user can create a maximum of 10 business-specific hotword vocabularies.

SLP.ASR_VOCAB_ERROR

The error code returned because a hotword vocabulary error other than the preceding ones has occurred.

Rectify the error based on the specific error message.

The following example shows an error response returned when the number of existing hotword vocabularies has reached the upper limit:

{
        "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)"
}

Sample code

Note

  • In this example, the CommonRequest method of Alibaba Cloud SDK for Java is used to send POP API requests in a remote procedure call (RPC) style

  • For more information about Alibaba Cloud SDK for Java, see Get started with Alibaba Cloud Classic SDK for Java.

  • For more information about how to use the CommonRequest method of Alibaba Cloud SDK for Java, see Use CommonRequest.

  • You only need to add dependencies on the core library of Alibaba Cloud SDK for Java and the Alibaba open source library fastjson. The core library version of Alibaba Cloud SDK for Java must be V3.5.0 or later. If the version is V4.0.0 or later, you must add dependencies on third-party libraries as prompted.

    <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 {
    /**
     * The region information.
     * The constant parameters. Do not modify their values.
     */
    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;
    /**
     * The POP API information.
     * The constant parameters. Do not modify their values.
     */
    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";
    /**
     * The keys of parameters.
     * The constant parameters. Do not modify their values.
     */
    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";
    // Create and authenticate a 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;
    }
    /**
     * Create a hotword vocabulary.
     *
     * @param name Required. The name of the hotword vocabulary that you want to create.
     * @param description Optional. The description of the hotword vocabulary.
     * @param wordWeights Required. The JSON map of the hotwords in the hotword vocabulary and their weights.
     *
     * @return String The ID of the hotword vocabulary.
     */
    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("The hotword vocabulary fails to be created. HTTP status code:" + response.getHttpStatus());
            return null;
        }
        JSONObject result = JSONObject.parseObject(response.getData());
        String vocabId = result.getString(KEY_VOCAB_ID);
        return vocabId;
    }
    /**
     * Query a single hotword vocabulary.
     *
     * @param vocabId The ID of the hotword vocabulary that you want to query.
     *
     * @return Vocab The Vocab object.
     */
    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("The hotword vocabulary fails to be queried. HTTP status code:" + 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;
    }
    /**
     * Update a hotword vocabulary.
     *
     * @param vocabId The ID of the hotword vocabulary that you want to update.
     * @param name The new name of the hotword vocabulary.
     * @param description The new description of the hotword vocabulary.
     * @param wordWeights The JSON map of the hotwords in the new hotword vocabulary and their weights.
     *
     * @return boolean Indicates whether the hotword vocabulary is updated.
     */
    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("The hotword vocabulary fails to be updated. HTTP status code:" + response.getHttpStatus());
            return false;
        }
        return true;
    }
    /**
     * Delete a hotword vocabulary.
     *
     * @param vocabId The ID of the hotword vocabulary that you want to delete.
     *
     * @return boolean Indicates whether the hotword vocabulary is deleted.
     * */
    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("The hotword vocabulary fails to be deleted. HTTP status code:" + response.getHttpStatus());
            return false;
        }
        return true;
    }
    /**
     * Query hotword vocabularies.
     * If you do not specify the page number in the request, information about the hotword vocabularies on the first page is returned.
     * If you do not specify the number of hotword vocabularies on each page to return, a maximum of 10 hotword vocabularies are returned per page.
     *
     * @return Page The information about the returned hotword vocabularies.
     */
    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("The hotword vocabularies fail to be queried. HTTP status code:" + 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);
        // The ID of the hotword vocabulary.
        String vocabId = null;
        /**
         * Create a hotword vocabulary.
         */
        String name = "Test vocabulary";
        String description = "Test description";
        String wordWeights = "{\"Apple\": 3, \"Watermelon\": 3}";
        vocabId = demo.createAsrVocab(name, description, wordWeights);
        if (vocabId != null) {
            System.out.println("The hotword vocabulary is created. Vocabulary ID:" + vocabId);
        }
        else {
            System.out.println("The hotword vocabulary fails to be created.") ;
            return;
        }
        /**
         * Query a single hotword vocabulary.
         */
        Vocab vocab = demo.getAsrVocab(vocabId);
        if (vocab != null) {
            System.out.println("The information about the hotword vocabulary is returned." + JSONObject.toJSONString(vocab));
        }
        else {
            System.out.println("The hotword vocabulary fails to be queried.") ;
        }
        /**
         * Update a hotword vocabulary.
         */
        name = "Test vocabulary 2";
        description = "Test description 2";
        wordWeights = "{\"Apple\": 2, \"Watermelon\": 2}";
        boolean isUpdated = demo.updateAsrVocab(vocabId, name, description, wordWeights);
        if (isUpdated) {
            System.out.println("The hotword vocabulary is updated." + JSONObject.toJSONString(demo.getAsrVocab(vocabId)));
        }
        else {
            System.out.println("The hotword vocabulary fails to be updated.") ;
        }
        /**
         * Delete a hotword vocabulary.
         */
        boolean isDeleted = demo.deleteAsrVocab(vocabId);
        if (isDeleted) {
            System.out.println("The hotword vocabulary is deleted.") ;
        }
        else {
            System.out.println("The hotword vocabulary fails to be deleted.") ;
        }
        /**
         /* Manage multiple hotword vocabularies.
         */
        // Create multiple hotword vocabularies.
        for (int i = 0; i < 10; i++) {
            name = "Test vocabulary_" + String.valueOf(i);
            description = "Test description_" + String.valueOf(i);
            JSONObject jsonObject = new JSONObject();
            jsonObject.put("Apple", 2);
            jsonObject.put("Watermelon", 2);
            wordWeights = jsonObject.toJSONString();
            demo.createAsrVocab(name, description, wordWeights);
        }
        // Query multiple hotword vocabularies.
        Page page = demo.listAsrVocab();
        if (page != null) {
            System.out.println("The information about the hotword vocabularies on the specified page is returned." + JSONObject.toJSONString(page));
        }
        else {
            System.out.println("The hotword vocabularies fail to be queried.") ;
            return;
        }
        // Delete multiple hotword vocabularies.
        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("The hotword vocabularies on the specified page are deleted." + JSONObject.toJSONString(page));
        }
    }
}