Alibaba Cloud Model Studio:カスタムホットワード

Python

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


# シンガポールリージョンと中国 (北京) リージョンの API キーは異なります。API キーを取得するには、https://www.alibabacloud.com/help/model-studio/get-api-key をご参照ください
# 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# 以下はシンガポールリージョンの URL です。中国 (北京) リージョンのモデルを使用する場合は、URL を https://dashscope.aliyuncs.com/api/v1 に置き換えてください
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# 以下はシンガポールリージョンの URL です。中国 (北京) リージョンのモデルを使用する場合は、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": "Speech Lab", "weight": 4}
]

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

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)

service.delete_vocabulary(vocabulary_id)

Java

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 キーは異なります。API キーを取得するには、https://www.alibabacloud.com/help/model-studio/get-api-key をご参照ください
    // 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください：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 です。中国 (北京) リージョンのモデルを使用する場合は、URL を https://dashscope.aliyuncs.com/api/v1 に置き換えてください
        Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
        // 以下はシンガポールリージョンの URL です。中国 (北京) リージョンのモデルを使用する場合は、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("Speech Lab", 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);

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

            try {
                System.out.println("Recognition result: " + recognizer.call(param, new File("asr_example.wav")));
            } catch (Exception e) {
                e.printStackTrace();
            } finally {
                // タスク完了後、WebSocket 接続を閉じる
                recognizer.getDuplexApi().close(1000, "bye");
            }
        }

        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;
    }
}

Python SDK

• API の説明

  重要

  target_model：ホットワードリストを使用する音声認識モデル。このモデルは、後続の音声認識 API 呼び出しで指定されるものと同じでなければなりません。

  def create_vocabulary(self, target_model: str, prefix: str, vocabulary: List[dict]) -> str:
      '''
      ホットワードリストを作成します。
      param: target_model ホットワードリスト用の音声認識モデル。これは、後続の API 呼び出しで使用される音声認識モデルと同じでなければなりません。
      param: prefix ホットワードリストのカスタムプレフィックス。10 文字未満の小文字と数字を含む必要があります。
      param: vocabulary ホットワードリストの JSON。
      return: ホットワードリスト ID。
      '''

• コード例

  import dashscope
  from dashscope.audio.asr import *
  import os
  
  # シンガポールリージョンと中国 (北京) リージョンの API キーは異なります。API キーを取得するには、https://www.alibabacloud.com/help/model-studio/get-api-key をご参照ください
  # 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください：dashscope.api_key = "sk-xxx"
  dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')
  
  # 以下はシンガポールリージョンの URL です。中国 (北京) リージョンのモデルを使用する場合は、URL を https://dashscope.aliyuncs.com/api/v1 に置き換えてください
  dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
  
  prefix = 'testpfx'
  target_model = "fun-asr"
  
  my_vocabulary = [
      {"text": "Seediq Bale", "weight": 4}
  ]
  
  # ホットワードの作成
  service = VocabularyService()
  vocabulary_id = service.create_vocabulary(
      prefix=prefix,
      target_model=target_model,
      vocabulary=my_vocabulary)
  
  print(f"The hotword list ID is: {vocabulary_id}")

Java SDK

• API の説明

  重要

  targetModel：ホットワードリストを使用する音声認識モデル。このモデルは、後続の音声認識 API 呼び出しで指定されるものと同じでなければなりません。

  /**
   * 新しいホットワードリストを作成します。
   *
   * @param targetModel ホットワードリスト用の音声認識モデル。これは、後続の API 呼び出しで使用される音声認識モデルと同じでなければなりません。
   * @param prefix ホットワードのカスタムプレフィックス。10 文字未満の小文字と数字を含む必要があります。
   * @param vocabulary ホットワードリストの JSON。
   * @return ホットワードリストオブジェクト。
   * @throws NoApiKeyException API キーが空の場合。
   * @throws InputRequiredException 必須パラメーターが空の場合。
   */
  public Vocabulary createVocabulary(String targetModel, String prefix, JsonArray vocabulary)
      throws NoApiKeyException, InputRequiredException 

