热词没有生效？先核对传递链路和安装包

FunASR 技术博客 · 2026-11-13

团队接入语音识别时，产品名和人名常常需要热词提示。识别结果不理想，不一定是词表不够大：先确认客户端传出的词，确实以模型支持的形式到达了推理入口。

例如，客户端把两个术语放进带权重的 JSON 对象，再将它编码成 WebSocket 消息中的字符串。服务端不能把大括号、引号和数字一起当作热词正文。下面沿着消息、服务脚本和独立运行时三层，给出可核对的路径。

热词是提示，不是强制替换或正确率保证。本文解释已经验证的协议和运行时边界，不提供新的识别准确率、性能排名或生产部署承诺。

一、先分清你使用的入口

这三个入口不是同一个发布物。升级根包 funasr，不会自动更新你复制的服务脚本，也不能替代独立运行时的安装。WebSocket 热词修复见 #3892（保留 #3880 作者历史）；不要仅凭一个版本号推断整个服务已升级。

二、让 JSON 热词成为模型实际接收的词

以下只展示消息编码，不会启动服务、下载权重或发送音频：

import json

hotwords = {"阿里巴巴": 20, "通义实验室": 30}
message = {"hotwords": json.dumps(hotwords, ensure_ascii=False)}
assert json.loads(message["hotwords"]) == hotwords
print(json.dumps(message, ensure_ascii=False))

修复后的 Python 服务会把 JSON 对象的键整理为以空格分隔的词，分别写入离线和在线模型参数；空对象变为空字符串。普通字符串及不能解析成 JSON 的字符串仍按原文本传递。这里的 AutoModel 接口不接收数值权重，因此 20 和 30 不会成为模型的相对偏置强度。需要权重能力时，应单独核对所选模型与部署协议，不能把另一套运行时的约定直接搬过来。

线上的完整消息还需要按相应客户端协议设置音频和分块参数。上述片段不是完整的流式客户端，其他格式也不能仅凭此示例认定兼容。部署时还需配置 TLS、鉴权、资源限制，并避免把私人音频、转录或敏感词表写进公开日志。

三、检查真正安装和导入的 Torch 包

在独立测试环境中安装指定版本，再查看包元数据和实际导入位置。不要直接改动正在服务的共享环境：

python -m pip install "funasr-torch==0.1.7"
python -m pip check
python -c 'import importlib.metadata as m, funasr_torch; print(m.version("funasr-torch")); print(funasr_torch.__file__)'

Contextual 和 Seaco 包装器使用的导出热词嵌入宽度为 10。0.1.7 会忽略空白条目，长热词保留前十个字符，并将索引限制在对应嵌入范围内。这解决的是运行时边界，不代表超长词的剩余部分仍能参与提示。请优先使用业务中有区分度的短词，并用获得授权的录音检查收益与误触发。

四、用单条与批次结果检查时间戳

把短音频与长音频分别运行一次，再组成同一批次运行。输出数量、文本和短音频的时间戳都应按各自录音核对。0.1.7 的 Paraformer 修复会按每条输入的特征长度截取峰值序列，防止填充帧拉长短音频的末尾时间戳。同一版本还包括末尾缩写合并及富转录片段词间空格修复。

发布前分别测试了 wheel 和源码分发包的安装后行为。真实 GPU 证据使用既有合成夹具，且逐文件绑定运行时代码；它不是新的预训练模型准确率评测，也不是任意模型和硬件的完整兼容性证明。将自己常用的语言、噪声和长短录音纳入验收，仍然不可省略。

发布物与下一步

查看 Torch 0.1.7 Release 与校验清单、PyPI 安装包及 ONNX 0.4.11 Release。源码修复分别记录在 #3882、#3871和 #3869。

下一步，用你有权处理的一小组录音，按会议转写验收清单检查术语、遗漏和时间戳，再决定何时更新自己的服务。