搜"语音转文字专有名词识别错误"进来的人，多半手里已经有一批转错的稿子。我这边那批长这样：珞珈三号变成洛家三号，同一段合成音频连转三次，还出过三种不同写法。这类问题在客服通话转写、会议记录、医疗与法务口述整理里都常见。
语音识别（ASR，声音进去文字出来）遇到生僻专名会往常用词上靠，光换模型不解决。阿里云百炼给这件事配了三条热词通道：预编译热词表、即时热词、上下文词表。热词表是你提前递给识别服务的一张清单，意思是"这些词要认准"。
这篇按排查顺序写：先确认你的组合真的会听错，再选通道，最后是"热词加了没生效"的对照表与常见问题。
取数口径：命令行工具是阿里云百炼的bl（2.1.0），转写模型 qwen-audio-3.0-asr-flash，素材是我用语音合成现做的两段（不是真实录音），所有输出是 2026-10-14 我在自己电脑上跑出来的。语音识别有随机性，每条结论后面都标了重复次数。
一、环境准备
- 装好
bl：入口在 CLI 安装页，一条 npm 命令 - 配好 API Key：在 API Key 签发页 签发。合成音频、转写、建表删表都要 Key，查表的 list 和 get 同样要，这组命令没有免鉴权的那一档
- 确认模型在架：
bl model search --keyword asr
二、第一步：先跑基线，确认它真的会听错
热词有没有用，前提是有一个"听错"的基线。我合成了一段塞满生僻专名的话：
请把 XQ-7734 号工单转给岑巩县的冉雍，抄送珞珈三号项目组的仇池和濮阳办事处。
bl speech recognize--urlaudio2.mp3--modelqwen-audio-3.0-asr-flash--languagezh三个模型各转一遍的结果：
| 模型 | 基线结果 |
|---|---|
| fun-asr | 全对 |
| fun-asr-flash-2026-06-15 | 全对 |
| qwen-audio-3.0-asr-flash | 珞珈三号 → 洛家三号，其余全对 |
只有第三个模型听错，后面的步骤都在它身上做。它的错还不稳定：同一段合成音频连转三次，拿到过"洛家三号"“洛家三号”"洛嘉3号"三种写法。
这一步最容易跳过，也最不该跳过。基线全对的组合加热词，没有可测量的增量，你会以为热词生效了，其实什么都没变。
顺便记一条报错：我想加测的第四个模型qwen3-asr-flash返回 HTTP 403AllocationQuota.FreeTierOnly，口径是免费额度用尽、要续费用或者去控制台关掉"仅用免费额度"模式。余量数字我这边查不到（控制台会话过期），去控制台额度页看当天读数。
三、第二步：三条通道怎么用
3.1 通道一：预编译热词表（长期词表用这条）
先建表，把词和权重写进去。权重是 1 到 5 的整数，数越大越"认准"，帮助文本推荐 4；Qwen-Audio-3.0 系还能用 50 的超级热词。
bl speech vocabulary create--modelqwen-audio-3.0-asr-flash--prefixhw1014a--words'{"珞珈三号":4,"仇池":4}'--prefix只能用小写字母和数字、最长 10 位。建完返回一个vocab-开头的 ID，转写时引用它：
bl speech recognize--urlaudio2.mp3--modelqwen-audio-3.0-asr-flash--languagezh --vocabulary-id<表 ID>结果：珞珈三号修对（1 次）。
3.2 通道二：即时热词（一次性调用用这条）
不建表，词直接内联进调用：
bl speech recognize--urlaudio2.mp3--modelqwen-audio-3.0-asr-flash--languagezh--vocabulary'{"珞珈三号":4,"仇池":4}'结果：珞珈三号修对（1 次）。注意帮助文本写明这条只对 Qwen-Audio-3.0-ASR-Flash 系列生效，换别的模型带了也不起作用。
3.3 通道三：上下文词表（只有词清单、不想管权重时用）
不给权重，只给词，空格隔开：
bl speech recognize--urlaudio2.mp3--modelqwen-audio-3.0-asr-flash--languagezh--context"珞珈三号 仇池"结果：珞珈三号修对（1 次）。这条的范围比通道二宽一点，Qwen-Audio-3.0-ASR-Flash 和 Fun-ASR-Flash 都吃，帮助文本给的上限是 400 字。
3.4 怎么选
| 场景 | 走哪条 |
|---|---|
| 词表长期不变、多个服务共用 | 通道一，建一次反复引用 |
| 临时一两次调用 | 通道二，内联不建表 |
| 手里只有一份词清单，不想给权重 | 通道三 |
上面三条各只有 1 次读数，够说明这条通道能把词修对，不够当稳定性结论。落到你自己那段合成音频上，按第四节的对照表重复跑两遍再定。
四、热词加了没生效：排查对照表
| 现象 | 先看哪里 | 结论与处理 |
|---|---|---|
加了--context还是听错 | 参数里有没有目标词本身 | 只写主题描述没用。我换成"卫星工单项目组办事处"连试两次，两次都还是洛家三号；帮助文本也写明必须包含目标词本身 |
加了--vocabulary没反应 | 模型是不是 Qwen-Audio-3.0-ASR-Flash 系列 | 即时热词只对这个系列生效，别的模型上带了也白戴 |
加了--context没反应 | 模型是不是这两家之一 | 上下文词表只对 Qwen-Audio-3.0-ASR-Flash 与 Fun-ASR-Flash 生效，且不超过 400 字 |
| 表和模型不匹配，以为会被静默忽略 | 别按这个假设做设计 | 帮助文本写的是错配则静默忽略；我错配三次，三次都生效了，没复现忽略。哪边是常态我没查明，稳妥做法是建表--model与调用--model保持一致 |
| 只试了一次就下结论 | 重复次数 | 语音识别有随机性，同一段合成音频连转三次能出三种写法，任何通道结论至少重复两次 |
bl speech vocabulary get --vocabulary-id <id>报未知参数 | 参数名 | get 和 delete 用--id，只有 recognize 那边叫--vocabulary-id |
| 删除热词表的命令没反应 | 有没有加--yes | 不带确认参数会被拦下，提示永久删除、不可撤销；加--yes才真删 |
五、第三步：建表和删表的纪律
查表两条命令：
bl speech vocabulary listbl speech vocabulary get--id<表 ID>删表有高风险闸：
bl speech vocabulary delete--id<表 ID>不带--yes直接跑会被拦下来，提示该操作永久删除、不可撤销，加--yes重跑；带上--yes才真删。
我把自己建的两张表删掉之后做了两次复核：列表里只剩别人 09-09 建的三张表（一张没碰），再 get 已删的 ID 返回 400 资源不存在。共享工作空间里跑测试，建议照这个流程走：别人的表只 list 和 get，自建的表用独立前缀，测完删除并双重复核。
六、常见问题
Q1：热词表是不是加上就一定生效？
不是。三条通道各有生效模型范围，--vocabulary只对 Qwen-Audio-3.0-ASR-Flash 系列生效，--context只对 Qwen-Audio-3.0-ASR-Flash 与 Fun-ASR-Flash 生效。先确认模型在范围内。
Q2：--context里写"这段是客服通话"这类主题描述有用吗？
没用。我换成主题词连试两次，两次都还是洛家三号。这个参数要放目标词本身，400 字的上限留给词。
Q3：同一条命令跑两次结果不一样，是不是热词没生效？
不一定。同一段合成音频不加热词连转三次，我拿到过"洛家三号"“洛家三号”"洛嘉3号"三种写法。判断有没有生效要重复跑，至少两次。
Q4：建表时的--model和调用时的--model不一致会怎样？
帮助文本写的是热词表被静默忽略。我错配着连试三次，三次都把词修对了，没复现忽略；反方向（3.0 的表给 fun-asr）观察不到，因为 fun-asr 基线本来就全对。所以哪边是常态我没查明，实操上建议两边保持一致，别把"错配会自动忽略"当兜底设计。
Q5：权重填多少？
1 到 5，帮助文本推荐 4；Qwen-Audio-3.0 系可以用 50 的超级热词。我这一轮用的是 4。
Q6：--prefix有什么限制？
只能用小写字母和数字，最长 10 位。
Q7：怎么确认表已经删掉了？
两步：bl speech vocabulary list看列表里还在不在，bl speech vocabulary get --id <已删 ID>看是不是返回 400 资源不存在。
Q8：报 403AllocationQuota.FreeTierOnly怎么办？
口径是免费额度用尽。要么续费用，要么去控制台关掉"仅用免费额度"模式。剩余额度去控制台额度页看当天读数，别信文章里的数字。
Q9：查表要不要 Key？
要。list 和 get 同样需要鉴权，这组命令没有免鉴权的那一档。
七、六条清单
- 先跑基线，确认你的合成音频和模型组合真的会听错再上热词；全对的组合加热词没有可测量的增量
- 语音识别有随机性，任何通道结论至少重复两次
- 长期词表走
vocabulary create+--vocabulary-id；临时调用走--vocabulary；只有词清单走--context --context必须含目标词本身，写主题没用（实测两次仍错）- 建表的
--model与调用的--model保持一致；帮助文本的"错配静默忽略"我这次没复现，别拿它当兜底设计 - 删表有高风险闸，不加
--yes会被拦；删完 list + get 双重复核
八、这篇没覆盖的
字幕链路（识别加翻译加时间轴）是另一篇的事，这篇只用到 recognize 一条命令。实时流式识别（realtime 系列模型）不在范围内。真实带噪素材我手里没有，这一篇的音频是合成的，噪声环境下的表现以你自己那次为准。花费与额度走控制台账单页与额度页，控制台侧的入口在 阿里云百炼首页。
会变的部分是模型在架名单、额度状态、热词表清单，重跑一遍就有当天读数。感兴趣的可以照第二节先跑一次基线，看你自己那段合成音频和模型组合会不会听错，再决定要不要上热词。
