Alibaba Cloud Model Studio：自訂熱詞

熱詞格式

熱詞以 JSON 數組提交，數組元素定義單個熱詞及其屬性。

樣本：提升電影名稱的識別率。

[
    {"text": "賽德克巴萊", "weight": 4, "lang": "zh"},
    {"text": "Seediq Bale", "weight": 4, "lang": "en"},
    {"text": "夏洛特煩惱", "weight": 4, "lang": "zh"},
    {"text": "Goodbye Mr. Loser", "weight": 4, "lang": "en"},
    {"text": "闕裡人家", "weight": 4, "lang": "zh"},
    {"text": "Confucius' Family", "weight": 4, "lang": "en"}
]

欄位說明：

工作流程

先建立熱詞列表，再在語音辨識時引用其 ID：

1. 建立熱詞列表。

   調用建立熱詞列表介面，必須指定 target_model（Java 中為 targetModel），表明該列表所屬的語音辨識模型。

   如已有熱詞列表（可通過查詢所有熱詞列表介面查看），跳過此步。

2. 調用語音辨識介面並傳入熱詞列表 ID。

   語音辨識使用的模型必須與建立時指定的 target_model（Java 中為 targetModel）一致，否則熱詞不生效。

範例程式碼

完整流程樣本：建立熱詞列表 → 調用語音辨識 → 刪除列表。樣本音頻：asr_example.wav。

import dashscope
from dashscope.audio.asr import *
import os


# 北京與新加坡地區的 API Key 不同。擷取 API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 未配置環境變數時，將下行替換為：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# 新加坡地區 URL；北京地區改為：https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# 新加坡地區 WebSocket URL；北京地區改為：wss://dashscope.aliyuncs.com/api-ws/v1/inference
dashscope.base_websocket_api_url = 'wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference'
prefix = 'testpfx'
target_model = "fun-asr-realtime"

my_vocabulary = [
    {"text": "語音實驗室", "weight": 4}
]

service = VocabularyService()
vocabulary_id = service.create_vocabulary(
      prefix=prefix,
      target_model=target_model,
      vocabulary=my_vocabulary)

try:
    if service.query_vocabulary(vocabulary_id)['status'] == 'OK':
        recognition = Recognition(model=target_model,
                              format='wav',
                              sample_rate=16000,
                              callback=None,
                              vocabulary_id=vocabulary_id)
        result = recognition.call('asr_example.wav')
        print(result.output)
finally:
    # 無論識別成功與否都刪除熱詞列表，避免佔用配額
    service.delete_vocabulary(vocabulary_id)

import com.alibaba.dashscope.audio.asr.recognition.Recognition;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionParam;
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.io.File;
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
    // 未配置環境變數時，將下行替換為：public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // 新加坡地區 URL；北京地區改為：https://dashscope.aliyuncs.com/api/v1
        Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
        // 新加坡地區 WebSocket URL；北京地區改為：wss://dashscope.aliyuncs.com/api-ws/v1/inference
        Constants.baseWebsocketApiUrl = "wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference";

        String targetModel = "fun-asr-realtime";

        JsonArray vocabularyJson = new JsonArray();
        List<Hotword> wordList = new ArrayList<>();
        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);

        try {
            if ("OK".equals(service.queryVocabulary(vocabulary.getVocabularyId()).getStatus())) {
                Recognition recognizer = new Recognition();
                RecognitionParam param =
                        RecognitionParam.builder()
                                .model(targetModel)
                                .apiKey(apiKey)
                                .format("wav")
                                .sampleRate(16000)
                                .vocabularyId(vocabulary.getVocabularyId())
                                .build();

                try {
                    System.out.println("識別結果：" + recognizer.call(param, new File("asr_example.wav")));
                } catch (Exception e) {
                    e.printStackTrace();
                } finally {
                    // 關閉 WebSocket 串連
                    recognizer.getDuplexApi().close(1000, "bye");
                }
            }
        } finally {
            // 無論識別成功與否都刪除熱詞列表，避免佔用配額
            service.deleteVocabulary(vocabulary.getVocabularyId());
        }
        System.exit(0);
    }
}

class Hotword {
    String text;
    int weight;

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

調整熱詞權重

權重控制模型對熱詞的偏好程度，合理設定可在提升目標詞識別率的同時避免誤識別。

建議從 weight=4 起測，根據識別效果逐步調整。

熱詞文本規範

熱詞文本必須為實際詞語，長度限制如下：

• 含非 ASCII 字元時：總字元數（漢字、日文假名、韓文諺文、西裡爾字母等非 ASCII 字元與 ASCII 字元合計）不超過 15 個。

  樣本：

  • ✅ "厄洛替尼鹽酸鹽"（7 字元）

  • ✅ "EGFR抑製劑"（7 字元，其中 EGFR 占 4 個 ASCII 字元）

  • ✅ "こんにちは"（5 字元）

  • ✅ "Фенибут Белфарм"（15 字元，含中間空格）

  • ❌ "Клофелин Белмедпрепараты"（24 字元）

• 純 ASCII 字元時：按空格切分後的片段數不超過 7 個。

  樣本：

  • ✅ "Exothermic reaction" → 2 個片段

  • ✅ "Human immunodeficiency virus type 1" → 5 個片段

  • ❌ "The effect of temperature variations on enzyme activity in biochemical reactions" → 11 個片段

設計熱詞表

• 按情境分組：為不同業務情境建立獨立的熱詞列表（如醫學術語、產品名稱各建一個），便於維護與複用。

• 多語種混合：同一熱詞列表可混入不同語種的熱詞，通過 lang 欄位區分。語音辨識時指定 language_hints 後，僅匹配該語種的熱詞生效。

• 定期清理：刪除不再使用的熱詞列表以釋放額度（每帳號上限 10 個）。

Q：設定熱詞後識別效果沒有改善？

依次排查：

1. 模型是否匹配：建立時指定的 target_model 必須與語音辨識介面使用的模型一致。兩者不一致時介面不會報錯，識別仍能返回結果，但熱詞不生效；識別結果未命中預期熱詞時應優先排查此項。

2. 模型是否支援：模型必須為 Fun-ASR 或 Paraformer 系列，其他系列不支援熱詞。在不支援的系列上調用時介面同樣不會報錯，但識別結果可能為空白或不含熱詞增強；使用 SenseVoice 等系列時應優先排查此項。

3. 權重是否合適：將權重從 4 提到 5 觀察效果。如果出現發音相近的其他詞被誤識別為熱詞，回調到 4。

4. 熱詞列表狀態：通過查詢介面確認 status 為 OK。

Q：熱詞在即時和非即時語音辨識中的使用方式是否相同？

建立方式相同，調用時存在差異：

• 即時語音辨識：在 Recognition 或 WebSocket 串連參數中傳入 vocabulary_id。

• 錄音檔案識別：在 Transcription 請求參數中傳入 vocabulary_id。

兩種情境的 target_model 都必須與實際調用的語音辨識模型一致。

Q：如何提升識別準確率？

除熱詞外，可從以下方向最佳化：

• 音頻品質：採樣率匹配模型要求（16 kHz 或 8 kHz），降低背景雜訊。

• 選擇合適的模型：不同情境適用模型不同，詳見語音辨識選型指南。

• 指定語種：通過 language_hints 聲明音頻語種，可提升單語種情境的準確率。