跳转到主要内容
语音识别

提升识别准确率

通过热词(即时热词、预编译热词)和上下文增强,改善人名、产品名、行业术语等词汇的语音识别效果。

选择优化方式

人名、产品名和行业术语可能与常用词发音相近,识别时容易出现同音字或词语错误。热词和上下文增强可为模型补充这些词汇的准确写法或相关背景,帮助改善识别效果。 选择优化方式时,先看业务已有的信息:有明确的术语清单,可使用热词;已有对话历史或业务说明,可使用上下文增强。热词再按词表是否需要跨请求复用,分为即时热词和预编译热词。使用前确认支持的模型。
方式适用情况使用方法
即时热词待识别的人名、产品名等随请求变化,或只有少量临时术语,不需要保存和管理词表。在每次识别请求中直接传入“词语:权重”对象。应用需准备待识别词语的准确写法,可通过权重调整模型对这些词语的偏好。
预编译热词已有业务词库,或一组术语会在多次识别中反复使用,希望统一维护词表。先创建包含词语、权重和可选语种的热词列表,识别时引用列表 ID。词库有变化时更新列表,无需在每个识别请求中重复提交词条。
上下文增强应用已保存前几轮对话、业务说明或领域文本,希望直接利用这些内容辅助识别。将相关文本作为上下文消息随音频传入,无需先提取词条或逐词设置权重。上下文应包含待识别术语的准确写法;只有明确的术语清单时,也可以使用热词解决同类问题。

使用热词

运行示例前,请先下载示例音频并准备 API Key(可在千问AI平台控制台获取)。音频内容:“请把祺元项目的报告发给洛柯,下周我们要上线璇枢系统。”

即时热词

即时热词适合随请求变化的词语。在识别请求的 parameters.vocabulary 中传入 JSON 对象:键为热词文本(string),值为权重(integer),无需预先创建词表。
  1. 不配置热词,识别原始音频 未配置热词时,本例中的三个名称识别不准确。原始识别结果可通过以下请求获取。
cURL
curl --request POST 'https://maas.qianwenaiapi.com/api/v1/services/aigc/multimodal-generation/generation' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "X-DashScope-SSE: disable" \
  --data '
{
  "model": "qwen-audio-3.1-asr-flash",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_audio",
            "input_audio": {
              "data": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/zh/audios/6a4b3c2d1e0f9093.wav"
            }
          }
        ]
      }
    ]
  },
  "parameters": {
    "format": "wav",
    "sample_rate": 16000
  }
}
'
  1. 随请求加入即时热词 在相同请求中加入“祺元”“洛柯”“璇枢”,权重均设为 4,其余输入保持一致。权重范围和调整方法参见调整热词权重。
cURL
curl --request POST 'https://maas.qianwenaiapi.com/api/v1/services/aigc/multimodal-generation/generation' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "X-DashScope-SSE: disable" \
  --data '
{
  "model": "qwen-audio-3.1-asr-flash",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_audio",
            "input_audio": {
              "data": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/zh/audios/6a4b3c2d1e0f9093.wav"
            }
          }
        ]
      }
    ]
  },
  "parameters": {
    "format": "wav",
    "sample_rate": 16000,
    "vocabulary": {
      "祺元": 4,
      "洛柯": 4,
      "璇枢": 4
    }
  }
}
'
配置前后的识别文本示例如下:
配置识别文本示例
未配置请把漆园项目的报告发给罗科,下周我们要上线玄枢系统。
配置后请把祺元项目的报告发给洛柯,下周我们要上线璇枢系统。

预编译热词

预编译热词适合需要跨请求复用的业务词表。预先创建热词列表后,在识别请求中传入 vocabulary_id,无需每次重复提交词条。 创建时以 JSON 数组提交词条,每个元素的字段如下:
字段类型必填说明
textstring是实际词语,语种须在所选模型的支持范围内。长度要求参见热词文本规范。
weightinteger是普通热词取值为 1~5,推荐从 4 起调。部分模型支持超级热词权重 50,详见调整热词权重。
langstring否语种代码,限定词条作用的语种;语种未知时可省略。与识别接口 language_hints 的关系参见组织与维护词表。
创建热词列表时指定的目标模型须与实际识别模型一致。
热词管理与语音识别必须使用同一账号,否则识别接口无法访问对应的热词列表。
  • HTTP / cURL
  • SDK
  1. 创建热词列表 以下示例使用 qwen-audio-3.1-asr-flash,通过 target_model 指定目标模型。保存响应中 output.vocabulary_id 的值。
