定製熱詞Java SDK參考_Alibaba Cloud Model Studio(Model Studio) - Alibaba Cloud Model Studio

通過Java SDK管理定製熱詞列表，包括VocabularyService類的方法說明與範例程式碼。

使用者指南：提升識別準確率。熱詞列表數量上限等使用限制詳見熱詞限制與計費。

重要僅主業務空間支援熱詞功能，子業務空間暫不支援。

介面地址

SDK 預設使用北京地區的介面地址。如需切換到其他地區，需在初始化前修改 Constants.baseHttpApiUrl。

新加坡

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1

調用時請將{WorkspaceId}替換為真實的業務空間ID。

華北2（北京）

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1

調用時請將{WorkspaceId}替換為真實的Workspace ID。

重要阿里雲百鍊為華北2（北京）、新加坡地區推出了業務空間專屬網域名稱，能夠為推理請求提供卓越的效能和更高的穩定性，建議遷移至新網域名稱：

華北2（北京）地區：從 dashscope.aliyuncs.com 遷移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com
新加坡地區：從 dashscope-intl.aliyuncs.com 遷移至 {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId}需要替換為真實的Workspace ID。現有網域名稱仍可正常使用。

切換到新加坡地區：

import com.alibaba.dashscope.utils.Constants;

// 在代碼開頭設定
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

注意：

不同地區的 API Key 不同，請確保使用對應地區的 API Key
地區配置為全域設定，影響所有 DashScope SDK 的 API 呼叫

VocabularyService

包路徑：com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService

功能：管理熱詞列表的生命週期（建立、查詢、更新、刪除）

構造方法

public VocabularyService(String apiKey)

參數：

參數	類型	說明
apiKey	String	DashScope API Key

createVocabulary() - 建立熱詞列表

方法簽名：

public Vocabulary createVocabulary(String targetModel,String prefix,JsonArray vocabulary) throws NoApiKeyException, InputRequiredException

參數：

參數	類型	必填	說明
targetModel	String	是	使用熱詞列表的語音辨識模型，必須與後續調用語音辨識介面時使用的模型一致。
prefix	String	是	熱詞列表自訂首碼，僅允許數字和小寫字母，長度不超過10個字元。
vocabulary	JsonArray	是	熱詞列表，每個JsonObject包含 text、weight、lang 等欄位。詳情請參見熱詞對象結構。

參數

類型

必填

說明

targetModel

String

是

使用熱詞列表的語音辨識模型，必須與後續調用語音辨識介面時使用的模型一致。

prefix

String

是

熱詞列表自訂首碼，僅允許數字和小寫字母，長度不超過10個字元。

vocabulary

JsonArray

是

熱詞列表，每個JsonObject包含 text、weight、lang 等欄位。

詳情請參見熱詞對象結構。

傳回值：

類型	說明
Vocabulary	熱詞列表對象，包含 vocabularyId 等資訊。

異常：

異常類型	說明
NoApiKeyException	API Key 為空白。
InputRequiredException	必填參數為空白。

listVocabulary() - 批量查詢熱詞列表

方法簽名：

public Vocabulary[] listVocabulary(String prefix) throws NoApiKeyException, InputRequiredException

public Vocabulary[] listVocabulary(String prefix, int pageIndex, int pageSize) throws NoApiKeyException, InputRequiredException

參數：

參數	類型	必填	說明
prefix	String	否	熱詞列表自訂首碼，如果設定則只返回指定首碼的熱詞列表。
pageIndex	int	否	頁碼索引，從0開始計數。預設值：0。
pageSize	int	否	每頁包含資料條數。預設值：10。

傳回值：

類型	說明
Vocabulary[]	熱詞列表對象數組。

Vocabulary 對象欄位（list返回）：

欄位	類型	說明
vocabularyId	String	熱詞列表ID。
gmtCreate	String	建立時間。
gmtModified	String	修改時間。
status	String	狀態： OK：可調用 UNDEPLOYED：不可調用。

異常：

異常類型	說明
NoApiKeyException	API Key 為空白。
InputRequiredException	必填參數為空白。

queryVocabulary() - 查詢熱詞列表

方法簽名：

public Vocabulary queryVocabulary(String vocabularyId) throws NoApiKeyException, InputRequiredException

參數：

參數	類型	必填	說明
vocabularyId	String	是	需要查詢的熱詞列表ID。

傳回值：

類型	說明
Vocabulary	熱詞列表對象，包含詳細資料。

Vocabulary 對象欄位（query返回）：

欄位	類型	說明
vocabulary	JsonArray	熱詞列表內容
targetModel	String	使用熱詞列表的語音辨識模型，必須與後續調用語音辨識介面時使用的模型一致。
gmtCreate	String	建立時間。
gmtModified	String	修改時間。
status	String	狀態： OK：可調用 UNDEPLOYED：不可調用。

異常：

異常類型	說明
NoApiKeyException	API Key 為空白。
InputRequiredException	必填參數為空白。

updateVocabulary() - 更新熱詞列表

方法簽名：

public void updateVocabulary(String vocabularyId,JsonArray vocabulary) throws NoApiKeyException, InputRequiredException

參數：

參數	類型	必填	說明
vocabularyId	String	是	需要更新的熱詞列表ID。
vocabulary	JsonArray	是	新的熱詞列表，將完全替換原有內容。

傳回值：無

異常：

異常類型	說明
NoApiKeyException	API Key 為空白。
InputRequiredException	必填參數為空白。

deleteVocabulary() - 刪除熱詞列表

方法簽名：

public void deleteVocabulary(String vocabularyId) throws NoApiKeyException, InputRequiredException

參數：

參數	類型	必填	說明
vocabularyId	String	是	需要刪除的熱詞列表ID。