• コード例

  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 キーは異なります。API キーを取得するには、https://www.alibabacloud.com/help/model-studio/get-api-key をご参照ください
      // 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください：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 です。中国 (北京) リージョンのモデルを使用する場合は、URL を https://dashscope.aliyuncs.com/api/v1 に置き換えてください
          Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
          String targetModel = "fun-asr";
  
          JsonArray vocabularyJson = new JsonArray();
          List<Hotword> wordList = new ArrayList<>();
          wordList.add(new Hotword("Wu Yigong", 4));
          wordList.add(new Hotword("Queli Renjia", 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("Hotword list ID: " + vocabulary.getVocabularyId());
      }
  }
  
  class Hotword {
      String text;
      int weight;
      String lang;
  
      public Hotword(String text, int weight) {
          this.text = text;
          this.weight = weight;
      }
  }

RESTful API

• URL

  中国 (北京)：

  POST https://dashscope.aliyuncs.com/api/v1/services/audio/asr/customization

  シンガポール (国際)：

  POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization

• リクエストヘッダー

  パラメーター	タイプ	必須	説明
  Authorization	string	対応	認証トークン。フォーマットは Bearer <your_api_key> です。<your_api_key> を実際の API キーに置き換えてください。
  Content-Type	string	対応	リクエストボディで転送されるデータのメディアタイプ。値を application/json に設定します。

• リクエストボディ

  以下のリクエストボディには、すべてのリクエストパラメーターが含まれています。必要に応じてオプションのフィールドを省略できます。

  重要

  以下のパラメーターの違いに注意してください：

  • model：カスタムホットワードモデル。値を speech-biasing に設定します。

  • target_model：ホットワードリストを使用する音声認識モデル。このモデルは、後続の音声認識 API 呼び出しで指定されるものと同じでなければなりません。

  {
      "model": "speech-biasing",
      "input": {
          "action": "create_vocabulary",
          "target_model": "fun-asr",
          "prefix": "testpfx",
          "vocabulary": [
            {"text": "Seediq Bale", "weight": 4, "lang": "zh"}
          ]
      }
  }

• リクエストパラメーター

  パラメーター	タイプ	デフォルト	必須	説明
  model	string	-	対応	カスタムホットワードモデル。値を speech-biasing に設定します。
  action	string	-	対応	操作タイプ。値を create_vocabulary に設定します。
  target_model	string	-	はい	ホットワードリストを使用する音声認識モデル。詳細については、「サポート対象モデル」をご参照ください。 これは、後続の API 呼び出しで使用される音声認識モデルと同じでなければなりません。
  prefix	string	-	はい	ホットワードリストに識別しやすい名前を指定します。10 文字未満の小文字と数字を含む必要があります。 このキーワードはホットワードリスト ID に表示されます。たとえば、キーワードが「testpfx」の場合、最終的なホットワードリスト ID は「vocab-testpfx-51773d05xxxxxx」になります。
  vocabulary	array[object]	-	対応	ホットワードリストの JSON。詳細については、「ホットワードの概要」をご参照ください。

• レスポンスパラメーター

  レスポンス例の表示

  {
      "output": {
          "vocabulary_id": "vocab-testpfx-5112c3de3705486baxxxxxxx"
      },
      "usage": {
          "count": 1
      },
      "request_id": "aee47022-2352-40fe-acfa-xxxx"
  }

  以下のパラメーターに注意してください：

  パラメーター	タイプ	説明
  vocabulary_id	string	ホットワードリスト ID。

