全部產品
Search
文件中心

Alibaba Cloud Model Studio:定製熱詞Python SDK參考

更新時間:Oct 27, 2026

通過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

熱詞列表對象,通過 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

否

每頁包含資料條數。

預設值:10。

傳回值:

類型

說明

VocabularyList

熱詞列表分頁對象,vocabularies 欄位為熱詞列表資訊數組,每個dict包含 vocabulary_id、gmt_create、gmt_modified、status。

返回對象欄位:

欄位

類型

說明

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。

返回對象欄位:

欄位

類型

說明

vocabulary

List[dict]

熱詞列表內容。

target_model

str

使用熱詞列表的語音辨識模型,必須與後續調用語音辨識介面時使用的模型一致。

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 欄位為操作狀態。

熱詞字典結構

用於vocabulary參數的字典定義:

欄位

類型

必填

說明

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: 日語

範例程式碼

建立熱詞列表

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}")