使用POP API建立業務專屬熱詞 - Intelligent Speech Interaction

本文為您介紹如何使用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));
        }
    }
}