通過Python SDK管理定製熱詞列表,包括client.audio.vocabularies資源的方法說明與範例程式碼。
使用者指南:提升識別準確率。熱詞列表數量上限等使用限制詳見熱詞限制與計費。
重要僅主業務空間支援熱詞功能,子業務空間暫不支援。
介面地址
SDK 預設使用北京地區的介面地址。如需切換到其他地區,在構造 dashscope.Client 時指定 region 參數(如新加坡地區為 ap-southeast-1)。
新加坡
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。現有網域名稱仍可正常使用。
重要阿里雲百鍊為華北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 os
import dashscope
# 構造 Client 時指定地區
client = dashscope.Client(
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
注意:
- 不同地區的 API Key 不同,請確保使用對應地區的 API Key
- 地區配置為
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 | 是 | 使用熱詞列表的語音辨識模型,必須與後續調用語音辨識介面時使用的模型一致。 |
prefix | str | 是 | 熱詞列表自訂首碼,僅允許數字和小寫字母,長度不超過10個字元。 |
vocabulary | List[dict] | 是 | 熱詞列表,每個dict包含 text、weight、lang 等欄位。 詳情請參見熱詞字典結構。 |
傳回值:
類型 | 說明 |
|---|---|
Vocabulary | 熱詞列表對象,通過 |
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 | 否 | 每頁包含資料條數。 預設值:10。 |
傳回值:
類型 | 說明 |
|---|---|
VocabularyList | 熱詞列表分頁對象, |
返回對象欄位:
欄位 | 類型 | 說明 |
|---|---|---|
vocabulary_id | str | 熱詞列表ID。 |
gmt_create | str | 建立時間。 |
gmt_modified | str | 修改時間。 |
status | str | 狀態:
|
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。 |
返回對象欄位:
欄位 | 類型 | 說明 |
|---|---|---|
vocabulary | List[dict] | 熱詞列表內容。 |
target_model | str | 使用熱詞列表的語音辨識模型,必須與後續調用語音辨識介面時使用的模型一致。 |
gmt_create | str | 建立時間。 |
gmt_modified | str | 修改時間。 |
status | str | 狀態:
|
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 欄位為操作狀態。
熱詞字典結構
用於vocabulary參數的字典定義:
欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
text | str | 是 | 熱詞文本。 熱詞文本的語言必須在所選模型的支援範圍內,不同模型支援的語言各不相同。 熱詞用於提升識別的準確率,請使用實際詞語而非任一字元組合。 長度限制:含非 ASCII 字元時不超過 15 個字元;純 ASCII 時空格分隔片段不超過 7 個。 |
weight | int | 是 | 熱詞權重。常用值:4。 取值範圍:[1, 5]。 如果效果不明顯,可以適當增加權重,但權重過大可能產生負面效果,導致其他詞語識別不準確。 |
lang | str | 否 | 待識別音訊語言代碼。設定後,系統將對指定語種進行熱詞識別增強。如果無法提前確定語種,可不設定,模型會自動識別語種。 取值範圍(因模型而異):
|
範例程式碼
建立熱詞列表
import os
import dashscope
# 以下為新加坡地區的配置,調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區的region取值不同。
client = dashscope.Client(
# 新加坡和北京地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
api_key=os.environ.get('DASHSCOPE_API_KEY'),
workspace='{WorkspaceId}',
region='ap-southeast-1',
)
prefix = 'testpfx'
target_model = "fun-asr"
my_vocabulary = [
{"text": "賽德克巴萊", "weight": 4}
]
# 建立熱詞
vocabulary = client.audio.vocabularies.create(
prefix=prefix,
target_model=target_model,
vocabulary=my_vocabulary)
print(f"熱詞列表ID為:{vocabulary.vocabulary_id}")
批量查詢熱詞列表
import json
import os
import dashscope
# 以下為新加坡地區的配置,調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區的region取值不同。
client = dashscope.Client(
# 新加坡和北京地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
api_key=os.environ.get('DASHSCOPE_API_KEY'),
workspace='{WorkspaceId}',
region='ap-southeast-1',
)
result = client.audio.vocabularies.list()
print(f"熱詞列表:{json.dumps(result.vocabularies)}")
查詢熱詞列表
import json
import os
import dashscope
# 以下為新加坡地區的配置,調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區的region取值不同。
client = dashscope.Client(
# 新加坡和北京地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
api_key=os.environ.get('DASHSCOPE_API_KEY'),
workspace='{WorkspaceId}',
region='ap-southeast-1',
)
# 查詢時替換為實際的熱詞列表ID
vocabulary = client.audio.vocabularies.get("vocab-testpfx-xxx")
print(f"熱詞列表:{json.dumps(vocabulary.vocabulary, ensure_ascii=False)}")
更新熱詞列表
import os
import dashscope
# 以下為新加坡地區的配置,調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區的region取值不同。
client = dashscope.Client(
# 新加坡和北京地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
api_key=os.environ.get('DASHSCOPE_API_KEY'),
workspace='{WorkspaceId}',
region='ap-southeast-1',
)
my_vocabulary = [
{"text": "賽德克巴萊", "weight": 4, "lang": "zh"}
]
# 替換為實際的熱詞列表ID
result = client.audio.vocabularies.update("vocab-testpfx-xxx", vocabulary=my_vocabulary)
print(f"更新狀態:{result.status}")
刪除熱詞列表
import os
import dashscope
# 以下為新加坡地區的配置,調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區的region取值不同。
client = dashscope.Client(
# 新加坡和北京地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
api_key=os.environ.get('DASHSCOPE_API_KEY'),
workspace='{WorkspaceId}',
region='ap-southeast-1',
)
# 替換為實際的熱詞表ID
result = client.audio.vocabularies.delete("vocab-testpfx-xxxx")
print(f"刪除狀態:{result.status}")