傳回值：無

異常：

異常類型	說明
NoApiKeyException	API Key 為空白。
InputRequiredException	必填參數為空白。

Vocabulary 類

包路徑：com.alibaba.dashscope.audio.asr.vocabulary.Vocabulary

功能：熱詞列表對象，封裝熱詞列表的中繼資料和內容

主要方法

方法	傳回型別	說明
getVocabularyId()	String	擷取熱詞列表ID。
getTargetModel()	String	擷取目標模型。
getVocabulary()	JsonArray	擷取熱詞列表內容。
getStatus()	String	擷取狀態。
getGmtCreate()	String	擷取建立時間。
getGmtModified()	String	擷取修改時間。
getData()	JsonObject	擷取完整資料（JSON格式）。

熱詞對象結構

用於vocabulary參數的 JsonObject 定義：

欄位	類型	必填	說明
text	String	是	熱詞文本。熱詞文本的語言必須在所選模型的支援範圍內，不同模型支援的語言各不相同。熱詞用於提升識別的準確率，請使用實際詞語而非任一字元組合。長度限制：含非 ASCII 字元時不超過 15 個字元；純 ASCII 時空格分隔片段不超過 7 個。
weight	int	是	熱詞權重。常用值：4。取值範圍：[1, 5]。如果效果不明顯，可以適當增加權重，但權重過大可能產生負面效果，導致其他詞語識別不準確。
lang	String	否	待識別音訊語言代碼。設定後，系統將對指定語種進行熱詞識別增強。如果無法提前確定語種，可不設定，模型會自動識別語種。取值範圍（因模型而異）： Paraformer： zh: 中文 en: 英文 ja: 日語 yue: 粵語 ko: 韓語 de：德語 fr：法語 ru：俄語 Fun-ASR： zh: 中文 en: 英文 ja: 日語

範例程式碼

建立熱詞列表

import com.alibaba.dashscope.audio.asr.vocabulary.Vocabulary;
import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.JsonArray;
import com.google.gson.JsonObject;

import java.util.ArrayList;
import java.util.List;

public class Main {
    // 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    // 若沒有配置環境變數，請用百鍊API Key將下行替換為：public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        String targetModel = "fun-asr";

        JsonArray vocabularyJson = new JsonArray();
        List<Hotword> wordList = new ArrayList<>();
        wordList.add(new Hotword("吳貽弓", 4));
        wordList.add(new Hotword("闕裡人家", 4));

        for (Hotword word : wordList) {
            JsonObject jsonObject = new JsonObject();
            jsonObject.addProperty("text", word.text);
            jsonObject.addProperty("weight", word.weight);
            vocabularyJson.add(jsonObject);
        }

        VocabularyService service = new VocabularyService(apiKey);
        Vocabulary vocabulary = service.createVocabulary(targetModel, "testpfx", vocabularyJson);
        System.out.println("熱詞列表ID：" + vocabulary.getVocabularyId());
    }
}

class Hotword {
    String text;
    int weight;

    public Hotword(String text, int weight) {
        this.text = text;
        this.weight = weight;
    }
}

批量查詢熱詞列表

import com.alibaba.dashscope.audio.asr.vocabulary.Vocabulary;
import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

public class Main {
    // 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    // 若沒有配置環境變數，請用百鍊API Key將下行替換為：public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

        VocabularyService service = new VocabularyService(apiKey);
        Vocabulary[] vocabularies = service.listVocabulary("testpfx");
        Gson gson = new GsonBuilder()
                .setPrettyPrinting()
                .create();
        System.out.println("熱詞列表：" + gson.toJson(vocabularies));
    }
}

查詢熱詞列表

import com.alibaba.dashscope.audio.asr.vocabulary.Vocabulary;
import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

public class Main {
    // 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    // 若沒有配置環境變數，請用百鍊API Key將下行替換為：public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

        VocabularyService service = new VocabularyService(apiKey);
        // 查詢時替換為實際的熱詞列表ID
        Vocabulary vocabulary = service.queryVocabulary("vocab-testpfx-xxxx");
        Gson gson = new GsonBuilder()
                .setPrettyPrinting()
                .create();
        System.out.println("熱詞列表：" + gson.toJson(vocabulary.getData()));
    }
}

更新熱詞列表

import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.JsonArray;
import com.google.gson.JsonObject;

import java.util.ArrayList;
import java.util.List;

public class Main {
    // 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    // 若沒有配置環境變數，請用百鍊API Key將下行替換為：public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

        JsonArray vocabularyJson = new JsonArray();
        List<Hotword> wordList = new ArrayList<>();
        wordList.add(new Hotword("吳貽弓", 4, "zh"));
        wordList.add(new Hotword("闕裡人家", 4, "zh"));

        for (Hotword word : wordList) {
            JsonObject jsonObject = new JsonObject();
            jsonObject.addProperty("text", word.text);
            jsonObject.addProperty("weight", word.weight);
            jsonObject.addProperty("lang", word.lang);
            vocabularyJson.add(jsonObject);
        }

        VocabularyService service = new VocabularyService(apiKey);
        // 替換為實際的熱詞列表ID
        service.updateVocabulary("vocab-testpfx-xxx", vocabularyJson);
    }
}

class Hotword {
    String text;
    int weight;
    String lang;

    public Hotword(String text, int weight, String lang) {
        this.text = text;
        this.weight = weight;
        this.lang = lang;
    }
}

刪除熱詞列表

import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    // 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    // 若沒有配置環境變數，請用百鍊API Key將下行替換為：public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

        VocabularyService service = new VocabularyService(apiKey);
        // 刪除時替換為實際的熱詞列表ID
        service.deleteVocabulary("vocab-testpfx-xxxx");
    }
}