• コード例

  以下は cURL の例です。Java と Python の例については、対応する SDK をご参照ください。

  API キーを環境変数として設定していない場合は、$DASHSCOPE_API_KEY を実際の API キーに置き換えてください。

  https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization<a data-init-id="9f104f338c7kz" href="https://poc-dashscope.aliyuncs.com/api/v1/services/audio/tts/customization" id="35ebbc67890ds">https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization</a># ======= 重要 =======
  # 以下はシンガポールリージョンの URL です。中国 (北京) リージョンのモデルを使用する場合は、URL を https://dashscope.aliyuncs.com/api/v1/services/audio/asr/customization に置き換えてください
  # シンガポールリージョンと中国 (北京) リージョンの API キーは異なります。API キーを取得するには、https://www.alibabacloud.com/help/model-studio/get-api-key をご参照ください
  # === 実行前にこのコメントを削除してください ===
  
  curl -X POST <a data-init-id="9f104f338c7kz" href="https://poc-dashscope.aliyuncs.com/api/v1/services/audio/tts/customization" id="35ebbc67890ds">https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization</a> \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "model": "speech-biasing",
      "input": {
          "action": "create_vocabulary",
          "target_model": "fun-asr",
          "prefix": "testpfx",
          "vocabulary": [
            {"text": "Seediq Bale", "weight": 4}
          ]
      }
  }'

Python SDK

• API の説明

  def list_vocabularies(self, prefix=None, page_index: int = 0, page_size: int = 10) -> List[dict]:
      '''
      作成されたすべてのホットワードリストをクエリします。
      param: prefix カスタムプレフィックス。指定した場合、このプレフィックスを持つホットワードリストの識別子のみを返します。
      param: page_index ページインデックス。
      param: page_size ページサイズ。
      return: ホットワードリスト識別子のリスト。
      '''

• コード例

  import dashscope
  from dashscope.audio.asr import *
  import json
  import os
  
  # シンガポールリージョンと中国 (北京) リージョンの API キーは異なります。API キーを取得するには、https://www.alibabacloud.com/help/model-studio/get-api-key をご参照ください
  # 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください：dashscope.api_key = "sk-xxx"
  dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')
  
  # 以下はシンガポールリージョンの URL です。中国 (北京) リージョンのモデルを使用する場合は、URL を https://dashscope.aliyuncs.com/api/v1 に置き換えてください
  dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
  
  service = VocabularyService()
  vocabularies = service.list_vocabularies()
  print(f"Hotword list: {json.dumps(vocabularies)}")

• レスポンスパラメーター

  レスポンス例の表示

  [
    {
      "gmt_create": "2025-04-22 14:23:35",
      "vocabulary_id": "vocab-testpfx-5112c3de3705486baxxxxxxx",
      "gmt_modified": "2025-04-22 14:23:35",
      "status": "OK"
    }
  ]

  主要なパラメーターは以下の通りです：

  パラメーター	タイプ	説明
  vocabulary_id	string	ホットワードリスト ID。
  gmt_create	string	ホットワードリストが作成された時間。
  gmt_modified	string	ホットワードリストが変更された時間。
  status	string	ステータス： OK：呼び出し可能。 UNDEPLOYED：呼び出し不可。

Java SDK

• API の説明

  /**
   * 作成されたすべてのホットワードリストをクエリします。デフォルトのページインデックスは 0、デフォルトのページサイズは 10 です。
   *
   * @param prefix ホットワードのカスタムプレフィックス。
   * @return ホットワードリストオブジェクトの配列。
   * @throws NoApiKeyException API キーが空の場合。
   * @throws InputRequiredException 必須パラメーターが空の場合。
   */
  public Vocabulary[] listVocabulary(String prefix)
      throws NoApiKeyException, InputRequiredException
  
  /**
   * 作成されたすべてのホットワードリストをクエリします。
   *
   * @param prefix ホットワードのカスタムプレフィックス。
   * @param pageIndex ページインデックス。
   * @param pageSize ページサイズ。
   * @return ホットワードリストオブジェクトの配列。
   * @throws NoApiKeyException API キーが空の場合。
   * @throws InputRequiredException 必須パラメーターが空の場合。
   */
  public Vocabulary[] listVocabulary(String prefix, int pageIndex, int pageSize)
      throws NoApiKeyException, InputRequiredException

• コード例

  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 キーは異なります。API キーを取得するには、https://www.alibabacloud.com/help/model-studio/get-api-key をご参照ください
      // 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください：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 です。中国 (北京) リージョンのモデルを使用する場合は、URL を https://dashscope.aliyuncs.com/api/v1 に置き換えてください
          Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
  
          VocabularyService service = new VocabularyService(apiKey);
          Vocabulary[] vocabularies = service.listVocabulary("testpfx");
          Gson gson = new GsonBuilder()
                  .setPrettyPrinting()
                  .create();
          System.out.println("Hotword list: " + gson.toJson(vocabularies));
      }
  }

