跳转到主要内容
千问云 home page
开放平台文档
语音识别

自定义热词

提升专有名词的识别准确率

热词帮助模型准确识别容易漏识或误识的术语，如业务术语、产品名称或人名地名等专有名词。

热词概述

以 JSON 数组格式提交热词对象列表。 示例：提升电影名称的识别准确率（Fun-ASR 和 Paraformer 系列模型） 
[
  {"text": "赛德克巴莱", "weight": 4, "lang": "zh"},
  {"text": "Seediq Bale", "weight": 4, "lang": "en"},
  {"text": "夏洛特烦恼", "weight": 4, "lang": "zh"},
  {"text": "Goodbye Mr. Loser", "weight": 4, "lang": "en"},
  {"text": "阙里人家", "weight": 4, "lang": "zh"},
  {"text": "Confucius' Family", "weight": 4, "lang": "en"}
]
字段说明：
字段类型是否必填说明
textstring是热词文本。必须是所选模型支持的词语，不能使用随机字符。长度规则见下文。
weightint是优先级权重，取值范围为 1~5 的整数。建议从 4 开始调整。效果不佳时可适当调高，但权重过高可能影响其他词的识别。
langstring否语言代码。指定后仅对该语言的热词生效。留空则自动检测语言。支持的语言代码请参考对应模型的 API 参考文档。如果设置了 language_hints，仅匹配的热词会生效。
热词文本长度规则：
  • 包含非 ASCII 字符：总长度不超过 15 个字符，包括非 ASCII 字符（中文、日文假名、韩文、俄文西里尔字母）和 ASCII 字符。 示例：
    • "厄洛替尼盐酸盐"（7 个中文字符）
    • "EGFR抑制剂"（3 个中文字符和 4 个 ASCII 字符，共 7 个字符）
    • "こんにちは"（5 个字符）
    • "Фенибут Белфарм"（15 个字符，含空格）
    • "Клофелин Белмедпрепараты"（24 个字符）——超出限制
  • 仅包含 ASCII 字符：不超过 7 个词段。词段是以空格分隔的字符序列。 示例：
    • "Exothermic reaction" —— 2 个词段
    • "Human immunodeficiency virus type 1" —— 5 个词段
    • "The effect of temperature variations on enzyme activity in biochemical reactions" —— 11 个词段，超出限制

支持的模型

所有 Fun-ASR 模型均支持热词功能。完整模型列表请参见语音转文字模型。

计费

热词功能免费使用。

热词数量限制

  1. 每个账号最多创建 10 个热词表，所有模型共享。如需提升配额，请提交工单。
  2. 每个热词表最多包含 500 个词。

快速开始

使用流程

  1. 创建热词表：调用创建热词表 API。将 target_model（Java 中为 targetModel）设置为您要使用的语音识别模型。如果已有热词表，可跳过此步骤，调用查询所有热词表查看。
  2. 传入热词表 ID：将热词表 ID 传给语音识别 API。使用的模型必须与步骤 1 中的 target_model（Java 中为 targetModel）一致。

前提条件

  1. 获取 API Key：获取 API Key 并将其配置为环境变量。
  2. 安装 SDK：安装 DashScope SDK。

代码示例

示例中使用的音频文件：asr_example.wav。
  • Python
  • Java
import dashscope
from dashscope.audio.asr import *
import os


# 如果未配置环境变量，请将下一行替换为：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'
dashscope.base_websocket_api_url='wss://dashscope.aliyuncs.com/api-ws/v1/inference'
prefix = 'testpfx'
target_model = "fun-asr-realtime"

my_vocabulary = [
  {"text": "Speech Lab", "weight": 4}
]

service = VocabularyService()
vocabulary_id = service.create_vocabulary(
      prefix=prefix,
      target_model=target_model,
      vocabulary=my_vocabulary)

if service.query_vocabulary(vocabulary_id)['status'] == 'OK':
  recognition = Recognition(model=target_model,
                          format='wav',
                          sample_rate=16000,
                          callback=None,
                          vocabulary_id=vocabulary_id)
  result = recognition.call('asr_example.wav')
  print(result.output)

