热词是指用户可以预先定义的一组特定词汇或短语,这些词汇或短语在识别、翻译过程中会被赋予更高的优先级。使用热词可以显著提高这些特定词汇的识别、翻译准确率。针对您的特定业务领域,如果有部分词汇的语音识别、翻译效果不够好,可以将这些关键词或短语添加为热词进行优先识别或翻译,从而提升识别、翻译效果。
热词简介
热词通过热词列表的形式在SDK或API中使用,热词列表是JSON列表,其中每一个热词包含如下字段:
字段 | 类型 | 是否必填 | 说明 |
text | string | 是 | 热词文本。 热词用于提升识别/翻译的准确率,因此请使用实际词语而非任意字符组合。热词文本长度限制规则如下:
|
lang | string | 否 | 待识别语音的语言代码,支持对ASR模型对应的语种做热词加强。具体语种和语言代码对应关系请参见API详情。请在调用语音识别服务时保证该字段和源语言字段(Java: |
target_lang | string | 否 | 翻译目标语言。具体语种和语言代码对应关系请参见API详情。请在调用语音翻译服务时保证该字段和语音翻译时的翻译目标语言(Java: 如果需要输出多路翻译,需要逐个指定热词翻译目标语种,例如,将中文翻译成英文和日语的热词示例如下:
|
translation | string | 否 | 热词翻译目标。 例如希望将“夏洛特烦恼”翻译成“Goodbye Mr. Lose”:
|
应用场景示例
为了提高电影名称的识别和翻译的准确率,将如下电影名称作为热词添加到项目中。
[
{
"text": "赛德克巴莱",
"lang": "zh",
"target_lang": "en",
"translation": "Seediq Bale"
},
{
"text": "夏洛特烦恼",
"lang": "zh",
"target_lang": "en",
"translation": "Goodbye Mr. Lose"
},
{
"text": "夏洛特烦恼",
"lang": "zh",
"target_lang": "ja",
"translation": "夏洛の特別な悩み"
}
]
支持的模型列表
gummy-realtime-v1
gummy-chat-v1
计费说明
热词暂不收费。
前提条件
已开通服务并获得API-KEY:获取API Key。
我们推荐您将API-KEY配置到环境变量中以降低API-KEY的泄漏风险,详情可参考配置API Key到环境变量。您也可以在代码中配置API-KEY,但是泄漏风险会提高。
已安装最新版SDK:安装SDK。
注意:
1、每个热词列表最多添加500个词,
2、每个账号默认分配10个热词列表额度,该额度由Paraformer和Gummy共享,如果有需要创建更多请联系我们。
API详情
使用不同API时,请确保使用同一账号进行操作。
创建热词表
Python SDK
通过VocabularyService
类的create_vocabulary
方法创建热词表。VocabularyService
类的引入方式:from dashscope.audio.asr import *
。
create_vocabulary
方法返回热词表ID。
热词表字典各字段含义请参见热词简介。
def create_vocabulary(self, target_model: str, prefix: str, vocabulary: List[dict]) -> str:
'''
创建热词表
param: target_model 热词表对应的语音识别模型版本
param: prefix 热词表自定义前缀,仅允许数字和小写字母,小于十个字符。
param: vocabulary 热词表字典
return: 热词表标识符 vocabulary_id
'''
Java SDK
通过VocabularyService
类的createVocabulary
方法创建热词表。VocabularyService
类的引入方式:import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
。
createVocabulary
方法返回热词表ID。
热词表字典各字段含义请参见热词简介。
/**
* 创建新热词
*
* @param targetModel 热词对应的语音识别模型版本
* @param prefix 热词自定义前缀,仅允许数字和小写字母,小于十个字符。
* @param vocabulary 热词表
* @return 热词表对象
* @throws NoApiKeyException 如果apikey为空
* @throws InputRequiredException 如果必须参数为空
*/
public Vocabulary createVocabulary(String targetModel, String prefix, JsonArray vocabulary)
throws NoApiKeyException, InputRequiredException
RESTful API
基本信息
URL |
|
请求方法 | POST |
请求头 |
|
消息体 | 包含所有请求参数的消息体如下,对于可选字段,在实际业务中可根据需求省略:
|
请求参数
参数 | 类型 | 默认值 | 是否必须 | 说明 |
model | string | - | 是 | 固定为 |
action | string | - | 是 | 固定为 |
target_model | string | - | 是 | 热词表对应的语音识别模型,为 |
prefix | string | - | 是 | 热词表自定义前缀,仅允许数字和小写字母,小于十个字符。 |
vocabulary | object[] | - | 是 | 热词表字典。各字段含义参见热词简介。 |
响应参数
参数 | 类型 | 说明 |
vocabulary_id | string | 热词表ID。 |
查询所有热词表
Python SDK
通过VocabularyService
类的list_vocabularies
方法查询所有热词表。VocabularyService
类的引入方式:from dashscope.audio.asr import *
。
def list_vocabularies(self, prefix=None, page_index: int = 0, page_size: int = 10) -> List[dict]:
'''
查询已创建的所有热词表
param: prefix 自定义前缀,如果设定则只返回指定前缀的热词表标识符列表。
param: page_index 查询的页索引
param: page_size 查询页大小
return: 热词表标识符列表
'''
响应示例:
[
{
"gmt_create": "2025-04-22 14:23:35",
"vocabulary_id": "yourVocabularyId",
"gmt_modified": "2025-04-22 14:23:35",
"status": "OK"
}
]
响应参数:
参数 | 类型 | 说明 |
vocabulary_id | string | 热词表ID。 |
gmt_create | string | 创建热词表的时间。 |
gmt_modified | string | 修改热词表的时间。 |
status | string | 状态:
|
Java SDK
通过VocabularyService
类的listVocabulary
方法查询所有热词表。VocabularyService
类的引入方式:import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
。
/**
* 查询已创建的所有热词表。默认的页索引为0,默认的页大小为10
*
* @param prefix 热词自定义前缀
* @return 热词表对象数组
* @throws NoApiKeyException 如果apikey为空
* @throws InputRequiredException 如果必须参数为空
*/
public Vocabulary[] listVocabulary(String prefix)
throws NoApiKeyException, InputRequiredException
/**
* 查询已创建的所有热词表
*
* @param prefix 热词自定义前缀
* @param pageIndex 查询的页索引
* @param pageSize 查询的页大小
* @return 热词表对象数组
* @throws NoApiKeyException 如果apikey为空
* @throws InputRequiredException 如果必须参数为空
*/
public Vocabulary[] listVocabulary(String prefix, int pageIndex, int pageSize)
throws NoApiKeyException, InputRequiredException
响应示例:
[
{
"gmt_create": "2025-04-22 14:23:35",
"vocabulary_id": "yourVocabularyId",
"gmt_modified": "2025-04-22 14:23:35",
"status": "OK"
}
]
响应参数:
参数 | 类型 | 说明 |
vocabulary_id | string | 热词表ID。 |
gmt_create | string | 创建热词表的时间。 |
gmt_modified | string | 修改热词表的时间。 |
status | string | 状态:
|
RESTful API
基本信息
URL |
|
请求方法 | POST |
请求头 |
|
消息体 | 包含所有请求参数的消息体如下,对于可选字段,在实际业务中可根据需求省略:
|
请求参数
参数 | 类型 | 默认值 | 是否必须 | 说明 |
model | string | - | 是 | 固定为 |
action | string | - | 是 | 固定为 |
prefix | string | - | 是 | 热词表自定义前缀,仅允许数字和小写字母,小于十个字符。 |
page_index | integer | 0 | 否 | 页码索引,从0开始计数。 |
page_size | integer | 10 | 否 | 每页包含数据条数。 |
响应参数
参数 | 类型 | 说明 |
vocabulary_id | string | 热词表ID。 |
gmt_create | string | 创建热词表的时间。 |
gmt_modified | string | 修改热词表的时间。 |
status | string | 状态:
|
查询指定热词表
Python SDK
通过VocabularyService
类的query_vocabulary
方法查询指定热词表。VocabularyService
类的引入方式:from dashscope.audio.asr import *
。
def query_vocabulary(self, vocabulary_id: str) -> List[dict]:
'''
获取热词表内容
param: vocabulary_id 热词表标识符
return: 热词表
'''
响应示例:
{
"gmt_create": "2025-04-22 14:23:35",
"vocabulary": [
{
"target_lang": "en",
"translation": "Goodbye Mr. Lose",
"text": "夏洛特烦恼",
"lang": "zh"
}
],
"target_model": "gummy-realtime-v1",
"gmt_modified": "2025-04-22 14:23:35",
"status": "OK"
}
响应参数:
参数 | 类型 | 说明 |
vocabulary | object[] | 热词表字典。各字段含义参见热词简介。 |
gmt_create | string | 创建热词表的时间。 |
gmt_modified | string | 修改热词表的时间。 |
target_model | string | 热词表对应的语音识别模型,为 |
status | string | 状态:
|
Java SDK
通过VocabularyService
类的queryVocabulary
方法查询指定热词表。VocabularyService
类的引入方式:import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
。
/**
* 查询指定热词表
*
* @param vocabularyId 需要查询的热词表
* @return 热词表对象
* @throws NoApiKeyException 如果apikey为空
* @throws InputRequiredException 如果必须参数为空
*/
public Vocabulary queryVocabulary(String vocabularyId)
throws NoApiKeyException, InputRequiredException
响应示例:
{
"gmt_create": "2025-04-22 14:23:35",
"vocabulary": [
{
"target_lang": "en",
"translation": "Goodbye Mr. Lose",
"text": "夏洛特烦恼",
"lang": "zh"
}
],
"target_model": "gummy-realtime-v1",
"gmt_modified": "2025-04-22 14:23:35",
"status": "OK"
}
响应参数:
参数 | 类型 | 说明 |
vocabulary | object[] | 热词表字典。各字段含义参见热词简介。 |
gmt_create | string | 创建热词表的时间。 |
gmt_modified | string | 修改热词表的时间。 |
target_model | string | 热词表对应的语音识别模型,为 |
status | string | 状态:
|
RESTful API
基本信息
URL |
|
请求方法 | POST |
请求头 |
|
消息体 | 包含所有请求参数的消息体如下,对于可选字段,在实际业务中可根据需求省略:
|
请求参数
参数 | 类型 | 默认值 | 是否必须 | 说明 |
model | string | - | 是 | 固定为 |
action | string | - | 是 | 固定为 |
vocabulary_id | string | - | 是 | 待查询热词表ID。 |
响应参数
参数 | 类型 | 说明 |
vocabulary | object[] | 热词表字典。各字段含义参见热词简介。 |
gmt_create | string | 创建热词表的时间。 |
gmt_modified | string | 修改热词表的时间。 |
target_model | string | 热词表对应的语音识别模型,为 |
status | string | 状态:
|
更新热词表
Python SDK
通过VocabularyService
类的update_vocabulary
方法更新热词表。VocabularyService
类的引入方式:from dashscope.audio.asr import *
。
def update_vocabulary(self, vocabulary_id: str, vocabulary: List[dict]) -> None:
'''
用新的热词表替换已有热词表
param: vocabulary_id 需要替换的热词表标识符
param: vocabulary 热词表
'''
Java SDK
通过VocabularyService
类的updateVocabulary
方法更新热词表。VocabularyService
类的引入方式:import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
。
/**
* 更新热词表
*
* @param vocabularyId 需要更新的热词表
* @param vocabulary 热词表对象
* @throws NoApiKeyException 如果apikey为空
* @throws InputRequiredException 如果必须参数为空
*/
public void updateVocabulary(String vocabularyId, JsonArray vocabulary)
throws NoApiKeyException, InputRequiredException
RESTful API
基本信息
URL |
|
请求方法 | POST |
请求头 |
|
消息体 | 包含所有请求参数的消息体如下,对于可选字段,在实际业务中可根据需求省略:
|
请求参数
参数 | 类型 | 默认值 | 是否必须 | 说明 |
model | string | - | 是 | 固定为 |
action | string | - | 是 | 固定为 |
vocabulary_id | string | - | 是 | 待更新热词表ID。 |
vocabulary | object[] | - | 是 | 更新后的热词表字典。各字段含义参见热词简介。 |
响应参数
删除热词表
Python SDK
通过VocabularyService
类的delete_vocabulary
方法删除热词表。VocabularyService
类的引入方式:from dashscope.audio.asr import *
。
def delete_vocabulary(self, vocabulary_id: str) -> None:
'''
删除热词表
param: vocabulary_id 需要删除的热词表标识符
'''
Java SDK
通过VocabularyService
类的deleteVocabulary
方法删除热词表。VocabularyService
类的引入方式:import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
。
/**
* 删除热词表
*
* @param vocabularyId 需要删除的热词表
* @throws NoApiKeyException 如果apikey为空
* @throws InputRequiredException 如果必须参数为空
*/
public void deleteVocabulary(String vocabularyId)
throws NoApiKeyException, InputRequiredException
RESTful API
基本信息
URL |
|
请求方法 | POST |
请求头 |
|
消息体 | 包含所有请求参数的消息体如下,对于可选字段,在实际业务中可根据需求省略:
|
请求参数
参数 | 类型 | 默认值 | 是否必须 | 说明 |
model | string | - | 是 | 固定为 |
action | string | - | 是 | 固定为 |
vocabulary_id | string | - | 是 | 待删除热词表ID。 |
响应参数
使用创建的热词表进行语音识别/翻译
本文档介绍热词管理接口的功能,支持对热词进行创建、查询、更新和删除操作。若需在语音识别/翻译中调用已创建的热词表,请按以下步骤操作(请确保热词表与语音识别/翻译使用同一账号):
获取热词表ID
调用创建热词表或查询所有热词表接口,获取热词表ID(根据编程语言选择合适的接口。对于Java和Python以外的其他编程语言,如 Go、C#、PHP、Node.js 等,请使用RESTful接口)。
调用Gummy语音识别/翻译API
请根据您所使用的编程语言选择对应API文档,将第1步中获取的热词表ID作为
vocabulary_id
/vocabularyId
参数传递至语音识别接口(调用接口时,可通过请求参数对音频采样率、音频格式等进行调节):实时语音识别/翻译
Java:Java SDK
Python:Python SDK
其他编程语言(如Go、C#、PHP、Node.js等):WebSocket API
一句话识别/翻译
Java:Java SDK
Python:Python SDK
其他编程语言(如Go、C#、PHP、Node.js等):WebSocket API
以下示例代码展示如何创建一个热词表,并调用gummy-realtime-v1模型识别本地音频文件。
示例代码仅提供 Java 和 Python 的基础示例,实际业务场景中的相关代码需您根据具体需求自行开发。示例中用到的音频为:asr_example.wav。
import dashscope
from dashscope.audio.asr import *
# 若没有将API Key配置到环境变量中,需将your-api-key替换为自己的API Key
# dashscope.api_key = "your-api-key"
prefix = 'prefix'
target_model = "gummy-realtime-v1"
my_vocabulary = [
{"text": "阿里巴巴语音实验室", "lang": "zh", "target_lang": "en", "translation": "Alibaba Speech Lab"}
]
# 创建热词
service = VocabularyService()
vocabulary_id = service.create_vocabulary(
prefix=prefix,
target_model=target_model,
vocabulary=my_vocabulary)
print(f"热词表ID为:{vocabulary_id}")
# 使用热词进行语音识别
translator = TranslationRecognizerRealtime(
model=target_model, # 设置模型
format="wav", # 设置音频格式
sample_rate=16000, # 设置采样率
translation_target_languages=["en"], # 设置翻译目标语言
translation_enabled=True, # 启用翻译
vocabulary_id=vocabulary_id, # 传入热词表ID
callback=None,
)
result = translator.call("asr_example.wav")
if not result.error_message:
print("Request ID:", result.request_id)
print("识别结果:")
for transcription_result in result.transcription_result_list:
print(transcription_result.text)
print("翻译结果:")
for translation_result in result.translation_result_list:
print(translation_result.get_translation('en').text)
else:
print("出现异常:", result.error_message)
import com.alibaba.dashscope.audio.asr.translation.TranslationRecognizerParam;
import com.alibaba.dashscope.audio.asr.translation.TranslationRecognizerRealtime;
import com.alibaba.dashscope.audio.asr.translation.results.TranscriptionResult;
import com.alibaba.dashscope.audio.asr.translation.results.TranslationRecognizerResultPack;
import com.alibaba.dashscope.audio.asr.translation.results.TranslationResult;
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.google.gson.JsonArray;
import com.google.gson.JsonObject;
import java.io.File;
import java.util.ArrayList;
import java.util.List;
public class Main {
public static String apiKey = System.getenv("DASHSCOPE_API_KEY"); // 若没有将API Key配置到环境变量中,需将apiKey替换为自己的API Key
public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
String targetModel = "gummy-realtime-v1";
// 定义热词类
class HotWord {
String text;
String lang;
String targetLang;
String translation;
public HotWord(String text, String lang, String targetLang, String translation) {
this.text = text;
this.lang = lang;
this.targetLang = targetLang;
this.translation = translation;
}
}
JsonArray vocabulary = new JsonArray();
List<HotWord> wordList = new ArrayList<>();
wordList.add(new HotWord("阿里巴巴语音实验室", "zh", "en", "Alibaba Speech Lab"));
for (HotWord word : wordList) {
JsonObject jsonObject = new JsonObject();
jsonObject.addProperty("text", word.text);
jsonObject.addProperty("lang", word.lang);
jsonObject.addProperty("target_lang", word.targetLang);
jsonObject.addProperty("translation", word.translation);
vocabulary.add(jsonObject);
}
// 创建热词
VocabularyService service = new VocabularyService(apiKey);
Vocabulary myVoc = service.createVocabulary(targetModel, "prefix", vocabulary);
System.out.println("热词表ID:" + myVoc.getVocabularyId());
// 使用热词进行语音识别
String targetLanguage = "en";
// 创建TranslationRecognizerRealtime实例
TranslationRecognizerRealtime translator = new TranslationRecognizerRealtime();
// 设置请求参数
TranslationRecognizerParam param =
TranslationRecognizerParam.builder()
.apiKey(apiKey)
.model("gummy-realtime-v1") // 设置模型
.format("wav") // 设置音频格式
.sampleRate(16000) // 设置采样率
.transcriptionEnabled(true) // 启用语音识别
.translationEnabled(true) // 启用翻译
.translationLanguages(new String[] {targetLanguage}) // 设置翻译目标语言
.vocabularyId(myVoc.getVocabularyId()) // 设置热词表ID
.build();
// 解析识别/翻译结果
TranslationRecognizerResultPack result = translator.call(param, new File("asr_example.wav"));
if (result.getError() != null) {
System.out.println("error: " + result.getError());
throw new RuntimeException(result.getError());
} else {
System.out.println("RequestId:" + result.getRequestId());
System.out.println("识别结果:");
ArrayList<TranscriptionResult> transcriptionResults = result.getTranscriptionResultList();
for (int i = 0; i < transcriptionResults.size(); i++) {
System.out.println(transcriptionResults.get(i).getText());
}
System.out.println("翻译结果:");
ArrayList<TranslationResult> translationResultList = result.getTranslationResultList();
for (int i = 0; i < translationResultList.size(); i++) {
System.out.println(translationResultList.get(i).getTranslation(targetLanguage).getText());
}
}
System.exit(0);
}
}
错误码说明
如遇报错问题,请参见错误信息进行排查。