• レスポンス例の表示

  [
    {
      "gmt_create": "2025-04-22 14:23:35",
      "vocabulary_id": "vocab-testpfx-5112c3de3705486baxxxxxxx",
      "gmt_modified": "2025-04-22 14:23:35",
      "status": "OK"
    }
  ]

  主要なパラメーターは以下の通りです：

  パラメーター	タイプ	説明
  vocabulary_id	string	ホットワードリスト ID。
  gmt_create	string	ホットワードリストが作成された時間。
  gmt_modified	string	ホットワードリストが変更された時間。
  status	string	ステータス： OK：呼び出し可能。 UNDEPLOYED：呼び出し不可。

RESTful API

• URL

  中国 (北京)：

  POST https://dashscope.aliyuncs.com/api/v1/services/audio/asr/customization

  シンガポール (国際)：

  POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization

• リクエストヘッダー

  パラメーター	タイプ	必須	説明
  Authorization	string	はい	認証トークン。フォーマットは Bearer <your_api_key> です。<your_api_key> を実際の API キーに置き換えてください。
  Content-Type	string	はい	リクエストボディで転送されるデータのメディアタイプ。値を application/json に設定します。

• リクエストボディ

  以下のリクエストボディには、すべてのリクエストパラメーターが含まれています。必要に応じてオプションのフィールドを省略できます。

  重要

  model：カスタムホットワードモデル。値を speech-biasing に設定します。

  {
      "model": "speech-biasing",
      "input": {
          "action": "list_vocabulary",
          "prefix": "testpfx",
          "page_index": 0,
          "page_size": 10
      }
  }

• リクエストパラメーター

  パラメーター	タイプ	デフォルト	必須	説明
  model	string	-	はい	カスタムホットワードモデル。値を speech-biasing に設定します。
  action	string	-	対応	操作タイプ。値を list_vocabulary に設定します。
  prefix	string	-	非対応	ホットワードリストのカスタムプレフィックス。10 文字未満の小文字と数字を含む必要があります。
  page_index	integer	0	サポートされていません	ページ番号。カウントは 0 から始まります。
  page_size	integer	10	サポートされていません	ページあたりのエントリ数。

• レスポンスパラメーター

  レスポンス例の表示

  {
    "output": {
      "vocabulary_list": [
        {
          "gmt_create": "2025-12-19 11:47:11",
          "gmt_modified": "2025-12-19 11:47:11",
          "status": "OK",
          "vocabulary_id": "vocab-testpfx-xxxxxxxx"
        }
      ]
    },
    "usage": {
      "count": 1
    },
    "request_id": "10e8cde2-b711-4609-b19b-xxxxxx"
  }

  以下のパラメーターに注意してください：

  パラメーター	タイプ	説明
  vocabulary_id	string	ホットワードリスト ID。
  gmt_create	string	ホットワードリストが作成された時間。
  gmt_modified	string	ホットワードリストが変更された時間。
  status	string	ステータス： OK：呼び出し可能。 UNDEPLOYED：呼び出し不可。

• コード例

  以下は cURL の例です。Java と Python の例については、対応する SDK をご参照ください。

  API キーを環境変数として設定していない場合は、$DASHSCOPE_API_KEY を実際の API キーに置き換えてください。

  # ======= 重要 =======
  # 以下はシンガポールリージョンの URL です。中国 (北京) リージョンのモデルを使用する場合は、URL を https://dashscope.aliyuncs.com/api/v1/services/audio/asr/customization に置き換えてください
  # シンガポールリージョンと中国 (北京) リージョンの API キーは異なります。API キーを取得するには、https://www.alibabacloud.com/help/model-studio/get-api-key をご参照ください
  # === 実行前にこのコメントを削除してください ===
  
  curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/customization \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "model": "speech-biasing",
      "input": {
          "action": "list_vocabulary",
          "prefix": "testpfx",
          "page_index": 0,
          "page_size": 10
      }
  }'