カスタムホットワード Java SDK リファレンス

Alibaba Cloud Model Studio は、中国 (北京) リージョンおよびシンガポールリージョン向けにワークスペース専用ドメインをリリースしました。新しい専用ドメインは、推論リクエストに対して優れたパフォーマンスと高い安定性を提供します。以下の新しいドメインへの移行を推奨します。

中国 (北京)： dashscope.aliyuncs.com から {WorkspaceId}.cn-beijing.maas.aliyuncs.com
シンガポール： dashscope-intl.aliyuncs.com から {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} は、実際のワークスペース IDに置き換えてください。既存のドメインは引き続き完全に機能します。

ユーザーガイド： 認識精度の向上。

カスタム語彙はプライマリワークスペースでのみサポートされます。サブワークスペースではサポートされません。

エンドポイント

SDK はデフォルトで中国 (北京) のエンドポイントを使用します。他のリージョンに切り替えるには、初期化前に Constants.baseHttpApiUrl を変更してください。

シンガポール
中国 (北京)

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1{WorkspaceId} は、実際のワークスペース IDに置き換えてください。

シンガポールリージョンを使用するには、初期化前に Constants.baseHttpApiUrl を設定してください。

import com.alibaba.dashscope.utils.Constants;

// コードの先頭でこの設定を行ってください
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

注記：

API キーはリージョンごとに異なります。ご利用のリージョンに一致する API キーを使用してください。
リージョン設定はグローバルであり、すべての DashScope API 呼び出しに影響します。

VocabularyService

パッケージ： com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService 説明：カスタム語彙の作成、照会、更新、および削除を行います。

コンストラクター

public VocabularyService(String apiKey)

パラメーター：

パラメーター	型	説明
apiKey	String	DashScope API キー

createVocabulary() - カスタム語彙の作成

メソッドシグネチャー：

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

パラメーター：

パラメーター	型	必須	説明
targetModel	String	はい	この語彙を使用する音声認識モデルです。この値は、音声認識 API を呼び出す際に指定するモデルと一致している必要があります。
prefix	String	はい	語彙のカスタムプレフィックスです。小文字と数字のみが許可され、最大長は 10 文字です。
vocabulary	JsonArray	はい	ホットワードのリストです。各 JsonObject には text、weight、lang などのフィールドが含まれます。詳細については、「ホットワードオブジェクト構造」をご参照ください。

パラメーター

型

必須

説明

targetModel

String

はい

この語彙を使用する音声認識モデルです。この値は、音声認識 API を呼び出す際に指定するモデルと一致している必要があります。

prefix

String

はい

語彙のカスタムプレフィックスです。小文字と数字のみが許可され、最大長は 10 文字です。

vocabulary

JsonArray

はい

ホットワードのリストです。各 JsonObject には text、weight、lang などのフィールドが含まれます。

詳細については、「ホットワードオブジェクト構造」をご参照ください。

戻り値：

型	説明
Vocabulary	語彙 ID およびその他のメタデータを含むカスタム語彙オブジェクトです。

例外：

例外	説明
NoApiKeyException	API キーが空です。
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	いいえ	1 ページあたりのエントリー数です。デフォルト値： 10

戻り値：

型	説明
Vocabulary[]	カスタム語彙オブジェクトの配列です。

listVocabulary() が返すフィールド：

フィールド	型	説明
vocabularyId	String	語彙 ID です。
gmtCreate	String	作成時刻です。
gmtModified	String	最終更新時刻です。
status	String	ステータスです。 OK：準備完了 UNDEPLOYED：利用不可

例外：

例外	説明
NoApiKeyException	API キーが空です。
InputRequiredException	必須パラメーターが空です。

queryVocabulary() - カスタム語彙の照会

メソッドシグネチャー：

public Vocabulary queryVocabulary(String vocabularyId) throws NoApiKeyException, InputRequiredException

パラメーター：

パラメーター	型	必須	説明
vocabularyId	String	はい	照会するカスタム語彙の ID です。

戻り値：

型	説明
Vocabulary	ホットワードエントリーおよびメタデータを含む `Vocabulary` オブジェクトです。

queryVocabulary() が返すフィールド：

フィールド	型	説明
vocabulary	JsonArray	カスタム語彙の内容です。
targetModel	String	この語彙を使用する音声認識モデルです。この値は、音声認識 API を呼び出す際に指定するモデルと一致している必要があります。
gmtCreate	String	作成時刻です。
gmtModified	String	最終更新時刻です。
status	String	ステータスです。 OK：準備完了 UNDEPLOYED：利用不可

例外：

例外	説明
NoApiKeyException	API キーが空です。
InputRequiredException	必須パラメーターが空です。

updateVocabulary() - カスタム語彙の更新

メソッドシグネチャー：

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

パラメーター：

パラメーター	型	必須	説明
vocabularyId	String	はい	更新する語彙の ID です。
vocabulary	JsonArray	はい	新しい語彙です。これにより、既存のエントリーが完全に置き換えられます。

戻り値：なし例外：

例外	説明
NoApiKeyException	API キーが空です。
InputRequiredException	必須パラメーターが空です。

deleteVocabulary() - カスタム語彙の削除

メソッドシグネチャー：

public void deleteVocabulary(String vocabularyId) throws NoApiKeyException, InputRequiredException

パラメーター：

パラメーター	型	必須	説明
vocabularyId	String	はい	削除する語彙の ID です。

戻り値：なし例外：

例外	説明
NoApiKeyException	API キーが空です。
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 形式の完全なデータを返します。

ホットワードオブジェクト構造

各ホットワード 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 キーは異なります。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 {
        // 次の設定はシンガポールリージョン用です。{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("Wu yi gong", 4));
        wordList.add(new Hotword("A Family in Queli", 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 キーは異なります。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 {
        // 次の設定はシンガポールリージョン用です。{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 キーは異なります。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 {
        // 次の設定はシンガポールリージョン用です。{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 キーは異なります。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 {
        // 次の設定はシンガポールリージョン用です。{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("Wu yi gong", 4, "en"));
        wordList.add(new Hotword("A Family in Queli", 4, "en"));

        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 キーは異なります。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 {
        // 次の設定はシンガポールリージョン用です。{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");
    }
}

​エンドポイント

​VocabularyService

​コンストラクター

​createVocabulary() - カスタム語彙の作成

​listVocabulary() - カスタム語彙の一覧表示

​queryVocabulary() - カスタム語彙の照会

​updateVocabulary() - カスタム語彙の更新

​deleteVocabulary() - カスタム語彙の削除

​Vocabulary クラス

​メソッド

​ホットワードオブジェクト構造

​サンプルコード

​カスタム語彙の作成

​カスタム語彙の一覧表示

​カスタム語彙の照会

​カスタム語彙の更新

​カスタム語彙の削除

エンドポイント

VocabularyService

コンストラクター

createVocabulary() - カスタム語彙の作成

listVocabulary() - カスタム語彙の一覧表示

queryVocabulary() - カスタム語彙の照会

updateVocabulary() - カスタム語彙の更新

deleteVocabulary() - カスタム語彙の削除

Vocabulary クラス

メソッド

ホットワードオブジェクト構造

サンプルコード

カスタム語彙の作成

カスタム語彙の一覧表示

カスタム語彙の照会

カスタム語彙の更新

カスタム語彙の削除