通过热词(即时热词、预编译热词)和上下文增强,改善人名、产品名、行业术语等词汇的语音识别效果。
选择优化方式
人名、产品名和行业术语可能与常用词发音相近,识别时容易出现同音字或词语错误。热词和上下文增强可为模型补充这些词汇的准确写法或相关背景,帮助改善识别效果。
选择优化方式时,先看业务已有的信息:有明确的术语清单,可使用热词;已有对话历史或业务说明,可使用上下文增强。热词再按词表是否需要跨请求复用,分为即时热词和预编译热词。使用前确认支持的模型。
| 方式 | 适用情况 | 使用方法 |
|---|---|---|
| 即时热词 | 待识别的人名、产品名等随请求变化,或只有少量临时术语,不需要保存和管理词表。 | 在每次识别请求中直接传入“词语:权重”对象。应用需准备待识别词语的准确写法,可通过权重调整模型对这些词语的偏好。 |
| 预编译热词 | 已有业务词库,或一组术语会在多次识别中反复使用,希望统一维护词表。 | 先创建包含词语、权重和可选语种的热词列表,识别时引用列表 ID。词库有变化时更新列表,无需在每个识别请求中重复提交词条。 |
| 上下文增强 | 应用已保存前几轮对话、业务说明或领域文本,希望直接利用这些内容辅助识别。 | 将相关文本作为上下文消息随音频传入,无需先提取词条或逐词设置权重。上下文应包含待识别术语的准确写法;只有明确的术语清单时,也可以使用热词解决同类问题。 |
使用热词
运行示例前,请先下载示例音频并准备 API Key(可在千问AI平台控制台获取)。音频内容:“请把祺元项目的报告发给洛柯,下周我们要上线璇枢系统。”
即时热词
即时热词适合随请求变化的词语。在识别请求的 parameters.vocabulary 中传入 JSON 对象:键为热词文本(string),值为权重(integer),无需预先创建词表。
- 不配置热词,识别原始音频 未配置热词时,本例中的三个名称识别不准确。原始识别结果可通过以下请求获取。
cURL
- 随请求加入即时热词 在相同请求中加入“祺元”“洛柯”“璇枢”,权重均设为 4,其余输入保持一致。权重范围和调整方法参见调整热词权重。
cURL
| 配置 | 识别文本示例 |
|---|---|
| 未配置 | 请把漆园项目的报告发给罗科,下周我们要上线玄枢系统。 |
| 配置后 | 请把祺元项目的报告发给洛柯,下周我们要上线璇枢系统。 |
预编译热词
预编译热词适合需要跨请求复用的业务词表。预先创建热词列表后,在识别请求中传入 vocabulary_id,无需每次重复提交词条。
创建时以 JSON 数组提交词条,每个元素的字段如下:
创建热词列表时指定的目标模型须与实际识别模型一致。
热词管理与语音识别必须使用同一账号,否则识别接口无法访问对应的热词列表。
- HTTP / cURL
- SDK
-
创建热词列表
以下示例使用
qwen-audio-3.1-asr-flash,通过target_model指定目标模型。保存响应中output.vocabulary_id的值。
cURL
-
确认列表可用
将
<vocabulary_id>替换为创建接口返回的列表 ID,再查询状态。确认响应中的output.status为OK后进行识别。
cURL
-
在识别请求中引用列表
在识别请求中通过
parameters.vocabulary_id引用该列表,无需重复传入词条。
cURL
- 复用或删除列表 后续请求可继续引用同一 ID。仅在不再需要此列表时调用以下删除接口,释放列表配额。
cURL
使用上下文增强
上下文增强可以直接利用已有对话历史或领域文本。与热词要求应用提供词语和权重不同,上下文以文本消息传入,不需要先把业务资料拆成词条。两种方式都可能改善专有名词的识别,应根据应用已有的信息选择。
准备上下文
沿用上述音频:如果应用已有“祺元项目、璇枢系统、同事洛柯”的业务信息,可直接传入包含这些准确名称的文本。常见的上下文来源有以下两种。
- 业务背景或领域文本
- 历史对话
例如已有的项目说明或行业资料。将相关文本放入
role=user、type=input_text 的消息中,无需为此构造对话或添加回复。以下数组可作为上下文传入:assistant 消息可省略。使用历史对话时,按轮次排列,每轮 user 在对应 assistant 之前。文本长度和保留轮数参见使用限制。配置与调用
使用准备好的上下文识别同一段音频,按模型系列选择调用示例。
- Qwen-Audio-ASR
- Qwen-Audio-ASR-Message / Qwen-Audio-ASR-Streaming
- Qwen-Audio-ASR-Filetrans
以下示例使用
qwen-audio-3.1-asr-flash,在 input.messages 中按顺序放入上下文消息,并将包含 input_audio 的当前音频消息放在最后。cURL
| 配置 | 识别文本示例 |
|---|---|
| 未配置 | 请把漆园项目的报告发给罗科,下周我们要上线玄枢系统。 |
| 配置后 | 请把祺元项目的报告发给洛柯,下周我们要上线璇枢系统。 |
效果调优与排查
使用同一音频对比配置前后的结果,再调整词条、权重或上下文内容。热词调优同时适用于即时热词和预编译热词。
调整热词权重
普通热词的权重范围为 1~5,建议从 weight=4 起调。权重越高,模型越倾向于输出该词;权重过高可能把其他发音相近的词错误替换为热词。
| 权重 | 偏好程度 | 适用情况 |
|---|---|---|
| 1~2 | 较弱 | 与常用词发音相近,需要避免过度纠偏 |
| 3~4 | 较明显 | 推荐作为大多数场景的起始配置 |
| 5 | 较强 | 音频中频繁出现、较少与其他词混淆的术语 |
weight=50,可提高目标词召回率,每个词表或请求最多 50 个。
组织与维护词表
- 按场景分组:预编译热词可为不同业务场景创建独立列表,例如分别维护医疗术语和产品名称,减少无关词条。
-
区分词条语种与音频语种:预编译词表可混入不同语种的词条,通过
lang区分。language_hints属于识别接口,用于声明音频语种;设置后,仅语种匹配的热词生效,其他语种的热词被忽略。 - 定期维护:按业务需要更新词条,删除不再使用的列表以释放配额。
建议两次热词列表更新至少间隔 5 分钟,否则更新后的热词可能不生效。
排查识别效果
先区分是配置未生效、词语纠偏过强,还是音频本身难以识别,再检查相应项目。
| 现象 | 检查与处理 |
|---|---|
| 热词未按预期识别 | 先确认支持的模型。即时热词应位于 parameters.vocabulary;预编译热词需核对账号、vocabulary_id、status=OK,以及创建列表时的 target_model 是否与当前模型一致。在支持范围内调大热词权重,并对比同一音频的结果,判断是否为权重偏低导致。 |
| 其他词被误识别为热词 | 在支持范围内调小热词权重,并按业务场景减少无关词条。检查 lang 与识别接口 language_hints 是否匹配,避免使用不属于当前语种的词条。 |
| 上下文没有改善目标词 | 检查文本是否包含术语的准确写法,并核对消息角色、类型、顺序和所用接口的传入位置。超过长度或轮数限制的文本可能被截断或丢弃,规则参见使用限制。 |
| 普通词也大量识别错误 | 检查音频格式、采样率是否符合模型要求,并降低背景噪声。单语种音频可通过识别接口的 language_hints 声明语种。模型选型与音频要求参见语音识别概述。 |
支持的模型
- 预编译热词
- 即时热词
- 上下文增强
- Qwen-Audio-ASR:qwen-audio-3.1-asr-flash、qwen-audio-3.0-asr-flash
- Qwen-Audio-ASR-Streaming:qwen-audio-3.1-asr-flash-streaming、qwen-audio-3.0-asr-flash-streaming
- Qwen-Audio-ASR-Filetrans:qwen-audio-3.1-asr-flash-filetrans、qwen-audio-3.0-asr-flash-filetrans
- Qwen-Audio-ASR-Message:qwen-audio-3.1-asr-flash-message
- Fun-ASR-Realtime:fun-asr-realtime、fun-asr-realtime-2026-02-28、fun-asr-flash-8k-realtime、fun-asr-flash-8k-realtime-2026-01-28
- Fun-ASR-Flash:fun-asr-flash-2026-06-15
- Fun-ASR:fun-asr
- Paraformer-Realtime:paraformer-realtime-v2、paraformer-realtime-8k-v2
- Paraformer:paraformer-v2、paraformer-8k-v2
使用限制
- 热词限制
- 热词文本规范
- 上下文限制
| 限制项 | 说明 |
|---|---|
| 热词列表数量 | 每账号最多 50 个预编译热词列表,所有模型共享。每个列表对应一个 vocabulary_id。 |
| 热词数量 | Qwen-Audio-ASR-Message、Qwen-Audio-ASR-Streaming、Qwen-Audio-ASR-Filetrans、Qwen-Audio-ASR 系列:最多 2000 个。 Fun-ASR-Realtime、Fun-ASR-Flash、Fun-ASR 系列主版本模型:最多 2000 个;上述系列的其他模型以及 Paraformer 系列:最多 500 个。 预编译热词按单个列表计数,即时热词按单次请求计数。 |
| 超级热词数量 | 权重为 50 的词条最多 50 个。 |
对于 Qwen-Audio-ASR-Message、Qwen-Audio-ASR-Streaming、Qwen-Audio-ASR-Filetrans 和 Qwen-Audio-ASR 系列模型,同时配置预编译热词和即时热词时,系统会合并两类热词;合并后超过 2000 个时,随机选择 2000 个使用。
功能计费
即时热词和预编译热词功能本身免费。使用热词或上下文增强的模型调用费用,请参见计费规则。
相关 API
- 热词列表的创建、查询、更新和删除等操作,参见热词管理 API。
- 热词管理 SDK:Java SDK、Python SDK。
- 模型调用 API:Qwen-Audio-ASR-Message 客户端事件、Qwen-Audio-ASR-Streaming 客户端事件、Qwen-Audio-ASR-Filetrans HTTP API、Qwen-Audio-ASR HTTP API。