service.delete_vocabulary(vocabulary_id)

API 参考

所有操作请使用同一账号。

创建热词表

热词表的 JSON 格式请参见热词概述。
  • Python SDK
  • Java SDK
  • RESTful API
接口说明
target_model 必须与语音识别调用中使用的模型一致。
def create_vocabulary(self, target_model: str, prefix: str, vocabulary: List[dict]) -> str:
  '''
  创建热词表。
  param: target_model 语音识别模型（必须与识别调用中使用的模型一致）。
  param: prefix 自定义前缀（不超过 10 个小写字母或数字）。
  param: vocabulary 热词列表。
  return: 热词表 ID。
  '''
代码示例
import dashscope
from dashscope.audio.asr import *
import os

# 如果未配置环境变量，请将下一行替换为：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

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

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

# 创建热词表
service = VocabularyService()
vocabulary_id = service.create_vocabulary(
  prefix=prefix,
  target_model=target_model,
  vocabulary=my_vocabulary)

print(f"热词表 ID：{vocabulary_id}")

查询所有热词表

  • Python SDK
  • Java SDK
  • RESTful API
接口说明
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: 热词表标识列表。
  '''
代码示例
import dashscope
from dashscope.audio.asr import *
import json
import os

# 如果未配置环境变量，请将下一行替换为：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

service = VocabularyService()
vocabularies = service.list_vocabularies()
print(f"热词表列表：{json.dumps(vocabularies)}")
响应示例
[
  {
  "gmt_create": "2025-04-22 14:23:35",
  "vocabulary_id": "vocab-testpfx-5112c3de3705486baxxxxxxx",
  "gmt_modified": "2025-04-22 14:23:35",
  "status": "OK"
  }
]

查询指定热词表

  • Python SDK
  • Java SDK
  • RESTful API
接口说明
def query_vocabulary(self, vocabulary_id: str) -> List[dict]:
  '''
  根据 ID 查询热词表。
  param: vocabulary_id 热词表 ID。
  return: 热词表内容。
  '''
代码示例
import dashscope
from dashscope.audio.asr import *
import json
import os

# 如果未配置环境变量，请将下一行替换为：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

service = VocabularyService()
# 查询时请替换为实际的热词表 ID
vocabulary = service.query_vocabulary("vocab-testpfx-xxx")
print(f"热词表内容：{json.dumps(vocabulary, ensure_ascii=False)}")
响应示例
{
  "gmt_create": "2025-12-19 11:47:11",
  "gmt_modified": "2025-12-19 11:47:11",
  "status": "OK",
  "target_model": "fun-asr",
  "vocabulary": [
  {
      "lang": "zh",
      "text": "Seediq Bale",
      "weight": 4
  }
  ]
}

更新热词表

  • Python SDK
  • Java SDK
  • RESTful API
接口说明
def update_vocabulary(self, vocabulary_id: str, vocabulary: List[dict]) -> None:
  '''
  替换热词表内容。
  param: vocabulary_id 要替换的热词表 ID。
  param: vocabulary 新的热词列表。
  '''
代码示例
import dashscope
from dashscope.audio.asr import *
import os

# 如果未配置环境变量，请将下一行替换为：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

service = VocabularyService()
my_vocabulary = [
  {"text": "Seediq Bale", "weight": 4, "lang": "zh"}
]
# 请替换为实际的热词表 ID
service.update_vocabulary("vocab-testpfx-xxx", my_vocabulary)

删除热词表

  • Python SDK
  • Java SDK
  • RESTful API
接口说明
def delete_vocabulary(self, vocabulary_id: str) -> None:
  '''
  删除热词表。
  param: vocabulary_id 要删除的热词表 ID。
  '''
代码示例
import dashscope
from dashscope.audio.asr import *
import os

# 如果未配置环境变量，请将下一行替换为：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

service = VocabularyService()
# 请替换为实际的热词表 ID
service.delete_vocabulary("vocab-testpfx-xxxx")