Python SDK參考

通過Python SDK管理定製熱詞列表，包括VocabularyService類的方法說明與範例程式碼。

使用者指南：提升識別準確率。熱詞列表數量上限等使用限制詳見限制與計費。

重要

僅主業務空間支援熱詞功能，子業務空間暫不支援。

服務端點

SDK 預設使用北京地區的服務端點。如需切換到其他地區，需在初始化前修改 dashscope.base_http_api_url。

新加坡

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 dashscope

# 在代碼開頭設定
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

注意：

不同地區的 API Key 不同，請確保使用對應地區的 API Key
地區配置為全域設定，影響所有 DashScope SDK 的 API 呼叫

VocabularyService

包路徑：dashscope.audio.asr.VocabularyService

功能：管理熱詞列表的生命週期（建立、查詢、更新、刪除）

構造方法

VocabularyService(api_key: str = None, workspace: str = None, model: str = None)

未傳 api_key 時，SDK 使用全域 dashscope.api_key 的值。

create_vocabulary() - 建立熱詞列表

方法簽名：

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

參數：

參數	類型	必填	說明
target_model	str	是	使用熱詞列表的語音辨識模型，必須與後續調用語音辨識介面時使用的模型一致。
prefix	str	是	熱詞列表自訂首碼，僅允許數字和小寫字母，長度不超過10個字元。
vocabulary	List[dict]	是	熱詞列表，每個dict包含 text、weight、lang 等欄位。詳情請參見熱詞字典結構。

傳回值：

類型	說明
str	熱詞列表ID。

list_vocabularies() - 批量查詢熱詞列表

對應 HTTP API 的 action: list_vocabulary（HTTP 用單數，Python 方法名用複數 list_vocabularies）。

方法簽名：

def list_vocabularies(
    self,
    prefix: str = None,
    page_index: int = 0,
    page_size: int = 10) -> List[dict]

參數：

參數	類型	必填	說明
prefix	str	否	熱詞列表自訂首碼，如果設定則只返回指定首碼的熱詞列表。
page_index	int	否	頁碼索引，從0開始計數。預設值：0。
page_size	int	否	每頁包含資料條數。預設值：10。

傳回值：

類型	說明
List[dict]	熱詞列表資訊數組，每個dict包含 vocabulary_id、gmt_create、gmt_modified、status。

返回對象欄位：

欄位	類型	說明
vocabulary_id	str	熱詞列表ID。
gmt_create	str	建立時間。
gmt_modified	str	修改時間。
status	str	狀態： OK：可調用 UNDEPLOYED：不可調用。

query_vocabulary() - 查詢熱詞列表

方法簽名：

def query_vocabulary(
    self,
    vocabulary_id: str) -> dict

參數：

參數	類型	必填	說明
vocabulary_id	str	是	需要查詢的熱詞列表ID。

傳回值：

類型	說明
dict	熱詞列表詳細資料，包含 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_vocabulary() - 更新熱詞列表

方法簽名：

def update_vocabulary(
    self,
    vocabulary_id: str,
    vocabulary: List[dict]) -> None

參數：

參數	類型	必填	說明
vocabulary_id	str	是	需要更新的熱詞列表ID。
vocabulary	List[dict]	是	新的熱詞列表，將完全替換原有內容。

傳回值：無

delete_vocabulary() - 刪除熱詞列表

方法簽名：

def delete_vocabulary(
    self,
    vocabulary_id: str) -> None

參數：

參數	類型	必填	說明
vocabulary_id	str	是	需要刪除的熱詞列表ID。

傳回值：無

熱詞字典結構

用於 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 dashscope
# 以下為華北2（北京）地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
from dashscope.audio.asr import *
import os

# 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數，請用百鍊API Key將下行替換為：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

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

my_vocabulary = [
    {"text": "賽德克巴萊", "weight": 4}
]

# 建立熱詞
service = VocabularyService()
vocabulary_id = service.create_vocabulary(
    prefix=prefix,
    target_model=target_model,
    vocabulary=my_vocabulary)

print(f"熱詞列表ID為：{vocabulary_id}")

批量查詢熱詞列表

import dashscope
# 以下為華北2（北京）地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
from dashscope.audio.asr import *
import json
import os

# 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數，請用百鍊API Key將下行替換為：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

service = VocabularyService()
vocabularies = service.list_vocabularies()
print(f"熱詞列表：{json.dumps(vocabularies)}")

查詢熱詞列表

import dashscope
# 以下為華北2（北京）地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
from dashscope.audio.asr import *
import json
import os

# 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數，請用百鍊API Key將下行替換為：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

service = VocabularyService()
# 查詢時替換為實際的熱詞列表ID
vocabulary = service.query_vocabulary("vocab-testpfx-xxx")
print(f"熱詞列表：{json.dumps(vocabulary, ensure_ascii=False)}")

更新熱詞列表

import dashscope
# 以下為華北2（北京）地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
from dashscope.audio.asr import *
import os

# 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數，請用百鍊API Key將下行替換為：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

service = VocabularyService()
my_vocabulary = [
    {"text": "賽德克巴萊", "weight": 4, "lang": "zh"}
]
# 替換為實際的熱詞列表ID
service.update_vocabulary("vocab-testpfx-xxx", my_vocabulary)

刪除熱詞列表

import dashscope
# 以下為華北2（北京）地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
from dashscope.audio.asr import *
import os

# 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數，請用百鍊API Key將下行替換為：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

service = VocabularyService()
# 替換為實際的熱詞表ID
service.delete_vocabulary("vocab-testpfx-xxxx")