cURL
curl --request POST 'https://maas.qianwenaiapi.com/api/v1/services/audio/asr/customization' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<EOF
{
  "model": "speech-biasing",
  "input": {
    "action": "create_vocabulary",
    "target_model": "qwen-audio-3.1-asr-flash",
    "prefix": "testpfx",
    "vocabulary": [
      {
        "text": "祺元",
        "weight": 4,
        "lang": "zh"
      },
      {
        "text": "洛柯",
        "weight": 4,
        "lang": "zh"
      },
      {
        "text": "璇枢",
        "weight": 4,
        "lang": "zh"
      }
    ]
  }
}
EOF
  1. 确认列表可用 将 <vocabulary_id> 替换为创建接口返回的列表 ID,再查询状态。确认响应中的 output.status 为 OK 后进行识别。
cURL
export VOCABULARY_ID="<vocabulary_id>"

curl --request POST 'https://maas.qianwenaiapi.com/api/v1/services/audio/asr/customization' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<EOF
{
  "model": "speech-biasing",
  "input": {
    "action": "query_vocabulary",
    "vocabulary_id": "$VOCABULARY_ID"
  }
}
EOF
  1. 在识别请求中引用列表 在识别请求中通过 parameters.vocabulary_id 引用该列表,无需重复传入词条。
cURL
curl --request POST 'https://maas.qianwenaiapi.com/api/v1/services/aigc/multimodal-generation/generation' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "X-DashScope-SSE: disable" \
  --data @- <<EOF
{
  "model": "qwen-audio-3.1-asr-flash",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_audio",
            "input_audio": {
              "data": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/zh/audios/6a4b3c2d1e0f9093.wav"
            }
          }
        ]
      }
    ]
  },
  "parameters": {
    "format": "wav",
    "sample_rate": 16000,
    "vocabulary_id": "$VOCABULARY_ID"
  }
}
EOF
  1. 复用或删除列表 后续请求可继续引用同一 ID。仅在不再需要此列表时调用以下删除接口,释放列表配额。
cURL
curl --request POST 'https://maas.qianwenaiapi.com/api/v1/services/audio/asr/customization' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<EOF
{
  "model": "speech-biasing",
  "input": {
    "action": "delete_vocabulary",
    "vocabulary_id": "$VOCABULARY_ID"
  }
}
EOF

使用上下文增强

上下文增强可以直接利用已有对话历史或领域文本。与热词要求应用提供词语和权重不同,上下文以文本消息传入,不需要先把业务资料拆成词条。两种方式都可能改善专有名词的识别,应根据应用已有的信息选择。

准备上下文

沿用上述音频:如果应用已有“祺元项目、璇枢系统、同事洛柯”的业务信息,可直接传入包含这些准确名称的文本。常见的上下文来源有以下两种。
  • 业务背景或领域文本
  • 历史对话
例如已有的项目说明或行业资料。将相关文本放入 role=user、type=input_text 的消息中,无需为此构造对话或添加回复。以下数组可作为上下文传入:
[
  {
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "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
curl --request POST 'https://maas.qianwenaiapi.com/api/v1/services/aigc/multimodal-generation/generation' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "X-DashScope-SSE: disable" \
  --data '
{
  "model": "qwen-audio-3.1-asr-flash",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "我在祺元项目工作,负责璇枢系统。我的同事叫洛柯。"
          }
        ]
      },
      {
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "好的,我们继续讨论祺元项目、璇枢系统和洛柯的工作。"
          }
        ]
      },
      {
        "role": "user",
        "content": [
          {
            "type": "input_audio",
            "input_audio": {
              "data": "https://g-adoc.alcasset.com/media/maas_docs/sfm-cn/zh/audios/6a4b3c2d1e0f9093.wav"
            }
          }
        ]
      }
    ]
  },
  "parameters": {
    "format": "wav",
    "sample_rate": 16000
  }
}
'
移除示例中的上下文配置,再识别同一段音频,即可对比配置前后的结果。以下为识别文本示例:
配置识别文本示例
未配置请把漆园项目的报告发给罗科,下周我们要上线玄枢系统。
配置后请把祺元项目的报告发给洛柯,下周我们要上线璇枢系统。

效果调优与排查

使用同一音频对比配置前后的结果,再调整词条、权重或上下文内容。热词调优同时适用于即时热词和预编译热词。

调整热词权重

普通热词的权重范围为 1~5,建议从 weight=4 起调。权重越高,模型越倾向于输出该词;权重过高可能把其他发音相近的词错误替换为热词。
权重偏好程度适用情况
1~2较弱与常用词发音相近,需要避免过度纠偏
3~4较明显推荐作为大多数场景的起始配置
5较强音频中频繁出现、较少与其他词混淆的术语
超级热词:Qwen-Audio-ASR-Message、Qwen-Audio-ASR-Streaming、Qwen-Audio-ASR-Filetrans 和 Qwen-Audio-ASR 系列的即时热词、预编译热词还支持 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