カスタムホットワード Python 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 はデフォルトで中国 (北京) のエンドポイントに接続します。他のリージョンに切り替えるには、dashscope.Client の構築時に region パラメーターを指定します（例：シンガポールリージョンは ap-southeast-1）。

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

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

シンガポールリージョンへの切り替え：

import os
import dashscope

# Client 構築時にリージョンを指定します
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

注記：

API キーはリージョンごとに異なります。ご利用のリージョンに一致する API キーを使用してください。
リージョン設定は dashscope.Client インスタンスレベルの設定であり、その client の API 呼び出しのみに影響します。

client.audio.vocabularies

リソースエントリー： dashscope.Client インスタンスの client.audio.vocabularies リソース説明：カスタム語彙の登録、一覧表示、照会、更新、および削除を行います。

コンストラクター

import os
import dashscope

client = dashscope.Client(
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    workspace='{WorkspaceId}',
    region='ap-southeast-1',
)

api_key が渡されない場合、SDK は DASHSCOPE_API_KEY 環境変数の値を自動的に読み取ります。

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

メソッドシグネチャー：

def create(
    self,
    *,
    target_model: str,
    prefix: str,
    vocabulary: List[dict]) -> Vocabulary

パラメーター：

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

パラメーター

型

必須

説明

target_model

str

はい

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

prefix

str

はい

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

vocabulary

List[dict]

はい

ホットワードのリストです。各エントリは、text、weight、lang のフィールドを持つ dict です。

詳細については、「ホットワード辞書構造」をご参照ください。

戻り値：

型	説明
Vocabulary	語彙オブジェクトです。`vocabulary_id` フィールドから語彙 ID を取得します。

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

HTTP API の action: list_vocabulary に対応しています。 メソッドシグネチャー：

def list(
    self,
    *,
    prefix: str = None,
    page_index: int = 0,
    page_size: int = 10) -> VocabularyList

パラメーター：

パラメーター	型	必須	説明
prefix	str	いいえ	語彙のカスタムプレフィックスです。指定した場合、このプレフィックスを持つ語彙のみが返されます。
page_index	int	いいえ	ページ番号（0 から開始）です。デフォルト値： 0
page_size	int	いいえ	1 ページあたりのエントリ数です。デフォルト値： 10

戻り値：

型	説明
VocabularyList	語彙のページングオブジェクトです。`vocabularies` フィールドは語彙情報の配列で、各 dict に vocabulary_id、gmt_create、gmt_modified、status が含まれます。

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

フィールド	型	説明
vocabulary_id	str	語彙 ID です。
gmt_create	str	作成時刻です。
gmt_modified	str	最終変更時刻です。
status	str	ステータスです。 OK: 準備完了。 UNDEPLOYED：利用不可

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

1.x SDK の query_vocabulary() に対応しています。 メソッドシグネチャー：

def get(
    self,
    vocabulary_id: str) -> Vocabulary

パラメーター：

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

戻り値：

型	説明
Vocabulary	語彙の詳細情報オブジェクトです。vocabulary、target_model、gmt_create、gmt_modified、status が含まれます。

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

フィールド	型	説明
vocabulary	List[dict]	ホットワードリストの内容です。
target_model	str	この語彙を使用する音声認識モデルです。この値は、音声認識 API を呼び出す際に指定するモデルと一致している必要があります。
gmt_create	str	作成時刻です。
gmt_modified	str	最終変更時刻です。
status	str	ステータスです。 OK：利用可能 UNDEPLOYED：利用不可

update() - カスタム語彙を更新する

メソッドシグネチャー：

def update(
    self,
    vocabulary_id: str,
    *,
    vocabulary: List[dict]) -> JobStatus

パラメーター：

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

戻り値： JobStatus オブジェクト。status フィールドは操作のステータスです。

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

メソッドシグネチャー：

def delete(
    self,
    vocabulary_id: str) -> JobStatus

パラメーター：

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

戻り値： JobStatus オブジェクト。status フィールドは操作のステータスです。

ホットワード辞書構造

各語彙辞書のフィールド：

フィールド	型	必須	説明
text	str	はい	語彙エントリのテキストです。テキストの言語は、選択したモデルでサポートされている必要があります。サポートされる言語はモデルによって異なります。認識精度を向上させるには、任意の文字列ではなく実際の単語を使用してください。最大長：非 ASCII 文字を含むテキストの場合は 15 文字、ASCII のみのテキストの場合はスペース区切りで 7 単語。
weight	int	はい	語彙エントリの重みです。推奨値： 4 有効な値： 1 ～ 5 認識精度が向上しない場合は、重みを増やしてください。ただし、重みが高すぎると他の単語の認識精度が低下する可能性があります。
lang	str	いいえ	認識対象の音声の言語コードです。設定すると、指定された言語の語彙エントリの認識が向上します。事前に言語を特定できない場合は、このパラメーターを未設定にしてください。モデルが自動的に言語を検出します。有効な値（モデルによって異なります）： Paraformer： zh：中国語 en：英語 ja：日本語 yue：広東語 ko：韓国語 de：ドイツ語 fr：フランス語 ru：ロシア語 Fun-ASR： zh：中国語 en：英語 ja：日本語

サンプルコード

すべての例では、環境変数から API キーを読み取ります。

カスタム語彙の作成

import os
import dashscope

# シンガポールおよび北京リージョンの API キーは異なります。API キーの取得方法： https://www.alibabacloud.com/help/model-studio/get-api-key
# 環境変数が設定されていない場合は、次の行を実際の Model Studio API キーに置き換えてください： api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # 次の構成はシンガポールリージョン用です。"{WorkspaceId}" は実際のワークスペース ID に置き換えてください。構成はリージョンによって異なります。
    workspace='{WorkspaceId}',
    region='ap-southeast-1',
)

prefix = 'testpfx'
target_model = "fun-asr"

my_vocabulary = [
    {"text": "Seediq Bale", "weight": 4}
]

# カスタム語彙を作成します
vocabulary = client.audio.vocabularies.create(
    prefix=prefix,
    target_model=target_model,
    vocabulary=my_vocabulary)

print(f"Vocabulary ID: {vocabulary.vocabulary_id}")

カスタム語彙の一覧表示

import json
import os
import dashscope

# シンガポールおよび北京リージョンの API キーは異なります。API キーの取得方法： https://www.alibabacloud.com/help/model-studio/get-api-key
# 環境変数が設定されていない場合は、次の行を実際の Model Studio API キーに置き換えてください： api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # 次の構成はシンガポールリージョン用です。"{WorkspaceId}" は実際のワークスペース ID に置き換えてください。構成はリージョンによって異なります。
    workspace='{WorkspaceId}',
    region='ap-southeast-1',
)

result = client.audio.vocabularies.list()
print(f"Vocabularies: {json.dumps(result.vocabularies)}")

カスタム語彙の照会

import json
import os
import dashscope

# シンガポールおよび北京リージョンの API キーは異なります。API キーの取得方法： https://www.alibabacloud.com/help/model-studio/get-api-key
# 環境変数が設定されていない場合は、次の行を実際の Model Studio API キーに置き換えてください： api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # 次の構成はシンガポールリージョン用です。"{WorkspaceId}" は実際のワークスペース ID に置き換えてください。構成はリージョンによって異なります。
    workspace='{WorkspaceId}',
    region='ap-southeast-1',
)

# 照会時に実際の語彙 ID に置き換えてください
vocabulary = client.audio.vocabularies.get("vocab-testpfx-xxx")
print(f"Vocabulary: {json.dumps(vocabulary.vocabulary, ensure_ascii=False)}")

カスタム語彙の更新

import os
import dashscope

# シンガポールおよび北京リージョンの API キーは異なります。API キーの取得方法： https://www.alibabacloud.com/help/model-studio/get-api-key
# 環境変数が設定されていない場合は、次の行を実際の Model Studio API キーに置き換えてください： api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # 次の構成はシンガポールリージョン用です。"{WorkspaceId}" は実際のワークスペース ID に置き換えてください。構成はリージョンによって異なります。
    workspace='{WorkspaceId}',
    region='ap-southeast-1',
)

my_vocabulary = [
    {"text": "Seediq Bale", "weight": 4, "lang": "en"}
]
# 更新時に実際の語彙 ID に置き換えてください
result = client.audio.vocabularies.update("vocab-testpfx-xxx", vocabulary=my_vocabulary)
print(f"Update status: {result.status}")

カスタム語彙の削除

import os
import dashscope

# シンガポールおよび北京リージョンの API キーは異なります。API キーの取得方法： https://www.alibabacloud.com/help/model-studio/get-api-key
# 環境変数が設定されていない場合は、次の行を実際の Model Studio API キーに置き換えてください： api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # 次の構成はシンガポールリージョン用です。"{WorkspaceId}" は実際のワークスペース ID に置き換えてください。構成はリージョンによって異なります。
    workspace='{WorkspaceId}',
    region='ap-southeast-1',
)

# 削除時に実際の語彙 ID に置き換えてください
result = client.audio.vocabularies.delete("vocab-testpfx-xxxx")
print(f"Delete status: {result.status}")

​エンドポイント

​client.audio.vocabularies

​コンストラクター

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

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

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

​update() - カスタム語彙を更新する

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

​ホットワード辞書構造

​サンプルコード

​カスタム語彙の作成

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

​カスタム語彙の照会

​カスタム語彙の更新

​カスタム語彙の削除

エンドポイント

client.audio.vocabularies

コンストラクター

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

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

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

update() - カスタム語彙を更新する

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

ホットワード辞書構造

サンプルコード

カスタム語彙の作成

カスタム語彙の一覧表示

カスタム語彙の照会

カスタム語彙の更新

カスタム語彙の削除